TypeScript

Next.js 內建 TypeScript，當您使用 create-next-app 建立新專案時，會自動安裝必要的套件並設定適當的設定。

若要將 TypeScript 新增至現有專案，請將檔案重新命名為 .ts / .tsx。執行 next dev 和 next build 以自動安裝必要的相依性，並新增包含建議設定選項的 tsconfig.json 檔案。

小提示：如果您已經有 jsconfig.json 檔案，請將舊 jsconfig.json 中的 paths 編譯器選項複製到新的 tsconfig.json 檔案中，並刪除舊的 jsconfig.json 檔案。

IDE 外掛程式

Next.js 包含自訂 TypeScript 外掛程式和類型檢查器，VSCode 和其他程式碼編輯器可以使用它們進行進階類型檢查和自動完成。

您可以在 VS Code 中啟用此外掛程式，方法是

1. 開啟命令面板 (Ctrl/⌘ + Shift + P)
2. 搜尋 "TypeScript: Select TypeScript Version" (TypeScript：選取 TypeScript 版本)
3. 選取 "Use Workspace Version" (使用工作區版本)

現在，編輯檔案時，將會啟用自訂外掛程式。執行 next build 時，將會使用自訂類型檢查器。

TypeScript 外掛程式可以協助處理：

• 當傳遞 區段設定選項 的無效值時發出警告。
• 顯示可用選項和上下文文件。
• 確保 use client 指示詞使用正確。
• 確保用戶端 Hook (例如 useState) 僅在用戶端元件中使用。

🎥 觀看： 了解內建的 TypeScript 外掛程式 → YouTube (3 分鐘)

端對端類型安全

Next.js App Router 具有增強的類型安全。這包括：

1. 在抓取函式和頁面之間不需序列化資料：您可以直接在伺服器上的元件、版面配置和頁面中 fetch。此資料不需要序列化 (轉換為字串) 才能傳遞到用戶端，以在 React 中使用。相反地，由於 app 預設使用伺服器元件，因此我們可以使用 Date、Map、Set 等值，而無需任何額外步驟。先前，您需要使用 Next.js 特定的類型手動為伺服器和用戶端之間的界線設定類型。
2. 簡化元件之間的資料流：隨著移除 _app 而改用根版面配置，現在更容易視覺化元件和頁面之間的資料流。先前，在個別 pages 和 _app 之間流動的資料難以設定類型，並且可能會引入令人困惑的錯誤。透過 App Router 中的共置資料抓取，這不再是問題。

Next.js 中的資料抓取現在提供盡可能接近端對端類型安全性的功能，而不會對您的資料庫或內容提供者選擇過於規範。

我們可以像預期的一樣使用一般 TypeScript 為回應資料設定類型。例如：

async function getData() {
  const res = await fetch('https://api.example.com/...')
  // The return value is *not* serialized
  // You can return Date, Map, Set, etc.
  return res.json()
}
 
export default async function Page() {
  const name = await getData()
 
  return '...'
}

為了完整的端對端類型安全，這也需要您的資料庫或內容提供者支援 TypeScript。這可以透過使用 ORM 或類型安全查詢建構器來達成。

範例

類型檢查 next.config.ts

您可以使用 TypeScript 並在 Next.js 設定中匯入類型，方法是使用 next.config.ts。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  /* config options here */
}
 
export default nextConfig

小提示：next.config.ts 中的模組解析目前僅限於 CommonJS。這可能會導致與 next.config.ts 中載入的 ESM 僅限套件不相容。

當使用 next.config.js 檔案時，您可以使用 JSDoc 在 IDE 中新增一些類型檢查，如下所示：

// @ts-check
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* config options here */
}
 
module.exports = nextConfig

靜態類型連結

Next.js 可以靜態設定連結類型，以防止在使用 next/link 時發生錯字和其他錯誤，從而在頁面之間導航時提高類型安全。

若要選擇加入此功能，需要啟用 experimental.typedRoutes，且專案需要使用 TypeScript。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    typedRoutes: true,
  },
}
 
export default nextConfig

Next.js 將在 .next/types 中產生連結定義，其中包含有關應用程式中所有現有路由的資訊，然後 TypeScript 可以使用這些資訊在您的編輯器中提供有關無效連結的回饋。

目前，實驗性支援包括任何字串文字，包括動態區段。對於非文字字串，您目前需要使用 as Route 手動轉換 href。

import type { Route } from 'next';
import Link from 'next/link'
 
// No TypeScript errors if href is a valid route
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />
 
// TypeScript errors if href is not a valid route
<Link href="/aboot" />

若要接受包裝 next/link 的自訂元件中的 href，請使用泛型：

import type { Route } from 'next'
import Link from 'next/link'
 
function Card<T extends string>({ href }: { href: Route<T> | URL }) {
  return (
    <Link href={href}>
      <div>My Card</div>
    </Link>
  )
}

它是如何運作的？

當執行 next dev 或 next build 時，Next.js 會在 .next 內產生一個隱藏的 .d.ts 檔案，其中包含有關應用程式中所有現有路由的資訊 (作為 Link 的 href 類型的所有有效路由)。此 .d.ts 檔案包含在 tsconfig.json 中，而 TypeScript 編譯器將檢查 .d.ts 並在您的編輯器中提供有關無效連結的回饋。

使用非同步伺服器元件

若要搭配 TypeScript 使用 async 伺服器元件，請確保您使用的是 TypeScript 5.1.3 或更高版本，以及 @types/react 18.2.8 或更高版本。

如果您使用的是舊版 TypeScript，您可能會看到 'Promise<Element>' is not a valid JSX element 類型錯誤。更新到最新版本的 TypeScript 和 @types/react 應該可以解決此問題。

增量類型檢查

自 v10.2.1 起，Next.js 支援 增量類型檢查，當在您的 tsconfig.json 中啟用時，這有助於加快大型應用程式中的類型檢查速度。

在生產環境中停用 TypeScript 錯誤

當您的專案中存在 TypeScript 錯誤時，Next.js 會使您的生產環境建置 (next build) 失敗。

如果您希望 Next.js 即使在您的應用程式有錯誤時也能危險地產生生產環境程式碼，您可以停用內建的類型檢查步驟。

如果停用，請務必在您的建置或部署過程中執行類型檢查，否則這可能會非常危險。

開啟 next.config.ts 並在 typescript 設定中啟用 ignoreBuildErrors 選項：

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

小提示：您可以在建置之前執行 tsc --noEmit 以自行檢查 TypeScript 錯誤。這對於您希望在部署之前檢查 TypeScript 錯誤的 CI/CD 管道非常有用。

自訂類型宣告

當您需要宣告自訂類型時，您可能會想要修改 next-env.d.ts。但是，此檔案是自動產生的，因此您所做的任何變更都會被覆寫。相反地，您應該建立一個新檔案，我們稱之為 new-types.d.ts，並在您的 tsconfig.json 中參考它：

{
  "compilerOptions": {
    "skipLibCheck": true
    //...truncated...
  },
  "include": [
    "new-types.d.ts",
    "next-env.d.ts",
    ".next/types/**/*.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": ["node_modules"]
}

版本變更