TypeScript configuration for Next.js applications with App Router and Pages Router support
npm install @jmlweb/tsconfig-nextjs
> TypeScript configuration for Next.js applications. Extends @jmlweb/tsconfig-react with Next.js-specific optimizations, incremental builds, and path aliases.
- 🔒 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
``bash`
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.
Create a tsconfig.json file in your Next.js project root:
`json`
{
"extends": "@jmlweb/tsconfig-nextjs",
"include": ["next-env.d.ts", "/.ts", "/.tsx", ".next/types/*/.ts"],
"exclude": ["node_modules"]
}
`json`
{
"extends": "@jmlweb/tsconfig-nextjs",
"include": ["next-env.d.ts", "/.ts", "/.tsx", ".next/types/*/.ts"],
"exclude": ["node_modules"]
}
`json`
{
"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"]
}
`json`
{
"extends": "@jmlweb/tsconfig-nextjs",
"include": ["next-env.d.ts", "/.ts", "/.tsx"],
"exclude": ["node_modules"]
}
`json`
{
"extends": "@jmlweb/tsconfig-nextjs",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/": ["./src/"]
},
"noEmit": true
},
"include": ["next-env.d.ts", "/.ts", "/.tsx", ".next/types/*/.ts"],
"exclude": ["node_modules"]
}
> 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.
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
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
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 compilation:
- ✅ Faster subsequent builds
- ✅ Only recompiles changed files
- ✅ Stores build information in .tsbuildinfo file
- ✅ Recommended by Next.js for better performance
Default path alias configuration:
`typescript
// 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:
`json`
{
"compilerOptions": {
"paths": {
"@/": ["./src/"]
}
}
}
Note: Make sure to also configure the same alias in your next.config.js:
`javascript`
// 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:
`javascript`
// next.config.js
module.exports = {
// Next.js 13+ automatically resolves tsconfig paths
};
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.
You can extend or override the configuration for your specific needs:
`json`
{
"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"]
}
If you need to disable the Next.js plugin:
`json`
{
"extends": "@jmlweb/tsconfig-nextjs",
"compilerOptions": {
"plugins": []
}
}
Override the default path alias:
`json`
{
"extends": "@jmlweb/tsconfig-nextjs",
"compilerOptions": {
"baseUrl": ".",
"paths": {
"~/": ["./src/"]
}
}
}
Next.js handles TypeScript compilation automatically. You typically don't need to run tsc manually, but you can add type checking scripts:
`json`
{
"scripts": {
"dev": "next dev",
"build": "next build",
"typecheck": "tsc --noEmit"
}
}
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
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.
- 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)
This package requires the following peer dependencies:
- typescript (>= 5.0.0)next
- (>= 13.0.0)@jmlweb/tsconfig-react
- (^1.0.0)
- @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
- 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
> 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.
See CHANGELOG.md for version history and release notes.
MIT