왜 Next.js 프로젝트에 TypeScript를 써야 할까?

안녕하세요, 모던 웹 개발의 세계에 오신 여러분을 환영합니다! Next.js가 제공하는 강력한 기능들(SSR, SSG, ISR 등)에 이미 매료되셨을 겁니다. 그런데 여기에 TypeScript라는 날개를 달아주면 어떨까요? JavaScript의 유연함도 좋지만, 프로젝트 규모가 커질수록 예상치 못한 타입 오류로 골머리를 앓는 경우가 많습니다. 바로 이 지점에서 TypeScript가 구세주처럼 등장합니다.

TypeScript를 사용하면 다음과 같은 엄청난 이점을 얻을 수 있습니다.

• 컴파일 타임 에러 체크: 런타임에서 발생할 수 있는 수많은 버그를 개발 단계에서 미리 잡을 수 있습니다.
• 강력한 자동 완성: 코드 에디터(VSCode 등)에서 변수나 함수의 타입을 정확히 알고 있기 때문에, 개발 생산성이 수직 상승합니다.
• 명확한 코드: 함수의 인자나 반환 값의 타입이 명시되어 있어 코드를 이해하기 훨씬 쉬워집니다. 이건 유지보수 측면에서 정말 중요합니다!
• 대규모 프로젝트에서의 안정성: 여러 개발자가 협업할 때, 타입 시스템은 훌륭한 가이드라인이 되어줍니다.

Next.js는 TypeScript를 공식적으로, 그리고 아주 긴밀하게 지원하고 있습니다. 이제부터 그 강력한 조합을 어떻게 활용하는지 차근차근 알아보겠습니다.

1. Next.js + TypeScript 프로젝트 시작하기

시작은 놀랍도록 간단합니다. Next.js 공식 CLI는 TypeScript 프로젝트 생성을 위한 플래그를 제공합니다.

npx create-next-app@latest --ts your-project-name
# 또는 yarn create next-app --typescript your-project-name

위 명령어를 실행하면, TypeScript에 필요한 설정들(tsconfig.json, next-env.d.ts 등)이 자동으로 구성된 프로젝트가 생성됩니다. 이제 여러분은 타입의 세계로 뛰어들 준비가 되었습니다!

2. 페이지 컴포넌트 타입 정의하기: NextPage

페이지 컴포넌트를 작성할 때, Next.js는 NextPage라는 타입을 제공합니다. 이를 사용하면 페이지가 받을 수 있는 props를 명확하게 정의할 수 있습니다.

예를 들어, getStaticProps나 getServerSideProps를 통해 데이터를 받아오는 페이지를 생각해봅시다.

// pages/posts/[id].tsx
import { GetServerSideProps, NextPage } from 'next';

// 이 페이지가 받을 props의 타입을 정의합니다.
interface PostProps {
  post: {
    id: number;
    title: string;
    body: string;
  };
}

const PostPage: NextPage<PostProps> = ({ post }) => {
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </article>
  );
};

export const getServerSideProps: GetServerSideProps = async (context) => {
  const { id } = context.params!;
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/${id}`);
  const post = await res.json();

  // props는 PostProps 타입과 일치해야 합니다.
  return {
    props: {
      post,
    },
  };
};

export default PostPage;

NextPage<PostProps>와 같이 제네릭을 사용하여 props의 타입을 지정하면, PostPage 컴포넌트 내부에서 post 객체의 속성들(id, title, body)을 사용할 때 자동 완성이 지원되고, 잘못된 속성에 접근하려고 하면 에디터가 바로 알려줍니다. 정말 편리하죠!

3. API 라우트도 타입 세이프하게!

Next.js의 강력한 기능 중 하나인 API 라우트 역시 TypeScript로 더욱 안전하게 만들 수 있습니다. next 패키지는 NextApiRequest와 NextApiResponse 타입을 제공하여 요청과 응답 객체를 타이핑할 수 있게 해줍니다.

// pages/api/hello.ts
import type { NextApiRequest, NextApiResponse } from 'next';

// 응답 데이터의 타입을 미리 정의합니다.
type Data = {
  message: string;
  timestamp: number;
} | {
  error: string;
}

export default function handler(
  req: NextApiRequest,
  res: NextApiResponse<Data>
) {
  if (req.method === 'GET') {
    res.status(200).json({ message: 'Hello, World!', timestamp: Date.now() });
  } else {
    res.setHeader('Allow', ['GET']);
    res.status(405).json({ error: `Method ${req.method} Not Allowed` });
  }
}

NextApiResponse<Data>와 같이 응답 데이터의 타입을 지정하면, res.json() 메서드에 Data 타입에 맞지 않는 객체를 전달하려고 할 때 TypeScript 컴파일러가 오류를 발생시킵니다. 이를 통해 API의 응답 형식을 일관성 있게 유지하고 실수를 방지할 수 있습니다.

4. 마무리: 더 견고하고 예측 가능한 웹을 향하여

Next.js와 TypeScript의 조합은 단순히 코드를 몇 줄 더 작성하는 것을 넘어, 웹 애플리케이션의 안정성과 개발 경험을 한 차원 높여주는 강력한 시너지 효과를 냅니다. 처음에는 타입을 정의하는 것이 조금 번거롭게 느껴질 수 있지만, 그 작은 노력이 나중에 디버깅에 쏟아야 할 엄청난 시간을 절약해 줄 것입니다.

아직 망설이고 계신다면, 다음 프로젝트는 꼭 create-next-app --ts로 시작해보세요. 타입이 주는 안정감과 개발의 즐거움을 만끽하게 되실 겁니다. 여러분의 코드가 더 견고해지고, 협업은 더 원활해지며, 무엇보다도 개발자로서 한 단계 더 성장하는 계기가 될 것이라고 확신합니다!