Node Gitignore: What to Ignore in Node.js Projects

November 11, 2026 · 9 min read

Node Gitignore: What to Ignore in a Node.js Project

A node gitignore file tells Git to skip node_modules/, .env secrets, build output, coverage reports and package-manager logs, while you keep committing package.json and your lock file. Below is a short Node.js .gitignore you can paste today, then why each block exists and how to untrack files Git already has.

A Short Node Gitignore to Start From

The rules most Node projects need fit on one screen. Save this as .gitignore in the root of your repository, next to package.json. Lines starting with # are comments, and each group covers one kind of generated or private file.

# Dependencies (rebuilt by npm install)
node_modules/
.pnpm-store/

# Environment files (keep the example)
.env
.env.*
!.env.example

# Build output
dist/
build/
*.tsbuildinfo
*.tgz

# Test coverage
coverage/
.nyc_output/

# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

# Tool caches
.npm/
.eslintcache

# Operating system clutter
.DS_Store
Thumbs.db

# Lock files are NOT listed here: commit them

Git now leaves every matching file out of git status and git add. To check, run git status --ignored: it lists the ignored paths in their own block, so you can spot anything you meant to commit. One catch: the file only affects files Git isn't tracking yet. If node_modules is already in a commit, adding a rule changes nothing until you untrack it, which the removal section below covers.

Why node_modules Never Belongs in Git

Running npm install fills node_modules/ with every dependency plus everything those packages depend on. A handful of direct dependencies often expands into a much larger tree, so committing the folder bloats every clone and turns each upgrade into a diff nobody reviews.

The folder can also be machine-specific. Packages with native addons build or download compiled binaries during install, and those binaries match the operating system and CPU that ran it. A folder built on a Mac won't necessarily run on a Linux CI server.

You don't lose anything by putting it in your Node gitignore. The npm docs say the lock file gives teammates and CI the same dependency tree, and lets you restore earlier states of node_modules without committing the directory itself. That makes package.json plus the lock file the real source of truth.

The trailing slash in node_modules/ means the rule matches directories only. Because the pattern has no slash at the start or middle, it matches at any depth, so it also covers the node_modules folders inside workspace packages in a monorepo.

Keeping .env Out of Git While Committing .env.example

Environment files hold API keys, database URLs and tokens. They belong on each machine, never in history. The three lines in the file above handle that:

.env
.env.*
!.env.example

The first two lines ignore .env plus every variant such as .env.local or .env.production. The ! line re-includes .env.example, a copy with the keys listed and the values blanked, so a new contributor can see which variables the app expects.

Some templates, including the one in our generator, use a narrower set instead: .env, .env.local and .env.*.local. That version still tracks .env.production, which is fine only if you're sure that file never holds a secret.

Ignoring a file doesn't scrub it from history. If a real key was ever pushed, rotate it with the provider first, then untrack the file as shown below.

Should package-lock.json Be in .gitignore?

No. Commit package-lock.json, yarn.lock or pnpm-lock.yaml, whichever matches your package manager. All three projects say so in their own docs:

  • npm describes package-lock.json as "intended to be committed into source repositories" in its package-lock.json docs.
  • Yarn's Q&A page says lockfiles should always be kept in the repository, even for libraries.
  • pnpm's Git guide tells you to always commit pnpm-lock.yaml.

The lock file pins the exact version of every package in the tree. Without it, npm install on a CI runner can resolve newer versions than the ones you tested, and a bug appears that nobody can reproduce locally.

We prefer committing the lock file even in published libraries, so CI installs exactly what you tested. Commit only the lock file of the manager you actually use. Two lock files in one repo usually means two people ran different tools, and they'll drift apart.

npm, Yarn and pnpm: Logs, Stores and the .yarn Folder

Each package manager writes its own debug logs and caches. The -debug.log* patterns end in * so they also match names that carry an extra suffix. Here's what to commit and what to ignore for each one:

Package managerLock file to commitPaths to ignore
npmpackage-lock.jsonnode_modules/, npm-debug.log*, .npm/
Yarn Classic (1.x)yarn.locknode_modules/, yarn-debug.log*, yarn-error.log*
Yarn Berry (2+)yarn.lock.yarn/* with exceptions, .pnp.* (see below)
pnpmpnpm-lock.yamlnode_modules/, pnpm-debug.log*, .pnpm-store/

Modern Yarn needs extra care, because part of its .yarn folder must stay in Git. If you don't use Zero-Installs, Yarn's docs list this block:

.pnp.*
.yarn/*
!.yarn/patches
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
!.yarn/versions

With Zero-Installs, you commit the cache and the .pnp.* loader, so drop the .pnp.* line and add !.yarn/cache. The patches folder stays committed either way because installs need it, and plugins and releases stay committed so everyone runs the same Yarn version.

Two smaller caches round out the list. ESLint writes .eslintcache when you run it with --cache. TypeScript writes *.tsbuildinfo files for incremental builds. Both regenerate on the next run.

Build Output, Coverage and What npm publish Ships

Anything a script can regenerate stays out of Git. That means compiled output in dist/ or build/, coverage reports in coverage/, nyc's .nyc_output/ folder, and the *.tgz tarballs that npm pack writes. Framework folders such as .next/, .nuxt/ or .svelte-kit/ follow the same rule; add the ones your stack creates.

There's one trap for package authors. The npm developers guide says that if a package has no .npmignore, npm uses .gitignore to decide what to leave out. Ignore dist/ in Git and it can vanish from the published package.

Two fixes work. List what ships in the files field of package.json, which acts as an allow list. Or add a .npmignore, which replaces .gitignore for publishing. Run npm pack before publishing and check the file list it prints.

This short Node gitignore has a limit, too. It doesn't cover every framework, bundler or test runner, so add their folders yourself or start from a longer template.

How Do You Remove node_modules Already Committed to Git?

Adding node_modules/ to .gitignore doesn't untrack anything. Remove the folder from Git's index, keep it on disk, and commit:

git rm -r --cached node_modules
git commit -m "Stop tracking node_modules"
git check-ignore -v node_modules

The --cached flag removes the paths from the index only and leaves your working copy alone. -r is needed for a directory. The last command prints the ignore file, line number and pattern that matched, which proves the rule works. If workspace packages in a monorepo committed their own node_modules too, run the same git rm on each of those paths.

There's a side effect for your team. When teammates pull the commit, Git deletes the tracked copy from their working tree, so they run npm install once to get the folder back.

The same pattern untracks a committed secret file: git rm --cached .env. Pulling that commit deletes each teammate's .env too, so warn them to back it up first. The old commits still contain the file, so rotate any key it held.

Node Gitignore Templates: GitHub's Long List or a Generated File

GitHub keeps a much longer Node.gitignore template. It covers Bower, jspm, Gatsby, VuePress, Docusaurus, Serverless, Firebase, Vite, Astro, Turborepo and the Yarn block above. It's useful when you're unsure what your tools write, though most projects only need a fraction of it. Treat it as a menu: copy the blocks for tools you actually run and leave the rest out. The same repository has templates for other stacks, and our gitignore for Unity guide explains the Unity template group by group.

To build your own instead, open our .gitignore generator. It runs in your browser, with 29 templates in 5 groups: languages, frameworks, operating systems, editors, and tools and platforms. Tick Node, add macOS, Windows, VS Code or JetBrains, and type extra rules into the custom patterns box. Duplicate lines across templates are merged, and you copy or download the result.

The generator's Node template ignores .yarn/cache, which suits Yarn without Zero-Installs. Remove that line if you commit the cache. A new Node repo usually ships with a README next to the ignore file, and our README Markdown guide covers that. If your project renders Markdown itself, see rendering Markdown in JavaScript.

A good node gitignore stays short: dependencies, secrets, build output, coverage, logs and caches, with the lock file and .env.example committed. Paste the file above, add the folders your framework writes, and run git check-ignore -v when a rule seems to miss. To build one from templates, try the .gitignore generator, and write the README that goes with it in the editor.