.gitignore for Next.js Projects

Next.js has a unique build system that generates server-side and client-side bundles, API route handlers, and static assets. A well-configured .gitignore is essential to avoid committing large, machine-specific build caches.

Next.js-specific patterns:

• .next/ — The primary build output directory. This contains compiled pages, webpack chunks, server bundles, and the build manifest. It can easily exceed 500MB in large applications. Every developer regenerates it with npm run dev or npm run build.
• out/ — The static HTML export directory created by next export or the output: 'export' configuration. This is a deployment artifact, not source code.
• .vercel/ — Vercel CLI configuration and project linking metadata. This directory is generated by vercel link and contains project-specific identifiers.
• next-env.d.ts — Auto-generated TypeScript declaration file. While Next.js recreates it automatically, the official recommendation is to commit this file as it ensures TypeScript understands Next.js types.

Environment files:

Next.js loads environment variables from multiple files in a specific order. A recommended ignore pattern is:

• Ignore: .env.local, .env.development.local, .env.production.local
• Commit: .env (non-sensitive defaults), .env.development, .env.production (if they contain only public values)

Caching and performance:

• .swc/ — The SWC compiler cache directory used by Next.js for fast Rust-based compilation.
• *.tsbuildinfo — TypeScript incremental build information file.

Deployment note: When deploying to Vercel, the .next/ directory is built on Vercel's servers. When self-hosting, your CI pipeline should build it. Either way, the build output does not belong in git.

Common mistake: Ignoring public/ — do NOT ignore this directory. It contains static assets (images, fonts, robots.txt) that are part of your source code and must be versioned.