TypeScript

版本歷史

版本	更動
v12.0.0	SWC is now used by default to compile TypeScript and TSX for faster builds. 是預設作為為了快速建立而用來編譯 TypeScript 和 TSX 的工具
v10.2.1	增量 type 檢查 支援將會被加入當 tsconfig.json 被啟用

Next.js 提供包含無額外設定以及為了頁面、API 及更多的內建 types 的 TypeScript 整合體驗。

• 複製以及部署 TypeScript 模板
• 查看應用程式例子

支援 create-next-app

你可以使用 create-next-app 以及指令 --ts, --typescript 建立一個 TypeScript 專案，如下面所示：

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

既有的專案

既有的專案，請在根目錄資料夾內建立一個 tsconfig.json 檔案：

touch tsconfig.json

Next.js 除了會自動地以預設值來設定檔案；也可以支援帶有自定義的編譯器選項的 tsconfig.json 檔。

你可以在 next.config.js 檔案內透過設定 typescript.tsconfigPath 屬性，來提供 tsconfig.json 檔一個相對的路徑位置。

版本 v12.0.0，Next.js 為達到快速建置，預設使用 SWC 來編譯 TypeScript 和 TSX。

如果有 .babelrc 檔， Next.js 將會使用 Babel 來處理 TypeScript。但這將會有一些限制和一些編譯器選項處理方式的不同。

接著，執行 next (一般來說是 npm run dev 或 yarn dev)， Next.js 會引導你安裝所需的相關模組直到設定完畢：

npm run dev

# 你將會看到相關指引如下:
#
# 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 的檔案會被建立。這個檔案確保 Next.js types 有被 TypeScript 編譯器接管。它有可能在任何時候被改變，因此千萬不要移除或編輯它，這個檔案不應該被 commit 且需要被版本控制忽略(例如：在你的 gitignore 檔案)。

TypeScript 嚴格模式 預設狀況下是關閉的。當你習慣 TypeScript，我們建議在 tsconfig.json 將它開啟。

與其編輯 next-env.d.ts， 你可以透過建立一個如 additional.d.ts 的檔案來新增額外的 types，並藉由 include 陣列中引用。

預設下，Next.js 會視 type 檢查為 next build 的一個部分。我們建議在開發階段中使用程式碼編輯器做 type 檢查。

如果你不想顯示任何錯誤訊息，可以查看忽略 TypeScript 錯誤訊息 文件。

靜態生成和伺服器端渲染

如果是 getStaticProps 、 getStaticPaths 和 getServerSideProps，你可以分別使用 GetStaticProps 、 GetStaticPaths 和 GetServerSideProps types :

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 路由的內建 type 的例子：

import type { NextApiRequest, NextApiResponse } from 'next'

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

你也可以輸入 response 的資料：

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，你可以使用內建的 type Appprops 並且更換檔案名稱 ./pages/_app.tsx，例如：

import type { AppProps } from 'next/app'

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

Path aliases 和 baseUrl

Next.js 自動支援 tsconfig.json "paths" 和 "baseUrl" 的多種選擇。

你可以點擊 Module Path aliases 文件 來學習更多。

Type 檢查 next.config.js

Next.config.js 若不是 Javascript 檔案的話，將無法被 Babel 或 TypeScript 解析，但你可以使用 JSDoc，加入一些 type 檢查你的 IDE，參考如下：

// @ts-check

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

module.exports = nextConfig

增量 type 檢查

自從 v10.2.1 Next.js 支援 增量 type 檢查 當你啟用 tsconfig.json，這可以幫助你針對大型應用程式加速作 type 檢查。

使用此功能的話，強烈建議至少要版本 v4.3.2 的 TypeScript 來體驗最佳效能。

忽略 TypeScript 錯誤

當 TypeScript 錯誤訊息存在於你的專案中時，Next.js 會在 生產環境建置 (next build) 階段顯示失敗。

如果你仍舊希望 Next.js 在即使有錯誤訊息的狀況下仍然要執行生產環境的建置，你可以取消內建的 type 檢查階段；如果取消，請確保 type 檢查是建置或部署流程的其中一部分。

打開 next.config.js 和啟用在 typescript 設定內的 ignoreBuildErrors 選項：

module.exports = {
  typescript: {
    // !! 警告 !!
    // 即使存在著 type 錯誤，仍舊執行生產環境的建置是非常危險的。
    // !! 警告 !!
    ignoreBuildErrors: true,
  },
}