Build Your Own Module

A Nuxt module is a function that hooks into Nuxt's setup, letting you add components, composables, plugins, and server routes from a single package.

5 min read Level 3/5 #nuxt#modules#advanced

What you'll learn

Scaffold a module with the nuxi init module template
Define a module with defineNuxtModule and typed options
Hook into the Nuxt lifecycle with helpers like addComponent and addPlugin

When the same setup repeats across projects — analytics, design-system components, internal SDKs — package it as a module. The Nuxt kit gives you everything you need.

Scaffold

npx nuxi init -t module my-mod
cd my-mod
npm install

This generates a module package with a src/module.ts entry, playground app, and build config.

Define the Module

// src/module.ts
import { defineNuxtModule, addComponent, createResolver } from '@nuxt/kit'

export interface ModuleOptions {
  prefix: string
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-mod',
    configKey: 'myMod',
  },
  defaults: {
    prefix: 'My',
  },
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addComponent({
      name: `${options.prefix}Button`,
      filePath: resolver.resolve('./runtime/MyButton.vue'),
    })
  },
})

createResolver lets the module reference files relative to itself, even after it’s installed in a consumer project.

Useful Kit Helpers

addComponent({ name, filePath }) — register a global component.
addImports({ name, from }) — make a function auto-importable as a composable.
addPlugin(filePath) — drop a plugin into the app.
addServerHandler({ route, handler }) — mount a Nitro route.
installModule(name, options) — recursively install another module.

Hooking the Lifecycle

nuxt.hook('pages:extend', (pages) => {
  pages.push({ name: 'admin', path: '/admin', file: resolver.resolve('./runtime/Admin.vue') })
})

There are dozens of hooks; check the Nuxt docs for the full list.

Publish

npm run prepack builds with unbuild. Then npm publish. Consumers install it with nuxi module add my-mod.

Nitro — The Server Engine →