TypeScript

Next.js는 React 애플리케이션을 구축하기 위한 TypeScript 우선적으로 사용하는 개발 경험을 제공합니다. 필요한 패키지를 자동으로 설치하고 적절한 설정을 구성하는 내장 TypeScript 지원이 함께 제공됩니다.

또한 에디터를 위한 TypeScript 플러그인도 제공됩니다.

🎥 시청하기: 내장 TypeScript 플러그인에 대해 알아보기 → YouTube (3분)

새 프로젝트

create-next-app은 이제 기본적으로 TypeScript와 함께 제공됩니다.

npx create-next-app@latest

기존 프로젝트

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

이미 jsconfig.json 파일이 있었다면, 이전 jsconfig.json의 paths 컴파일러 옵션을 새 tsconfig.json 파일로 복사하고 이전 jsconfig.json 파일을 삭제하세요.

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

TypeScript 플러그인

Next.js는 VSCode 및 다른 코드 에디터에서 사용할 수 있는 고급 타입 체크와 자동 완성을 위한 사용자 정의 TypeScript 플러그인과 타입 체커를 포함하고 있습니다.

VS Code에서 플러그인을 활성화하는 방법:

1. 명령 팔레트 열기 (Ctrl/⌘ + Shift + P)
2. "TypeScript: Select TypeScript Version" 검색
3. "Use Workspace Version" 선택

이제 파일을 편집할 때 사용자 정의 플러그인이 활성화됩니다. next build를 실행할 때는 사용자 정의 타입 체커가 사용됩니다.

플러그인 기능

TypeScript 플러그인은 다음과 같은 도움을 제공할 수 있습니다:

• 세그먼트 구성 옵션에 잘못된 값이 전달될 경우 경고합니다.
• 사용 가능한 옵션과 상황에 맞는 문서를 보여줍니다.
• use client 지시문이 올바르게 사용되는지 확인합니다.
• 클라이언트 훅(예: useState)이 클라이언트 컴포넌트에서만 사용되는지 확인합니다.

알아두면 좋은 점: 향후 더 많은 기능이 추가될 예정입니다.

최소 TypeScript 버전

import 이름에 대한 타입 수정자와 성능 개선과 같은 구문 기능을 얻으려면 최소한 TypeScript v4.5.2 버전을 사용하는 것이 강력히 권장됩니다.

Next.js 구성에서의 타입 체크

next.config.js 타입 체크

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

// @ts-check
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 여기에 구성 옵션 */
};
 
module.exports = nextConfig;

next.config.ts 타입 체크

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

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  /* 여기에 구성 옵션 */
};
 
export default nextConfig;

알아두면 좋은 점: next.config.ts에서 추가 구성 없이 Native ESM 모듈을 가져올 수 있습니다. .cjs, .cts, .mjs, .mts와 같은 확장자 가져오기를 지원합니다.

정적으로 타입이 지정된 링크

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는 이를 사용하여 에디터에서 잘못된 링크에 대한 피드백을 제공할 수 있습니다.

현재 실험적 지원에는 동적 세그먼트를 포함한 모든 문자열 리터럴이 포함됩니다. 리터럴이 아닌 문자열의 경우 현재 href를 as Route로 수동 캐스팅해야 합니다:

import type { Route } from 'next';
import Link from 'next/link'
 
// href가 유효한 경로인 경우 TypeScript 오류 없음
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />
 
// href가 유효한 경로가 아닌 경우 TypeScript 오류
<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 내부에 애플리케이션의 모든 기존 경로에 대한 정보(모든 유효한 경로를 Link의 href 타입으로)가 포함된 숨겨진 .d.ts 파일을 생성합니다. 이 .d.ts 파일은 tsconfig.json에 포함되어 있으며 TypeScript 컴파일러가 해당 .d.ts를 확인하고 에디터에서 잘못된 링크에 대한 피드백을 제공합니다.

End-to-End 타입 안전성

Next.js App Router는 향상된 타입 안전성을 제공합니다. 이는 다음을 포함합니다:

1. Fetch 함수와 페이지 간 데이터 직렬화 없음: 서버에서 컴포넌트, 레이아웃 및 페이지에서 직접 fetch할 수 있습니다. 이 데이터는 클라이언트 측에서 사용하기 위해 직렬화(문자열로 변환)될 필요가 없습니다. 대신, app은 기본적으로 서버 컴포넌트를 사용하므로 추가 단계 없이 Date, Map, Set 등의 값을 사용할 수 있습니다. 이전에는 Next.js 특정 타입으로 서버와 클라이언트 사이의 경계를 수동으로 타입 지정해야 했습니다.
2. 컴포넌트 간 간소화된 데이터 흐름: 루트 레이아웃을 위해 _app을 제거함으로써 컴포넌트와 페이지 간의 데이터 흐름을 더 쉽게 시각화할 수 있게 되었습니다. 이전에는 개별 pages와 _app 사이의 데이터 흐름을 타입 지정하기 어려웠고 혼란스러운 버그를 초래할 수 있었습니다. App Router에서 공동 위치 데이터 페칭을 통해 이 문제가 더 이상 발생하지 않습니다.

Next.js에서의 데이터 가져오기는 이제 데이터베이스나 콘텐츠 제공자 선택에 대해 규정하지 않고도 가능한 한 End-to-End 타입 안전성을 제공합니다.

일반 TypeScript에서 예상하는 대로 응답 데이터의 타입을 지정할 수 있습니다. 예를 들어:

async function getData() {
  const res = await fetch("https://api.example.com/...");
  // 반환 값은 직렬화되지 *않습니다*
  // Date, Map, Set 등을 반환할 수 있습니다.
  return res.json();
}
 
export default async function Page() {
  const name = await getData();
 
  return "...";
}

완전한 End-to-End 타입 안전성을 위해서는 데이터베이스나 콘텐츠 제공자도 TypeScript를 지원해야 합니다. 이는 ORM이나 타입 안전 쿼리 빌더를 사용하여 달성할 수 있습니다.

비동기 서버 컴포넌트 TypeScript 오류

TypeScript로 async 서버 컴포넌트를 사용하려면 TypeScript 5.1.3 이상과 @types/react 18.2.8 이상을 사용해야 합니다.

TypeScript의 이전 버전을 사용하는 경우 'Promise<Element>' is not a valid JSX element 타입 오류가 발생할 수 있습니다. TypeScript와 @types/react를 최신 버전으로 업데이트하면 이 문제가 해결될 것입니다.

서버 및 클라이언트 컴포넌트 간 데이터 전달

props를 통해 서버와 클라이언트 컴포넌트 간에 데이터를 전달할 때, 데이터는 여전히 브라우저에서 사용하기 위해 직렬화(문자열로 변환)됩니다. 그러나 특별한 타입이 필요하지 않습니다. 다른 컴포넌트 간에 props를 전달하는 것과 동일하게 타입이 지정됩니다.

더욱이, 렌더링되지 않은 데이터는 서버와 클라이언트 사이를 이동하지 않고 서버에 남아 있기 때문에 직렬화해야 할 코드가 줄어듭니다. 이는 서버 컴포넌트에 대한 지원을 통해 이제 가능해졌습니다.

경로 별칭 및 baseUrl

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

이 기능에 대해 자세히 알아보려면 모듈 경로 별칭 문서를 참조하세요.

단계적 타입 체크

v10.2.1 이후부터 Next.js는 tsconfig.json에서 활성화된 경우 단계적 타입 체크를 지원합니다. 이는 대규모 애플리케이션에서 타입 체크 속도를 향상시키는 데 도움이 될 수 있습니다.

TypeScript 오류 무시하기

Next.js는 프로젝트에 TypeScript 오류가 있을 때 프로덕션 빌드(next build)를 실패시킵니다.

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

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

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

export default {
  typescript: {
    // !! 경고 !!
    // 프로젝트에 타입 오류가 있더라도 프로덕션 빌드가
    // 성공적으로 완료되도록 위험하게 허용합니다.
    // !! 경고 !!
    ignoreBuildErrors: true,
  },
};

사용자 정의 타입 선언

사용자 정의 타입을 선언해야 할 때, 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"]
}

버전 변경 사항