gil
5f664546cf
- CLAUDE.md 운영 규칙 - wiki/ 정리된 지식 페이지 (Nuxt + Claude Code) - raw/ 원본 자료 - reference/ Nuxt 4.x 공식 문서 Co-authored-by: Cursor <cursoragent@cursor.com>
104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
---
|
|
title: "Create Your First Module"
|
|
description: "Learn how to create your first Nuxt module using the official starter template."
|
|
---
|
|
|
|
## Create a Module
|
|
|
|
We recommend you get started with Nuxt modules using our [starter template](https://github.com/nuxt/starter/tree/module):
|
|
|
|
::code-group{sync="pm"}
|
|
|
|
```bash [npm]
|
|
npm create nuxt -- -t module my-module
|
|
```
|
|
|
|
```bash [yarn]
|
|
yarn create nuxt -t module my-module
|
|
```
|
|
|
|
```bash [pnpm]
|
|
pnpm create nuxt -t module my-module
|
|
```
|
|
|
|
```bash [bun]
|
|
bun create nuxt --template=module my-module
|
|
```
|
|
::
|
|
|
|
This will create a `my-module` project with all the boilerplate necessary to develop and publish your module.
|
|
|
|
**Next steps:**
|
|
|
|
1. Open `my-module` in your IDE of choice
|
|
2. Install dependencies using your favorite package manager
|
|
3. Prepare local files for development using `npm run dev:prepare`
|
|
4. Follow this document to learn more about Nuxt modules
|
|
|
|
## Use the Starter Template
|
|
|
|
Learn how to perform basic tasks with the module starter.
|
|
|
|
::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/navigating-the-official-starter-template?friend=nuxt" target="_blank"}
|
|
Watch Vue School video about Nuxt module starter template.
|
|
::
|
|
|
|
### Develop Your Module
|
|
|
|
While your module source code lives inside the `src` directory, to develop a module you often need a Nuxt application to test it against. That's what the `playground` directory is for. It's a Nuxt application you can tinker with that is already configured to run with your module.
|
|
|
|
You can interact with the playground like with any Nuxt application.
|
|
|
|
- Launch its development server with `npm run dev`, it should reload itself as you make changes to your module in the `src` directory
|
|
- Build it with `npm run dev:build`
|
|
|
|
::note
|
|
All other `nuxt` commands can be used against the `playground` directory (e.g. `nuxt <COMMAND> playground`). Feel free to declare additional `dev:*` scripts within your `package.json` referencing them for convenience.
|
|
::
|
|
|
|
### Run Tests
|
|
|
|
The module starter comes with a basic test suite:
|
|
|
|
- A linter powered by [ESLint](https://eslint.org), run it with `npm run lint`
|
|
- A test runner powered by [Vitest](https://vitest.dev), run it with `npm run test` or `npm run test:watch`
|
|
|
|
::tip
|
|
Feel free to augment this default test strategy to better suit your needs.
|
|
::
|
|
|
|
### Build Your Module
|
|
|
|
Nuxt modules come with their own builder provided by [`@nuxt/module-builder`](https://github.com/nuxt/module-builder#readme). This builder doesn't require any configuration on your end, supports TypeScript, and makes sure your assets are properly bundled to be distributed to other Nuxt applications.
|
|
|
|
You can build your module by running `npm run prepack`.
|
|
|
|
::tip
|
|
While building your module can be useful in some cases, most of the time you won't need to build it on your own: the `playground` takes care of it while developing, and the release script also has you covered when publishing.
|
|
::
|
|
|
|
### Publish to npm
|
|
|
|
::important
|
|
Before publishing your module to npm, makes sure you have an [npmjs.com](https://www.npmjs.com) account and that you're authenticated to it locally with `npm login`.
|
|
::
|
|
|
|
While you can publish your module by bumping its version and using the `npm publish` command, the module starter comes with a release script that helps you make sure you publish a working version of your module to npm and more.
|
|
|
|
To use the release script, first, commit all your changes (we recommend you follow [Conventional Commits](https://www.conventionalcommits.org) to also take advantage of automatic version bump and changelog update), then run the release script with `npm run release`.
|
|
|
|
When running the release script, the following will happen:
|
|
|
|
- First, it will run your test suite by:
|
|
- Running the linter (`npm run lint`)
|
|
- Running unit, integration, and e2e tests (`npm run test`)
|
|
- Building the module (`npm run prepack`)
|
|
- Then, if your test suite went well, it will proceed to publish your module by:
|
|
- Bumping your module version and generating a changelog according to your Conventional Commits
|
|
- Publishing the module to npm (for that purpose, the module will be built again to ensure its updated version number is taken into account in the published artifact)
|
|
- Pushing a git tag representing the newly published version to your git remote origin
|
|
|
|
::tip
|
|
As with other scripts, feel free to fine-tune the default `release` script in your `package.json` to better suit your needs.
|
|
::
|