TypeScript

Next.js는 React 애플리케이션을 구축하기 위한 TypeScript 우선 개발 환경을 제공합니다.

필요한 패키지를 자동으로 설치하고 적절한 설정을 구성하는 내장 TypeScript 지원을 제공합니다.

New Projects

create-next-app은 이제 기본적으로 TypeScript를 포함합니다.

npx create-next-app@latest

Existing Projects

.ts / .tsx 파일로 이름을 변경하여 프로젝트에 TypeScript를 추가하세요. next dev 및 next build를 실행하면 필요한 종속성을 자동으로 설치하고 권장 설정 옵션이 포함된 tsconfig.json 파일을 추가합니다.

이미 jsconfig.json 파일이 있는 경우, 이전 jsconfig.json에서 paths 컴파일러 옵션을 새 tsconfig.json 파일로 복사하고 이전 jsconfig.json 파일을 삭제하세요.

또한, 더 나은 타입 추론을 위해 next.config.js보다 next.config.ts를 사용하는 것을 권장합니다.

Minimum TypeScript Version

import 이름에 타입 수정자 (opens in a new tab) 및 성능 개선 (opens in a new tab)과 같은 구문 기능을 얻으려면 최소 v4.5.2 이상의 TypeScript를 사용하는 것이 좋습니다.

Type checking in Next.js Configuration

Type checking next.config.js

next.config.js 파일을 사용할 때, JSDoc을 사용하여 IDE에서 일부 타입 체크를 추가할 수 있습니다:

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

Type checking next.config.ts

next.config.ts 파일을 사용하여 Next.js 구성에서 TypeScript와 타입을 가져올 수 있습니다.

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

참고: 추가 구성 없이 next.config.ts에서 Native ESM 모듈을 가져올 수 있습니다. .cjs, .cts, .mjs, .mts와 같은 확장자를 가져오는 것을 지원합니다.

Static Generation and Server-side Rendering

getStaticProps, getStaticPaths 및 getServerSideProps에 대해 각각 GetStaticProps, GetStaticPaths, GetServerSideProps 타입을 사용할 수 있습니다:

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

참고: satisfies는 TypeScript 4.9 (opens in a new tab)에 추가되었습니다. 최신 버전의 TypeScript로 업그레이드하는 것을 권장합니다.

API Routes

다음은 API 라우트에 내장된 타입을 사용하는 예입니다:

import type { NextApiRequest, NextApiResponse } from 'next'
 
export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ name: 'John Doe' })
}

응답 데이터를 타입 지정할 수도 있습니다:

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' })
}

Custom App

custom App가 있는 경우, 내장 타입 AppProps를 사용하고 파일 이름을 ./pages/_app.tsx로 변경하세요:

import type { AppProps } from "next/app";
 
export default function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

Path aliases and baseUrl

Next.js는 tsconfig.json의 "paths" 및 "baseUrl" 옵션을 자동으로 지원합니다.

이 기능에 대해 더 알아보려면 Module Path aliases documentation를 참조하세요.

Incremental type checking

v10.2.1 이후 Next.js는 tsconfig.json에서 incremental type checking (opens in a new tab)이 활성화된 경우 이를 지원하여 대규모 애플리케이션에서 타입 체크 속도를 높일 수 있습니다.

Ignoring TypeScript Errors

Next.js는 프로젝트에 TypeScript 오류가 있는 경우 production build (next build)를 실패합니다.

애플리케이션에 오류가 있는 경우에도 Next.js가 위험하게 프로덕션 코드를 생성하도록 하려면, 내장된 타입 체크 단계를 비활성화할 수 있습니다.

비활성화된 경우, 빌드 또는 배포 프로세스의 일부로 타입 체크를 실행하고 있는지 확인하세요. 그렇지 않으면 매우 위험할 수 있습니다.

next.config.ts를 열고 typescript 구성에서 ignoreBuildErrors 옵션을 활성화하세요:

export default {
  typescript: {
    // !! 경고 !!
    // 프로젝트에 타입 오류가 있어도 프로덕션 빌드를 성공적으로 완료하도록 허용
    // !! 경고 !!
    ignoreBuildErrors: true,
  },
}

Custom Type Declarations

커스텀 타입을 선언해야 할 때, next-env.d.ts를 수정하고 싶을 수 있습니다. 그러나 이 파일은 자동으로 생성되므로 변경 사항이 덮어쓰여질 것입니다. 대신 새 파일을 생성하고 new-types.d.ts라고 이름을 짓고 이를 tsconfig.json에 참조하세요:

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

Version Changes