Best .gitignore Setup for React and Next.js Projects: A Complete Guide

The optimal .gitignore configuration for React and Next.js projects combines Node.gitignore for dependency management and Nextjs.gitignore for framework-specific build outputs, preventing commits of node_modules, .next directories, and environment secrets.

When initializing a React or Next.js repository, establishing a robust .gitignore file should be your first priority. Drawing from the official github/gitignore repository, this guide provides a production-ready configuration that handles Node.js dependencies, framework build artifacts, and sensitive environment variables for modern React applications.

Why You Need a Specialized .gitignore for React and Next.js

React-based applications, including Create React App, Vite, and Next.js, run on Node.js and therefore inherit the dependency management challenges of the Node ecosystem. However, each framework generates its own build directories and development artifacts that generic Node ignore patterns fail to catch. A comprehensive setup must exclude both the massive node_modules directory referenced in Node.gitignore and framework-specific outputs like Next.js's .next folder.

Core Components of the Best .gitignore Setup

Node.js Dependencies and Runtime Files

The foundation of any React project ignore list starts with Node.gitignore. According to the source code at lines 40-42, you must exclude node_modules/ to prevent committing dependency trees that can exceed hundreds of megabytes. Additionally, lines 9-10 specify ignoring coverage/ directories generated by test runners like Jest, while lines 73-75 cover tool-specific caches such as .vite/ and .cache/.

Framework-Specific Build Outputs

Next.js projects require additional patterns found in Nextjs.gitignore. Lines 12-14 explicitly ignore the .next/ directory, which contains the server-side rendered build output, and the out/ folder used for static HTML exports. Lines 16-17 add the generic build/ directory used by Create React App and other bundlers. These directories contain compiled assets that are regenerated during each build and should never be versioned.

Environment Variables and Secrets

Security-critical patterns appear in Node.gitignore lines 68-71, which specify .env* to ignore all environment files including .env.local, .env.production, and .env.development. These files often contain API keys, database credentials, and other secrets. The pattern !.env.example preserves a template file for documentation purposes while keeping actual secrets out of the repository.

IDE and Operating System Artifacts

Lines 19-20 of Node.gitignore cover .DS_Store files created by macOS, while common community additions include .vscode/ and .idea/ directories for VS Code and JetBrains IDEs. These are user-specific configuration files that create unnecessary noise in pull requests when committed.

Complete .gitignore Template for React and Next.js

Place this file at the root of your repository to cover React, Next.js, Vite, and Create React App projects:

# ----- Node defaults (from Node.gitignore) -----

# Logs

logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*

# Runtime data

pids
*.pid
*.seed
*.pid.lock

# Dependency directories

node_modules/
jspm_packages/
web_modules/               # Snowpack

.pnp
.pnp.js

# Optional npm/yarn caches

.npm
.yarn-integrity
.pnp.*
.yarn/*

# TypeScript cache

*.tsbuildinfo

# Environment files (never commit secrets)

.env
.env.*
!.env.example

# OS / editor artefacts

.DS_Store
Thumbs.db

# IDE / editor caches

.vscode/
.idea/
*.sublime-workspace
*.sublime-project

# ----- Next.js defaults (from Nextjs.gitignore) -----

# Next.js build output

.next/
out/

# Production build folder (CRA / generic React)

build/
dist/

# Local Vercel / deployment artefacts

.vercel

# Typescript specific

next-env.d.ts

# ----- Common testing & coverage -----

coverage/
.nyc_output/
.vscode-test/

# ----- Misc caches used by modern bundlers -----

.cache/
.parcel-cache/
.vite/
.svelte-kit/

Summary

• Combine Node.gitignore and Nextjs.gitignore to create a comprehensive defense against committing generated files and secrets.
• Always exclude node_modules/ (Node.gitignore lines 40-42) and .next/ (Nextjs.gitignore lines 12-14) to prevent repository bloat.
• Protect secrets by ignoring .env* (Node.gitignore lines 68-71) while keeping !.env.example for documentation.
• Include framework-agnostic patterns for testing (coverage/), IDE files (.vscode/), and OS files (.DS_Store).

Frequently Asked Questions

What is the difference between Node.gitignore and Nextjs.gitignore?

Node.gitignore provides the foundational ignore patterns for any Node.js project, covering node_modules/, log files, and environment variables as seen in lines 40-42 and 68-71. Nextjs.gitignore extends these rules with framework-specific entries like .next/ and out/ (lines 12-14) that handle Next.js's server-side rendering and static export directories. For React applications, you need both files to ensure complete coverage.

Should I commit .env.example to my repository?

Yes, you should commit .env.example while keeping actual .env files ignored. The pattern !.env.example (negation) in your .gitignore ensures this template file is tracked, providing a safe reference for required environment variables without exposing sensitive values. This practice allows new developers to copy the example file and fill in their own secrets locally.

Why does Next.js create a .next folder that needs to be ignored?

The .next/ directory contains the build output generated by Next.js during compilation, including server-side rendered pages, optimized static assets, and webpack bundles. As noted in Nextjs.gitignore lines 12-14, these files are regenerated on every build and can become quite large. Committing this directory would bloat your repository with ephemeral files that are specific to each build environment and deployment.

Can I use the same .gitignore for Create React App and Next.js?

Yes, the merged template provided in this guide works for both Create React App (CRA) and Next.js because it combines patterns from both Node.gitignore and Nextjs.gitignore. CRA typically generates a build/ directory (covered by Nextjs.gitignore lines 16-17), while Next.js uses .next/ (lines 12-14). The unified file also supports modern alternatives like Vite and Remix, making it a versatile standard for any React-based toolchain.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}