{"id":14964157,"url":"https://github.com/nuxt/module-builder","last_synced_at":"2025-05-15T00:10:51.792Z","repository":{"id":37092810,"uuid":"434558841","full_name":"nuxt/module-builder","owner":"nuxt","description":"Complete solution to build and ship Nuxt modules.","archived":false,"fork":false,"pushed_at":"2025-04-10T04:25:02.000Z","size":3399,"stargazers_count":254,"open_issues_count":16,"forks_count":31,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-10T05:32:40.741Z","etag":null,"topics":["nuxt","nuxt-module"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nuxt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-03T10:40:14.000Z","updated_at":"2025-04-09T12:55:31.000Z","dependencies_parsed_at":"2023-02-14T01:16:28.495Z","dependency_job_id":"8feebd63-dd48-411f-be81-3878e12e0b04","html_url":"https://github.com/nuxt/module-builder","commit_stats":{"total_commits":352,"total_committers":20,"mean_commits":17.6,"dds":0.3892045454545454,"last_synced_commit":"d76be4671f30c28b70f9528411319917ba39a62e"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt%2Fmodule-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt%2Fmodule-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt%2Fmodule-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt%2Fmodule-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nuxt","download_url":"https://codeload.github.com/nuxt/module-builder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248804784,"owners_count":21164131,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nuxt","nuxt-module"],"created_at":"2024-09-24T13:32:39.606Z","updated_at":"2025-04-14T00:53:50.804Z","avatar_url":"https://github.com/nuxt.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# 📦 Nuxt Module Builder\n\n[![npm version][npm-version-src]][npm-version-href]\n[![License][license-src]][license-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n\u003ca href=\"https://volta.net/nuxt/module-builder?utm_source=nuxt_module_builder_readme\"\u003e\u003cimg src=\"https://user-images.githubusercontent.com/904724/209143798-32345f6c-3cf8-4e06-9659-f4ace4a6acde.svg\" alt=\"Volta board\"\u003e\u003c/a\u003e\n\n\u003e The complete solution to build and ship [Nuxt modules](https://nuxt.com/modules).\n\n## Features\n\n- Compatible with Nuxt 3 and Nuxt Kit\n- Unified build with [unjs/unbuild](https://github.com/unjs/unbuild)\n- Automated build config using last module spec\n- Typescript and ESM support\n- Auto generated types and shims for `@nuxt/schema`\n\nWe recommend to checkout the [Nuxt modules author guide](https://nuxt.com/docs/guide/going-further/modules) before starting with the module-builder.\n\n## Requirements\n\nFor a user to use a module generated from module-builder, it's recommended they have:\n- Node.js \u003e= 18.x. _Latest Node LTS preferred_\n- Nuxt 3+.\n\n## Quick start\n\nGet started with our [module starter](https://github.com/nuxt/starter/tree/module):\n\n```bash\nnpm create nuxt -- -t module my-module\n```\n\n## Project structure\n\nThe module builder requires a special project structure. You can check out the [module template](https://github.com/nuxt/starter/tree/module).\n\n### `src/module.ts`\n\nThe entrypoint for module definition.\n\nA default export using `defineNuxtModule` and `ModuleOptions` type export is expected.\n\nYou could also optionally export `ModuleHooks` or `ModuleRuntimeHooks` to annotate any custom hooks the module uses.\n\n```ts [src/module.ts]\nimport { defineNuxtModule } from '@nuxt/kit'\n\nexport interface ModuleOptions {\n  apiKey: string\n}\n\nexport interface ModuleHooks {\n  'my-module:init': any\n}\n\nexport interface ModuleRuntimeHooks {\n  'my-module:runtime-hook': any\n}\n\nexport interface ModuleRuntimeConfig {\n  PRIVATE_NAME: string\n}\n\nexport interface ModulePublicRuntimeConfig {\n  NAME: string\n}\n\nexport default defineNuxtModule\u003cModuleOptions\u003e({\n  meta: {\n    name: 'my-module',\n    configKey: 'myModule'\n  },\n  defaults: {\n    apiKey: 'test'\n  },\n  async setup (moduleOptions, nuxt) {\n    // Write module logic in setup function\n  }\n})\n```\n\n### `src/runtime/`\n\nAny runtime file and code that we need to provide by module including plugins, composables and server api, should be in this directory.\n\nEach file will be transformed individually using [unjs/mkdist](https://github.com/unjs/mkdist) to `dist/runtime/`.\n\n\u003c!-- TODO: Docs about how to address runtime from within setup --\u003e\n\n### `package.json`:\n\nA minimum `package.json` should look like this:\n\n```json [package.json]\n{\n  \"name\": \"my-module\",\n  \"license\": \"MIT\",\n  \"version\": \"1.0.0\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/types.d.mts\",\n      \"import\": \"./dist/module.mjs\"\n    }\n  },\n  \"main\": \"./dist/module.mjs\",\n  \"typesVersions\": {\n    \"*\": {\n      \".\": [\n        \"./dist/types.d.mts\"\n      ]\n    }\n  },\n  \"files\": [\n    \"dist\"\n  ],\n  \"scripts\": {\n    \"prepack\": \"nuxt-module-build build\"\n  },\n  \"dependencies\": {\n    \"@nuxt/kit\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"@nuxt/module-builder\": \"latest\"\n  }\n}\n```\n\n### `build.config.ts` (optional)\n\nModule builder is essentially a preset for [unjs/unbuild](https://github.com/unjs/unbuild), check out the [build command](./src/commands/build.ts#L51) for reference.\n\nTo customize/extend the unbuild configuration you can add a `build.config.ts` in the root of your project:\n\n```ts\nimport { defineBuildConfig } from 'unbuild'\n\nexport default defineBuildConfig({\n  // set additional configuration or customize using hooks\n})\n```\n\n## Dist files\n\nModule builder generates dist files in `dist/` directory:\n\n- `module.mjs`: Module entrypoint build from `src/module`\n- `module.json`: Module meta extracted from `module.mjs` + `package.json`\n- `types.d.mts`: Exported types in addition to shims for `nuxt.config` auto completion.\n- `runtime/*`: Individually transformed files using [unjs/mkdist](https://github.com/unjs/mkdist)\n  - Javascript and `.ts` files will be transformed to `.js` with extracted types on `.d.ts` file with same name\n  - `.vue` files will be transformed with extracted `.d.ts` file\n  - Other files will be copied as is\n\n## 💻 Development\n\n- Clone repository\n- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`\n- Install dependencies using `pnpm install`\n- Try building [example module](./example) using `pnpm example:build`\n\n## License\n\n[MIT](./LICENSE) - Made with 💚\n\n\u003c!-- Badges --\u003e\n[npm-version-src]: https://img.shields.io/npm/v/@nuxt/module-builder/latest.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[npm-version-href]: https://npmjs.com/package/@nuxt/module-builder\n\n[npm-downloads-src]: https://img.shields.io/npm/dt/@nuxt/module-builder.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[npm-downloads-href]: https://npm.chart.dev/@nuxt/module-builder\n\n[license-src]: https://img.shields.io/github/license/nuxt/module-builder.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\n[license-href]: https://github.com/nuxt/module-builder/blob/main/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuxt%2Fmodule-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnuxt%2Fmodule-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuxt%2Fmodule-builder/lists"}