tsconfig.json for Next.js

Overview

A TypeScript configuration tailored for Next.js projects using the App Router. Includes settings for React server components, JSX transform, path aliases, and Next.js-specific type plugins. Based on the default Next.js tsconfig with additional strict safety checks.

Configuration

// tsconfig.json
{
  "compilerOptions": {
    // ── Language & Environment ──
    "target": "ES2017",               // Next.js targets this for broad browser support
    "lib": ["DOM", "DOM.Iterable", "ES2023"],  // Browser + modern JS types
    "jsx": "preserve",                // Let Next.js handle JSX transformation
    "module": "ESNext",               // ESM modules for tree shaking
    "moduleResolution": "Bundler",    // Resolve like a bundler (Next.js/Webpack/Turbopack)

    // ── Strict Type Checking ──
    "strict": true,                   // Enable all strict checks
    "noUncheckedIndexedAccess": true, // Index access returns T | undefined
    "noImplicitReturns": true,        // All code paths must return
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,

    // ── Module & Import ──
    "esModuleInterop": true,          // CJS/ESM interop
    "isolatedModules": true,          // Required for Next.js (SWC transpilation)
    "resolveJsonModule": true,        // Allow JSON imports
    "allowJs": true,                  // Allow .js files alongside .ts

    // ── Path Aliases ──
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],             // @/components/Button
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/hooks/*": ["./src/hooks/*"],
      "@/types/*": ["./src/types/*"],
      "@/styles/*": ["./src/styles/*"]
    },

    // ── Output ──
    "noEmit": true,                   // Next.js handles compilation, no tsc output
    "declaration": false,             // Not needed — Next.js bundles everything
    "sourceMap": true,

    // ── Performance ──
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo",
    "skipLibCheck": true,             // Skip node_modules type checking

    // ── Next.js Plugin ──
    "plugins": [
      { "name": "next" }             // Enables Next.js-specific type checking
    ]
  },

  "include": [
    "next-env.d.ts",                  // Next.js type declarations
    "**/*.ts",
    "**/*.tsx",
    "**/*.mts",
    ".next/types/**/*.ts"             // Auto-generated route types
  ],

  "exclude": [
    "node_modules",
    ".next",                          // Build output
    "out"                             // Static export output
  ]
}

// Additional: next-env.d.ts (auto-generated by Next.js, do not edit)
/// <reference types="next" />
/// <reference types="next/image-types/global" />
/// <reference types="next/navigation-types/compat/navigation" />

Key Options Explained

• jsx: "preserve" — Keeps JSX syntax as-is in the output. Next.js uses SWC (not tsc) to transform JSX, so TypeScript should not transform it.
• moduleResolution: "Bundler" — Resolves imports the way modern bundlers do: supports exports fields in package.json, conditional imports, and extensionless imports.
• noEmit: true — TypeScript only performs type checking. Next.js handles all compilation and bundling through SWC/Turbopack.
• isolatedModules: true — Required because SWC transpiles each file independently without cross-file type information. Catches patterns that would break under this model.
• plugins: [{ "name": "next" }] — Enables Next.js-specific validation in your editor, like checking that server component exports are valid.
• .next/types/**/*.ts — Next.js generates type definitions for route parameters, metadata, and page props based on your file system routes.
• allowJs: true — Permits gradual migration from JavaScript. Remove once all files are TypeScript.

Common Modifications

• Pages Router: Remove the next plugin and .next/types include if using the older Pages Router exclusively.
• Absolute imports without src/: Change paths to "@/*": ["./*"] if your app directory is at the project root.
• Monorepo: Add "references": [{ "path": "../packages/shared" }] for shared packages with project references.
• Stricter checks: Add "exactOptionalPropertyTypes": true and "noPropertyAccessFromIndexSignature": true for maximum type safety.
• CSS modules: Types are auto-generated by Next.js. For custom handling, add declare module '*.module.css' in a global .d.ts file.