Create Your First Module

Learn how to create your first Nuxt module using the official starter template.

Create a Module

We recommend you get started with Nuxt modules using our starter template:

npm create nuxt -- -t module my-module

This will create a my-module project with all the boilerplate necessary to develop and publish your module.

Next steps:

  1. Open my-module in your IDE of choice
  2. Install dependencies using your favorite package manager
  3. Prepare local files for development using npm run dev:prepare
  4. Follow this document to learn more about Nuxt modules

Use the Starter Template

Learn how to perform basic tasks with the module starter.

Watch Vue School video about Nuxt module starter template.

Develop Your Module

While your module source code lives inside the src directory, to develop a module you often need a Nuxt application to test it against. That's what the playground directory is for. It's a Nuxt application you can tinker with that is already configured to run with your module.

You can interact with the playground like with any Nuxt application.

  • Launch its development server with npm run dev, it should reload itself as you make changes to your module in the src directory
  • Build it with npm run dev:build
All other nuxt commands can be used against the playground directory (e.g. nuxt <COMMAND> playground). Feel free to declare additional dev:* scripts within your package.json referencing them for convenience.

Run Tests

The module starter comes with a basic test suite:

  • A linter powered by ESLint, run it with npm run lint
  • A test runner powered by Vitest, run it with npm run test or npm run test:watch
Feel free to augment this default test strategy to better suit your needs.

Build Your Module

Nuxt modules come with their own builder provided by @nuxt/module-builder. This builder doesn't require any configuration on your end, supports TypeScript, and makes sure your assets are properly bundled to be distributed to other Nuxt applications.

You can build your module by running npm run prepack.

While building your module can be useful in some cases, most of the time you won't need to build it on your own: the playground takes care of it while developing, and the release script also has you covered when publishing.

Publish to npm

Before publishing your module to npm, makes sure you have an npmjs.com account and that you're authenticated to it locally with npm login.

While you can publish your module by bumping its version and using the npm publish command, the module starter comes with a release script that helps you make sure you publish a working version of your module to npm and more.

To use the release script, first, commit all your changes (we recommend you follow Conventional Commits to also take advantage of automatic version bump and changelog update), then run the release script with npm run release.

When running the release script, the following will happen:

  • First, it will run your test suite by:
    • Running the linter (npm run lint)
    • Running unit, integration, and e2e tests (npm run test)
    • Building the module (npm run prepack)
  • Then, if your test suite went well, it will proceed to publish your module by:
    • Bumping your module version and generating a changelog according to your Conventional Commits
    • Publishing the module to npm (for that purpose, the module will be built again to ensure its updated version number is taken into account in the published artifact)
    • Pushing a git tag representing the newly published version to your git remote origin
As with other scripts, feel free to fine-tune the default release script in your package.json to better suit your needs.