DOCSEARCHbyAlgolia
Submit Docs

Nuxt Skills

repository·main·Indexed 20 days ago

https://github.com/onmax/nuxt-skills

A collection of specialized knowledge sets (skills) designed to enhance AI coding assistants like Claude Code, Cursor, and GitHub Copilot when working with Vue, Nuxt, and the broader Nuxt ecosystem. It provides coverage for Nuxt 4+, NuxtHub, Nuxt Content, Nuxt UI, and other ecosystem tools, following the Agent Skills open format for auto-discovery and manual invocation.

Tokens
258.9K
Snippets
877
Records
1.3K
Agent score
70%

What's inside nuxt-skills

  1. Use Nuxt UI v4 for styled UI components

    main

    Nuxt UI v4 is a component library for Vue 3 and Nuxt 4+ built on top of Reka UI (headless primitives), Tailwind CSS v4, and Tailwind Variants. It is designed for building styled interfaces including forms with validation, data tables, modal dialogs, and overlays.

    When to use this skill:

    • Installing or configuring @nuxt/ui.
    • Using UI components like Button, Card, Table, or Form.
    • Customizing themes via colors, variants, or CSS variables.
    • Implementing forms with Zod or Valibot validation.
    • Using overlays such as Modal, Toast, or CommandPalette.
    • Working with Nuxt UI composables like useToast or useOverlay.

    Note on related skills:

    • For raw Vue component patterns, use the vue skill.
    • For Nuxt routing or server-side logic, use the nuxt skill.
    • For headless component primitives (accessibility, asChild pattern), use the reka-ui skill.

  2. Use the phaser-best-practices skill

    main

    The phaser-best-practices skill is designed for building and refactoring Phaser 3 browser games. It is suitable for:

    • New Projects: Scaffolding a new Phaser 3 game or prototype.
    • Feature Work: Adding or refactoring scenes, entities, UI, physics, tilemaps, input, audio, or cameras.
    • Bug Fixing: Debugging scene lifecycles, asset loading, physics/collider issues, or rendering problems (e.g., blurry pixel art).
    • Optimization: Improving architecture, maintainability, or runtime performance (pooling, culling, etc.).

    Compatibility: Intended for Phaser 3 JavaScript or TypeScript projects. New project scaffolding assumes Node.js/npm or an existing browser bundler.

  3. Use the writing-web-documentation skill

    main

    The writing-web-documentation skill is designed to produce high-quality technical documentation for web software projects (frontend, backend, full-stack, SDKs, APIs, or frameworks). It focuses on creating documentation that is easy to enter, scan, trust, and maintain, rather than just providing text around code.

    Core Optimization Goals

    • Fast first success: Help readers reach a working result quickly.
    • Clear routing by intent: Separate content for beginners vs. experts.
    • Low ambiguity: Explicitly state commands, filenames, versions, and prerequisites.
    • Scannability: Use headings, lists, and tables for quick navigation.
    • Maintenance: Ensure docs are easy to update alongside code changes.

    Non-goals

    Do not use this skill for:

    • Marketing copy or hype.
    • Exhaustive background on every page.
    • Clever prose or giant, unexplained code dumps.

  4. Use the ts-library skill for TypeScript library development

    main

    The ts-library skill provides patterns and guidance for authoring high-quality TypeScript libraries or npm packages. Use this skill when you need to:

    • Start a new TypeScript library (single or monorepo).
    • Configure package.json exports for dual CJS/ESM support.
    • Set up build tooling like tsdown or unbuild.
    • Design type-safe APIs using builder, factory, or plugin patterns.
    • Implement advanced TypeScript types and inference.
    • Set up testing with vitest.
    • Configure release workflows and CI/CD.

    Note: If you are developing a Nuxt module, use the nuxt-modules skill instead.

  5. Manage complex behavior with Finite State Machines (FSM)

    main

    When entity behavior (like AI or player movement) becomes branch-heavy with many if/else statements, implement a Finite State Machine. This allows you to define explicit states (e.g., idle, chase, stunned) and handle transitions cleanly within an update loop.

    type EnemyState = 'idle' | 'patrol' | 'chase' | 'stunned' | 'dead';

class EnemyBrain {
  private state: EnemyState = 'idle';

  constructor(private readonly enemy: Phaser.Physics.Arcade.Sprite) {}

  update(player: Phaser.Physics.Arcade.Sprite) {
    switch (this.state) {
      case 'idle':
        if (Phaser.Math.Distance.Between(this.enemy.x, this.enemy.y, player.x, player.y) < 180) {
          this.state = 'chase';
        }
        break;
      case 'chase':
        this.enemy.setVelocityX(player.x < this.enemy.x ? -80 : 80);
        break;
      case 'stunned':
      case 'dead':
        this.enemy.setVelocityX(0);
        break;
    }
  }

  stun() { this.state = 'stunned'; }
  die() { this.state = 'dead'; }
}

  6. How the Stepper component works

    main

    The Stepper is a multi-step progress indicator composed of several sub-components. It uses a root-item hierarchy to manage state and navigation through a sequence of steps.

    Core Components:

    • StepperRoot: The main container that manages the current step state and orientation.
    • StepperItem: Represents an individual step in the sequence.
    • StepperTrigger: The interactive element (usually a button) used to navigate to a specific step.
    • StepperTitle & StepperDescription: Textual elements for labeling steps.
    • StepperIndicator & StepperSeparator: Visual elements for showing progress and separating steps.

    To build a stepper, you wrap StepperItem components inside a StepperRoot. You can control the current step using modelValue (for two-way binding) or defaultValue.

    <StepperRoot v-model="currentStep">
  <StepperItem :step="1">
    <StepperTrigger>
      <StepperTitle>Step 1</StepperTitle>
    </StepperTrigger>
  </StepperItem>
  <StepperItem :step="2">
    <StepperTrigger>
      <StepperTitle>Step 2</StepperTitle>
    </StepperTrigger>
  </StepperItem>
</StepperRoot>

  7. Choose the correct Nuxt data fetching primitive

    main

    Nuxt provides three primary ways to handle data fetching. Choosing the right one ensures proper SSR hydration and prevents double-fetching.

    • useFetch: Best for a single HTTP endpoint. It automatically generates a stable key from the URL, transfers data from SSR to the client via the Nuxt payload, and forwards request context (cookies/headers) for relative server calls.
    • useAsyncData: Best for custom async logic, SDK calls, multiple requests, or when you need to provide an explicit shared cache key.
    • $fetch: Best for event-driven requests (e.g., form submissions). Warning: Do not call $fetch directly during component setup for initial data loading, as it will run once on the server and again on the client during hydration because its result is not transferred in the Nuxt payload.
    <script setup lang="ts">
const page = ref(1)

// Use useFetch for standard API calls to ensure SSR hydration works correctly
const { data, status, error, execute, clear } = await useFetch('/api/products', {
  query: { page },
  immediate: false,
  watch: false,
})
</script>

  8. Use Lifecycle Hooks in a Nuxt Module

    main

    Nuxt modules can tap into various lifecycle hooks to modify the application behavior. Common hooks include:

    • ready: When Nuxt is initialized.
    • modules:done: After all modules are loaded.
    • pages:extend: To modify the pages array.
    • nitro:config: To configure the Nitro server.
    • close: When Nuxt is shutting down.
    export default defineNuxtModule({
  hooks: {
    'pages:extend': (pages) => {
      pages.push({ name: 'custom', path: '/custom', file: resolve('./runtime/pages/custom.vue') })
    }
  },
  setup(options, nuxt) {
    nuxt.hook('nitro:config', (nitroConfig) => {
      nitroConfig.prerender ||= {}
      nitroConfig.prerender.routes ||= []
      nitroConfig.prerender.routes.push('/my-route')
    })

    nuxt.hook('close', async () => {
      await cleanup()
    })
  }
})

  9. How Nuxt Skills work and how to trigger them

    main

    Nuxt Skills follow the Agent Skills open format. They are activated in two ways:

    1. Auto-discovery: The AI agent reads the description of each skill and automatically loads it when it detects relevant context in your project (e.g., seeing a .vue file might trigger the vue skill).
    2. Manual invocation: You can explicitly force an agent to load a specific skill by typing its name preceded by a slash, for example: /nuxt.

    Common Auto-load Triggers:

    • .vue file $\rightarrow$ vue skill
    • server/api/ route or nuxt.config.ts $\rightarrow$ nuxt skill
    • NuxtHub storage $\rightarrow$ nuxthub skill
    • Auth/login/session $\rightarrow$ nuxt-better-auth skill

  10. Vite Build and SSR Capabilities

    main

    Vite provides specialized modes for different deployment targets:

    • Library Mode: Optimized for bundling libraries.
    • SSR Middleware Mode: For running Vite as middleware in a server environment.
    • SSR API: Includes ssrLoadModule and a dedicated JavaScript API for server-side execution.

  11. Structure of a web documentation template

    main

    This template provides a standardized structure for writing effective web documentation. It is designed to help users navigate information based on their current intent (e.g., getting started, solving a specific task, or looking up technical references).

    Key sections include:

    • Navigation Paths: Categorized links for Quickstart, Core Concepts, How-to guides, Reference, Troubleshooting, and Migration guides.
    • Contextual Information: Sections for 'What the product does' and 'Who this documentation is for' to orient the reader.
    • Task-Oriented Entry Points: A 'Recommended first step' and a list of 'Popular tasks' to reduce time-to-value.
    • Reference Organization: Dedicated sections for API, CLI, Configuration, and Component/SDK references.
    • Community Engagement: Links for reporting problems, contributing to documentation, and accessing the repository.

  12. Understand tsdown CLI flag patterns

    main

    tsdown uses standard CLI flag patterns for boolean, object, and array values:

    • Boolean true: --foo sets foo: true.
    • Boolean false: --no-foo sets foo: false.
    • Nested objects: --foo.bar sets { foo: { bar: true } }.
    • Arrays: Multiple flags of the same name create an array, e.g., --format esm --format cjs sets format: ['esm', 'cjs'].
    --foo              # foo: true
--no-foo           # foo: false
--foo.bar          # foo: { bar: true }
--format esm --format cjs  # format: ['esm', 'cjs']