📦 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 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 >= 18.x. Latest Node LTS preferred
- Nuxt 3+.
Quick start
Get started with our module starter:
npm create nuxt -- -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) {
}
})
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": {
".": {
"types": "./dist/types.d.mts",
"import": "./dist/module.mjs"
}
},
"main": "./dist/module.mjs",
"typesVersions": {
"*": {
".": [
"./dist/types.d.mts"
]
}
},
"files": [
"dist"
],
"scripts": {
"prepack": "nuxt-module-build build"
},
"dependencies": {
"@nuxt/kit": "latest"
},
"devDependencies": {
"@nuxt/module-builder": "latest"
}
}
build.config.ts
(optional)
Module builder is essentially a preset for unjs/unbuild, check out the build command for reference.
To customize/extend the unbuild configuration you can add a build.config.ts
in the root of your project:
import { defineBuildConfig } from 'unbuild'
export default defineBuildConfig({
})
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
types.d.mts
: 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 .js
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 💚