Nuxt.js를 실무 흐름으로 이해하기
Vue 3 기반 풀스택 SSR 프레임워크. 파일 기반 라우팅, Nitro 서버, useFetch, SEO 최적화, Vercel 배포까지 한국어로 배우세요. 이 가이드는 개념을 나열하기보다, 실제 프로젝트에서 판단해야 하는 순서대로 내용을 따라갈 수 있게 구성했습니다.
Vue 프레임워크 가이드
Nuxt.js 완전 가이드
Vue 3 기반 풀스택 SSR 프레임워크. 파일 기반 라우팅, Nitro 서버, useFetch, SEO 최적화, Vercel 배포까지 한국어로 배우세요.
목차 11개 섹션
가이드 사용법
프론트엔드 / 앱 개발
화면을 그리는 법에서 멈추지 않고, 상태, 데이터 요청, 라우팅, 접근성, 배포 단위까지 함께 봅니다.
구조 다이어그램
글로 읽은 내용을 머릿속에 오래 남기려면 먼저 흐름을 그림으로 잡는 편이 좋습니다. 아래 두 그림은 Nuxt.js를 학습할 때 계속 되돌아볼 수 있는 기준 지도입니다.
학습 흐름
다이어그램 렌더링 중…
아키텍처 관점
다이어그램 렌더링 중…
Nuxt.js란?
Nuxt.js를 처음 펼칠 때는 세부 명령보다 큰 그림이 먼저입니다. 이 섹션에서는 앞으로 배울 개념들이 어떤 문제를 풀기 위해 등장했는지부터 잡아봅니다.
Nuxt는 Vue 위에 파일 기반 라우팅, 서버 사이드 렌더링, API 서버(Nitro)를 하나로 묶은 풀스택 프레임워크입니다. 폴더 구조 자체가 곧 규칙이 되어, pages/에 파일을 추가하면 라우트가, server/api/에 파일을 추가하면 백엔드 엔드포인트가 자동으로 생성됩니다.
BASH
npx nuxi@latest init my-app
cd my-app && npm run dev
# 구조
pages/ # 파일 기반 라우팅
server/api/ # Nitro 서버 API
composables/# 자동 임포트 composables
layouts/ # 레이아웃파일 기반 라우팅
여기서는 파일 기반 라우팅을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
Nuxt는 `pages/` 디렉토리의 파일 구조를 그대로 라우트로 변환합니다. 대괄호로 감싼 파일·폴더 이름(`[id]`)은 동적 세그먼트가 되고, 컴포넌트 안에서는 `useRoute()`로 그 값을 읽습니다.
pages/ 구조 → 라우트TEXT
pages/
index.vue → /
about.vue → /about
users/
index.vue → /users
[id].vue → /users/:id
[id]/
settings.vue → /users/:id/settings
[...slug].vue → /그 외 모든 경로 (catch-all)pages/users/[id].vueVUE
<script setup>
const route = useRoute();
const { data: user } = await useFetch(`/api/users/${route.params.id}`);
</script>
<template>
<h1>{{ user?.name }}</h1>
</template>useFetch / useAsyncData
여기서는 useFetch / useAsyncData을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
useFetch는 서버 사이드에서 한 번 데이터를 가져와 클라이언트로 그대로 전달하기 때문에, 같은 요청을 브라우저에서 중복으로 다시 보내지 않습니다. watch 옵션에 넣은 반응형 값이 바뀌면 자동으로 재요청되므로, userId가 바뀔 때마다 수동으로 fetch를 다시 호출하는 코드를 작성할 필요가 없습니다.
VUE
<script setup>
const userId = ref(1);
// reactive params → userId 변경 시 자동 재실행
const { data: user, pending, error } = useFetch(
() => `/api/users/${userId.value}`,
{ watch: [userId] }
);
</script>
<template>
<p v-if="pending">로딩 중...</p>
<p v-else-if="error">오류 발생</p>
<div v-else>{{ user?.name }}</div>
</template>Nitro 서버 API Routes
여기서는 Nitro 서버 API Routes을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
server/api/ 아래에 파일을 만들면 그 자체가 백엔드 엔드포인트가 되어, 별도의 Express나 NestJS 서버 없이 프런트엔드와 같은 프로젝트 안에서 API를 함께 운영할 수 있습니다. 파일명의 .get.ts 같은 접미사가 HTTP 메서드를 결정하므로 라우터 설정 없이도 REST 규칙을 그대로 따르게 됩니다.
server/api/users/index.get.tsTYPESCRIPT
import { defineEventHandler, getQuery } from 'h3';
export default defineEventHandler(async (event) => {
const { page = 1 } = getQuery(event);
const users = await db.user.findMany({
skip: (Number(page) - 1) * 20,
take: 20,
});
return users;
});SEO & Meta
여기서는 SEO & Meta을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
useSeoMeta는 페이지별 title, description, Open Graph, Twitter Card 태그를 한 번에 선언하게 해주는 컴포저블입니다. Nuxt가 이 값들을 서버 렌더링 단계에서 HTML head에 직접 심어주기 때문에, 검색엔진이나 SNS 크롤러가 자바스크립트를 실행하지 않아도 메타 정보를 그대로 읽을 수 있습니다.
VUE
<script setup>
useSeoMeta({
title: 'My Page',
description: '페이지 설명',
ogTitle: 'My Page',
ogImage: '/og-image.png',
twitterCard: 'summary_large_image',
});
</script>배포
여기서는 배포을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.
Nuxt는 Nitro 엔진 덕분에 같은 코드베이스를 여러 배포 타겟에 맞춰 빌드할 수 있습니다. `nitro.preset`을 지정하지 않으면 Nuxt가 배포 환경(Vercel, Netlify 등)을 자동으로 감지해 알맞은 프리셋을 사용합니다.
BASH
# 기본 Node 서버로 빌드 (SSR)
npm run build
node .output/server/index.mjs
# 완전 정적 사이트로 생성 (SSG)
npx nuxi generatenuxt.config.tsTYPESCRIPT
export default defineNuxtConfig({
nitro: {
preset: 'vercel', // 'node-server' | 'netlify' | 'cloudflare-pages' 등
},
});| 배포 타겟 | 명령 | 특징 |
|---|---|---|
| Node 서버 (SSR) | npm run build | 요청마다 서버 렌더링 — 실시간 데이터에 적합 |
| 정적 사이트 (SSG) | npx nuxi generate | 빌드 시점에 모든 페이지를 HTML로 미리 생성 — 블로그 등에 적합 |
| Vercel/Netlify/Cloudflare | nitro.preset 지정 | 해당 플랫폼의 엣지/서버리스 런타임에 맞춰 자동 최적화 |
Nuxt.js 실무 설계
Nuxt.js 실무 설계은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.
Nuxt는 SSR/CSR/hybrid 전략을 페이지별로 정해야 합니다. auto import와 convention은 편하지만 경계가 흐려지지 않게 관리해야 합니다.
| 결정 지점 | 확인 질문 | 실무 기준 |
|---|---|---|
| 경계 | Nuxt.js 코드에서 바뀌기 쉬운 부분은 어디인가? | 입출력, 설정, 외부 연동, 핵심 규칙을 분리합니다. |
| 상태 | 상태가 어디서 생성되고 어디서 사라지는가? | 상태 소유자와 수명 주기를 코드로 드러냅니다. |
| 장애 | 실패했을 때 호출자는 무엇을 받는가? | timeout, fallback, error contract를 먼저 정합니다. |
Nuxt.js 운영 기준
이 섹션은 Nuxt.js 운영 기준을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.
Nitro server, route rules, payload size, caching, image optimization이 운영 성능에 영향을 줍니다.
Nuxt.js 검증 전략
Nuxt.js 검증 전략은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.
route rules, server API, hydration, SEO metadata를 검증해야 합니다.
| 품질 축 | 검증 방법 | 완료 기준 |
|---|---|---|
| 정확성 | 정상/실패 케이스를 자동화합니다. | 핵심 시나리오가 재현 가능하게 통과합니다. |
| 회귀 방지 | 버그 수정 시 동일 케이스를 테스트로 남깁니다. | 같은 장애가 다시 배포되지 않습니다. |
| 운영성 | 로그, 메트릭, 알림을 확인합니다. | 문제가 생겼을 때 원인 추적 경로가 있습니다. |