smith-nuxt

tianjianjiang's avatarfrom tianjianjiang

Nuxt 3 development patterns including auto-import stubbing for tests, environment variable conventions, and middleware testing. Use when working with Nuxt projects, testing Nuxt components/middleware, or configuring Nuxt environment variables.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026
[Testing and QA]

When & Why to Use This Skill

This Claude skill provides specialized Nuxt 3 development patterns designed to streamline testing and configuration workflows. It solves critical issues related to auto-import stubbing in unit tests and establishes clear conventions for environment variable management, ensuring robust, secure, and maintainable Vue/Nuxt applications.

Use Cases

  • Case 1: Stubbing Nuxt-specific global auto-imports (like defineEventHandler or createError) in Vitest/Jest environments to allow unit testing of server middleware and composables without runtime errors.
  • Case 2: Implementing secure environment variable configurations by correctly utilizing NUXT_PUBLIC_ prefixes for client-side access while keeping sensitive credentials server-only.
  • Case 3: Standardizing project architecture by enforcing proper import sequences, preventing common pitfalls where modules execute before their global dependencies are initialized.
namesmith-nuxt
descriptionNuxt 3 development patterns including auto-import stubbing for tests, environment variable conventions, and middleware testing. Use when working with Nuxt projects, testing Nuxt components/middleware, or configuring Nuxt environment variables.

Nuxt Development Standards

  • Scope: Nuxt 3 specific patterns
  • Load if: Working with Nuxt projects
  • Prerequisites: @smith-principles/SKILL.md, @smith-standards/SKILL.md, @smith-typescript/SKILL.md

CRITICAL: Auto-Import Stubbing (Primacy Zone)

Stub Nuxt auto-imports BEFORE importing modules that use them - module code executes at import time.
  • Mocking h3 module expecting auto-imports (they're globals)
  • Importing middleware before stubbing globals

Auto-Import Stubbing in Tests

Nuxt auto-imports utilities like defineEventHandler, createError, useState. These are globally available in Nuxt runtime but NOT in test environments.

Stub auto-imports globally BEFORE importing the module under test:

import { describe, it, expect, vi } from 'vitest';
import type { H3Event } from 'h3';

// Stub Nuxt auto-imports BEFORE any imports that use them
(globalThis as Record<string, unknown>).defineEventHandler =
  (handler: (event: H3Event) => unknown) => handler;
(globalThis as Record<string, unknown>).createError =
  (options: { statusCode: number; statusMessage: string }) =>
    Object.assign(new Error(options.statusMessage), { statusCode: options.statusCode });

// Now import the module that uses auto-imports
import middleware from '../myMiddleware';
  • NEVER mock h3 module expecting auto-imports to work (they're globals, not module exports)
  • NEVER import middleware before stubbing globals (module executes at import time)

Environment Variables

Nuxt uses NUXT_ prefix for runtime config environment variables.

  • NUXT_PUBLIC_* - Exposed to client
  • NUXT_* - Server-only

Server-only:

NUXT_DATABASE_URL=postgres://...
NUXT_API_SECRET=secret

Public (exposed to browser):

NUXT_PUBLIC_API_BASE=https://api.example.com
  • @smith-typescript/SKILL.md - General TypeScript patterns
  • @smith-tests/SKILL.md - Testing standards

ACTION (Recency Zone)

Before testing Nuxt code:

  1. Stub auto-imports BEFORE any imports
  2. Use NUXT_PUBLIC_* for client-exposed env vars
  3. Use NUXT_* for server-only env vars