프로젝트 시작 – 타입스크립트, app/ 골격 만들기

들어가며

지난 1편에서는 Next.js가 왜 특별한 프레임워크인지 소개하는 시간을 가졌습니다. 이번 포스트에서는 타입스크립트 기반의 Next.js 프로젝트를 처음부터 만들어가는 과정을 함께 따라가보겠습니다.

Next.js 프로젝트 생성과 실행

이제 실제로 Next.js 프로젝트를 만들어보겠습니다. Next.js는 프로젝트 생성을 위한 CLI 도구를 공식적으로 제공합니다. 이 도구를 사용하면 기본적인 프로젝트 구조를 한 번에 만들 수 있습니다.

저는 개인적으로 pnpm을 패키지 매니저로 사용하고 있기 때문에, pnpm 명령어로 프로젝트를 생성하겠습니다.

터미널을 열고 다음 명령을 입력해보겠습니다.

pnpm create-next-app@latest my-nextjs-app

명령을 실행하면 Next.js가 프로젝트 설정을 위한 몇 가지 질문을 합니다. 각 옵션에 대해 선택하면 됩니다.

옵션	설명
TypeScript	타입 시스템을 추가하여 코드 안정성을 높임 (저는 Yes)
ESLint	코드 품질 검사 및 일관된 스타일 유지 (저는 Yes)
Tailwind CSS	유틸리티 기반 CSS 프레임워크 (저는 yes)
src/ directory	src/ 폴더 구조 사용 여부 (기본값: app/) (저는 no)
App Router	최신 파일 기반 라우팅 시스템 사용 (저는 yes)
import alias	@/components 같은 경로 별칭 사용 (저는 No)

설정이 완료되면 프로젝트 폴더가 생성되고 의존성이 자동으로 설치됩니다.

프로젝트 구조 확인

설정 선택이 끝나면 Next.js가 자동으로 프로젝트 폴더를 만들고 필요한 파일들을 생성합니다. 생성된 프로젝트의 구조를 한번 살펴보겠습니다.

my-nextjs-app/
├── app/
│   ├── globals.css
│   ├── layout.tsx
│   ├── page.tsx
│   └── favicon.ico
├── public/
│   └── next.svg
├── package.json
├── tailwind.config.js
├── tsconfig.json
├── next.config.js
├── postcss.config.js
├── eslint.config.mjs
└── README.md

주요 파일들의 역할:

파일	설명
`app/`	페이지와 라우팅의 중심 폴더
`package.json`	프로젝트 의존성과 스크립트
`tailwind.config.js`	Tailwind CSS 설정
`tsconfig.json`	TypeScript 설정
`next.config.js`	Next.js 설정

개발 서버 실행

이제 만들어진 프로젝트를 실제로 실행해보겠습니다. 터미널에서 프로젝트 폴더로 이동한 다음, 개발 서버를 시작하는 명령을 입력합니다.

cd my-nextjs-app
pnpm dev

명령을 실행하면 Next.js가 개발 서버를 시작합니다. 잠시 기다리면 터미널에 다음과 같은 성공 메시지가 나타납니다:

- ready started server on 0.0.0.0:3000, url: http://localhost:3000

이 메시지가 나타나면 서버가 정상적으로 실행된 것입니다. 이제 브라우저를 열고 http://localhost:3000 주소로 접속해보겠습니다. 그러면 Next.js가 기본으로 제공하는 시작 페이지가 나타날 것입니다.

이렇게 해서 우리는 첫 번째 Next.js 프로젝트를 성공적으로 실행했습니다. 이제 이 프로젝트의 구조를 더 자세히 살펴보겠습니다.

루트 레이아웃 구성

프로젝트를 생성하면 기본적으로 app/layout.tsx 파일이 만들어집니다. 이 파일은 모든 페이지의 공통 틀 역할을 합니다.

import './globals.css'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  )
}

이 파일에서 html과 body 태그를 정의하고, children prop을 통해 각 페이지의 내용이 들어갈 자리를 지정합니다. 모든 페이지가 이 layout.tsx의 틀 안에 들어갑니다.

기본 페이지 생성

이제 실제 페이지를 만들어보겠습니다. App Router에서는 app/page.tsx 파일이 웹사이트의 메인 페이지가 됩니다. 프로젝트를 생성하면 기본적으로 다음과 같은 페이지가 만들어져 있습니다:

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm lg:flex">
        {/* 페이지 내용 */}
      </div>
    </main>
  )
}

이 코드를 보면 Home이라는 함수 컴포넌트를 만들고, Tailwind CSS 클래스로 스타일링한 것을 볼 수 있습니다. 이 컴포넌트가 우리가 브라우저에서 보는 실제 웹페이지가 됩니다.

페이지 생성의 더 다양한 방식과 레이아웃 구성 방법은 2-1편에서 자세히 살펴보겠습니다. 지금은 기본 골격을 잡는 단계라고 생각하면 됩니다.

요약

Next.js 프로젝트를 CLI 도구로 생성하고 기본 구조를 갖추는 과정을 살펴보았습니다. pnpm create-next-app 명령어로 타입스크립트, ESLint, Tailwind CSS가 포함된 프로젝트를 만들고, 개발 서버를 실행하여 기본 페이지를 확인했습니다.

이제 Next.js 프로젝트의 최소한의 골격이 준비되었습니다. 다음 편부터는 이 골격 위에 레이아웃과 내비게이션 등의 기능을 어떻게 구축할지 자세히 살펴보겠습니다.

참조

Next.js 공식문서 – Getting Started
Next.js 공식문서 – Creating Layouts and Pages
Next.js 공식문서 – Navigating Between Pages

2프로젝트 시작 – 타입스크립트, app/ 골격 만들기