TypeScript

示例

TypeScript

Next.js 提供了集成的 TypeScript 开发体验，并且开箱即用，类似一个 IDE。

对 `create-next-app` 的支持

You can create a TypeScript project with create-next-app using the --ts, --typescript flag like so:

npx create-next-app@latest --ts
# or
yarn create next-app --typescript

Existing projects

To get started in an existing project, create an empty tsconfig.json file in the root folder:

touch tsconfig.json

Next.js 将自动用默认值填充该文件。你还可以在 tsconfig.json 中自定义编译器参数。

You can also provide a relative path to a tsconfig.json file by setting typescript.tsconfigPath prop inside your next.config.js file.

Next.js 使用 Babel 来处理 TypeScript，因此有一些 [需要注意的事项(https://babeljs.io/docs/en/babel-plugin-transform-typescript#caveats) 和一些对编译器参数处理上的不同。

然后，运行 next （通常是 npm run dev 或 yarn dev），Next.js 将引导你完成所需软件包的安装以及设置：

npm run dev

# You'll see instructions like these:
#
# Please install TypeScript, @types/react, and @types/node by running:
#
#         yarn add --dev typescript @types/react @types/node
#
# ...

现在你就可以将文件从 .js 转换为 .tsx 并且充分利用 TypeScript 所带来的好处了！

在项目的根目录下将创建一个名为 next-env.d.ts 的文件。此文件确保 TypeScript 编译器选择 Next.js 的类型信息。由于此文件随时可能会改变，因此 你不能删除或编辑此文件。

默认情况下，TypeScript 的 strict 模式是关闭的。如果你对 TypeScript 觉得适应，建议在 tsconfig.json 中将其开启。

Instead of editing next-env.d.ts, you can include additional types by adding a new file e.g. additional.d.ts and then referencing it in the include array in your tsconfig.json.

默认情况下，Next.js 将在 next build 阶段进行类型检查。我们建议你在开发过程中使用代码编辑器的类型检查功能。

如果要关闭错误报告，请参考文档忽略 TypeScript 报错。

静态生成和服务器端渲染

对于 getStaticProps、getStaticPaths 和 getServerSideProps，你可以分别使用 GetStaticProps、GetStaticPaths 和 GetServerSideProps 类型：

import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'

export const getStaticProps: GetStaticProps = async (context) => {
  // ...
}

export const getStaticPaths: GetStaticPaths = async () => {
  // ...
}

export const getServerSideProps: GetServerSideProps = async (context) => {
  // ...
}

如果你使用的是 getInitialProps，则可以参考此页面上的说明。

API 路由

以下是 API 路由如何使用内置类型的示例：

import type { NextApiRequest, NextApiResponse } from 'next'

export default (req: NextApiRequest, res: NextApiResponse) => {
  res.status(200).json({ name: 'John Doe' })
}

你还可以指定响应数据的类型：

import type { NextApiRequest, NextApiResponse } from 'next'

type Data = {
  name: string
}

export default (req: NextApiRequest, res: NextApiResponse<Data>) => {
  res.status(200).json({ name: 'John Doe' })
}

自定义 `App`

如果你自定义了 App，你可以使用内置类型 AppProps 并将文件名更改为 ./pages/_app.tsx，如下所示：

// import App from "next/app";
import type { AppProps /*, AppContext */ } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

// Only uncomment this method if you have blocking data requirements for
// every single page in your application. This disables the ability to
// perform automatic static optimization, causing every page in your app to
// be server-side rendered.
//
// MyApp.getInitialProps = async (appContext: AppContext) => {
//   // calls page's `getInitialProps` and fills `appProps.pageProps`
//   const appProps = await App.getInitialProps(appContext);

//   return { ...appProps }
// }

export default MyApp

路径别名和 baseUrl

Next.js 自动支持 tsconfig.json 的 "paths" 和 "baseUrl" 参数。

你可以在模块路径别名文档中了解此功能的更多信息。

Type checking next.config.js

The next.config.js file must be a JavaScript file as it does not get parsed by Babel or TypeScript, however 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

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.

It is highly recommended to be on at least v4.3.2 of TypeScript to experience the best performance when leveraging this feature.

ESLint Environment Variables