How to Fix: Error when initializing Next.js project with TypeScript (v14.2.17 and v15)

Next.js 14.2.17 and 15 can fail immediately on a fresh TypeScript startup when the project boots with a configuration mismatch between the expected TypeScript runtime setup and the actual module or dependency state inside the app. In the reproduction case, the failure appears right at npm run dev, which usually points to an initialization problem in the project scaffold rather than an application logic bug.

This guide explains why the error happens, how to fix it reliably in both Next.js v14.2.17 and Next.js v15, and how to avoid the same issue when creating or upgrading TypeScript-based Next.js apps.

Understanding the Root Cause

The core problem is usually caused by a broken alignment between Next.js, React, TypeScript, and the generated project configuration. When Next.js starts a TypeScript project, it expects a valid combination of:

• Compatible package versions for next, react, and react-dom
• A valid tsconfig.json that Next.js can augment automatically
• A supported module resolution strategy for the active Next.js version
• A clean dependency tree without stale lockfile or node_modules conflicts
• Correct ESM/CommonJS behavior across config files and imported code

In fresh initialization scenarios, the bug often surfaces because the app is technically created successfully, but the installed dependency graph or TypeScript settings do not match what the runtime expects. This is especially visible when:

• The project uses a partially upgraded dependency set
• An old lockfile pins incompatible package versions
• The generated TypeScript config includes options that are accepted by TypeScript but not handled cleanly by the current Next.js boot process
• The project mixes App Router, TypeScript, and newer package versions with stale local caches

In short, this is not usually a bug in your page code. It is a project initialization and runtime compatibility issue.

Step-by-Step Solution

The safest fix is to reset the dependency state, align package versions, and let Next.js regenerate any TypeScript defaults it needs.

1. Remove stale install artifacts

rm -rf node_modules .next package-lock.json

If you are using Windows PowerShell:

Remove-Item -Recurse -Force node_modules, .next, package-lock.json

2. Verify package versions in package.json

Make sure your dependencies are aligned. For Next.js 14.2.17, use a compatible React pair. For Next.js 15, use the versions recommended by that release.

"dependencies": {
  "next": "14.2.17",
  "react": "18.2.0",
  "react-dom": "18.2.0"
},
"devDependencies": {
  "typescript": "^5.0.0",
  "@types/node": "^20.0.0",
  "@types/react": "^18.0.0",
  "@types/react-dom": "^18.0.0"
}

If you are targeting Next.js 15, keep the next, react, and react-dom versions explicitly matched to the release you installed.

3. Use a clean, Next-compatible tsconfig.json

Replace your TypeScript config with a minimal known-good version:

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": false,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ]
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Why this matters: moduleResolution, jsx, and the Next TypeScript plugin are common points of failure when the project is initialized with older or incompatible defaults.

4. Reinstall dependencies cleanly

npm install

5. Regenerate Next.js TypeScript support files if needed

If next-env.d.ts is missing or corrupted, recreate it with this content:

/// <reference types="next" />
/// <reference types="next/image-types/global" />

// NOTE: This file should not be edited

6. Start the dev server again

npm run dev

7. If the issue persists, recreate the app shell and move source files back

This confirms whether the bug is in the scaffold or in your project state:

npx create-next-app@latest temp-next-app --typescript
cd temp-next-app
npm run dev

If the new app works, compare these files against the failing project:

• package.json
• tsconfig.json
• next.config.js or next.config.mjs
• next-env.d.ts

8. Check next.config for module format issues

A subtle but common startup error happens when config syntax does not match the project module system.

For CommonJS:

/** @type {import('next').NextConfig} */
const nextConfig = {}

module.exports = nextConfig

For ESM:

const nextConfig = {}

export default nextConfig

Do not mix module.exports with .mjs, and do not use export default inside a plain CommonJS config unless your environment is configured for it.

Common Edge Cases

• Mismatched React versions: Next.js may install, but runtime initialization can fail if react and react-dom do not match the expected pair.
• Old lockfile after upgrade: Upgrading from 14 to 15 without deleting package-lock.json can preserve an invalid dependency tree.
• Invalid next.config format: A bad ESM/CommonJS export pattern can crash startup before your app code even runs.
• Custom tsconfig options: Settings like older moduleResolution values or aggressive path aliases can interfere with clean initialization.
• Corrupted cache: The .next build cache can preserve bad state after version changes.
• Node.js version mismatch: Running a Next.js version on an unsupported Node runtime can produce confusing startup errors that look unrelated to TypeScript.

If you are debugging a team project, also make sure everyone is using the same Node.js major version and package manager behavior.

FAQ

Why does this happen on a fresh project with almost no code?

Because the failure is usually caused by tooling initialization, not business logic. Next.js has to coordinate TypeScript, React, config loading, and dependency resolution before rendering anything.

Should I use moduleResolution “bundler” or “node”?

For modern Next.js TypeScript projects, bundler is typically the safest choice because it aligns better with current framework expectations and generated defaults.

Is deleting node_modules enough to fix it?

Not always. If the root problem is pinned in package-lock.json, a broken tsconfig.json, or an invalid next.config export format, you need to fix those as well before reinstalling.

The most reliable resolution is to treat this as a dependency and configuration consistency issue: clean the install, align package versions, restore a valid TypeScript config, and verify the config module format. That fixes the majority of Next.js initialization errors reported for v14.2.17 and v15.