Nuxt 3 Framework Skill

<workflow>

Quick Reference

Page Component

<example>

<!-- pages/users/[id].vue -->
<script setup lang="ts">
const route = useRoute();
const { data: user, error } = await useFetch(`/api/users/${route.params.id}`);

definePageMeta({
  layout: 'admin',
  middleware: ['auth'],
});

useHead({
  title: () => user.value?.name ?? 'User',
});
</script>

<template>
  <div v-if="error">Error: {{ error.message }}</div>
  <div v-else-if="user">
    <h1>{{ user.name }}</h1>
    <p>{{ user.email }}</p>
  </div>
</template>

</example>

Server API Routes

<example>

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

  const user = await db.users.findUnique({ where: { id } });

  if (!user) {
    throw createError({
      statusCode: 404,
      message: 'User not found',
    });
  }

  return user;
});

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

  const user = await db.users.create({ data: body });

  return user;
});

</example>

Composables

<example>

// composables/useAuth.ts
export function useAuth() {
  const user = useState<User | null>('auth-user', () => null);
  const isAuthenticated = computed(() => !!user.value);

  async function login(credentials: Credentials) {
    const { data } = await useFetch('/api/auth/login', {
      method: 'POST',
      body: credentials,
    });
    user.value = data.value;
  }

  async function logout() {
    await useFetch('/api/auth/logout', { method: 'POST' });
    user.value = null;
    navigateTo('/login');
  }

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

</example>

Data Fetching

<example>

<script setup lang="ts">
// Simple fetch
const { data, pending, error, refresh } = await useFetch('/api/items');

// With options
const { data: items } = await useFetch('/api/items', {
  query: { page: 1, limit: 10 },
  pick: ['id', 'name'],  // Only include these fields
  transform: (data) => data.items,
  watch: [page],  // Re-fetch when page changes
});

// Lazy fetch (doesn't block navigation)
const { data, pending } = useLazyFetch('/api/slow-data');

// useAsyncData for custom async operations
const { data } = await useAsyncData('key', () => {
  return $fetch('/api/items');
});
</script>

</example>

Middleware

<example>

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  const { isAuthenticated } = useAuth();

  if (!isAuthenticated.value && to.path !== '/login') {
    return navigateTo('/login');
  }
});

// middleware/admin.ts (named middleware)
export default defineNuxtRouteMiddleware(() => {
  const { user } = useAuth();

  if (user.value?.role !== 'admin') {
    throw createError({
      statusCode: 403,
      message: 'Forbidden',
    });
  }
});

</example>

Plugins

<example>

// plugins/api.ts
export default defineNuxtPlugin(() => {
  const api = $fetch.create({
    baseURL: '/api',
    onRequest({ options }) {
      const token = useCookie('token');
      if (token.value) {
        options.headers = {
          ...options.headers,
          Authorization: `Bearer ${token.value}`,
        };
      }
    },
  });

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

// Usage: const { $api } = useNuxtApp();

</example>

Hybrid Rendering

<example>

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/blog/**': { isr: 3600 },  // ISR: revalidate every hour
    '/admin/**': { ssr: false },  // SPA mode
    '/api/**': { cors: true },
  },
});

</example>

State Management

<example>

// With useState (SSR-safe)
const count = useState('counter', () => 0);

// With Pinia
// stores/user.ts
export const useUserStore = defineStore('user', () => {
  const user = ref<User | null>(null);

  async function fetch() {
    user.value = await $fetch('/api/user');
  }

  return { user, fetch };
});

</example>

Best Practices

• Use useFetch for data fetching (handles SSR)
• Use useState for SSR-safe reactive state
• Use route rules for hybrid rendering strategies
• Use server routes for backend logic
• Use middleware for route guards
• Use definePageMeta for page-level config

</workflow>

References Index

• Litestar-Vite Integration — Backend integration with Litestar-Vite plugin.

Official References

• https://nuxt.com/docs/4.x/getting-started/introduction
• https://nuxt.com/docs/4.x/getting-started/upgrade
• https://nuxt.com/docs/4.x/api/composables/use-fetch
• https://nuxt.com/docs/4.x/api/utils/define-nuxt-route-middleware
• https://nitro.build/config/
• https://github.com/nuxt/nuxt/releases

Shared Styleguide Baseline

• Use shared styleguides for generic language/framework rules to reduce duplication in this skill.
• General Principles
• TypeScript
• Keep this skill focused on tool-specific workflows, edge cases, and integration details.

<guardrails> ## Guardrails

• Use useFetch or useAsyncData for data fetching -- These composables are SSR-aware and prevent duplicate requests on the client. Never use plain $fetch in a component's top-level setup.
• Never access browser-only globals during SSR -- Always check import.meta.client or use onMounted before accessing window, document, or localStorage.
• Use server/ directory for sensitive operations -- Keep database queries, API keys, and complex logic in Nitro server routes to ensure they never leak to the client.
• Always provide a unique key to useAsyncData -- This is critical for proper hydration and preventing data mismatch between server and client.
• Prefer useState over local refs for global state -- useState is SSR-safe and preserves state during hydration. </guardrails>

<validation> ## Validation Checkpoint

• useFetch or useAsyncData is used for all top-level data fetching
• No browser-only globals are accessed in the setup script without checks
• Sensitive logic and API calls are moved to the server/api/ directory
• useAsyncData calls have unique and stable keys
• definePageMeta is used for route-level guards and layouts
• Components that require browser APIs are wrapped in <ClientOnly> or used within onMounted

</validation>