Nuxt Framework Priming

Note: This command references the nuxt:nuxt skill for progressive disclosure of additional patterns and module-specific documentation.

Data Fetching

useFetch for API Calls

Use useFetch for API endpoints. It runs on both server and client, with automatic hydration.

const { data, status, error, refresh } = await useFetch("/api/users")

// With query parameters
const { data, status } = await useFetch("/api/users", {
  query: { limit: 10, page: 1 },
})

// With type safety
interface User {
  id: number
  name: string
}
const { data, status, error } = await useFetch<User[]>("/api/users")

Handle all states in templates:

<template>
  <div v-if="status === 'pending'">Loading...</div>
  <div v-else-if="status === 'error'">
    <p>Error: {{ error?.message }}</p>
  </div>
  <div v-else-if="data">
    <!-- Success state -->
    <ul>
      <li v-for="user of data" :key="user.id">{{ user.name }}</li>
    </ul>
  </div>
</template>

useAsyncData for Complex Data

Use useAsyncData when you need more control or complex transformations.

const { data, status, error } = await useAsyncData("users", async () => {
  const users = await $fetch("/api/users")
  const stats = await $fetch("/api/stats")
  return { users, stats }
})

// With caching key
const { data, status, error } = await useAsyncData(`user-${id}`, () =>
  $fetch(`/api/users/${id}`),
)

Lazy Fetching

Use lazy variants when you don't want to block navigation:

// Non-blocking
const { status, data } = await useLazyFetch('/api/users')

// Show loading state
<div v-if="status === 'pending'">Loading...</div>
<div v-else>{{ data }}</div>

Client-Only Fetching

const { data } = await useFetch("/api/users", {
  server: false, // Only fetch on client
})

Refresh and Refetch

const { data, status, refresh } = await useFetch("/api/users")

// Manually refetch
await refresh()

// Refetch on event
watch(searchQuery, () => refresh())

SEO and Meta Tags

useHead

useHead({
  title: "My Page",
  meta: [
    { name: "description", content: "Page description" },
    { property: "og:title", content: "My Page" },
  ],
  link: [{ rel: "canonical", href: "https://example.com/page" }],
})

useSeoMeta (Type-Safe)

useSeoMeta({
  title: "My Page",
  description: "Page description",
  ogTitle: "My Page",
  ogDescription: "Page description",
  ogImage: "https://example.com/image.jpg",
  twitterCard: "summary_large_image",
})

definePageMeta

definePageMeta({
  title: "User Profile",
  description: "View user profile",
  middleware: ["auth"],
})

Error Handling

Show Error Page

showError({
  statusCode: 404,
  message: "Page not found",
})

// With custom error
showError({
  statusCode: 403,
  message: "Access denied",
  fatal: true,
})

Clear Error

clearError({ redirect: "/" })

Handle Errors in Data Fetching

const { data, status, error } = await useFetch("/api/users")

if (error.value) {
  showError({
    statusCode: error.value.statusCode,
    message: error.value.message,
  })
}

Error Component

<!-- error.vue -->
<template>
  <div>
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p>
    <button @click="handleError">Go Home</button>
  </div>
</template>

<script setup lang="ts">
const { error } = defineProps<{
  error: { statusCode: number; message: string }
}>()

function handleError() {
  clearError({ redirect: "/" })
}
</script>

Environment Variables and Config

Runtime Config

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Private (server-only)
    apiSecret: process.env.API_SECRET,
    databaseUrl: process.env.DATABASE_URL,

    // Public (exposed to client)
    public: {
      apiBase: process.env.API_BASE_URL || "http://localhost:3000",
      environment: process.env.NODE_ENV,
    },
  },
})

// Usage
const config = useRuntimeConfig()
console.log(config.public.apiBase) // Available everywhere
console.log(config.apiSecret) // Server-only

App Config

For non-sensitive configuration that can be updated at runtime:

// app.config.ts
export default defineAppConfig({
  theme: {
    primaryColor: "#3b82f6",
  },
})

// Usage
const appConfig = useAppConfig()
console.log(appConfig.theme.primaryColor)

Server API Routes

GET Request

// server/api/users.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event)

  return {
    users: [
      { id: 1, name: "Alice" },
      { id: 2, name: "Bob" },
    ],
  }
})

POST Request

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)

  // Validate and save user
  return { success: true, user: body }
})

Dynamic Routes

// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, "id")

  // Fetch user by id
  return { id, name: "User" }
})

Error Handling in API Routes

export default defineEventHandler(async (event) => {
  try {
    const data = await fetchData()
    return data
  } catch (error) {
    throw createError({
      statusCode: 500,
      message: "Internal server error",
    })
  }
})

Protected API Routes

// server/api/admin/users.get.ts
export default defineEventHandler(async (event) => {
  const session = await requireUserSession(event)

  if (!session.user.isAdmin) {
    throw createError({
      statusCode: 403,
      message: "Forbidden",
    })
  }

  return { users: [] }
})

Middleware

Route Middleware

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const user = useState("user")

  if (!user.value) {
    return navigateTo("/login")
  }
})

// Usage in page
definePageMeta({
  middleware: "auth",
})

Global Middleware

// middleware/analytics.global.ts
export default defineNuxtRouteMiddleware((to, from) => {
  // Track page view
  console.log("Navigating to:", to.path)
})

State Management

useState

For shared state across components:

// composables/useAuth.ts
export const useAuth = () => {
  const user = useState<User | null>("user", () => null)
  const isAuthenticated = computed(() => !!user.value)

  async function login(credentials: LoginCredentials) {
    const response = await $fetch("/api/auth/login", {
      method: "POST",
      body: credentials,
    })
    user.value = response.user
  }

  function logout() {
    user.value = null
  }

  return {
    user,
    isAuthenticated,
    login,
    logout,
  }
}

// Usage in component
const { user, login, logout } = useAuth()

Composables

Auto-Import from composables/

// composables/useCounter.ts
export const useCounter = () => {
  const count = ref(0)

  function increment() {
    count.value++
  }

  function decrement() {
    count.value--
  }

  return {
    count,
    increment,
    decrement,
  }
}

// Usage (auto-imported)
const { count, increment } = useCounter()

Layouts

Default Layout

<!-- layouts/default.vue -->
<template>
  <div>
    <header>
      <nav>Navigation</nav>
    </header>
    <main>
      <slot />
    </main>
    <footer>Footer</footer>
  </div>
</template>

Custom Layout

<!-- layouts/admin.vue -->
<template>
  <div class="admin-layout">
    <aside>Sidebar</aside>
    <main>
      <slot />
    </main>
  </div>
</template>

<!-- Usage in page -->
<script setup lang="ts">
definePageMeta({
  layout: "admin",
})
</script>

Dynamic Layout

setPageLayout("admin")

Plugins

Client-Only Plugin

// plugins/analytics.client.ts
export default defineNuxtPlugin(() => {
  // Only runs on client
  console.log("Client-side analytics initialized")
})

Server-Only Plugin

// plugins/database.server.ts
export default defineNuxtPlugin(() => {
  // Only runs on server
  return {
    provide: {
      db: createDatabaseConnection(),
    },
  }
})

Universal Plugin

// plugins/api.ts
export default defineNuxtPlugin(() => {
  const api = $fetch.create({
    baseURL: "/api",
    onResponseError({ response }) {
      if (response.status === 401) {
        navigateTo("/login")
      }
    },
  })

  return {
    provide: {
      api,
    },
  }
})

// Usage
const { $api } = useNuxtApp()
const data = await $api("/users")

Auto-Imported APIs

Don't manually import these - Nuxt auto-imports them:

Vue APIs: ref, reactive, computed, watch, onMounted, defineProps, defineEmits, defineModel

Nuxt Composables: useState, useFetch, useAsyncData, useRoute, useRouter, navigateTo, useCookie, useHead, useSeoMeta, useRuntimeConfig, showError, clearError

File-Based Conventions

Routing:

• pages/index.vue → /
• pages/about.vue → /about
• pages/users/[id].vue → /users/:id

Server API:

• server/api/users.get.ts → /api/users (GET)
• server/api/users.post.ts → /api/users (POST)
• server/routes/healthz.ts → /healthz

Layouts & Middleware:

• layouts/default.vue - Default layout
• middleware/auth.ts - Named middleware
• middleware/analytics.global.ts - Global middleware

Nuxt CLI Commands

Development:

• nuxt dev - Start dev server
• nuxt dev --host - Expose to network

Building:

• nuxt build - Production build
• nuxt generate - Static site generation
• nuxt preview - Preview production build

Analysis:

• nuxt analyze - Bundle size analysis
• nuxt typecheck - Type checking
• nuxt info - Environment info