[Configuring] Next 공식문서 번역 / Configuring - TypeScript / Next.js Typescript / Next.js 타입스크립트

타입스크립트

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 파일을 추가합니다.

 

TypeScript 플러그인

Next.js에는 사용자 지정 TypeScript 플러그인 및 유형 검사기가 포함되어 있으며, VSCode 및 기타 코드 편집기에서 고급 유형 검사 및 자동 완성을 위해 사용할 수 있습니다.

TypeScript 파일을 열어 놓은 상태에서 next dev를 처음 실행하면 플러그인을 활성화하라는 메시지가 표시됩니다.

프롬프트를 까먹은 경우 다음과 같이 수동으로 플러그인을 활성화할 수 있습니다:

• 명령 팔레트 열기(Ctrl/⌘ + Shift + P)
• "TypeScript"를 검색합니다: Select TypeScript Version"
• "Use Workspace Version" 선택

이제 파일을 편집할 때 사용자 정의 플러그인이 활성화됩니다. next build를 실행할 때 사용자 정의 유형 검사기가 사용됩니다. 또한 이 프로세스를 자동화할 수 있도록 VSCode 설정 파일을 자동으로 생성합니다.

 

플러그인 기능

타입스크립트 플러그인이 도움이 될 수 있습니다:

• 세그먼트 구성 옵션에 대해 잘못된 값을 전달할 경우 경고.
• 사용 가능한 옵션 및 컨텍스트 내 문서 표시.
• use client 지시어가 올바르게 사용되었는지 확인.
• 클라이언트 hooks(예: useState)가 클라이언트 컴포넌트에서만 사용되는지 확인합니다.

참고: 향후 더 많은 기능이 추가될 예정입니다.

 

최소 TypeScript 버전

type modifiers on import names 및 performance improvements과 같은 구문 기능을 사용하려면 TypeScript v4.5.2 이상을 사용하는 것이 좋습니다.

 

정적으로 입력된 링크

Next.js는 링크를 정적으로 입력하여 next/link 사용 시 오타 및 기타 오류를 방지하고, 페이지 간 탐색 시 유형 안전성을 향상시킬 수 있습니다. 이 기능을 사용하려면 experimental.typedRoutes를 활성화해야 하며 프로젝트에서 TypeScript를 사용해야 합니다.

// next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
};
 
module.exports = 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} />
 
// 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는 애플리케이션의 모든 기존 경로(링크의 href 유형이 유효한 모든 경로)에 대한 정보가 포함된 숨겨진 .d.ts 파일을 .next 안에 생성합니다. 이 .d.ts 파일은 tsconfig.json에 포함되며 TypeScript 컴파일러는 해당 .d.ts를 검사하여 유효하지 않은 링크에 대한 피드백을 편집기에 제공합니다.

 

end-to-end 타입 안전

Next.js 13은 타입 안전성이 강화되었습니다. 여기에는 다음이 포함됩니다:

• 불러오는 함수와 페이지 사이에 데이터 직렬화가 없습니다:
  서버의 컴포넌트, 레이아웃, 페이지에서 직접 fetch 할 수 있습니다. 이 데이터는 React에서 사용하기 위해 클라이언트 측으로 전달하기 위해 직렬화(문자열로 변환)할 필요가 없습니다. 대신 app이 기본적으로 서버 컴포넌트를 사용하기 때문에 추가 단계 없이 Date, map, Set 등의 값을 사용할 수 있습니다. 이전에는 서버와 클라이언트 사이의 경계를 Next.js 전용 타입으로 수동으로 입력해야 했습니다.
• 컴포넌트 간 데이터 흐름이 간소화되었습니다: 루트 레이아웃을 위해 _app을 제거하여 이제 컴포넌트와 페이지 간의 데이터 흐름을 시각화하기가 더 쉬워졌습니다. 이전에는 개별 page와 _app 사이의 데이터 흐름이 입력하기 어렵고 혼란스러운 버그를 유발할 수 있었습니다. Next.js 13의 콜로케이드된 데이터 불러오기를 사용하면 더 이상 문제가 되지 않습니다.

이제 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 또는 타입 안전 쿼리 빌더를 사용하는 것을 통해 이루어질 수 있습니다.

 

비동기 서버 컴포넌트 타입스크립트 오류

비동기(async) 서버 컴포넌트가 사용된 곳에서 'Promise<Element>'가 유효한 JSX 엘리먼트 유형이 아닙니다라는 오류를 발생시킵니다.
이는 TypeScript의 알려진 문제이며 업스트림에서 작업 중입니다.
임시 해결 방법으로 컴포넌트 위에 {/* @ts-expect-error Async Server Component */}를 추가하여 해당 컴포넌트에 대한 유형 검사를 비활성화할 수 있습니다.

//app/page.tsx

import { ExampleAsyncComponent } from './ExampleAsyncComponent';
export default function Page() {
  return (
    <>
      {/* @ts-expect-error Async Server Component */}
      <ExampleAsyncComponent />
    </>
  );
}

레이아웃 및 페이지 구성 요소에는 적용되지 않습니다.
이 문제는 여기에서 추적 중입니다. 이 문제는 TypeScript 5.1(Stable)에서 수정될 예정입니다.

 

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

prop을 통해 서버와 클라이언트 컴포넌트 간에 데이터를 전달할 때에도 브라우저에서 사용할 수 있도록 데이터가 직렬화(문자열로 변환)됩니다. 그러나 특별한 타입이 필요하지 않습니다. 컴포넌트 간에 다른 프로퍼티를 전달할 때와 동일한 타입으로 전달됩니다.

또한 렌더링되지 않은 데이터는 서버와 클라이언트 간에 교차하지 않으므로(서버에 남아 있음) 직렬화할 코드가 더 적습니다. 이 기능은 이제 서버 컴포넌트 지원을 통해서만 가능합니다.

 

경로 별칭 및 baseUrl

Next.js는 tsconfig.json, "paths" 및 "baseUrl" 옵션을 자동으로 지원합니다.
이 기능에 대한 자세한 내용은 모듈 경로 별칭 문서에서 확인할 수 있습니다.

 

next.config.js 타입 검사

next.config.js 파일은 바벨이나 타입스크립트에서 구문 분석되지 않으므로 자바스크립트 파일이어야 하지만, 아래와 같이 JSDoc을 사용하여 IDE에서 타입 검사를 추가할 수 있습니다:

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

 

증분(incremental) 유형 검사

v10.2.1 Next.js는 tsconfig.json에서 활성화하면 증분 유형 검사를 지원하므로 대규모 애플리케이션에서 유형 검사 속도를 높이는 데 도움이 될 수 있습니다.

 

TypeScript 오류 무시

프로젝트에 TypeScript 오류가 있는 경우 Next.js는 프로덕션 빌드(next build)에 실패합니다.
애플리케이션에 오류가 있는 경우에도 Next.js가 프로덕션 코드를 위험하게 생성하지 않게 하려면 기본 제공 유형 검사 단계를 비활성화할 수 있습니다.
비활성화할 경우 빌드 또는 배포 프로세스의 일부로 유형 검사를 실행하고 있는지 확인해야 하며, 그렇지 않으면 매우 위험할 수 있습니다.
next.config.js를 열고 typescript 구성에서 ignoreBuildErrors 옵션을 활성화하세요:

module.exports = {
  typescript: {
    // !! WARN !!
    // 프로젝트에 유형 오류가 있어도 프로덕션 빌드가 성공적으로 완료되도록 위험한 허용을 합니다.
    // !! WARN !!
    ignoreBuildErrors: true,
  },
};