이제 진짜로 프로젝트를 만든다
앞 장까지는 준비 운동이었습니다. 운동화를 신고, 물도 챙기고, 스트레칭도 했습니다. 이제는 진짜로 뛰어볼 차례입니다.
이번 장의 목표는 아주 분명합니다. 최신 Next.js 기본 설정이 들어간 프로젝트를 한 번에 만들고, 내 브라우저에서 직접 실행해 보는 것입니다. 여기서 중요한 건 설명을 많이 읽는 게 아닙니다. 내 손으로 만들고, 내 화면에서 돌아가는 순간을 보는 것입니다.
우리가 앞으로 함께 만들 앱은 '작은 기록 상점'입니다. 이번 장에서는 그 첫 바닥 공사를 합니다. 아직 멋진 기능은 없지만, 괜찮습니다. 집도 처음엔 현관문부터 달지, 옥상 정원부터 만들진 않으니까요.
create-next-app이 왜 편할까
create-next-app은 Next.js 팀이 제공하는 공식 시작 도구입니다. 쉽게 말하면, 새 프로젝트를 만들 때 필요한 기본 세팅을 대신 깔아 주는 친절한 출발 버튼입니다.
예전에는 프로젝트를 시작하려면 이것저것 손으로 붙여야 했습니다. React 설치하고, Next 설치하고, TypeScript 붙이고, ESLint 붙이고, 스타일링 도구도 정하고, 라우터 구조도 고르고, 개발 서버 설정도 맞추고… 시작하기도 전에 숨이 찼죠.
하지만 최신 Next.js에서는 이걸 훨씬 단순하게 만들었습니다. create-next-app 하나로 보통 다음 요소들이 함께 준비됩니다.
TypeScript: 코드 실수를 조금 더 빨리 잡아주는 도구
Tailwind CSS: 빠르게 스타일을 붙일 수 있는 도구
ESLint: 코드 품질을 점검해 주는 검사기
App Router: 최신 Next.js의 기본 라우팅 방식
Turbopack: 개발 서버를 빠르게 돌려 주는 엔진
즉, 우리는 설정에 에너지를 다 쓰지 않고, 앱을 만드는 일에 더 빨리 들어갈 수 있습니다.
이번 책에서 만들 프로젝트 이름
프로젝트 이름은 폴더 이름이 됩니다. 이번 책에서는 영어 소문자와 하이픈을 써서 이렇게 만들겠습니다.
small-record-shop이름을 이렇게 짓는 이유는 단순합니다. 터미널과 경로에서 다루기 편하고, 운영체제마다 생길 수 있는 자잘한 문제를 줄이기 좋기 때문입니다.
브랜드 이름처럼 멋지게 지을 필요는 없습니다. 지금은 잘 만들어지고 잘 실행되는 이름이 더 중요합니다.
한 줄로 프로젝트 만들기
이제 터미널을 열고, 프로젝트를 만들고 싶은 작업 폴더로 이동한 다음 아래 명령어를 입력해 봅시다.
npx create-next-app@latest small-record-shop --yes이 명령어를 천천히 읽어보면 이렇습니다.
npx는 필요한 도구를 그때 실행해 주는 명령어이고, create-next-app@latest는 최신 버전의 프로젝트 생성기를 쓰겠다는 뜻입니다. small-record-shop은 새로 생길 폴더 이름입니다. 그리고 --yes는 질문을 하나하나 묻지 말고, 권장되는 기본값으로 바로 진행해 달라는 뜻입니다.
초보자에게 이 방식이 좋은 이유는 간단합니다. 처음부터 선택지가 너무 많으면 배우기보다 고민하게 되기 때문입니다. 지금은 "무엇을 고를까?"보다 "일단 프로젝트를 띄워보자"가 더 중요합니다.
명령어를 실행하면 잠시 동안 파일이 내려받아지고, 폴더가 만들어지고, 필요한 패키지들이 설치됩니다. 인터넷 상태에 따라 조금 시간이 걸릴 수 있습니다. 화면에 영어가 주르르 지나가도 놀라지 마세요. 컴퓨터가 열심히 공사 중인 것입니다.
질문에 직접 답하고 싶다면
--yes를 빼고 실행하면 몇 가지 질문이 나올 수 있습니다.
npx create-next-app@latest small-record-shop그럴 때는 이번 책 기준으로 이렇게 생각하면 됩니다.
TypeScript: Yes
ESLint: Yes
Tailwind CSS: Yes
App Router: Yes
Turbopack: Yes
import alias: 기본값 그대로 사용
이 조합이 바로 우리가 앞으로 책 전체에서 사용할 기본 장비입니다. 최신 Next.js를 배우는 입장에서도 가장 자연스러운 출발점입니다.
프로젝트 폴더 안으로 들어가기
프로젝트 생성이 끝났다면 이제 그 폴더 안으로 들어가야 합니다.
cd small-record-shop이 단계는 아주 자주 놓치는 부분입니다. 프로젝트는 만들어졌는데 아직 그 프로젝트 안으로 들어가지 않은 상태라면, 다음 명령어들이 엉뚱한 자리에서 실행됩니다. 마치 집 앞까지 와 놓고 남의 초인종을 누르는 셈이죠.
터미널에 현재 위치가 small-record-shop으로 보이면 준비 완료입니다.
개발 서버 실행하기
이제 가장 설레는 순간입니다. 아래 명령어를 입력해 봅시다.
npm run dev이 명령은 개발 서버를 실행합니다. 개발 서버는 우리가 코드를 고치면서 결과를 바로 확인할 수 있게 도와주는 실습용 서버입니다.
잠시 후 터미널에 http://localhost:3000 같은 주소가 보일 것입니다. 브라우저에서 그 주소를 열어 보세요.
화면에 Next.js 시작 페이지가 보인다면 성공입니다.
정말 중요하니 한 번 더 말하겠습니다. 이제 여러분은 Next.js 프로젝트를 만든 사람이 아니라, 실제로 실행까지 성공한 사람입니다. 이 차이는 생각보다 큽니다.
방금 무슨 일이 일어난 걸까
겉으로 보기엔 명령어 두세 줄이 전부였지만, 실제로는 꽤 많은 일이 자동으로 끝났습니다.
프로젝트 폴더가 만들어졌고, 필요한 패키지들이 설치되었고, 개발용 스크립트가 준비되었고, App Router 구조가 들어간 첫 화면도 함께 생성되었습니다. TypeScript 설정, ESLint 설정, Tailwind CSS 연결, 개발 서버 실행 환경까지 이미 갖춰진 상태입니다.
쉽게 말해, 우리는 빈 운동장이 아니라 골대와 라인까지 그려진 경기장에 들어온 것입니다. 이제부터는 공만 차면 됩니다.
첫 화면을 우리 프로젝트답게 바꿔 보자
기본 시작 화면이 보였다면, 이제 아주 작게 한 번 손을 대 보겠습니다. 프로젝트 안에서 app/page.tsx 파일을 열어 아래처럼 바꿔 보세요.
export default function Home() {
return (
<main className="min-h-screen bg-amber-50 px-6 py-16 text-slate-900">
<div className="mx-auto max-w-3xl">
<p className="text-sm font-semibold tracking-wide text-amber-700">
우리의 첫 Next.js 프로젝트
</p>
<h1 className="mt-4 text-4xl font-bold sm:text-5xl">
작은 기록 상점에 오신 것을 환영합니다
</h1>
<p className="mt-6 text-lg leading-8 text-slate-700">
오늘은 가게 문만 열었지만, 앞으로 이곳에 기록 목록도 놓고,
상세 페이지도 만들고, 직접 글을 추가하는 기능도 넣어 볼 거예요.
</p>
</div>
</main>
)
}저장하고 브라우저를 다시 보면 화면이 거의 바로 바뀝니다. 이게 참 기분 좋습니다. 내가 쓴 코드가 즉시 눈앞에 나타나기 때문입니다.
여기서 벌써 몇 가지를 동시에 경험한 셈입니다. 페이지를 수정했고, Tailwind CSS 클래스를 사용했고, 개발 서버가 변경 사항을 빠르게 반영하는 것도 봤습니다. 아직 어려운 개념을 깊게 이해하지 않아도 괜찮습니다. 지금은 "아, 진짜 바뀌는구나"를 몸으로 느끼는 게 더 중요합니다.
폴더 안을 잠깐만 들여다보자
이번 장에서는 구조를 깊게 파지 않겠습니다. 그건 다음 장의 주인공이니까요. 다만 지금 막 생긴 프로젝트 안에서 몇 가지만 눈에 익혀 두면 좋습니다.
app/ 폴더는 페이지를 만드는 핵심 공간입니다. app/page.tsx는 홈 화면이고, app/layout.tsx는 여러 페이지를 감싸는 공통 틀입니다. public/은 이미지 같은 정적 파일을 두는 곳입니다. package.json에는 실행 명령과 설치된 도구 정보가 들어 있습니다.
그리고 경우에 따라 AGENTS.md 같은 파일이 보일 수도 있습니다. 최근 기본 템플릿에는 코딩 도우미가 프로젝트 규칙을 이해하는 데 도움이 되는 파일이 함께 들어갈 수 있습니다. 처음 보는 파일이라고 겁먹을 필요는 없습니다. 지금은 "기본 템플릿에 포함될 수 있는 안내 파일" 정도로만 알고 있으면 충분합니다.
초보자가 여기서 가장 많이 헷갈리는 것
첫 프로젝트를 만들 때 자주 나오는 실수는 의외로 비슷합니다.
첫째, 프로젝트를 만든 뒤 cd small-record-shop을 하지 않고 바로 npm run dev를 입력하는 경우가 많습니다. 이러면 지금 프로젝트 바깥에서 명령을 실행하게 됩니다.
둘째, React에서 하던 습관대로 npm start를 입력하는 경우가 있습니다. 하지만 Next.js에서 개발할 때 가장 먼저 쓰는 명령은 npm run dev입니다.
셋째, 브라우저가 자동으로 안 열리면 실패한 줄 아는 경우가 있습니다. 자동으로 열리지 않아도 괜찮습니다. 직접 http://localhost:3000을 주소창에 입력하면 됩니다.
이 세 가지만 기억해도 초반 시행착오를 꽤 줄일 수 있습니다.
이번 장의 진짜 성과
이번 장에서 우리가 한 일은 단순해 보이지만, 사실은 아주 중요합니다. 우리는 최신 Next.js 방식으로 프로젝트를 만들었고, 기본 개발 도구가 세팅된 상태를 손에 넣었고, 직접 개발 서버를 실행해 봤고, 첫 화면까지 우리 앱답게 바꿔 봤습니다.
이제부터는 "Next.js가 뭔가요?"를 묻는 단계에서 한 걸음 나아가, "좋아, 그럼 이걸로 뭘 만들 수 있지?"를 묻는 단계로 들어갑니다.
다음 장에서는 이제 막 만들어진 프로젝트를 천천히 산책해 보겠습니다. 폴더 구조를 읽는 법을 알게 되면, 지금까지는 그냥 생긴 파일들이 앞으로는 의미 있는 지도로 보이기 시작할 것입니다.
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.