@jmlweb/tsconfig-nextjs

TypeScript configuration for Next.js applications. Extends @jmlweb/tsconfig-react with Next.js-specific optimizations, incremental builds, and path aliases.

✨ Features

• 🔒 Strict Type Checking: Inherits all strict TypeScript rules from base configs
• ⚛️ React Support: Full JSX support with modern React transform
• 🚀 Next.js Optimized: Incremental builds and Next.js TypeScript plugin
• 📁 Path Aliases: Pre-configured @/* path alias for clean imports
• 🎯 App Router Ready: Optimized for Next.js App Router and Pages Router
• 🌐 DOM Types: Includes DOM and DOM.Iterable libs for browser APIs
• 📦 Bundler Resolution: Optimized moduleResolution: "bundler" for Next.js

📦 Installation

pnpm add -D @jmlweb/tsconfig-nextjs typescript next @jmlweb/tsconfig-react @jmlweb/tsconfig-base

💡 Upgrading from a previous version? See the Migration Guide for breaking changes and upgrade instructions.

🚀 Quick Start

Create a tsconfig.json file in your Next.js project root:

{
  "extends": "@jmlweb/tsconfig-nextjs",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

💡 Examples

Basic Next.js Setup (App Router)

{
  "extends": "@jmlweb/tsconfig-nextjs",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Next.js with Custom Path Aliases

{
  "extends": "@jmlweb/tsconfig-nextjs",
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Next.js Pages Router

{
  "extends": "@jmlweb/tsconfig-nextjs",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

Next.js with Additional Compiler Options

{
  "extends": "@jmlweb/tsconfig-nextjs",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    },
    "noEmit": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

🤔 Why Use This?

Philosophy: Next.js projects need TypeScript configured for both server and client code with incremental builds and framework-specific optimizations.

This package provides a TypeScript configuration specifically optimized for Next.js applications. It extends the React configuration while adding Next.js-specific settings like incremental compilation, the Next.js TypeScript plugin, and sensible path aliases that work with Next.js's file-based routing.

Design Decisions

Incremental Compilation (incremental: true): Faster rebuilds for development

• Why: Next.js projects are often large with many files. Incremental compilation dramatically speeds up subsequent builds by only recompiling changed files and their dependents. This makes the development experience much faster
• Trade-off: Creates a .tsbuildinfo file that needs to be gitignored. But the build speed improvement is worth it
• When to override: Never - there's no downside to incremental compilation in Next.js projects

Next.js TypeScript Plugin: Framework-specific type checking

• Why: Next.js has special conventions (Server Components, Route Handlers, Metadata API, etc.) that benefit from enhanced type checking. The plugin provides better autocomplete and catches Next.js-specific errors that generic TypeScript can't detect
• Trade-off: Adds a dependency on Next.js being installed. But if you're using this config, you're already using Next.js
• When to override: Only if the plugin causes issues (rare), but report bugs to Next.js if found

Path Aliases (@/* → project root): Clean imports for Next.js file structure

• Why: Next.js projects have deep file structures (app/components/ui/button/index.tsx). Path aliases like @/components/ui/button are more readable and easier to refactor than ../../../components/ui/button. The @/* convention is standard in Next.js projects
• Trade-off: Need to configure the same alias in next.config.js for runtime (though Next.js 13+ does this automatically from tsconfig.json)
• When to override: If your team prefers a different alias convention (like ~/*), but @/* is the Next.js convention

📋 Configuration Details

What's Included

This configuration extends @jmlweb/tsconfig-react and adds:

• ✅ Incremental Builds: incremental: true for faster compilation
• ✅ Next.js Plugin: TypeScript plugin for Next.js-specific type checking
• ✅ Path Aliases: Default @/* alias pointing to project root
• ✅ All React Config: Inherits JSX support, DOM types, and bundler resolution
• ✅ All Base Config: Inherits strict type checking and best practices

Next.js TypeScript Plugin

The Next.js TypeScript plugin provides:

• ✅ Enhanced type checking for Next.js APIs
• ✅ Better autocomplete for Next.js components
• ✅ Type safety for App Router and Pages Router
• ✅ Support for Next.js-specific features

Incremental Builds

Incremental compilation:

• ✅ Faster subsequent builds
• ✅ Only recompiles changed files
• ✅ Stores build information in .tsbuildinfo file
• ✅ Recommended by Next.js for better performance

Path Aliases

Default path alias configuration:

// Instead of:
import { Button } from '../../../components/Button';

// You can use:
import { Button } from '@/components/Button';

The @/* alias is pre-configured to point to your project root. You can customize it in your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Note: Make sure to also configure the same alias in your next.config.js:

// next.config.js
module.exports = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@': path.resolve(__dirname, './src'),
    };
    return config;
  },
};

Or use the built-in Next.js path mapping:

// next.config.js
module.exports = {
  // Next.js 13+ automatically resolves tsconfig paths
};

🎯 When to Use

Use this configuration when you want:

• ✅ Next.js application development (App Router or Pages Router)
• ✅ Strict type checking for Next.js code
• ✅ Incremental builds for faster development
• ✅ Next.js TypeScript plugin support
• ✅ Path aliases for cleaner imports
• ✅ Modern React JSX transform
• ✅ DOM API type support

For React projects without Next.js, use @jmlweb/tsconfig-react instead.

For non-React TypeScript projects, use @jmlweb/tsconfig-base instead.

🔧 Extending the Configuration

You can extend or override the configuration for your specific needs:

{
  "extends": "@jmlweb/tsconfig-nextjs",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/types/*": ["./src/types/*"]
    },
    "noEmit": true
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Disabling Next.js Plugin

If you need to disable the Next.js plugin:

{
  "extends": "@jmlweb/tsconfig-nextjs",
  "compilerOptions": {
    "plugins": []
  }
}

Customizing Path Aliases

Override the default path alias:

{
  "extends": "@jmlweb/tsconfig-nextjs",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}

📝 Usage with Scripts

Next.js handles TypeScript compilation automatically. You typically don't need to run tsc manually, but you can add type checking scripts:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "typecheck": "tsc --noEmit"
  }
}

Next.js Type Checking

Next.js includes built-in type checking:

• ✅ Type errors shown during next build
• ✅ Type errors shown in development mode
• ✅ IDE integration with TypeScript language server

VS Code Integration

For the best experience in VS Code:

1. Install the TypeScript extension
2. Open Command Palette (Ctrl/⌘ + Shift + P)
3. Select "TypeScript: Select TypeScript Version"
4. Choose "Use Workspace Version"

This ensures VS Code uses the Next.js TypeScript plugin for enhanced type checking.

📋 Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0
• Next.js >= 13.0.0 (for App Router support)
• React >= 17.0.0 (for JSX runtime support)

📦 Peer Dependencies

This package requires the following peer dependencies:

• typescript (>= 5.0.0)
• next (>= 13.0.0)
• @jmlweb/tsconfig-react (^1.0.0)

🔗 Related Packages

Internal Packages

• @jmlweb/tsconfig-react - TypeScript configuration for React (extended by this package)
• @jmlweb/tsconfig-base - Base TypeScript configuration
• @jmlweb/eslint-config-react - ESLint configuration for React/Next.js projects
• @jmlweb/prettier-config-base - Prettier config for consistent formatting

External Tools

• TypeScript - Strongly typed programming language that builds on JavaScript
• Next.js - The React framework for production
• React - JavaScript library for building user interfaces
• Turbopack - Incremental bundler optimized for JavaScript and TypeScript

🔄 Migration Guide

Upgrading to a New Version

Note: If no breaking changes were introduced in a version, it's safe to upgrade without additional steps.

No breaking changes have been introduced yet. This package follows semantic versioning. When breaking changes are introduced, detailed migration instructions will be provided here.

For version history, see the Changelog.

Need Help? If you encounter issues during migration, please open an issue.

📜 Changelog

See CHANGELOG.md for version history and release notes.

📄 License

MIT