typescript
Controls whether type errors fail production builds and which tsconfig file is used.
typescript?: {
ignoreBuildErrors?: boolean
tsconfigPath?: string
}Parameters
| Parameter | Type | Description |
|---|---|---|
$ignoreBuildErrorsoptional | boolean= false | Allow production builds to complete even with TypeScript errors. Skips the type-checking step entirely rather than suppressing individual errors. |
$tsconfigPathoptional | string= 'tsconfig.json' | Path to a custom `tsconfig.json` file. Used by `next dev`, `next build` and `next typegen`. |
$experimental.useTypeScriptClioptional | boolean= true | Set to `false` to use the TypeScript JavaScript compiler API instead of the project-local `tsc` CLI. The CLI checker is enabled by default and is what makes TypeScript 6 and 7 usable during builds. |
Errors
With `experimental.useTypeScriptCli` set to `false` while TypeScript 7 is installed, `next build` exits because the TypeScript JavaScript compiler API is unavailable.
Changelog
- PHP v15.0.0`next.config.ts` support added, so this option can be typed with the `NextConfig` type.
- PHP v10.2.1Incremental type checking is honoured when enabled in your tsconfig, which changes how much of the project is re-checked between builds.
Next.js type-checks your project during next build and fails the build when TypeScript reports an error. This option is the pair of escape hatches around that step: turn the check off, or point it at a different project file.
When to reach for it
tsconfigPath is the one you should reach for most. A monorepo build that also validates shared packages, or a CI pipeline you are migrating to stricter settings, can use a relaxed tsconfig.build.json that extends the strict config your editor reads. Your IDE keeps flagging problems while builds keep shipping.
ignoreBuildErrors is the blunt instrument. It does not run TypeScript and swallow the output — it bypasses the check completely. Only set it when type checking genuinely runs elsewhere in your pipeline, for example a tsc --noEmit step earlier in CI.
What trips people up
- Only
tsconfig.jsonis watched in development. Edit a file named bytsconfigPathand you must restart the dev server. - Builds run the project-local
tscCLI by default, so diagnostics are rawtscoutput with no Next.js code frames or route-aware rewriting. - The CLI checks everything your tsconfig
includeselects — test files and.next/dev/typesincluded — which can surface errors the old checker never reported.
Example
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
typescript: {
ignoreBuildErrors: false,
tsconfigPath: 'tsconfig.json',
},
}
export default nextConfigWhen to use it
- Point production builds at a relaxed tsconfig.build.json while the editor keeps strict settings.
- Unblock a deploy when type checking already runs as a separate CI step.
- Adopt TypeScript 7 by leaning on the default tsc CLI checker during builds.
- Loosen useUnknownInCatchVariables for a monorepo build without weakening the app's own config.
Frequently asked questions
How do I make next build ignore TypeScript errors?
Set `typescript.ignoreBuildErrors` to true in next.config.ts. This skips the type-checking step entirely rather than downgrading errors to warnings, so run `tsc --noEmit` elsewhere in your pipeline or nothing types your project at all. It also skips the tsc CLI checker.
Can I use a different tsconfig.json for builds?
Yes — set `typescript.tsconfigPath` to the file, for example 'tsconfig.build.json'. It applies to `next dev`, `next build` and `next typegen`, while IDEs keep reading tsconfig.json for diagnostics. In development only tsconfig.json is watched, so restart the dev server after editing the alternate file.
Why are my build type errors suddenly showing raw tsc output with no Next.js code frames?
Because `next build` runs the project-local tsc CLI by default, and CLI diagnostics are printed straight from tsc without Next.js code frames or route-specific rewriting. It also checks everything your tsconfig include selects, such as test files and .next/dev/types. Set `experimental.useTypeScriptCli` to false to go back to the compiler-API checker.
More examples
A separate tsconfig for production builds
The build reads tsconfig.build.json while development and your editor keep reading tsconfig.json. Pair it with a tsconfig.build.json that extends the strict one and relaxes only what the build needs — for example `{ "extends": "./tsconfig.json", "compilerOptions": { "useUnknownInCatchVariables": false } }`. Because development only watches tsconfig.json, editing the build config requires a dev server restart before the change is picked up.
import type { NextConfig } from 'next'
const isProd = process.env.NODE_ENV === 'production'
const nextConfig: NextConfig = {
typescript: {
tsconfigPath: isProd ? 'tsconfig.build.json' : 'tsconfig.json',
},
}
export default nextConfigBypassing the check, with the check moved into CI
This is the exact wording the docs use, warning banner included, because the setting removes the only type check in the default pipeline. Nothing types your code after this unless you add it back — run `tsc --noEmit` as its own CI job before the build step so a type error still stops a bad deploy.
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
typescript: {
// !! WARN !!
// Dangerously allow production builds to successfully complete even if
// your project has type errors.
// !! WARN !!
ignoreBuildErrors: true,
},
}
export default nextConfigOpting out of the tsc CLI checker
Restores the TypeScript JavaScript compiler API path, which gives you Next.js-specific code frames and route-aware error rewriting instead of raw tsc diagnostics. Note the option lives under `experimental`, not under `typescript`, and that it is experimental. On a project running TypeScript 7 this setting makes `next build` exit outright, because TypeScript 7 does not expose the JavaScript compiler API.
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
useTypeScriptCli: false,
},
}
export default nextConfig
Discussion