프로젝트 폴더는 '웹사이트 작업실'이다
이전 장에서 만든 my-next-site 폴더를 VS Code로 열면 파일과 폴더가 한꺼번에 보입니다. 처음 보면 꽤 복잡합니다. 하지만 지금 모든 것을 이해할 필요는 없습니다.
처음에는 이렇게 생각하면 됩니다.
app폴더: 실제 웹사이트 화면을 만드는 중심 공간public폴더: 이미지, 아이콘 같은 파일을 넣는 창고package.json: 이 프로젝트의 설명서와 준비물 목록나머지 설정 파일들: 당장은 건드리지 않아도 되는 장비 설정표
집을 고칠 때도 전기 배선도부터 보지 않습니다. 먼저 거실, 부엌, 현관이 어디인지 봅니다. Next.js 프로젝트도 마찬가지입니다. 오늘의 목표는 "어떤 파일을 열면 화면이 바뀌는지" 찾는 것입니다.
AI 생성 이미지
처음 보는 폴더 구조 살펴보기
프로젝트마다 약간 다를 수 있지만, 처음 만든 Next.js 프로젝트는 대체로 이런 모양입니다.
my-next-site/
├─ app/
│ ├─ layout.tsx
│ ├─ page.tsx
│ ├─ globals.css
│ └─ favicon.ico
├─ public/
├─ package.json
├─ package-lock.json
├─ next.config.ts
├─ tsconfig.json
├─ eslint.config.mjs
├─ .gitignore
└─ README.md파일 이름 끝이 .tsx가 아니라 .js 또는 .jsx일 수도 있습니다. 지금은 확장자 차이를 깊게 몰라도 됩니다. 중요한 것은 이름입니다.
page라는 이름이 붙으면 실제 페이지 화면과 관련이 있습니다.layout이라는 이름이 붙으면 여러 페이지가 함께 쓰는 공통 틀과 관련이 있습니다.public은 화면에 넣을 이미지 파일을 보관하는 곳입니다.
Next.js 공식 문서에서도 app은 App Router의 주요 폴더이고, public은 정적 파일을 제공하는 폴더이며, package.json은 프로젝트의 의존성과 실행 명령을 담는 파일로 설명합니다.1
app 폴더: 웹사이트의 주요 화면이 사는 곳
app 폴더는 앞으로 가장 자주 열게 될 곳입니다. 쉽게 말해 웹사이트의 "방 배치도"입니다.
브라우저 주소가 집 주소라면, app 폴더 안의 폴더와 파일은 그 집 안의 방 이름에 가깝습니다.
예를 들어 이런 구조가 있다고 해 봅시다.
app/
├─ page.tsx
└─ about/
└─ page.tsx그러면 보통 이렇게 연결됩니다.
app/page.tsx→ 첫 화면, 즉/app/about/page.tsx→ 소개 페이지, 즉/about
여기서 /는 홈페이지 첫 주소를 뜻합니다. 예를 들어 개발 서버를 켜고 http://localhost:3000으로 들어갔을 때 보이는 화면입니다.
아직 about 폴더를 만들 필요는 없습니다. 다음 장과 그다음 장에서 직접 페이지를 바꿔 보고, 폴더로 새 페이지를 만드는 연습을 할 것입니다. 지금은 app/page.tsx가 첫 화면이라는 것만 기억하면 충분합니다.
page 파일: 실제 페이지 내용
page.tsx 또는 page.js는 실제로 화면에 보이는 내용을 담는 파일입니다.
처음 화면을 바꾸고 싶다면 가장 먼저 볼 파일은 보통 이것입니다.
app/page.tsx이 파일을 열면 영어 문장, 링크, 이미지 관련 코드가 보일 수 있습니다. 겁먹지 않아도 됩니다. 지금은 코드 전체를 해석하려고 하지 말고, 화면에 보이는 문장을 찾아보면 됩니다.
예를 들어 브라우저 첫 화면에 "Get started by editing..." 같은 문장이 보인다면, app/page.tsx 안에서도 비슷한 문장을 찾을 수 있습니다. 그 문장을 바꾸고 저장하면 브라우저 화면도 바뀝니다.
이것이 Next.js 작업의 기본 흐름입니다.
브라우저에서 바꾸고 싶은 문장을 본다.
VS Code에서
app/page.tsx를 연다.비슷한 문장을 찾는다.
문장을 수정하고 저장한다.
브라우저에서 결과를 확인한다.
아직 코드를 잘 몰라도 이 방식으로 첫 수정은 가능합니다. 웹사이트 수정은 처음부터 문법을 외우는 일이 아니라, "이 화면이 어느 파일에서 오는지" 찾는 일에서 시작합니다.
layout 파일: 모든 페이지를 감싸는 공통 틀
layout.tsx는 page.tsx와 다릅니다.
page가 각 방 안의 가구라면, layout은 집 전체의 기본 구조에 가깝습니다. 예를 들어 모든 페이지에 공통으로 들어가는 상단 메뉴, 하단 정보, 기본 언어 설정, 전체 글꼴 설정 같은 것을 담당할 수 있습니다.
기본 프로젝트에서는 보통 이 파일이 있습니다.
app/layout.tsx이 파일 안에는 대략 다음과 같은 역할의 코드가 들어 있습니다.
사이트 전체의 기본 정보
모든 페이지를 감싸는 기본 HTML 구조
globals.css같은 전체 디자인 파일 연결화면 안에 실제 페이지 내용을 넣는 자리
여기서 중요한 단어가 children입니다. 영어로는 "자식들"이라는 뜻입니다. 비유하면 액자 속 사진 자리입니다. layout이라는 액자가 있고, 그 안에 각 페이지 내용이 children 자리에 들어갑니다.
초보 단계에서는 layout.tsx를 자주 수정하지 않아도 됩니다. 첫 화면의 문장을 바꾸고 싶다면 layout이 아니라 page를 먼저 보세요.
다만 모든 페이지에 공통으로 들어갈 사이트 이름, 상단 메뉴, 하단 저작권 문구를 넣고 싶을 때는 나중에 layout을 만지게 됩니다.
public 폴더: 이미지와 아이콘을 넣는 창고
public 폴더는 이미지나 아이콘 같은 파일을 넣는 곳입니다.
예를 들어 회사 로고 파일이 logo.png라면 이렇게 넣을 수 있습니다.
public/
└─ logo.png그러면 화면에서는 보통 다음과 같은 주소로 불러올 수 있습니다.
/logo.png주의할 점은 public이라는 이름을 주소에 쓰지 않는다는 것입니다.
파일 위치:
public/logo.png화면에서 부르는 주소:
/logo.png
이 흐름만 기억하면 됩니다. public은 창고이고, 브라우저에서는 창고 안에 있는 물건 이름을 바로 부르는 느낌입니다.
이미지를 실제로 예쁘게 넣는 방법은 뒤의 이미지 장에서 자세히 다룹니다. 지금은 "이미지 파일은 일단 public에 넣을 수 있다" 정도만 알면 충분합니다.
package.json: 프로젝트 설명서와 준비물 목록
package.json은 처음 보면 낯선 글자가 많습니다. 하지만 역할은 단순합니다. 이 파일은 프로젝트의 설명서이자 준비물 목록입니다.
예를 들어 안에는 이런 내용이 들어 있을 수 있습니다.
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
},
"dependencies": {
"next": "...",
"react": "...",
"react-dom": "..."
}
}여기서 scripts는 실행 버튼 목록처럼 이해하면 됩니다.
npm run dev: 개발 중에 사이트를 켭니다.npm run build: 배포하기 전에 완성본을 만듭니다.npm run start: 완성본을 실행합니다.
dependencies는 이 프로젝트가 사용하는 준비물 목록입니다. 예를 들어 next, react, react-dom은 Next.js 프로젝트가 움직이기 위해 필요한 핵심 재료입니다.
초보 단계에서 package.json을 직접 많이 수정할 일은 없습니다. 다만 "내가 입력한 npm run dev가 어디서 온 명령인지" 확인하고 싶을 때 이 파일을 보면 됩니다.
처음에는 건드리지 않아도 되는 파일들
처음 프로젝트를 열면 설정 파일이 많이 보입니다. 이 파일들은 중요하지만, 처음부터 만질 필요는 거의 없습니다.
대표적으로 이런 파일들이 있습니다.
next.config.ts또는next.config.jstsconfig.jsoneslint.config.mjs.gitignorepackage-lock.jsonnext-env.d.ts
하나씩 아주 짧게만 보겠습니다.
next.config는 Next.js의 세부 설정 파일입니다. 특별한 기능을 켜거나 외부 이미지 주소를 허용할 때 만질 수 있습니다. 지금은 그대로 두세요.
tsconfig.json은 TypeScript 설정 파일입니다. TypeScript는 JavaScript에 안전벨트를 채운 도구라고 생각하면 됩니다. 잘못된 사용을 미리 알려 주지만, 설정 파일은 초보 단계에서 수정하지 않아도 됩니다.
eslint.config.mjs는 코드 습관을 검사하는 규칙표입니다. 문장의 맞춤법 검사기처럼, 코드에서 위험하거나 어색한 부분을 알려 줍니다.
.gitignore는 Git에 올리지 않을 파일 목록입니다. Git은 파일 변경 기록을 남기는 도구입니다. 뒤에서 GitHub 배포를 할 때 다시 만납니다.
package-lock.json은 설치된 준비물의 정확한 버전 기록입니다. 직접 고치기보다 자동으로 관리되는 파일이라고 생각하세요.
next-env.d.ts도 자동으로 만들어지는 보조 파일입니다. 직접 수정하지 않는 편이 안전합니다.
처음에는 이 파일들을 열어 볼 수는 있지만, 저장하지 않는 것이 좋습니다. 실수로 바꿨다면 당황하지 말고 Ctrl + Z 또는 Cmd + Z로 되돌리면 됩니다.
절대 손으로 정리하지 말아야 할 폴더
프로젝트 안에는 경우에 따라 이런 폴더도 보일 수 있습니다.
node_modules/
.next/node_modules는 프로젝트가 사용하는 준비물들이 실제로 설치된 큰 창고입니다. 파일이 매우 많습니다. 직접 열어 고치는 곳이 아닙니다.
.next는 Next.js가 개발 서버나 빌드 과정에서 자동으로 만드는 작업 결과물입니다. 이것도 직접 수정하지 않습니다.
정리하고 싶다고 이 폴더 안의 파일을 하나씩 지우면 오류가 날 수 있습니다. 문제가 생겼을 때 폴더를 통째로 삭제하고 다시 설치하는 경우는 있지만, 그건 나중에 오류 해결 장에서 다룹니다. 지금은 "자동 생성 폴더는 손대지 않는다"만 기억하세요.
화면을 바꾸고 싶을 때의 확인 순서
처음에는 아래 순서대로만 움직이면 됩니다.
첫 화면을 바꾸고 싶다 →
app/page.tsx또는app/page.js를 연다.모든 페이지에 공통으로 보이는 부분을 바꾸고 싶다 →
app/layout.tsx또는app/layout.js를 확인한다.이미지 파일을 추가하고 싶다 →
public폴더에 넣는다.실행 명령이 궁금하다 →
package.json의scripts를 본다.설정 파일이 낯설다 → 일단 수정하지 않는다.
이 정도만 알아도 프로젝트 안에서 길을 잃을 가능성이 크게 줄어듭니다.
자주 하는 실수
가장 흔한 실수는 page.tsx의 파일 이름을 바꾸는 것입니다. 예를 들어 page.tsx를 home.tsx로 바꾸면 Next.js가 그 파일을 페이지로 인식하지 못할 수 있습니다. 폴더 이름은 주소가 되고, page 파일은 그 주소에서 보여 줄 화면이 됩니다.
또 다른 실수는 public 폴더 안의 이미지를 불러올 때 /public/logo.png라고 쓰는 것입니다. 앞에서 봤듯이 화면에서 부를 때는 /logo.png처럼 씁니다.
마지막으로 node_modules나 .next 안에서 파일을 찾으려는 경우가 있습니다. 그 안은 직접 작업하는 공간이 아닙니다. 내가 수정할 파일은 대부분 app, 나중에는 components, public 같은 곳에 있습니다.
이번 장에서 기억할 것
Next.js 프로젝트를 처음 열었을 때 모든 파일을 이해하려고 하면 지칩니다. 오늘은 네 가지만 기억하면 됩니다.
app은 화면의 중심입니다. page는 실제 페이지 내용입니다. layout은 여러 페이지를 감싸는 공통 틀입니다. public은 이미지와 아이콘을 넣는 창고입니다. 그리고 package.json은 이 프로젝트의 설명서와 준비물 목록입니다.
다음 장에서는 이 지식을 바탕으로 실제 첫 페이지를 바꿔 봅니다. 이제부터는 파일 이름을 보는 일이 곧 화면을 읽는 일이 됩니다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.