How to Fix: Docs state that `next.config.ts` is supported for both pages and app dir docs but `next dev` errors

Encountering a next dev error when trying to use a next.config.ts file, despite the Next.js documentation stating its support, is a frustrating yet common hurdle. This issue typically signals a subtle misconfiguration in your project’s TypeScript setup rather than a fundamental lack of support from Next.js itself. Let’s dive into resolving it efficiently.

Understanding the Root Cause

Next.js is designed to natively support next.config.ts, allowing developers to leverage TypeScript for their build configuration. The typical error you encounter when running next dev, even with a seemingly correct .ts config file, usually stems from how Next.js internally transpiles and loads this file.

Unlike your application code, which is handled by webpack and Babel/SWC based on your main tsconfig.json, the next.config.ts file is processed before the main build process even begins. Next.js uses its own internal TypeScript setup to transpile this configuration file. If your project’s tsconfig.json is not aligned with Next.js’s internal expectations for this specific file, or if essential TypeScript dependencies are missing, the transpilation step fails, leading to the dreaded error.

Key areas of potential mismatch include:

• Missing TypeScript Dependencies: While create-next-app usually installs them, sometimes typescript itself or @types/node might be missing or outdated, preventing Next.js from finding the necessary transpilation tools.
• tsconfig.json compilerOptions Mismatch: Specifically, settings like moduleResolution and module. Next.js often expects a modern module resolution strategy (e.g., "bundler", "node16", or "nodenext") and ES module output (e.g., "esnext") for internal config files, even if your app’s main code uses CommonJS or older module systems. An incompatible setting can prevent the config file from being parsed correctly.
• Export Syntax: Although less common with modern Next.js, an incorrect export (e.g., module.exports = {} instead of export default {}) in a TypeScript file can cause issues.

The reproduction example likely highlights one of these core configuration discrepancies, preventing Next.js from understanding the TypeScript configuration before it even starts compiling your application.

Step-by-Step Solution

Follow these steps to ensure your next.config.ts is correctly recognized and processed by Next.js.

1. Ensure Core TypeScript Dependencies are Installed

Even if you started with create-next-app, it’s good practice to verify these are present as devDependencies.

npm install --save-dev typescript @types/node
# OR
yarn add --dev typescript @types/node
pnpm add --save-dev typescript @types/node

2. Verify and Adjust Your tsconfig.json

The most common fix involves ensuring your tsconfig.json has appropriate compilerOptions for Next.js’s internal loader. Pay close attention to module and moduleResolution.

Open your tsconfig.json and ensure it contains (or adjust if conflicting) the following options within the "compilerOptions" block. The exact values might vary based on your Next.js version and Node.js environment, but these are generally robust:

// tsconfig.json
{
  "compilerOptions": {
    // ... other options ...
    "target": "es5", // Or "es2017", "es2020" etc.
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "incremental": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "module": "esnext", // Crucial for ESM compatibility
    "moduleResolution": "bundler", // Or "node16", "nodenext", "node"
    "resolveJsonModule": true,
    "baseUrl": ".",
    "paths": { /* ... */ }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
  "exclude": ["node_modules"]
}

Recommendation: For most modern Next.js projects, especially with Node.js 16+, "module": "esnext" and "moduleResolution": "bundler" (or "node16"/"nodenext") are good starting points. If you’re encountering issues, experiment with "node" for moduleResolution as a fallback.

3. Convert next.config.js to next.config.ts

Rename your next.config.js file to next.config.ts and ensure its content uses TypeScript syntax, typically an ES module default export.

Example next.config.ts:

// next.config.ts
import { type NextConfig } from 'next';

const nextConfig: NextConfig = {
  reactStrictMode: true,
  // Add any other Next.js specific configurations here
  // For example, if you're using `app` directory with `output: 'export'`
  // output: 'export', 
  // images: { unoptimized: true } // If output export is used
};

export default nextConfig;

Using import { type NextConfig } from 'next'; provides excellent type checking for your configuration, preventing many common errors.

4. Clean and Restart the Development Server

Sometimes, old build artifacts can interfere. It’s best to clear them out before restarting.

rm -rf .next
npm run dev
# OR
yarn dev
pnpm dev

Your next.config.ts should now be processed correctly, and next dev should start without errors.

Common Edge Cases

• Incorrect Export Syntax: Always use export default for next.config.ts. Using module.exports is for CommonJS files (.js, .cjs).
• Missing next-env.d.ts: This file is typically generated by Next.js and crucial for environment type definitions. Ensure it’s present and included in your tsconfig.json.
• TypeScript Version Incompatibility: Very rarely, an outdated or bleeding-edge TypeScript version might conflict with Next.js’s internal transpiler. Ensure you’re on a stable, relatively recent version that Next.js supports.
• Complex Configuration Logic: If your next.config.ts includes complex logic, imports from other files, or relies on specific environment variables, ensure all paths are correct and types are handled appropriately. Avoid side effects directly in the configuration file; if necessary, encapsulate them in utility functions.
• Monorepo Setup: In monorepos, tsconfig.json inheritance or root-level configurations can sometimes override project-specific settings, leading to unexpected behavior. Double-check that the Next.js app’s tsconfig.json is correctly configured and not being inadvertently overridden.

FAQ

Q1: Why does Next.js support .ts config but it still errors for me?

A: The core issue isn’t a lack of support, but often a mismatch in how Next.js’s internal transpiler expects the next.config.ts file to be configured via your project’s tsconfig.json. Specifically, moduleResolution and module compiler options are frequent culprits. Ensure these are set to values compatible with modern Next.js/Node.js environments.

Q2: Do I need to install ts-node or tsx to use next.config.ts?

A: No, you do not. Next.js has built-in support for transpiling next.config.ts and handles it internally. You only need typescript and @types/node as dev dependencies. Tools like ts-node or tsx are useful for running other TypeScript files (like custom scripts or server files) directly with Node.js, but not for Next.js config.

Q3: What if my next.config.ts needs to conditionally load different configurations based on environment?

A: You can certainly add conditional logic. For instance, you might use process.env.NODE_ENV. However, ensure all imported modules and types are correctly resolved and present. For example:

// next.config.ts
import { type NextConfig } from 'next';

const isProduction = process.env.NODE_ENV === 'production';

const nextConfig: NextConfig = {
  reactStrictMode: true,
  // Conditional configuration
  ...(isProduction && {
    output: 'export', // Example: Only export for production builds
    images: { unoptimized: true },
  }),
};

export default nextConfig;

Ensure any dynamic imports or logic are compatible with the Node.js environment where next.config.ts is executed.