Ch 03. 디렉토리 구조 완전 정복

프로젝트를 생성하고 나면 여러 폴더와 파일이 보입니다. 처음에는 낯설 수 있지만, 각 폴더의 역할을 알고 나면 어디에 무엇을 넣어야 할지 자연스럽게 감이 옵니다. Nuxt 3는 폴더 위치만으로 동작 방식을 결정하는 '컨벤션 기반' 프레임워크이기 때문에, 구조를 이해하는 것이 곧 Nuxt를 이해하는 것입니다.

전체 구조

my-nuxt-app/
├── .nuxt/          # 빌드 산출물 (git 제외)
├── node_modules/
├── pages/          # 라우팅 자동 생성
├── components/     # 자동 임포트 컴포넌트
├── composables/    # 자동 임포트 Composable
├── layouts/        # 레이아웃 템플릿
├── server/         # Nitro 서버 (API 라우트)
│   └── api/
├── public/         # 정적 파일
├── assets/         # Vite 처리 파일
├── app.vue         # 앱 진입점
├── nuxt.config.ts  # Nuxt 설정
└── package.json

각 폴더 역할

.nuxt/

개발 서버 실행 또는 빌드 시 Nuxt가 자동으로 생성하는 폴더입니다. 타입 정의, 라우터 설정, 플러그인 초기화 코드 등이 담깁니다. 이 폴더의 파일은 절대 직접 수정하지 않습니다. 수정해도 다음 빌드 때 덮어씌워집니다.

pages/

이 폴더에 .vue 파일을 만들면 Nuxt가 자동으로 라우트를 생성합니다. pages/about.vue를 만들면 /about 경로가 생기는 식입니다. 중요한 점은 pages/ 폴더가 없으면 파일 기반 라우팅 자체가 활성화되지 않는다는 것입니다. 처음 생성된 프로젝트에는 이 폴더가 없을 수 있으므로, 직접 만들어야 합니다.

components/

Vue 컴포넌트를 이 폴더에 넣으면 어디서든 import 없이 바로 사용할 수 있습니다. Nuxt가 자동 임포트를 처리하기 때문입니다. 하위 폴더로 구조화하면 컴포넌트 이름에 폴더명이 접두어로 붙습니다. components/base/Button.vue는 <BaseButton />으로 사용합니다.

composables/

Vue 3의 Composition API 기반 재사용 로직을 담는 폴더입니다. 여기에 넣은 함수도 자동 임포트됩니다. composables/useCounter.ts에 정의한 useCounter는 어느 컴포넌트에서든 바로 호출할 수 있습니다.

layouts/

여러 페이지에서 공통으로 사용하는 레이아웃 템플릿을 관리합니다. layouts/default.vue가 기본 레이아웃이며, 각 페이지에서 definePageMeta로 다른 레이아웃을 지정할 수 있습니다.

server/api/

Nitro 기반의 서버 API 엔드포인트를 정의합니다. server/api/hello.ts를 만들면 /api/hello 경로가 생깁니다. 데이터베이스 연결, 외부 API 호출 등 서버 사이드 로직은 이 폴더에서 처리합니다.

public/

이미지, 폰트, robots.txt 등 그대로 제공할 정적 파일을 보관합니다. public/logo.png는 브라우저에서 /logo.png로 접근할 수 있습니다.

assets/

Vite가 번들링 과정에서 처리하는 파일들을 담습니다. CSS, SCSS, 처리가 필요한 이미지 파일 등이 여기에 들어갑니다. public/과 달리 직접 URL로 접근할 수 없고, 코드에서 import하거나 ~/assets/ 경로로 참조합니다.