# Essential Files and Directories for Your Node.js Gitignore: A Complete Setup Guide > Learn which essential files and directories to add to your nodejs gitignore for a clean and secure repository. Avoid common mistakes and manage your project effectively. - Repository: [Node.js/node](https://github.com/nodejs/node) - Tags: best-practices - Published: 2026-02-20 --- **When setting up a new Node.js project, your `.gitignore` file must exclude `node_modules/`, environment files containing secrets, build output directories, log files, and IDE-specific configurations to prevent repository bloat and security vulnerabilities.** The official Node.js source repository at `nodejs/node` maintains a comprehensive `.gitignore` file that serves as the canonical reference for artifacts generated by the Node.js toolchain. While the core repository includes low-level build patterns for compiling the runtime itself, application developers can adapt these battle-tested conventions to create a clean, production-ready ignore list for typical projects. ## Dependency Directories The most critical entry in any Node.js gitignore is the `node_modules/` directory. In the `nodejs/node` repository, lines 110-113 explicitly exclude this folder to prevent thousands of dependency files from being committed. Since packages are reproducibly installed from [`package.json`](https://github.com/nodejs/node/blob/main/package.json) and lockfiles (as illustrated by the project manifest in the source), committing `node_modules/` wastes space and creates unnecessary merge conflicts. ```gitignore # Dependencies node_modules/ ``` ## Environment Variables and Secrets While not present in the core Node.js repository (which uses build configuration scripts), every application project must exclude `.env` files. These files contain API keys, database passwords, and other secrets that should never be version-controlled. ```gitignore # Environment variables .env .env.local .env.*.local ``` ## Build Output and Generated Artifacts Generated bundles, transpiled code, and compiled extensions should be excluded. According to lines 39-40 of the official `.gitignore`, directories like `dist/`, `build/`, and `out/` are ignored as they contain assets rebuilt during each deployment. Lines 33-34 also demonstrate excluding generated documentation such as [`doc/api.xml`](https://github.com/nodejs/node/blob/main/doc/api.xml). ```gitignore # Build outputs dist/ build/ out/ doc/api.xml ``` ## Log Files and Debug Traces Runtime logs change constantly and offer no value in version control. Exclude npm, yarn, and pnpm debug logs to prevent repository pollution. ```gitignore # Logs npm-debug.log* yarn-debug.log* yarn-error.log* pnpm-debug.log* ``` ## Test Coverage and Reports Coverage reports and test artifacts are regenerated during CI runs. Lines 124-127 of the Node.js `.gitignore` exclude the `coverage/` directory and XML output files produced by tools like c8, nyc, or tap. ```gitignore # Coverage directory used by tools like istanbul coverage/ *.lcov *.tap *.xml ``` ## Editor and Operating System Files IDE configurations and OS-specific junk vary per developer and should never be shared. Lines 165-168 exclude `.DS_Store` files created by macOS, while backup files (`*~`) and swap files (`*.swp`) are also ignored. ```gitignore # IDE .idea/ .vscode/ *.swp *~ # OS .DS_Store ``` ## Optional: Native Addon Build Artifacts If your project compiles C++ native addons, include patterns for compiled binaries and object files. The Node.js core build system generates these artifacts during compilation of the runtime itself. ```gitignore # Compiled binary addons *.node *.a *.so *.o *.obj *.dll ``` ## Complete Node.js Gitignore Template Combine these patterns into a minimal yet effective `.gitignore` for new projects: ```gitignore # Dependency directories node_modules/ # Environment configuration .env .env.local # Build outputs dist/ build/ out/ # Logs npm-debug.log* yarn-debug.log* yarn-error.log* # Coverage directory used by tools like istanbul coverage/ *.lcov *.tap # IDE and editor files .idea/ .vscode/ *.swp *~ # OS generated files .DS_Store ``` ## Summary - **Always exclude `node_modules/`** to avoid committing reproducible dependencies that bloat the repository. - **Protect sensitive data** by ignoring `.env` files and any configuration containing API keys or database credentials. - **Ignore build outputs** like `dist/` and `build/` since these are generated artifacts, not source code. - **Omit logs and coverage reports** which are temporary files that change with every test run. - **Filter IDE and OS files** to prevent developer-specific metadata from cluttering shared repositories. ## Frequently Asked Questions ### Is `node_modules/` the only required entry for a Node.js gitignore? No. While `node_modules/` is essential, a production-ready `.gitignore` must also exclude environment files (`.env`), build directories, log files, and IDE configurations. According to the `nodejs/node` source, ignoring only dependencies leaves your repository vulnerable to committing sensitive credentials and temporary build artifacts. ### Why doesn't the official Node.js repository include `.env` in its gitignore? The Node.js core project does not use `.env` files for configuration; instead, it relies on Python build scripts and command-line arguments during compilation. However, application developers following the 12-Factor App methodology should always add `.env` to their ignore list, as the Node.js ecosystem conventionally uses these files for local environment variables. ### Should I ignore [`package-lock.json`](https://github.com/nodejs/node/blob/main/package-lock.json) or `yarn.lock` in my gitignore? No, you should commit lockfiles to version control. The `nodejs/node` `.gitignore` excludes `node_modules/` but preserves lockfiles because they ensure reproducible installations across development and production environments. Only the dependency folder itself should be ignored. ### How do I handle native addon artifacts in my Node.js gitignore? If your project compiles C++ native addons using `node-gyp`, include patterns for binary artifacts: `*.node`, `*.a`, `*.so`, `*.o`, and `*.obj`. As implemented in the core Node.js build system, these patterns prevent compiled extensions from being committed while preserving the C++ source files (`.cc`, `.cpp`, `.h`) that generate them.