From 5070852ab8cb0c57e64e414221fc42ec195be79e Mon Sep 17 00:00:00 2001 From: gil Date: Wed, 13 May 2026 00:34:38 +0900 Subject: [PATCH] docs: update wiki with new pages and content - Removed `.claude/` from .gitignore - Updated index.md to reflect the addition of 7 new wiki pages, increasing total pages to 11 - Added detailed summaries for new pages including rendering modes, lifecycle, routing, data fetching, state management, auto imports, layers, performance, and runtime config - Created nuxt-runtime-config.md to document runtime configuration and environment variable handling - Updated log.md to include entries for newly created wiki pages --- .gitignore | 1 - wiki/index.md | 13 ++- wiki/log.md | 17 ++++ wiki/nuxt-runtime-config.md | 159 ++++++++++++++++++++++++++++++++++++ 4 files changed, 186 insertions(+), 4 deletions(-) create mode 100644 wiki/nuxt-runtime-config.md diff --git a/.gitignore b/.gitignore index 0e7bddc..f47d6e1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ .DS_Store node_modules/ .obsidian/ -.claude/ diff --git a/wiki/index.md b/wiki/index.md index 300531f..4d809a8 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -1,7 +1,7 @@ # Nuxt 개발 지식 위키 — 전체 목차 > **마지막 업데이트:** 2026-05-13 -> **총 페이지:** 4개 | **총 raw 자료:** 6개 +> **총 페이지:** 11개 | **총 raw 자료:** 6개 --- @@ -11,7 +11,13 @@ _Nuxt 라이프사이클, 렌더링 모드, 라우팅, 레이어 등 Nuxt의 근 | 페이지 | 요약 | |---|---| -| _(아직 없음)_ | | +| [[nuxt-rendering-modes]] | Universal SSR, CSR, Hybrid, Prerendering, Edge-Side Rendering 비교와 routeRules 설정 | +| [[nuxt-lifecycle]] | 서버·클라이언트 라이프사이클 순서, 실행 환경 분기, 하이드레이션 주의사항 | +| [[nuxt-routing]] | 파일 기반 라우팅, 동적 라우트, 미들웨어 3종류, validate, definePageMeta | +| [[nuxt-data-fetching]] | $fetch·useFetch·useAsyncData 비교, lazy/server/watch/pick 옵션, 캐시 key 전략 | +| [[nuxt-state-management]] | useState 패턴, callOnce 초기화, Pinia 통합, 공유 상태 composable | +| [[nuxt-auto-imports]] | 자동 임포트 대상·제약·설정, 서드파티 패키지 임포트, 명시적 임포트 | +| [[nuxt-layers]] | 레이어 설정·우선순위·오버라이드, DDD 모듈화, npm·GitHub 레이어 확장 | --- @@ -54,7 +60,8 @@ _번들 최적화, 캐싱 전략, CI/CD, 호스팅 환경별 설정_ | 페이지 | 요약 | |---|---| -| _(아직 없음)_ | | +| [[nuxt-performance]] | Lazy 컴포넌트·Hydration, NuxtImage·Fonts·Scripts, 하이드레이션 오류 5가지 원인과 해결 | +| [[nuxt-runtime-config]] | runtimeConfig 서버/public 분리, 환경 변수 오버라이드 규칙, TypeScript 타입 추가 | --- diff --git a/wiki/log.md b/wiki/log.md index e27722d..762e3fa 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -46,4 +46,21 @@ raw 자료 6개를 바탕으로 위키 페이지 4개 생성. --- +### 위키 페이지 생성 — Nuxt 공식 문서 정리 +`reference/` 공식 문서를 바탕으로 핵심 주제별 위키 페이지 7개 생성. + +| 페이지 | 주요 reference 파일 | +|---|---| +| `nuxt-rendering-modes.md` | 3.guide/1.concepts/1.rendering, 1.getting-started/15.prerendering, 16.deployment | +| `nuxt-lifecycle.md` | 3.guide/1.concepts/2.nuxt-lifecycle | +| `nuxt-routing.md` | 1.getting-started/07.routing | +| `nuxt-data-fetching.md` | 1.getting-started/10.data-fetching, 4.api/2.composables/use-fetch | +| `nuxt-state-management.md` | 1.getting-started/11.state-management | +| `nuxt-auto-imports.md` | 3.guide/1.concepts/3.auto-imports | +| `nuxt-layers.md` | 1.getting-started/14.layers | +| `nuxt-performance.md` | 3.guide/2.best-practices/performance, hydration | +| `nuxt-runtime-config.md` | 3.guide/6.going-further/10.runtime-config | + +--- + _이후 자료를 넣을 때마다 아래에 추가됩니다._ diff --git a/wiki/nuxt-runtime-config.md b/wiki/nuxt-runtime-config.md new file mode 100644 index 0000000..23d1956 --- /dev/null +++ b/wiki/nuxt-runtime-config.md @@ -0,0 +1,159 @@ +# Nuxt Runtime Config & 환경 변수 + +> **카테고리:** 성능 & 배포 +> **최종 수정:** 2026-05-13 +> **관련:** [[nuxt-lifecycle]], [[nuxt-layers]] + +## 요약 + +`runtimeConfig`는 빌드 시 고정되지 않고 런타임에 환경 변수로 덮어쓸 수 있는 설정이다. `runtimeConfig.public`은 클라이언트에도 노출되고, 그 외는 서버 전용. + +--- + +## 기본 설정 + +```typescript +// nuxt.config.ts +export default defineNuxtConfig({ + runtimeConfig: { + // 서버 전용 (클라이언트 노출 안됨) + apiSecret: '123', + dbPassword: '', + + // public: 서버·클라이언트 모두 접근 가능 + public: { + apiBase: '/api', + appVersion: '1.0.0', + }, + }, +}) +``` + +--- + +## 환경 변수로 오버라이드 + +### 네이밍 규칙 + +`NUXT_` 접두사 + 대문자 + `_`로 구분: + +```ini +# .env +NUXT_API_SECRET=prod-secret-token +NUXT_PUBLIC_API_BASE=https://api.example.com +NUXT_DB_PASSWORD=secret123 +``` + +```typescript +// 런타임에 자동으로 오버라이드됨 +runtimeConfig: { + apiSecret: '', // → NUXT_API_SECRET + dbPassword: '', // → NUXT_DB_PASSWORD + public: { + apiBase: '/api', // → NUXT_PUBLIC_API_BASE + }, +} +``` + +> ⚠️ 주의: `.env` 파일은 개발·빌드·generate 시에만 읽힘. 프로덕션 서버 실행 시에는 **`.env` 미적용**. 환경 변수는 OS 또는 플랫폼에서 직접 설정해야 함. + +--- + +## 접근 방법 + +### Vue 컴포넌트에서 + +```vue + +``` + +> ⚠️ 주의: 서버 전용 키를 template에 렌더링하거나 `useState`에 저장하면 클라이언트에 노출됨. + +### 플러그인에서 + +```typescript +// app/plugins/api.ts +export default defineNuxtPlugin((nuxtApp) => { + const config = useRuntimeConfig() + // config.public.apiBase 사용 +}) +``` + +### 서버 API 라우트에서 + +```typescript +// server/api/data.ts +export default defineEventHandler(async (event) => { + const { apiSecret } = useRuntimeConfig(event) // event 전달 권장 + const result = await $fetch('https://external-api.com/data', { + headers: { Authorization: `Bearer ${apiSecret}` }, + }) + return result +}) +``` + +--- + +## TypeScript 타입 추가 + +```typescript +// index.d.ts +declare module 'nuxt/schema' { + interface RuntimeConfig { + apiSecret: string + dbPassword: string + } + interface PublicRuntimeConfig { + apiBase: string + appVersion: string + } +} +export {} +``` + +--- + +## 직렬화 주의사항 + +`runtimeConfig`는 Nitro로 전달 전 직렬화됨. 함수, Set, Map, 클래스 인스턴스는 설정하면 안 됨. + +```typescript +// ❌ 직렬화 불가 +runtimeConfig: { + myFn: () => 'hello', // 함수 불가 +} + +// ✅ 플러그인에서 처리 +// app/plugins/my-plugin.ts +export default defineNuxtPlugin(() => { + const myFn = () => 'hello' + return { provide: { myFn } } +}) +``` + +--- + +## `public` vs 일반 설정 비교 + +| | `runtimeConfig` | `runtimeConfig.public` | `appConfig` | +|---|---|---|---| +| 노출 대상 | 서버 전용 | 서버·클라이언트 | 서버·클라이언트 | +| 런타임 오버라이드 | ✅ (환경 변수) | ✅ (환경 변수) | ❌ | +| 빌드 후 변경 | ✅ | ✅ | ❌ | +| 용도 | API 키, 시크릿 | 공개 API URL, 앱 버전 | 테마, UI 설정 | + +--- + +## 참고 / 출처 + +- `reference/3.guide/6.going-further/10.runtime-config.md`