{{ post?.title }}
+{{ post?.content }}
+Loading...
+ {{ data }}
+
+```
+
+Equivalent to using `useLazyFetch`:
+
+```vue
+
+```
+
+### When to Use Each
+
+| Pattern | Use Case |
+|---------|----------|
+| `await useFetch()` | Critical data needed for SEO/initial render |
+| `useFetch({ lazy: true })` | Non-critical data, better perceived performance |
+| `await useLazyFetch()` | Same as lazy, await only ensures initialization |
+
+## Avoid Double Fetching
+
+### ❌ Wrong: Using $fetch Alone in Setup
+
+```vue
+
+```
+
+### ✅ Correct: Use useFetch
+
+```vue
+
+```
+
+## Use Explicit Cache Keys
+
+### ❌ Avoid: Auto-generated Keys
+
+```vue
+
+```
+
+### ✅ Better: Explicit Keys
+
+```vue
+
+```
+
+## Handle Loading States Properly
+
+```vue
+
+
+
+
+
+
+
+
+
+
+```
+
+## Use Lazy Fetching for Non-critical Data
+
+```vue
+
+
+
+
+
+
+```
+
+## Shared Data Across Components
+
+```vue
+
+
+
+
+
+```
+
+## Avoid useAsyncData for Side Effects
+
+### ❌ Wrong: Side Effects in useAsyncData
+
+```vue
+
+```
+
+### ✅ Correct: Use callOnce for Side Effects
+
+```vue
+
+```
+
+
diff --git a/.claude/skills/nuxt/references/best-practices-ssr.md b/.claude/skills/nuxt/references/best-practices-ssr.md
new file mode 100644
index 0000000..2befef0
--- /dev/null
+++ b/.claude/skills/nuxt/references/best-practices-ssr.md
@@ -0,0 +1,355 @@
+---
+name: ssr-best-practices
+description: Avoiding SSR context leaks, hydration mismatches, and proper composable usage
+---
+
+# SSR Best Practices
+
+Patterns for avoiding common SSR pitfalls: context leaks, hydration mismatches, and composable errors.
+
+## The "Nuxt Instance Unavailable" Error
+
+This error occurs when calling Nuxt composables outside the proper context.
+
+### ❌ Wrong: Composable Outside Setup
+
+```ts
+// composables/bad.ts
+// Called at module level - no Nuxt context!
+const config = useRuntimeConfig()
+
+export function useMyComposable() {
+ return config.public.apiBase
+}
+```
+
+### ✅ Correct: Composable Inside Function
+
+```ts
+// composables/good.ts
+export function useMyComposable() {
+ // Called inside the composable - has context
+ const config = useRuntimeConfig()
+ return config.public.apiBase
+}
+```
+
+### Valid Contexts for Composables
+
+Nuxt composables work in:
+- `
+```
+
+### ✅ Correct: Use SSR-safe Alternatives
+
+```vue
+
+```
+
+### ❌ Wrong: Random/Time-based Values
+
+```vue
+
+ Failed to load: {{ error.message }}
+ +{{ Math.random() }}
+ {{ new Date().toLocaleTimeString() }}
+
+```
+
+### ✅ Correct: Use useState for Consistency
+
+```vue
+
+
+
+ {{ randomValue }}
+
+```
+
+### ❌ Wrong: Conditional Rendering on Client State
+
+```vue
+
+
+ Desktop
+
+```
+
+### ✅ Correct: Use CSS or ClientOnly
+
+```vue
+
+
+ Desktop
+ Mobile
+
+
+ {{ data }}
+
+```
+
+## Async Composable Patterns
+
+### ❌ Wrong: Await Before Composable
+
+```vue
+
+```
+
+### ✅ Correct: Get Context First
+
+```vue
+
+```
+
+## Plugin Best Practices
+
+### Client-only Plugins
+
+```ts
+// plugins/analytics.client.ts
+export default defineNuxtPlugin(() => {
+ // Only runs on client
+ initAnalytics()
+})
+```
+
+### Server-only Plugins
+
+```ts
+// plugins/server-init.server.ts
+export default defineNuxtPlugin(() => {
+ // Only runs on server
+ initServerConnections()
+})
+```
+
+### Provide/Inject Pattern
+
+```ts
+// plugins/api.ts
+export default defineNuxtPlugin(() => {
+ const api = createApiClient()
+
+ return {
+ provide: {
+ api,
+ },
+ }
+})
+```
+
+```vue
+
+```
+
+## Third-party Library Integration
+
+### ❌ Wrong: Import at Top Level
+
+```vue
+
+```
+
+### ✅ Correct: Dynamic Import
+
+```vue
+
+```
+
+### Use ClientOnly Component
+
+```vue
+
+ Loading...
+
+ Loading...
+ Error: {{ error.message }}
+
+
+ {{ post.title }}
+
+
+
+```
+
+### With Options
+
+```ts
+const { data } = await useFetch('/api/posts', {
+ // Query parameters
+ query: { page: 1, limit: 10 },
+ // Request body (for POST/PUT)
+ body: { title: 'New Post' },
+ // HTTP method
+ method: 'POST',
+ // Only pick specific fields
+ pick: ['id', 'title'],
+ // Transform response
+ transform: (posts) => posts.map(p => ({ ...p, slug: slugify(p.title) })),
+ // Custom key for caching
+ key: 'posts-list',
+ // Don't fetch on server
+ server: false,
+ // Don't block navigation
+ lazy: true,
+ // Don't fetch immediately
+ immediate: false,
+ // Default value
+ default: () => [],
+})
+```
+
+### Reactive Parameters
+
+```vue
+
+```
+
+### Computed URL
+
+```vue
+
+```
+
+## useAsyncData
+
+For wrapping any async function:
+
+```vue
+
+```
+
+### Multiple Requests
+
+```vue
+
+```
+
+## $fetch
+
+For client-side events (form submissions, button clicks):
+
+```vue
+
+```
+
+**Important**: Don't use `$fetch` alone in setup for initial data - it will fetch twice (server + client). Use `useFetch` or `useAsyncData` instead.
+
+## Return Values
+
+All composables return:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `ShallowRef
+
+
+```
+
+Use in pages:
+
+```vue
+
+```
+
+### `app/middleware/`
+
+Route middleware:
+
+```
+middleware/
+├── auth.ts → Named middleware
+├── admin.ts → Named middleware
+└── logger.global.ts → Global middleware (runs on every route)
+```
+
+### `app/plugins/`
+
+Nuxt plugins (auto-registered):
+
+```
+plugins/
+├── 01.analytics.ts → Order with number prefix
+├── 02.auth.ts
+├── vue-query.client.ts → Client-only plugin
+└── server-init.server.ts → Server-only plugin
+```
+
+### `server/` Directory
+
+Nitro server code:
+
+```
+server/
+├── api/
+│ ├── users.ts → GET /api/users
+│ ├── users.post.ts → POST /api/users
+│ └── users/[id].ts → /api/users/:id
+├── routes/
+│ └── sitemap.xml.ts → /sitemap.xml
+├── middleware/
+│ └── auth.ts → Runs on every request
+├── plugins/
+│ └── db.ts → Server startup plugins
+└── utils/
+ └── db.ts → Auto-imported server utilities
+```
+
+### `public/` Directory
+
+Static assets served at root URL:
+
+```
+public/
+├── favicon.ico → /favicon.ico
+├── robots.txt → /robots.txt
+└── images/
+ └── logo.png → /images/logo.png
+```
+
+### `assets/` Directory
+
+Build-processed assets:
+
+```
+assets/
+├── css/
+│ └── main.css
+├── images/
+│ └── hero.png
+└── fonts/
+ └── custom.woff2
+```
+
+Reference in components:
+
+```vue
+
+ 
+
+
+
+```
+
+## Special Files
+
+| File | Purpose |
+|------|---------|
+| `app/app.vue` | Root component (optional with pages/) |
+| `app/app.config.ts` | Runtime app configuration |
+| `app/error.vue` | Custom error page |
+| `app/router.options.ts` | Vue Router configuration (Nuxt 4) |
+| `app/spa-loading-template.html` | SPA loading UI |
+| `nuxt.config.ts` | Build-time configuration |
+| `.nuxtignore` | Ignore files from Nuxt |
+| `.env` | Environment variables |
+
+## File Naming Conventions
+
+| Pattern | Meaning |
+|---------|---------|
+| `[param]` | Dynamic route parameter |
+| `[[param]]` | Optional parameter |
+| `[...slug]` | Catch-all route |
+| `(group)` | Route group (not in URL) |
+| `.client.vue` | Client-only component |
+| `.server.vue` | Server-only component |
+| `.global.ts` | Global middleware |
+
+
diff --git a/.claude/skills/nuxt/references/core-modules.md b/.claude/skills/nuxt/references/core-modules.md
new file mode 100644
index 0000000..dab3f95
--- /dev/null
+++ b/.claude/skills/nuxt/references/core-modules.md
@@ -0,0 +1,292 @@
+---
+name: nuxt-modules
+description: Creating and using Nuxt modules to extend framework functionality
+---
+
+# Nuxt Modules
+
+Modules extend Nuxt's core functionality. They run at build time and can add components, composables, plugins, and configuration.
+
+## Using Modules
+
+Install and add to `nuxt.config.ts`:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+ modules: [
+ // npm package
+ '@nuxt/ui',
+ // Local module
+ './modules/my-module',
+ // Inline module
+ (options, nuxt) => {
+ console.log('Inline module')
+ },
+ // With options
+ ['@nuxt/image', { provider: 'cloudinary' }],
+ ],
+})
+```
+
+## Creating Modules
+
+### Basic Module
+
+```ts
+// modules/my-module.ts
+export default defineNuxtModule({
+ meta: {
+ name: 'my-module',
+ configKey: 'myModule',
+ },
+ defaults: {
+ enabled: true,
+ },
+ setup(options, nuxt) {
+ if (!options.enabled) return
+
+ console.log('My module is running!')
+ },
+})
+```
+
+### Adding Components
+
+```ts
+// modules/ui/index.ts
+import { addComponent, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+ setup(options, nuxt) {
+ const { resolve } = createResolver(import.meta.url)
+
+ // Add single component
+ addComponent({
+ name: 'MyButton',
+ filePath: resolve('./runtime/components/MyButton.vue'),
+ })
+
+ // Add components directory
+ addComponentsDir({
+ path: resolve('./runtime/components'),
+ prefix: 'My',
+ })
+ },
+})
+```
+
+### Adding Composables
+
+```ts
+// modules/utils/index.ts
+import { addImports, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+ setup() {
+ const { resolve } = createResolver(import.meta.url)
+
+ // Add auto-imported composable
+ addImports({
+ name: 'useMyUtil',
+ from: resolve('./runtime/composables/useMyUtil'),
+ })
+
+ // Add directory for auto-imports
+ addImportsDir(resolve('./runtime/composables'))
+ },
+})
+```
+
+### Adding Plugins
+
+```ts
+// modules/analytics/index.ts
+import { addPlugin, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+ setup() {
+ const { resolve } = createResolver(import.meta.url)
+
+ addPlugin({
+ src: resolve('./runtime/plugin'),
+ mode: 'client', // 'client', 'server', or 'all'
+ })
+ },
+})
+```
+
+Plugin file:
+
+```ts
+// modules/analytics/runtime/plugin.ts
+export default defineNuxtPlugin((nuxtApp) => {
+ nuxtApp.hook('page:finish', () => {
+ console.log('Page loaded')
+ })
+})
+```
+
+### Adding Server Routes
+
+```ts
+// modules/api/index.ts
+import { addServerHandler, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+ setup() {
+ const { resolve } = createResolver(import.meta.url)
+
+ addServerHandler({
+ route: '/api/my-endpoint',
+ handler: resolve('./runtime/server/api/my-endpoint'),
+ })
+ },
+})
+```
+
+### Extending Config
+
+```ts
+// modules/config/index.ts
+export default defineNuxtModule({
+ setup(options, nuxt) {
+ // Add CSS
+ nuxt.options.css.push('my-module/styles.css')
+
+ // Add runtime config
+ nuxt.options.runtimeConfig.public.myModule = {
+ apiUrl: options.apiUrl,
+ }
+
+ // Extend Vite config
+ nuxt.options.vite.optimizeDeps ||= {}
+ nuxt.options.vite.optimizeDeps.include ||= []
+ nuxt.options.vite.optimizeDeps.include.push('some-package')
+ },
+})
+```
+
+## Module Hooks
+
+```ts
+export default defineNuxtModule({
+ setup(options, nuxt) {
+ // Build-time hooks
+ nuxt.hook('modules:done', () => {
+ console.log('All modules loaded')
+ })
+
+ nuxt.hook('components:dirs', (dirs) => {
+ dirs.push({ path: '~/extra-components' })
+ })
+
+ nuxt.hook('pages:extend', (pages) => {
+ pages.push({
+ name: 'custom-page',
+ path: '/custom',
+ file: resolve('./runtime/pages/custom.vue'),
+ })
+ })
+
+ nuxt.hook('imports:extend', (imports) => {
+ imports.push({ name: 'myHelper', from: 'my-package' })
+ })
+ },
+})
+```
+
+## Module Options
+
+Type-safe options with defaults:
+
+```ts
+export interface ModuleOptions {
+ apiKey: string
+ enabled?: boolean
+ prefix?: string
+}
+
+export default defineNuxtModule
+ Header
+
+
+```
+
+```vue
+
+
+
+
+
+
+
+```
+
+Use in pages:
+
+```vue
+
+```
+
+Dynamic layout:
+
+```vue
+
+```
+
+## Navigation Hooks
+
+```vue
+
+```
+
+
diff --git a/.claude/skills/nuxt/references/features-components-autoimport.md b/.claude/skills/nuxt/references/features-components-autoimport.md
new file mode 100644
index 0000000..cd815c8
--- /dev/null
+++ b/.claude/skills/nuxt/references/features-components-autoimport.md
@@ -0,0 +1,328 @@
+---
+name: components-auto-imports
+description: Auto-imported components, lazy loading, and hydration strategies
+---
+
+# Components Auto-imports
+
+Nuxt automatically imports Vue components from `app/components/` directory.
+
+## Basic Auto-imports
+
+```
+components/
+├── Button.vue →
+├── Card.vue →
+
+
+ Something went wrong: {{ error.message }}
+ +Loading chart...
+ +
+
+ Modal content
+ +
+ Counter: {{ counter }}
+
+
+
+
+```
+
+## Creating Shared State
+
+Define reusable state composables:
+
+```ts
+// composables/useUser.ts
+export function useUser() {
+ return useState
+
+
+
+
+```
+
+## Hybrid Rendering
+
+Mix rendering modes per route using route rules:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+ routeRules: {
+ // Static pages - prerendered at build
+ '/': { prerender: true },
+ '/about': { prerender: true },
+
+ // ISR - regenerate in background
+ '/blog/**': { isr: 3600 }, // Cache for 1 hour
+ '/products/**': { swr: true }, // Stale-while-revalidate
+
+ // Client-only rendering
+ '/admin/**': { ssr: false },
+ '/dashboard/**': { ssr: false },
+
+ // Server-rendered (default)
+ '/api/**': { cors: true },
+ },
+})
+```
+
+### Route Rules Reference
+
+| Rule | Description |
+|------|-------------|
+| `prerender: true` | Pre-render at build time |
+| `ssr: false` | Client-side only |
+| `swr: number \| true` | Stale-while-revalidate caching |
+| `isr: number \| true` | Incremental static regeneration |
+| `cache: { maxAge: number }` | Cache with TTL |
+| `redirect: string` | Redirect to another path |
+| `cors: true` | Add CORS headers |
+| `headers: object` | Custom response headers |
+
+### Inline Route Rules
+
+Define per-page:
+
+```vue
+
+```
+
+## Prerendering
+
+Generate static HTML at build time:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+ // Prerender specific routes
+ routeRules: {
+ '/': { prerender: true },
+ '/about': { prerender: true },
+ '/posts/*': { prerender: true },
+ },
+})
+```
+
+Or use `nuxt generate`:
+
+```bash
+nuxt generate
+```
+
+### Programmatic Prerendering
+
+In Nuxt 4, `prerender:routes` receives a `Set` (not an array):
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+ hooks: {
+ async 'prerender:routes'({ routes }) {
+ // routes is a SetLoading...
+Loading...
+ +
+ {{ label }}
+
+ {{ value }}
+
+
+
+
+
diff --git a/app/components/PageLayout.vue b/app/components/PageLayout.vue
new file mode 100644
index 0000000..a6636f4
--- /dev/null
+++ b/app/components/PageLayout.vue
@@ -0,0 +1,50 @@
+
+
+
+
+
+
+
+
+
diff --git a/app/pages/hybrid.vue b/app/pages/hybrid.vue
new file mode 100644
index 0000000..629c176
--- /dev/null
+++ b/app/pages/hybrid.vue
@@ -0,0 +1,103 @@
+
+
+ ← 목록으로
+
+
+
+
+
+ {{ badge }}
+
+
+ {{ title }}
+
+
+
+
+
+
+
+
+ 동작 원리
+-
+
+
+ 설정 코드
+
+
+
+ {{ isDev ? '⚠ 개발 모드' : '✓ 프로덕션 모드' }}
+ {{ isDev
+ ? ' — ISR은 개발 서버에서 동작하지 않습니다. nuxt build 후 nuxt preview로 확인하세요.'
+ : ' — ISR이 활성화되어 있습니다. 서버 렌더링 시간이 60초간 고정됩니다.'
+ }}
+
+
+
+ -
+
npm run build→npm run preview실행
+ - 이 페이지를 열고 서버 렌더링 시간 기록 +
- 60초 이내 새로고침 → 서버 시간이 동일함 (캐시) +
- 60초 후 새로고침 → 여전히 이전 값 (캐시 반환 + 백그라운드 재생성 시작) +
- 한 번 더 새로고침 → 서버 시간이 변경됨 (새 HTML) +
swr: true는 TTL 없이 항상 캐시를 반환하고 매 요청마다 백그라운드 갱신합니다.{{ codeExample }}
+
+
+
+
+
+
diff --git a/app/pages/spa.vue b/app/pages/spa.vue
new file mode 100644
index 0000000..804a9e6
--- /dev/null
+++ b/app/pages/spa.vue
@@ -0,0 +1,39 @@
+
+ Nuxt 4 렌더링 전략 데모
+각 페이지에서 렌더링 방식의 차이를 확인해보세요.
+ +
+
+
+
+
+
+
+
+ {{ page.badge }}
+
+ {{ page.title }}
+
+ {{ page.description }}
+
+
+ 전략 비교
+
+
+
+
+
+ | + {{ col }} + | +
|---|
| + |
defineRouteRules({ ssr: false })로 서버 렌더링을 비활성화합니다.{{ codeExample }}
+
+ routeRules: { '/ssg': { prerender: true } }로 설정합니다.
+ nuxt generate 실행 시 /api/build-time을 딱 1회 호출하고,
+ 응답값을 HTML 안의 Nuxt payload에 직렬화합니다.
+ +
<script>window.__NUXT__ = { data: { time: "2026-..." } }</script>
+ nuxt generate 재실행 + 재배포가 필요합니다.
+ 자주 바뀌는 데이터라면 재배포 없이 자동 재생성하는 ISR(isr: N) 또는
+ SWR(swr: true)을 고려하세요.
+ npm run generate 후
+ .output/public/ssg/index.html을 열어 __NUXT__를 검색하면
+ 빌드 시 생성된 시간값이 HTML에 포함된 것을 볼 수 있습니다.
+ {{ codeExample }}
+
+ /api/time을 호출하고 HTML을 완성해 전달합니다.{{ codeExample }}
+
+ 로딩 중...
+ +로딩 중...
+ 에러: {{ error.message }}
+ -
+
- {{ item.name }} +