TypeScript
Next.js comes with built-in TypeScript, automatically installing the necessary packages and configuring the proper settings when you create a new project with create-next-app
.
To add TypeScript to an existing project, rename a file to .ts
/ .tsx
. Run next dev
and next build
to automatically install the necessary dependencies and add a tsconfig.json
file with the recommended config options.
Good to know: If you already have a
jsconfig.json
file, copy thepaths
compiler option from the oldjsconfig.json
into the newtsconfig.json
file, and delete the oldjsconfig.json
file.
## Examples
Type checking next.config.ts
You can use TypeScript and import types in your Next.js configuration by using next.config.ts
.
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
/* config options here */
}
export default nextConfig
Good to know: Module resolution in
next.config.ts
is currently limited toCommonJS
. This may cause incompatibilities with ESM only packages being loaded innext.config.ts
.
When using the next.config.js
file, you can add some type checking in your IDE using JSDoc as below:
// @ts-check
/** @type {import('next').NextConfig} */
const nextConfig = {
/* config options here */
}
module.exports = nextConfig
Static Generation and Server-side Rendering
For getStaticProps
, getStaticPaths
, and getServerSideProps
, you can use the GetStaticProps
, GetStaticPaths
, and GetServerSideProps
types respectively:
import type { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'
export const getStaticProps = (async (context) => {
// ...
}) satisfies GetStaticProps
export const getStaticPaths = (async () => {
// ...
}) satisfies GetStaticPaths
export const getServerSideProps = (async (context) => {
// ...
}) satisfies GetServerSideProps
Good to know:
satisfies
was added to TypeScript in 4.9. We recommend upgrading to the latest version of TypeScript.
With API Routes
The following is an example of how to use the built-in types for API routes:
import type { NextApiRequest, NextApiResponse } from 'next'
export default function handler(req: NextApiRequest, res: NextApiResponse) {
res.status(200).json({ name: 'John Doe' })
}
You can also type the response data:
import type { NextApiRequest, NextApiResponse } from 'next'
type Data = {
name: string
}
export default function handler(
req: NextApiRequest,
res: NextApiResponse<Data>
) {
res.status(200).json({ name: 'John Doe' })
}
With custom App
If you have a custom App
, you can use the built-in type AppProps
and change file name to ./pages/_app.tsx
like so:
import type { AppProps } from 'next/app'
export default function MyApp({ Component, pageProps }: AppProps) {
return <Component {...pageProps} />
}
Incremental type checking
Since v10.2.1
Next.js supports incremental type checking when enabled in your tsconfig.json
, this can help speed up type checking in larger applications.
Disabling TypeScript errors in production
Next.js fails your production build (next build
) when TypeScript errors are present in your project.
If you'd like Next.js to dangerously produce production code even when your application has errors, you can disable the built-in type checking step.
If disabled, be sure you are running type checks as part of your build or deploy process, otherwise this can be very dangerous.
Open next.config.ts
and enable the ignoreBuildErrors
option in the typescript
config:
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 nextConfig
Good to know: You can run
tsc --noEmit
to check for TypeScript errors yourself before building. This is useful for CI/CD pipelines where you'd like to check for TypeScript errors before deploying.
Custom type declarations
When you need to declare custom types, you might be tempted to modify next-env.d.ts
. However, this file is automatically generated, so any changes you make will be overwritten. Instead, you should create a new file, let's call it new-types.d.ts
, and reference it in your tsconfig.json
:
{
"compilerOptions": {
"skipLibCheck": true
//...truncated...
},
"include": [
"new-types.d.ts",
"next-env.d.ts",
".next/types/**/*.ts",
"**/*.ts",
"**/*.tsx"
],
"exclude": ["node_modules"]
}
Version Changes
Version | Changes |
---|---|
v15.0.0 | next.config.ts support added for TypeScript projects. |
v13.2.0 | Statically typed links are available in beta. |
v12.0.0 | SWC is now used by default to compile TypeScript and TSX for faster builds. |
v10.2.1 | Incremental type checking support added when enabled in your tsconfig.json . |
Was this helpful?