작업 환경 준비하기

오늘 준비할 세 가지 도구

Next.js 프로젝트를 만들기 전에 세 가지 도구를 준비합니다.

첫째, Node.js입니다. Node.js는 내 컴퓨터에서 JavaScript를 실행하게 해 주는 프로그램입니다. 식당으로 비유하면, 레시피만 있는 상태에서는 음식을 만들 수 없습니다. 실제로 조리할 주방이 필요합니다. 여기서 JavaScript 코드가 레시피라면, Node.js는 그 레시피를 실행하는 주방입니다.

둘째, Visual Studio Code입니다. 보통 줄여서 VS Code라고 부릅니다. 코드를 쓰고, 파일을 열고, 저장하는 편집기입니다. 한글 문서를 쓸 때 워드나 한글 프로그램을 쓰듯이, 웹사이트 파일을 다룰 때는 코드 편집기를 씁니다.

셋째, 브라우저입니다. 크롬, 엣지, 사파리 같은 프로그램입니다. VS Code에서 파일을 고치고, Node.js로 프로젝트를 실행한 뒤, 브라우저에서 결과를 확인합니다. 즉, 브라우저는 완성된 화면을 보는 창입니다.

이 세 가지의 역할을 한 줄로 정리하면 이렇습니다.

• Node.js: Next.js 프로젝트를 내 컴퓨터에서 움직이게 하는 실행 도구

• VS Code: 프로젝트 파일을 열고 수정하는 작업 책상

• 브라우저: 내가 만든 웹사이트를 확인하는 화면

Next.js 공식 문서에서는 현재 Node.js 20.9 이상을 요구합니다.¹ 설치할 때는 가능하면 최신 LTS 버전을 고르세요. LTS는 "오래 안정적으로 지원되는 버전"이라는 뜻입니다. 최신 기능보다 안정성이 중요할 때 고르는 안전한 선택지입니다.

AI 생성 이미지

Node.js 설치하기

먼저 Node.js를 설치합니다.

1. 브라우저에서 node.js를 검색합니다.

2. 공식 사이트에 들어갑니다.

3. LTS라고 표시된 버전을 내려받습니다.

4. 설치 파일을 실행합니다.

5. 특별한 이유가 없다면 계속 Next, Install을 눌러 기본값으로 설치합니다.

설치가 끝났다고 바로 다음 단계로 넘어가지 말고, 제대로 설치되었는지 확인해 봅니다.

윈도우라면 시작 메뉴에서 터미널, PowerShell, 또는 명령 프롬프트를 엽니다. 맥이라면 터미널 앱을 엽니다.

아래 명령어를 입력하고 Enter를 누릅니다.

node -v

예를 들어 이런 식으로 버전 번호가 나오면 정상입니다.

v22.0.0

정확히 같은 숫자일 필요는 없습니다. 중요한 것은 v로 시작하는 버전 번호가 보이는 것입니다. 단, 너무 오래된 숫자가 보인다면 최신 LTS 버전으로 다시 설치하는 편이 좋습니다.

이어서 아래 명령어도 입력합니다.

npm -v

npm은 Node.js와 함께 설치되는 도구입니다. Next.js 프로젝트를 만들고 실행할 때 필요한 여러 재료를 내려받는 역할을 합니다. 스마트폰에서 앱스토어가 앱을 설치해 주듯이, npm은 프로젝트에 필요한 프로그램 묶음을 설치해 줍니다.

만약 node 또는 npm을 찾을 수 없다는 메시지가 나오면, 터미널을 완전히 닫았다가 다시 열어 보세요. 그래도 안 되면 Node.js 설치를 다시 진행하는 것이 가장 빠른 해결책입니다.

VS Code 설치하기

다음으로 VS Code를 설치합니다.

1. 브라우저에서 VS Code를 검색합니다.

2. Microsoft의 Visual Studio Code 공식 사이트에 들어갑니다.

3. 내 컴퓨터에 맞는 설치 파일을 내려받습니다.

4. 설치 파일을 실행합니다.

5. 특별한 이유가 없다면 기본값으로 설치합니다.

설치가 끝나면 VS Code를 한 번 실행해 보세요. 처음 실행했을 때 영어 화면이 나오거나 여러 안내 문구가 보여도 괜찮습니다. 지금 당장 모든 메뉴를 이해할 필요는 없습니다.

이 책에서는 VS Code를 "코드를 전문적으로 다루는 복잡한 프로그램"이라기보다 "Next.js 프로젝트 폴더를 열어 두고 파일을 고치는 작업 공간"으로 사용할 것입니다.

VS Code에서 먼저 익힐 세 가지

VS Code는 기능이 많지만 처음부터 모두 알 필요는 없습니다. 지금은 세 가지만 익히면 됩니다.

1. 폴더 열기

2. 파일 저장하기

3. 파일 검색하기

VS Code를 실행해 보세요. 처음 화면이 복잡해 보여도 괜찮습니다. 우리는 필요한 기능만 사용할 것입니다.

폴더 열기

Next.js 프로젝트는 파일 하나가 아니라 여러 폴더와 파일의 묶음입니다. 그래서 VS Code에서는 파일 하나를 여는 것보다 프로젝트 폴더 전체를 여는 것이 중요합니다.

VS Code에서 다음 메뉴를 찾습니다.

• 윈도우: File > Open Folder

• 맥: File > Open Folder 또는 파일 > 폴더 열기

프로젝트 폴더를 열면 왼쪽에 파일 목록이 나타납니다. 이 영역을 탐색기라고 생각하면 됩니다. 컴퓨터의 파일 탐색기처럼 폴더와 파일을 보여 주는 곳입니다.

파일 저장하기

파일을 수정한 뒤에는 저장해야 합니다.

• 윈도우: Ctrl + S

• 맥: Command + S

파일 이름 옆에 작은 점이 보이면 아직 저장되지 않았다는 뜻입니다. 저장하면 점이 사라집니다. Next.js는 저장된 파일을 기준으로 화면을 다시 보여 줍니다. "수정했는데 화면이 안 바뀐다"면 가장 먼저 저장했는지 확인하세요.

파일 검색하기

프로젝트가 커지면 파일을 직접 찾기 어려워집니다. 이때 검색을 사용합니다.

• 윈도우: Ctrl + P

• 맥: Command + P

파일 이름 일부를 입력하면 관련 파일이 나타납니다. 예를 들어 page라고 입력하면 page.tsx 같은 파일을 빠르게 찾을 수 있습니다.

VS Code는 Node.js 프로젝트 폴더를 열고, 파일을 편집하고 저장하며, 안에 있는 터미널에서 명령어를 실행할 수 있는 작업 공간을 제공합니다.² 처음에는 "코딩 프로그램"이라기보다 "웹사이트 파일을 정리하는 책상"이라고 이해하면 충분합니다.

터미널은 컴퓨터에게 부탁하는 창이다

이제 가장 낯선 도구가 나옵니다. 바로 터미널입니다.

터미널은 검은 화면에 글자를 입력하는 창입니다. 처음 보면 해커 영화처럼 느껴질 수 있습니다. 하지만 실제로는 컴퓨터에게 작업을 부탁하는 창에 가깝습니다.

예를 들어 마우스로 폴더를 열 때는 우리가 직접 클릭합니다. 터미널에서는 이렇게 말로 부탁합니다.

cd Desktop

뜻은 "Desktop 폴더로 이동해 줘"입니다.

Next.js 프로젝트를 만들 때도 터미널에 명령어를 입력합니다. 여기서 명령어를 외울 필요는 없습니다. 책에 있는 것을 복사해서 붙여 넣으면 됩니다. 중요한 것은 명령어의 전체 의미를 대략 이해하는 것입니다.

VS Code 안에서도 터미널을 열 수 있습니다.

• 상단 메뉴에서 Terminal > New Terminal

• 또는 View > Terminal

이렇게 하면 VS Code 아래쪽에 터미널이 열립니다. 앞으로는 가능하면 VS Code 안의 터미널을 사용하겠습니다. 파일을 보는 창과 명령어를 입력하는 창이 한곳에 있어서 덜 헷갈립니다.

프로젝트를 만들 폴더 정하기

프로젝트를 아무 곳에나 만들면 나중에 찾기 어렵습니다. 처음에는 바탕화면이나 문서 폴더 안에 연습용 폴더를 하나 만드는 것을 추천합니다.

예를 들어 바탕화면에 next-practice라는 폴더를 만든다고 해 보겠습니다.

윈도우와 맥 모두 마우스로 폴더를 만들어도 됩니다. 꼭 터미널로 만들 필요는 없습니다. 비개발자에게 중요한 것은 "어디에 만들었는지 기억하는 것"입니다.

추천 구조는 이렇습니다.

바탕화면
└─ next-practice
   └─ my-next-site

next-practice는 연습 프로젝트를 모아 두는 큰 상자입니다. my-next-site는 이번에 만들 Next.js 프로젝트입니다.

create-next-app으로 새 프로젝트 만들기

이제 Next.js 프로젝트를 만듭니다. 공식 문서에서도 새 프로젝트를 시작할 때 create-next-app 사용을 안내합니다.¹

먼저 터미널에서 연습용 폴더로 이동합니다. 예를 들어 바탕화면에 next-practice 폴더를 만들었다면, VS Code에서 그 폴더를 열고 터미널을 여는 방식이 가장 쉽습니다.

그다음 아래 명령어를 입력합니다.

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

이 명령어는 이렇게 읽으면 됩니다.

• npx: 필요한 제작 도구를 잠깐 불러와 실행해 줘

• create-next-app@latest: 최신 Next.js 프로젝트 생성 도구를 사용해 줘

• my-next-site: 프로젝트 폴더 이름은 my-next-site로 만들어 줘

처음 실행하면 "이 패키지를 설치하고 진행할까요?"와 비슷한 질문이 나올 수 있습니다. 그때는 y를 입력하고 Enter를 누르면 됩니다.

그다음 몇 가지 설정 질문이 나올 수 있습니다. 버전에 따라 질문 문장이나 선택지가 조금씩 달라질 수 있으니, 아래 추천값을 기준으로 고르면 됩니다. 질문이 거의 나오지 않고 기본값으로 진행되어도 이상한 것이 아닙니다.

질문이 너무 많아 보여도 겁먹지 마세요. 대부분은 "프로젝트를 어떤 기본 세팅으로 만들까요?"라는 질문입니다. 가구를 주문할 때 색상, 크기, 배송 옵션을 고르는 것과 비슷합니다. 처음에는 위 표대로 고르면 됩니다.

설치가 진행되는 동안 여러 줄의 글자가 빠르게 지나갑니다. 오류처럼 보여도 대부분은 설치 과정에서 나오는 안내문입니다. 마지막에 프로젝트 폴더가 만들어지고 입력 대기 상태로 돌아오면 일단 성공입니다.

프로젝트 폴더로 이동하기

프로젝트를 만들었으면 그 폴더 안으로 들어가야 합니다.

cd my-next-site

cd는 "change directory"의 줄임말입니다. 쉽게 말해 "이 폴더로 들어가 줘"입니다.

현재 내가 어느 폴더에 있는지 헷갈리면 터미널 왼쪽 부분을 보세요. 보통 폴더 이름이 표시됩니다. 정확히 모르겠다면 VS Code에서 my-next-site 프로젝트 폴더를 다시 열어도 됩니다.

VS Code에서 my-next-site 폴더를 열면 왼쪽에 여러 파일과 폴더가 보입니다. 지금은 전부 이해하지 않아도 됩니다. 다음 장에서 프로젝트 폴더를 차근차근 읽어 볼 것입니다.

내 컴퓨터에서 사이트 실행하기

이제 프로젝트를 실행합니다.

npm run dev

이 명령어는 "개발 모드로 사이트를 실행해 줘"라는 뜻입니다. 개발 모드는 완성된 사이트를 인터넷에 올린 상태가 아니라, 내 컴퓨터 안에서 수정하며 확인하는 상태입니다.

잠시 기다리면 터미널에 다음과 비슷한 문장이 보입니다.

Local: http://localhost:3000

브라우저를 열고 아래 주소로 들어갑니다.

http://localhost:3000

여기서 localhost는 인터넷 어딘가에 있는 서버가 아니라 "내 컴퓨터 자신"을 가리키는 주소입니다. 집 주소로 비유하면, 외부 손님에게 알려 주는 주소가 아니라 집 안에서 "여기"라고 부르는 말에 가깝습니다.

:3000은 문 번호처럼 생각하면 됩니다. 내 컴퓨터 안에서 여러 프로그램이 동시에 움직일 수 있기 때문에, 그중 3000번 문으로 들어가 Next.js 사이트를 보는 것입니다.

브라우저에 Next.js 기본 화면이 보이면 성공입니다. 아직 인터넷에 공개된 것은 아닙니다. 내 컴퓨터 안에서만 열리는 연습용 사이트입니다.

멈추고 다시 실행하는 법

개발 서버를 켜 둔 터미널은 계속 실행 중인 상태입니다. 그래서 그 터미널에 다른 명령어를 입력하기 어렵습니다.

사이트 실행을 멈추고 싶으면 터미널에서 다음 키를 누릅니다.

• 윈도우: Ctrl + C

• 맥: Control + C

"종료할까요?" 같은 질문이 나오면 Y를 입력하고 Enter를 누르면 됩니다. 질문 없이 바로 멈추는 경우도 있습니다.

다시 실행하고 싶을 때는 프로젝트 폴더 안에서 다시 입력합니다.

npm run dev

이 흐름을 기억하세요.

1. VS Code에서 프로젝트 폴더를 연다.

2. 터미널을 연다.

3. npm run dev를 입력한다.

4. 브라우저에서 http://localhost:3000을 연다.

5. 파일을 수정하고 저장한다.

6. 브라우저에서 바뀐 화면을 확인한다.

Next.js 작업의 기본 리듬은 이 여섯 단계입니다.

자주 만나는 문제와 확인 순서

처음 설치할 때 자주 만나는 문제는 대부분 비슷합니다. 아래 순서대로 확인해 보세요.

node를 찾을 수 없다고 나올 때

가능한 원인:

• Node.js가 설치되지 않았습니다.

• 설치 후 터미널을 다시 열지 않았습니다.

• 설치가 중간에 실패했습니다.

확인 순서:

1. 터미널을 완전히 닫고 다시 엽니다.

2. node -v를 다시 입력합니다.

3. 그래도 안 되면 Node.js LTS 버전을 다시 설치합니다.

검색 키워드:

node is not recognized after install

npm run dev가 안 될 때

가능한 원인:

• 프로젝트 폴더 안에 들어가지 않았습니다.

• 설치가 끝나기 전에 터미널을 닫았습니다.

• 프로젝트 파일 일부가 없습니다.

확인 순서:

1. 터미널 위치가 my-next-site인지 확인합니다.

2. 왼쪽 파일 목록에 package.json이 있는지 확인합니다.

3. 없다면 프로젝트 폴더를 잘못 열었을 가능성이 큽니다.

4. my-next-site 폴더가 아니라 그 위의 next-practice 폴더에 있다면, cd my-next-site를 입력한 뒤 다시 시도합니다.

검색 키워드:

npm run dev missing package.json next.js

localhost:3000이 안 열릴 때

가능한 원인:

• npm run dev가 실행 중이 아닙니다.

• 주소를 잘못 입력했습니다.

• 이미 다른 프로그램이 3000번 포트를 쓰고 있습니다.

확인 순서:

1. 터미널에 Local: http://localhost:3000이 보이는지 확인합니다.

2. 브라우저 주소창에 http://localhost:3000을 정확히 입력합니다.

3. 터미널에 다른 주소가 표시되면 그 주소로 들어갑니다. 예를 들어 3001이라고 나오면 http://localhost:3001로 들어갑니다.

검색 키워드:

next.js localhost 3000 not working

직접 할 수 있는 일과 맡기면 좋은 일

이 장에서 다룬 작업은 대부분 직접 할 수 있습니다.

직접 해도 좋은 일:

• Node.js LTS 설치하기

• VS Code 설치하기

• 프로젝트 폴더 만들기

• create-next-app으로 새 프로젝트 만들기

• npm run dev로 내 컴퓨터에서 사이트 실행하기

• localhost 주소로 화면 확인하기

전문가에게 도움을 요청하면 좋은 일:

• 회사 보안 정책 때문에 프로그램 설치가 막혀 있을 때

• 사내 컴퓨터 권한 문제로 Node.js 설치가 안 될 때

• 여러 사람이 같은 프로젝트 환경을 맞춰야 할 때

• 오래된 프로젝트의 Node.js 버전 충돌을 해결해야 할 때

처음부터 모든 문제를 혼자 해결하려고 하지 않아도 됩니다. 지금 목표는 개발자가 되는 것이 아니라, Next.js 프로젝트가 어떤 흐름으로 만들어지고 실행되는지 몸으로 익히는 것입니다.

이번 장을 마쳤다면 이미 중요한 선을 넘었습니다. 이제 여러분의 컴퓨터에는 Next.js 사이트를 만들 수 있는 작은 작업실이 생겼습니다. 다음 장에서는 이 작업실 안에 어떤 폴더와 파일이 있는지 하나씩 읽어 보겠습니다.

참고

¹Getting Started: Installation | Next.js

²Node.js tutorial in Visual Studio Code