@nuxt/module-builder

📦 Nuxt Module Builder

The complete solution to build and ship Nuxt modules.

Features

• Compatible with Nuxt 3 and Nuxt Kit
• Unified build with unjs/unbuild
• Automated build config using last module spec
• Typescript and ESM support
• Auto generated CommonJS stubs
• Auto generated types and shims for @nuxt/schema

We recommend to checkout the Nuxt modules author guide before starting with the module-builder.

Requirements

For a user to use a module generated from module-builder, it's recommended they have:

• Node.js >= 16.x. Latest Node LTS preferred
• Nuxt 3 or Nuxt Bridge. Nuxt 2 is functional but not advised

Quick start

Get started with our module starter:

npx nuxi init -t module my-module

Project structure

The module builder requires a special project structure. You can check out the module template.

src/module.ts

The entrypoint for module definition.

A default export using defineNuxtModule and ModuleOptions type export is expected.

You could also optionally export ModuleHooks or ModuleRuntimeHooks to annotate any custom hooks the module uses.

import { defineNuxtModule } from '@nuxt/kit'

export interface ModuleOptions {
  apiKey: string
}

export interface ModuleHooks {
  'my-module:init': any
}

export interface ModuleRuntimeHooks {
  'my-module:runtime-hook': any
}

export interface ModuleRuntimeConfig {
  PRIVATE_NAME: string
}

export interface ModulePublicRuntimeConfig {
  NAME: string
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-module',
    configKey: 'myModule'
  },
  defaults: {
    apiKey: 'test'
  },
  async setup (moduleOptions, nuxt) {
    // Write module logic in setup function
  }
})

src/runtime/

Any runtime file and code that we need to provide by module including plugins, composables and server api, should be in this directory.

Each file will be transformed individually using unjs/mkdist to dist/runtime/.

package.json:

A minimum package.json should look like this:

{
  "name": "my-module",
  "license": "MIT",
  "version": "1.0.0",
  "exports": {
    ".": {
      "import": "./dist/module.mjs",
      "require": "./dist/module.cjs"
    }
  },
  "main": "./dist/module.cjs",
  "types": "./dist/types.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "prepack": "nuxt-module-build"
  },
  "dependencies": {
    "@nuxt/kit": "npm:@nuxt/kit-edge@latest"
  },
  "devDependencies": {
    "@nuxt/module-builder": "latest"
  }
}

Dist files

Module builder generates dist files in dist/ directory:

• module.mjs: Module entrypoint build from src/module
• module.json: Module meta extracted from module.mjs + package.json
• module.cjs: ESM proxy to allow require module in CommonJS context
• types.d.ts: Exported types in addition to shims for nuxt.config auto completion.
• runtime/*: Individually transformed files using unjs/mkdist
  • Javascript and .ts files will be transformed to .mjs with extracted types on .d.ts file with same name
  • .vue files will be transformed with extracted .d.ts file
  • Other files will be copied as is

💻 Development

• Clone repository
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Try building example module using pnpm example:build

License

MIT - Made with 💚

Changelog

v0.6.0

compare changes

🚀 Enhancements

• Generate runtime/ dts based on nuxt tsconfig options (#255)
• Add builder versions to module.json (f8567a3)
• Support transforming jsx (4841f2e)

🩹 Fixes

• ⚠️ Remove support for deprecated RuntimeModuleHooks interface (#228)
• Add -nightly versions to externals (0a88a87)
• Ignore exporting type if it is not defined (c308cc5)
• Mark runtime/ directory as external (7a68e1e)

🏡 Chore

• release: V0.5.5 (f158ffa)
• Dedupe kit/schema/vue versions (aa0a710)
• Add root dev:prepare command (c308a68)
• Migrate to eslint v9 (#250)
• Improve internal type safety and enable strict mode (78aa088)
• Tweak tsconfig settings (404aae7)
• Add more type annotations (ba0614b)

✅ Tests

• Update type testing step (#256)
• Add inline snapshots for runtime/ transforms (#257)
• Update snapshot (a39c183)

🎨 Styles

• Lint (c15fd92)
• Lint (3b805ec)

⚠️ Breaking Changes

• ⚠️ Remove support for deprecated RuntimeModuleHooks interface (#228)

❤️ Contributors

• Daniel Roe (@danielroe)