@nuxt/docs-nightly 4.3.0-29356103.2f7957ac → 4.3.0-29430616.754c35a4

package/3.guide/4.modules/3.recipes-basics.md

@@ -0,0 +1,299 @@
+---
+title: "Add Plugins, Components & More"
+description: "Learn how to inject plugins, components, composables and server routes from your module."
+---
+
+Here are some common patterns used by module authors.
+
+## Modify Nuxt Configuration
+
+Nuxt configuration can be read and altered by modules. Here's an example of a module enabling an experimental feature.
+
+```js
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    // We create the `experimental` object if it doesn't exist yet
+    nuxt.options.experimental ||= {}
+    nuxt.options.experimental.componentIslands = true
+  },
+})
+```
+
+When you need to handle more complex configuration alterations, you should consider using [defu](https://github.com/unjs/defu).
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/extending-and-altering-nuxt-configuration-and-options?friend=nuxt" target="_blank"}
+Watch Vue School video about altering Nuxt configuration.
+::
+
+## Expose Options to Runtime
+
+Because modules aren't part of the application runtime, their options aren't either. However, in many cases, you might need access to some of these module options within your runtime code. We recommend exposing the needed config using Nuxt's [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig).
+
+<!-- TODO: Update after #18466 (or equivalent) -->
+
+```js
+import { defineNuxtModule } from '@nuxt/kit'
+import { defu } from 'defu'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    nuxt.options.runtimeConfig.public.myModule = defu(nuxt.options.runtimeConfig.public.myModule, {
+      foo: options.foo,
+    })
+  },
+})
+```
+
+Note that we use [`defu`](https://github.com/unjs/defu) to extend the public runtime configuration the user provides instead of overwriting it.
+
+You can then access your module options in a plugin, component, the application like any other runtime configuration:
+
+```js
+import { useRuntimeConfig } from '@nuxt/kit'
+
+const options = useRuntimeConfig().public.myModule
+```
+
+::warning
+Be careful not to expose any sensitive module configuration on the public runtime config, such as private API keys, as they will end up in the public bundle.
+::
+
+:read-more{to="/docs/4.x/guide/going-further/runtime-config"}
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/passing-and-exposing-module-options?friend=nuxt" target="_blank"}
+Watch Vue School video about passing and exposing Nuxt module options.
+::
+
+## Add Plugins
+
+Plugins are a common way for a module to add runtime logic. You can use the `addPlugin` utility to register them from your module.
+
+```js
+import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    // Create resolver to resolve relative paths
+    const resolver = createResolver(import.meta.url)
+
+    addPlugin(resolver.resolve('./runtime/plugin'))
+  },
+})
+```
+
+:read-more{to="/docs/4.x/guide/going-further/kit"}
+
+## Add Components
+
+If your module should provide Vue components, you can use the `addComponent` utility to add them as auto-imports for Nuxt to resolve.
+
+```ts twoslash
+import { addComponent, createResolver, defineNuxtModule, useRuntimeConfig } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    // From the runtime directory
+    addComponent({
+      name: 'MySuperComponent', // name of the component to be used in vue templates
+      export: 'MySuperComponent', // (optional) if the component is a named (rather than default) export
+      filePath: resolver.resolve('runtime/components/MySuperComponent.vue'),
+    })
+
+    // From a library
+    addComponent({
+      name: 'MyAwesomeComponent', // name of the component to be used in vue templates
+      export: 'MyAwesomeComponent', // (optional) if the component is a named (rather than default) export
+      filePath: '@vue/awesome-components',
+    })
+  },
+})
+```
+
+Alternatively, you can add an entire directory by using `addComponentsDir`.
+
+```ts
+import { addComponentsDir, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    addComponentsDir({
+      path: resolver.resolve('runtime/components'),
+    })
+  },
+})
+```
+
+::tip{icon="i-lucide-lightbulb"}
+It is highly recommended to prefix your exports to avoid conflicts with user code or other modules.
+
+:read-more{to="/docs/4.x/guide/modules/best-practices#prefix-your-exports"}
+::
+
+## Add Composables
+
+If your module should provide composables, you can use the `addImports` utility to add them as auto-imports for Nuxt to resolve.
+
+```ts
+import { addImports, createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    addImports({
+      name: 'useComposable', // name of the composable to be used
+      as: 'useComposable',
+      from: resolver.resolve('runtime/composables/useComposable'), // path of composable
+    })
+  },
+})
+```
+
+Alternatively, you can add an entire directory by using `addImportsDir`.
+
+```ts
+import { addImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    addImportsDir(resolver.resolve('runtime/composables'))
+  },
+})
+```
+
+::tip{icon="i-lucide-lightbulb"}
+It is highly recommended to prefix your exports to avoid conflicts with user code or other modules.
+
+:read-more{to="/docs/4.x/guide/modules/best-practices#prefix-your-exports"}
+::
+
+## Add Server Routes
+
+```ts
+import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    addServerHandler({
+      route: '/api/_my-module/hello',
+      handler: resolver.resolve('./runtime/server/api/hello/index.get'),
+    })
+  },
+})
+```
+
+You can also add a dynamic server route:
+
+```ts
+import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    addServerHandler({
+      route: '/api/_my-module/hello/:name',
+      handler: resolver.resolve('./runtime/server/api/hello/[name].get'),
+    })
+  },
+})
+```
+
+::tip{icon="i-lucide-lightbulb"}
+It is highly recommended to prefix your server routes to avoid conflicts with user-defined routes. Common paths like `/api/auth`, `/api/login`, or `/api/user` may already be used by the application.
+
+:read-more{to="/docs/4.x/guide/modules/best-practices#prefix-your-exports"}
+::
+
+## Add Other Assets
+
+If your module should provide other kinds of assets, they can also be injected. Here's a simple example module injecting a stylesheet through Nuxt's `css` array.
+
+```js
+import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    nuxt.options.css.push(resolver.resolve('./runtime/style.css'))
+  },
+})
+```
+
+And a more advanced one, exposing a folder of assets through [Nitro](/docs/4.x/guide/concepts/server-engine)'s `publicAssets` option:
+
+```js
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    nuxt.hook('nitro:config', (nitroConfig) => {
+      nitroConfig.publicAssets ||= []
+      nitroConfig.publicAssets.push({
+        dir: resolver.resolve('./runtime/public'),
+        maxAge: 60 * 60 * 24 * 365, // 1 year
+      })
+    })
+  },
+})
+```
+
+## Use Other Modules
+
+If your module depends on other modules, you can specify them using the `moduleDependencies` option. This provides a more robust way to handle module dependencies with version constraints and configuration merging:
+
+```ts
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+
+const resolver = createResolver(import.meta.url)
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'my-module',
+  },
+  moduleDependencies: {
+    '@nuxtjs/tailwindcss': {
+      // You can specify a version constraint for the module
+      version: '>=6',
+      // Any configuration that should override `nuxt.options`
+      overrides: {
+        exposeConfig: true,
+      },
+      // Any configuration that should be set. It will override module defaults but
+      // will not override any configuration set in `nuxt.options`
+      defaults: {
+        config: {
+          darkMode: 'class',
+          content: {
+            files: [
+              resolver.resolve('./runtime/components/**/*.{vue,mjs,ts}'),
+              resolver.resolve('./runtime/*.{mjs,js,ts}'),
+            ],
+          },
+        },
+      },
+    },
+  },
+  setup (options, nuxt) {
+    // We can inject our CSS file which includes Tailwind's directives
+    nuxt.options.css.push(resolver.resolve('./runtime/assets/styles.css'))
+  },
+})
+```
+
+::callout{type="info"}
+The `moduleDependencies` option replaces the deprecated `installModule` function and ensures proper setup order and configuration merging.
+::

package/3.guide/4.modules/4.recipes-advanced.md

@@ -0,0 +1,231 @@
+---
+title: "Use Hooks & Extend Types"
+description: "Master lifecycle hooks, virtual files and TypeScript declarations in your modules."
+---
+
+Here are some advanced patterns for authoring modules, including hooks, templates, and type augmentation.
+
+## Use Lifecycle Hooks
+
+[Lifecycle hooks](/docs/4.x/guide/going-further/hooks) allow you to expand almost every aspect of Nuxt. Modules can hook to them programmatically or through the `hooks` map in their definition.
+
+```js
+import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  // Hook to the `app:error` hook through the `hooks` map
+  hooks: {
+    'app:error': (err) => {
+      console.info(`This error happened: ${err}`)
+    },
+  },
+  setup (options, nuxt) {
+    // Programmatically hook to the `pages:extend` hook
+    nuxt.hook('pages:extend', (pages) => {
+      console.info(`Discovered ${pages.length} pages`)
+    })
+  },
+})
+```
+
+:read-more{to="/docs/4.x/api/advanced/hooks"}
+
+::tip{icon="i-lucide-video" to="https://vueschool.io/lessons/nuxt-lifecycle-hooks?friend=nuxt" target="_blank"}
+Watch Vue School video about using Nuxt lifecycle hooks in modules.
+::
+
+::note
+**Module cleanup**
+:br
+:br
+If your module opens, handles, or starts a watcher, you should close it when the Nuxt lifecycle is done. The `close` hook is available for this.
+
+```ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    nuxt.hook('close', async (nuxt) => {
+      // Your custom code here
+    })
+  },
+})
+```
+::
+
+### Create Custom Hooks
+
+Modules can also define and call their own hooks, which is a powerful pattern for making your module extensible.
+
+If you expect other modules to be able to subscribe to your module's hooks, you should call them in the `modules:done` hook. This ensures that all other modules have had a chance to be set up and register their listeners to your hook during their own `setup` function.
+
+```ts
+// my-module/module.ts
+import { defineNuxtModule } from '@nuxt/kit'
+
+export interface ModuleHooks {
+  'my-module:custom-hook': (payload: { foo: string }) => void
+}
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    // Call your hook in `modules:done`
+    nuxt.hook('modules:done', async () => {
+      const payload = { foo: 'bar' }
+      await nuxt.callHook('my-module:custom-hook', payload)
+    })
+  },
+})
+```
+
+## Add Virtual Files
+
+If you need to add a virtual file that can be imported into the user's app, you can use the `addTemplate` utility.
+
+```ts
+import { addTemplate, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    // The file is added to Nuxt's internal virtual file system and can be imported from '#build/my-module-feature.mjs'
+    addTemplate({
+      filename: 'my-module-feature.mjs',
+      getContents: () => 'export const myModuleFeature = () => "hello world !"',
+    })
+  },
+})
+```
+
+For the server, you should use the `addServerTemplate` utility instead.
+
+```ts
+import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    // The file is added to Nitro's virtual file system and can be imported in the server code from 'my-server-module.mjs'
+    addServerTemplate({
+      filename: 'my-server-module.mjs',
+      getContents: () => 'export const myServerModule = () => "hello world !"',
+    })
+  },
+})
+```
+
+## Update Virtual Files
+
+If you need to update your templates/virtual files, you can leverage the `updateTemplates` utility like this:
+
+```ts
+nuxt.hook('builder:watch', (event, path) => {
+  if (path.includes('my-module-feature.config')) {
+    // This will reload the template that you registered
+    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
+  }
+})
+```
+
+## Add Type Declarations
+
+You might also want to add a type declaration to the user's project (for example, to augment a Nuxt interface
+or provide a global type of your own). For this, Nuxt provides the `addTypeTemplate` utility that both
+writes a template to the disk and adds a reference to it in the generated `nuxt.d.ts` file.
+
+If your module should augment types handled by Nuxt, you can use `addTypeTemplate` to perform this operation:
+
+```js
+import { addTemplate, addTypeTemplate, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    addTypeTemplate({
+      filename: 'types/my-module.d.ts',
+      getContents: () => `// Generated by my-module
+        interface MyModuleNitroRules {
+          myModule?: { foo: 'bar' }
+        }
+        declare module 'nitropack/types' {
+          interface NitroRouteRules extends MyModuleNitroRules {}
+          interface NitroRouteConfig extends MyModuleNitroRules {}
+        }
+        export {}`,
+    })
+  },
+})
+```
+
+If you need more granular control, you can use the `prepare:types` hook to register a callback that will inject your types.
+
+```ts
+const template = addTemplate({ /* template options */ })
+nuxt.hook('prepare:types', ({ references }) => {
+  references.push({ path: template.dst })
+})
+```
+
+## Extend TypeScript Config
+
+There are multiple ways to extend the TypeScript configuration of the user's project from your module.
+
+The simplest way is to modify the Nuxt configuration directly like this:
+
+<!-- @case-police-ignore tsConfig -->
+```ts
+// extend tsconfig.app.json
+nuxt.options.typescript.tsConfig.include ??= []
+nuxt.options.typescript.tsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.shared.json
+nuxt.options.typescript.sharedTsConfig.include ??= []
+nuxt.options.typescript.sharedTsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.node.json
+nuxt.options.typescript.nodeTsConfig.include ??= []
+nuxt.options.typescript.nodeTsConfig.include.push(resolve('./augments.d.ts'))
+
+// extend tsconfig.server.json
+nuxt.options.nitro.typescript ??= {}
+nuxt.options.nitro.typescript.tsConfig ??= {}
+nuxt.options.nitro.typescript.tsConfig.include ??= []
+nuxt.options.nitro.typescript.tsConfig.include.push(resolve('./augments.d.ts'))
+```
+
+Alternatively, you can use the `prepare:types` and `nitro:prepare:types` hooks to extend the TypeScript references for specific type contexts, or modify the TypeScript configuration similar to the example above.
+
+```ts
+nuxt.hook('prepare:types', ({ references, sharedReferences, nodeReferences }) => {
+  // extend app context
+  references.push({ path: resolve('./augments.d.ts') })
+  // extend shared context
+  sharedReferences.push({ path: resolve('./augments.d.ts') })
+  // extend node context
+  nodeReferences.push({ path: resolve('./augments.d.ts') })
+})
+
+nuxt.hook('nitro:prepare:types', ({ references }) => {
+  // extend server context
+  references.push({ path: resolve('./augments.d.ts') })
+})
+```
+
+::note
+TypeScript references add files to the type context [without being affected by the `exclude` option in `tsconfig.json`](https://www.typescriptlang.org/tsconfig/#exclude).
+::
+
+## Augment Types
+
+Nuxt automatically includes your module's directories in the appropriate type contexts. To augment types from your module, all you need to do is place the type declaration file in the appropriate directory based on the augmented type context. Alternatively, you can [extend the TypeScript configuration](#extend-typescript-config) to augment from an arbitrary location.
+
+- `my-module/runtime/` - app type context (except for the `runtime/server` directory)
+- `my-module/runtime/server/` - server type context
+- `my-module/` - node type context (except for the `runtime/` and `runtime/server` directories)
+
+```bash [Directory Structure]
+-| my-module/   # node type context
+---| runtime/   # app type context
+------| augments.app.d.ts
+------| server/ # server type context
+---------| augments.server.d.ts
+---| module.ts
+---| augments.node.d.ts
+```

package/3.guide/4.modules/5.testing.md

@@ -0,0 +1,76 @@
+---
+title: "Test Your Module"
+description: "Learn how to test your Nuxt module with unit, integration and E2E tests."
+---
+
+Testing helps ensure your module works as expected given various setups. Find in this section how to perform various kinds of tests against your module.
+
+## Write Unit Tests
+
+::tip
+We're still discussing and exploring how to ease unit and integration testing on Nuxt modules.
+:br :br
+[Check out this RFC to join the conversation](https://github.com/nuxt/nuxt/discussions/18399).
+::
+
+## Write E2E Tests
+
+[Nuxt Test Utils](/docs/4.x/getting-started/testing) is the go-to library to help you test your module in an end-to-end way. Here's the workflow to adopt with it:
+
+1. Create a Nuxt application to be used as a "fixture" inside `test/fixtures/*`
+2. Setup Nuxt with this fixture inside your test file
+3. Interact with the fixture using utilities from `@nuxt/test-utils` (e.g. fetching a page)
+4. Perform checks related to this fixture (e.g. "HTML contains ...")
+5. Repeat
+
+In practice, the fixture:
+
+```ts [test/fixtures/ssr/nuxt.config.ts]
+// 1. Create a Nuxt application to be used as a "fixture"
+import MyModule from '../../../src/module'
+
+export default defineNuxtConfig({
+  ssr: true,
+  modules: [
+    MyModule,
+  ],
+})
+```
+
+And its test:
+
+```ts [test/rendering.ts]
+import { describe, expect, it } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { $fetch, setup } from '@nuxt/test-utils/e2e'
+
+describe('ssr', async () => {
+  // 2. Setup Nuxt with this fixture inside your test file
+  await setup({
+    rootDir: fileURLToPath(new URL('./fixtures/ssr', import.meta.url)),
+  })
+
+  it('renders the index page', async () => {
+    // 3. Interact with the fixture using utilities from `@nuxt/test-utils`
+    const html = await $fetch('/')
+
+    // 4. Perform checks related to this fixture
+    expect(html).toContain('<div>ssr</div>')
+  })
+})
+
+// 5. Repeat
+describe('csr', async () => { /* ... */ })
+```
+
+::tip
+An example of such a workflow is available on [the module starter](https://github.com/nuxt/starter/blob/module/test/basic.test.ts).
+::
+
+## Test Manually
+
+Having a playground Nuxt application to test your module when developing it is really useful. [The module starter integrates one for that purpose](/docs/4.x/guide/modules/getting-started#develop-your-module).
+
+You can test your module with other Nuxt applications (applications that are not part of your module repository) locally. To do so, you can use [`npm pack`](https://docs.npmjs.com/cli/commands/npm-pack/) command, or your package manager equivalent, to create a tarball from your module. Then in your test project, you can add your module to `package.json` packages as: `"my-module": "file:/path/to/tarball.tgz"`.
+
+After that, you should be able to reference `my-module` like in any regular project.