01872025년 6월 25일

[Next.js] Next.js + TypeScript 기반 프로젝트 시작 가이드

Next.js는 React 기반의 프레임워크로, 서버 사이드 렌더링(SSR), 정적 사이트 생성(SSG), 파일 기반 라우팅 등 다양한 기능을 내장하고 있습니다. 여기에 TypeScript와 Tailwind CSS를 조합하면 생산성과 안정성을 동시에 챙길 수 있다.

이 글에서는 create-next-app 명령어를 통해 Next.js + TypeScript + Tailwind 기반 프로젝트를 만드는 전체 과정을 상세히 살펴보자.

1. 프로젝트 생성 명령어

code

npx create-next-app@latest my-app --typescript

my-app은 프로젝트 이름이며, 원하는 이름으로 변경 가능하다.

처음 실행하면 아래처럼 메시지가 나온다.

code

Need to install the following packages:
  create-next-app@latest
Ok to proceed? (y)

y를 입력하면 설치가 진행된다.

? 만약, 설치를 마친 뒤에 폴더명을 바꾸고 싶다면?1) mv 기존폴더명 새폴더명2) package.json / package-lock.json 파일에서 name 항목을 수정

2. 프로젝트 세팅 시 나오는 질문들

npx create-next-app@latest my-app --typescript 명령어를 입력하면, 사진과 같이 세팅을 위한 질문들이 나온다.

1. Would you like to use ESLint? (Y/n)

설명: 코드 스타일 체크 및 버그 방지를 위한 린팅 도구
추천: Y (혹은 엔터)
이유: TypeScript와 함께 사용 시 코드 안정성이 크게 향상됨

2. Would you like to use Tailwind CSS? (Y/n)

설명: 유틸리티 기반의 CSS 프레임워크
추천: Y
이유: 빠른 UI 개발, 유지보수성, 반응형 지원 모두 우수

3. Would you like to use src/ directory? (Y/n)

설명: pages, components 등을 src/ 내부로 구성할지 여부
추천: Y
이유: 규모가 커질수록 디렉토리 구조 분리의 이점이 큼

4. Would you like to use App Router (recommended)? (Y/n)

설명: pages/ 대신 app/ 폴더를 기반으로 한 최신 라우팅 방식
추천: Y
이유: Layout, Server Component, Suspense, Streaming 등 최신 기능 지원

5. Would you like to customize the import alias (@/* by default)? (Y/n)

설명: @/components/Button처럼 경로를 간단하게 만드는 alias 설정
추천: n (기본값 유지)
예외: 팀에서 ~/, src/ 등 특정 alias를 쓰기로 한 경우 y 선택 후 입력

@를 선택한 경우 tsconfig.json에 다음과 같이 설정된다:

code

"paths": {
  "@/*": ["./src/*"]
}

3. 생성된 기본 구조

선택한 옵션에 따라 다음과 같은 디렉토리 구조가 생성된다. (예: src/, app router 선택 시):

code

my-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/
│   └── styles/
├── public/
├── tsconfig.json
├── tailwind.config.ts
└── ...

4. 개발 서버 실행

code

cd my-app
npm run dev

브라우저에서 http://localhost:3000 으로 접속하여 앱을 확인할 수 있다.

마치며

Next.js 최신 버전은 설정 과정에서 많은 선택지를 제공하지만, 위와 같은 설정만 따르면 생산성, 유지보수성, 최신 기능 모두를 챙길 수 있다.

실무에 바로 적용 가능한 구조로 시작하고 싶다면, 위 설정을 그대로 따라가면 된다.

최근 글