playbooks

home / skills / onmax / nuxt-skills / nuxt-modules

nuxt-modules skill

/skills/nuxt-modules

This skill helps you build, test, and publish Nuxt modules using defineNuxtModule patterns, Kit utilities, and CI/CD workflows.

npx playbooks add skill onmax/nuxt-skills --skill nuxt-modules

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.4 KB
---
name: nuxt-modules
description: "Use when creating Nuxt modules: (1) Published npm modules (@nuxtjs/, nuxt-), (2) Local project modules (modules/ directory), (3) Runtime extensions (components, composables, plugins), (4) Server extensions (API routes, middleware), (5) Releasing/publishing modules to npm, (6) Setting up CI/CD workflows for modules. Provides defineNuxtModule patterns, Kit utilities, hooks, E2E testing, and release automation."
license: MIT
---

# Nuxt Module Development

Guide for creating Nuxt modules that extend framework functionality.

**Related skills:** `nuxt` (basics), `vue` (runtime patterns)

## Quick Start

```bash
npx nuxi init -t module my-module
cd my-module && npm install
npm run dev        # Start playground
npm run dev:build  # Build in watch mode
npm run test       # Run tests
```

## Available Guidance

- **[references/development.md](references/development.md)** - Module anatomy, defineNuxtModule, Kit utilities, hooks
- **[references/testing-and-publishing.md](references/testing-and-publishing.md)** - E2E testing, best practices, releasing, publishing
- **[references/ci-workflows.md](references/ci-workflows.md)** - Copy-paste CI/CD workflow templates

**Load based on context:**

- Building module features? → [references/development.md](references/development.md)
- Testing or publishing? → [references/testing-and-publishing.md](references/testing-and-publishing.md)
- CI workflow templates? → [references/ci-workflows.md](references/ci-workflows.md)

## Module Types

| Type      | Location         | Use Case                         |
| --------- | ---------------- | -------------------------------- |
| Published | npm package      | `@nuxtjs/`, `nuxt-` distribution |
| Local     | `modules/` dir   | Project-specific extensions      |
| Inline    | `nuxt.config.ts` | Simple one-off hooks             |

## Project Structure

```
my-module/
├── src/
│   ├── module.ts           # Entry point
│   └── runtime/            # Injected into user's app
│       ├── components/
│       ├── composables/
│       ├── plugins/
│       └── server/
├── playground/             # Dev testing
└── test/fixtures/          # E2E tests
```

## Resources

- [Module Guide](https://nuxt.com/docs/guide/going-further/modules)
- [Nuxt Kit](https://nuxt.com/docs/api/kit)
- [Module Starter](https://github.com/nuxt/starter/tree/module)

Overview

This skill helps you create, test, and publish Nuxt modules for both local projects and npm packages. I provide patterns for defineNuxtModule, Kit utilities, runtime and server extension placement, E2E testing guidance, and release/CI workflow templates. It accelerates module development and standardizes publishing steps.

How this skill works

I inspect your module type and suggest the appropriate structure and workflow: published npm modules, local modules in a modules/ directory, inline config-based hooks, runtime/runtime extensions (components, composables, plugins), and server extensions (API routes, middleware). I also guide you through testing (fixtures and E2E) and generating CI/CD templates for automated builds and releases.

When to use it

  • Creating a new Nuxt module package (npm scoped or unscoped)
  • Adding project-specific extensions in modules/ of an existing Nuxt app
  • Implementing runtime features like components, composables, or client plugins
  • Adding server-side routes, middleware, or server handlers in module runtime
  • Setting up E2E tests and release pipelines before publishing to npm
  • Scaffolding CI/CD workflows for automated builds, tests, and releases

Best practices

  • Use defineNuxtModule and Nuxt Kit utilities to keep module API consistent and typed
  • Separate src/module.ts (entry) from runtime/ assets (components, composables, plugins, server)
  • Provide a playground or dev mode for rapid iteration with npm run dev and dev:build
  • Include test fixtures and E2E tests for integration coverage before publishing
  • Automate releases with CI templates that run lint, tests, build, and npm publishing steps

Example use cases

  • Build and publish an @nuxtjs/ scoped module that adds auth middleware and composables
  • Create a local modules/ extension to inject shared components and a plugin across the project
  • Add server extensions inside module runtime to expose API endpoints or custom middleware
  • Run E2E tests with fixtures in test/fixtures to validate module behavior in a controlled playground
  • Configure CI workflow that builds the module, runs tests, and publishes a release tag to npm

FAQ

How do I structure files for runtime vs server code?

Put injected app code (components, composables, plugins) under runtime/ and server handlers under runtime/server/. Keep module entry logic in src/module.ts.

What commands speed up development?

Use npx nuxi init -t module to scaffold, then npm run dev for playground, npm run dev:build for build-watch, and npm run test for running tests.