nuxt
📦 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-moduleProject 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.
`ts [src/module.ts]
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](https://github.com/unjs/mkdist) to `dist/runtime/`.
<!-- TODO: Docs about how to address runtime from within setup -->
### `package.json`:
A minimum `package.json` should look like this:
```json [package.json]
{
"name": "my-module",
"license": "MIT",
"version": "1.0.0",
"exports": {
".": {
"types": "./dist/types.d.ts",
"import": "./dist/module.mjs",
"require": "./dist/module.cjs"
}
},
"main": "./dist/module.cjs",
"types": "./dist/types.d.ts",
"files": [
"dist"
],
"scripts": {
"prepack": "nuxt-module-build build"
},
"dependencies": {
"@nuxt/kit": "npm:@nuxt/kit-edge@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({
// set additional configuration or customize using hooks
})Dist files
Module builder generates dist files in dist/ directory:
module.mjs: Module entrypoint build fromsrc/modulemodule.json: Module meta extracted frommodule.mjs+package.jsonmodule.cjs: ESM proxy to allow require module in CommonJS contexttypes.d.ts: Exported types in addition to shims fornuxt.configauto completion.runtime/*: Individually transformed files using unjs/mkdist- Javascript and
.tsfiles will be transformed to.jswith extracted types on.d.tsfile with same name .vuefiles will be transformed with extracted.d.tsfile- Other files will be copied as is
- Javascript and
💻 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 💚