타입스크립트

Next.js는 리액트 애플리케이션을 구축하기 위한 타입스크립트 중심의 개발 경험을 제공합니다. 필요한 패키지를 자동으로 설치하고 적절한 설정을 구성하기 위한 내장 타입스크립트 지원이 포함되어 있습니다. 또한 에디터를 위한 타입스크립트 플러그인도 제공합니다.

🎥 시청하기: 내장된 타입스크립트 플러그인에 대해 알아보기 → YouTube (3분)

새 프로젝트

create-next-app은 이제 기본적으로 타입스크립트를 포함하고 배포됩니다.

npx create-next-app@latest

기존 프로젝트

프로젝트에 타입스크립트를 추가하려면 파일의 확장자를 .ts / .tsx로 변경합니다. next dev와 next build를 실행하면 필요한 의존성이 자동으로 설치되며 추천된 설정 옵션을 포함하는 tsconfig.json 파일이 추가됩니다.

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

타입스크립트 플러그인

Next.js는 VSCode 및 기타 코드 에디터에서 고급 타입 검사 및 자동 완성을 위해 사용할 수 있는 사용자 정의 타입스크립트 플러그인 및 타입 검사기를 포함하고 있습니다.

VS Code에서 플러그인을 활성화하려면 아래 순서대로 실행하세요.

1. 명령 팔레트를 엽니다 (Ctrl/⌘ + Shift + P)
2. "타입스크립트: 타입스크립트 버전 선택"을 검색합니다.
3. "작업 영역 버전 사용"을 선택합니다.

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

플러그인 기능

타입스크립트 플러그인은 다음을 도울 수 있습니다.

• 세그먼트 구성 옵션에 대한 잘못된 값이 전달되면 경고합니다.
• 사용 가능한 옵션과 문맥 중심의 문서를 보여줍니다.
• use client 지시문이 올바르게 사용되도록 합니다.
• 클라이언트 후크(예: useState)는 클라이언트 컴포넌트에서만 사용되도록 합니다.

최소 타입스크립트 버전

import 이름의 타입 수정자 및 성능 향상과 같은 문법 기능을 얻기 위해 최소한 v4.5.2 버전의 타입스크립트를 사용하는 것이 매우 권장됩니다.

정적 타입 링크

Next.js는 next/link를 사용할 때 타이핑 오류 및 기타 오류를 방지하기 위해 링크를 정적으로 타입화할 수 있습니다. 이를 통해 페이지 간 이동 시 타입 안정성이 향상됩니다.

이 기능을 사용하려면 experimental.typedRoutes를 활성화하고 프로젝트에서 타입스크립트를 사용해야 합니다.

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    typedRoutes: true,
  },
}

module.exports = nextConfig

Next.js는 애플리케이션의 모든 기존 경로에 대한 정보를 포함하는 .next/types에서 링크 정의를 생성합니다. 타입스크립트는 이를 사용하여 편집기에서 유효하지 않은 링크에 대한 피드백을 제공합니다.

현재 실험적인 지원은 동적 세그먼트를 포함한 모든 문자열 리터럴을 포함합니다. 리터럴이 아닌 문자열의 경우 현재 href를 as Route로 수동으로 형변환해야 합니다.

import type { Route } from 'next';
import Link from 'next/link'

// href가 유효한 경로인 경우 타입스크립트 오류 없음
<Link href="/about" />
<Link href="/blog/nextjs" />
<Link href={`/blog/${slug}`} />
<Link href={('/blog' + slug) as Route} />

// href가 유효한 경로가 아닌 경우 타입스크립트 오류 발생
<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.js 13은 향상된 타입 안정성을 가지고 있습니다. 이에는 다음이 포함됩니다.

1. 데이터 가져오기 함수와 페이지 간의 데이터 직렬화 없음: 서버에서 컴포넌트, 레이아웃 및 페이지 내에서 직접 fetch할 수 있습니다. 이 데이터는 클라이언트 측에서 리액트에서 사용하기 위해 직렬화(문자열로 변환)될 필요가 없습니다. 대신 app이 기본적으로 서버 컴포넌트를 사용하기 때문에 추가 단계 없이 Date, Map, Set 등의 값을 사용할 수 있습니다. 이전에는 서버와 클라이언트 간의 경계를 수동으로 타입화해야 했습니다.
2. 컴포넌트 간의 데이터 흐름 간소화: _app의 제거와 루트 레이아웃을 선호함으로써 컴포넌트와 페이지 간의 데이터 흐름을 더 쉽게 시각화할 수 있습니다. 이전에는 개별 pages와 _app 사이의 데이터 흐름을 타입화하는 것이 어렵고 혼란스러운 버그를 도입할 수 있었습니다. Next.js 13의 colocated data fetching을 통해 이제 더 이상 문제가 아닙니다.

Next.js의 데이터 가져오기는 데이터베이스 또는 콘텐츠 제공자 선택에 대해 규정적이지 않으면서 종단 간 타입 안정성에 최대한 가깝게 제공합니다.

평범한 타입스크립트로 응답 데이터를 타입화할 수 있습니다.

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

완벽한 종단 간 타입 안정성을 위해서는 데이터베이스나 콘텐츠 제공자가 타입스크립트를 지원해야 합니다. 이것은 ORM 또는 타입 안전한 쿼리 빌더를 사용함으로써 이루어질 수 있습니다.

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

타입스크립트와 함께 async 서버 컴포넌트를 사용하려면 타입스크립트 5.1.3 이상 및 @types/react 18.2.8 이상을 사용해야 합니다.

타입스크립트의 이전 버전을 사용하는 경우 'Promise<Element>'는 유효한 JSX 요소가 아닙니다. 타입 오류를 볼 수 있습니다. 타입스크립트와 @types/react의 최신 버전으로 업데이트하면 이 문제가 해결됩니다.

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

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

또한 직렬화해야 하는 코드가 줄어들었습니다. 렌더링되지 않은 데이터는 서버와 클라이언트 사이를 넘나들지 않습니다(서버에 남아 있음). 이제 서버 컴포넌트의 지원을 통해 이것이 가능해졌습니다.

경로 별칭과 baseUrl

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

이 기능에 대한 자세한 정보는 모듈 경로 별칭 문서에서 확인할 수 있습니다.

next.config.js의 타입 체크

next.config.js 파일은 Babel 또는 타입스크립트에 의해 파싱되지 않기 때문에 JavaScript 파일이어야 합니다. 그러나 아래와 같이 JSDoc을 사용하여 IDE에서 타입 체크를 추가할 수 있습니다.

// @ts-check

/**
 * @type {import('next').NextConfig}
 **/
const nextConfig = {
  /* 설정 옵션 */
}

module.exports = nextConfig

점진적 타입 체크

v10.2.1부터 Next.js는 tsconfig.json에서 활성화된 경우 점진적 타입 체크를 지원합니다. 이는 큰 애플리케이션에서 타입 체크 속도를 향상시킬 수 있습니다.

타입스크립트 오류 무시하기

프로젝트에 타입스크립트 오류가 있는 경우 Next.js는 프로덕션 빌드 (next build)를 실패시킵니다.

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

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

next.config.js를 열고 typescript 설정에서 ignoreBuildErrors 옵션을 활성화하십시오.

module.exports = {
  typescript: {
    // !! 경고 !!
    // 프로젝트에 타입 오류가 있음에도 불구하고 
    // 프로덕션 빌드를 성공적으로 완료하도록 허용합니다.
    // !! 경고 !!
    ignoreBuildErrors: true,
  },
}