Understand Module Structure

There are two types of Nuxt modules:

• published modules are distributed on npm - you can see a list of some community modules on the Nuxt website.
• "local" modules exist within a Nuxt project, either inlined in Nuxt config or within the modules directory.

In either case, they work in the same way.

Define Your Module

The module definition is the entry point of your module. It's what gets loaded by Nuxt when your module is referenced within a Nuxt configuration.

At a low level, a Nuxt module definition is a simple, potentially asynchronous, function accepting inline user options and a nuxt object to interact with Nuxt.

export default function (inlineOptions, nuxt) {
  // You can do whatever you like here..
  console.log(inlineOptions.token) // `123`
  console.log(nuxt.options.dev) // `true` or `false`
  nuxt.hook('ready', (nuxt) => {
    console.log('Nuxt is ready')
  })
}

You can get type hinting for this function using the higher-level defineNuxtModule helper provided by Nuxt Kit.

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule((options, nuxt) => {
  nuxt.hook('pages:extend', (pages) => {
    console.log(`Discovered ${pages.length} pages`)
  })
})

However, we do not recommend using this low-level function definition. Instead, to define a module, we recommend using the object-syntax with meta property to identify your module, especially when publishing to npm.

This helper makes writing Nuxt modules more straightforward by implementing many common patterns needed by modules, guaranteeing future compatibility and improving the experience for both module authors and users.

import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    // Usually the npm package name of your module
    name: '@nuxtjs/example',
    // The key in `nuxt.config` that holds your module options
    configKey: 'sample',
    // Compatibility constraints
    compatibility: {
      // Semver version of supported nuxt versions
      nuxt: '>=3.0.0',
    },
  },
  // Default configuration options for your module, can also be a function returning those
  defaults: {},
  // Shorthand sugar to register Nuxt hooks
  hooks: {},
  // Configuration for other modules - this does not ensure the module runs before
  // your module, but it allows you to change the other module's configuration before it runs
  moduleDependencies: {
    'some-module': {
      // You can specify a version constraint for the module. If the user has a different
      // version installed, Nuxt will throw an error on startup.
      version: '>=2',
      // By default moduleDependencies will be added to the list of modules to be installed
      // by Nuxt unless `optional` is set.
      optional: true,
      // Any configuration that should override `nuxt.options`.
      overrides: {},
      // Any configuration that should be set. It will override module defaults but
      // will not override any configuration set in `nuxt.options`.
      defaults: {},
    },
  },
  // The function holding your module logic, it can be asynchronous
  setup (moduleOptions, nuxt) {
    // ...
  },
})

defineNuxtModule returns a wrapper function with the lower level (inlineOptions, nuxt) module signature. This wrapper function applies defaults and other necessary steps before calling your setup function:

• Support defaults and meta.configKey for automatically merging module options
• Type hints and automated type inference
• Ensure module gets installed only once using a unique key computed from meta.name or meta.configKey
• Automatically register Nuxt hooks
• Automatically check for compatibility issues based on module meta
• Expose getOptions and getMeta for internal usage of Nuxt
• Ensuring backward and upward compatibility as long as the module is using defineNuxtModule from the latest version of @nuxt/kit
• Integration with module builder tooling

Add Runtime Code

Modules, like everything in a Nuxt configuration, aren't included in your application runtime. However, you might want your module to provide, or inject runtime code to the application it's installed on. That's what the runtime directory enables you to do.

Inside the runtime directory, you can provide any kind of assets related to the Nuxt app:

• Vue components
• Composables
• Nuxt plugins

To the server engine, Nitro:

• API routes
• Middlewares
• Nitro plugins

Or any other kind of asset you want to inject in users' Nuxt applications:

• Stylesheets
• 3D models
• Images
• etc.

You'll then be able to inject all those assets inside the application from your module definition.