From 4b74f7343483366f070b56094048e12917ee3670 Mon Sep 17 00:00:00 2001 From: Aleksa Date: Thu, 15 Sep 2022 11:43:08 +0200 Subject: [PATCH 1/5] docs(kit): add few more examples --- .../2.guide/4.going-further/3.modules.md | 34 +++++++++++++++++-- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/docs/content/2.guide/4.going-further/3.modules.md b/docs/content/2.guide/4.going-further/3.modules.md index ed63c69aa48..c6da7159d3d 100644 --- a/docs/content/2.guide/4.going-further/3.modules.md +++ b/docs/content/2.guide/4.going-further/3.modules.md @@ -184,7 +184,7 @@ Commonly, modules provide one or more run plugins to add runtime logic. import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit' export default defineNuxtModule({ - setup (options, nuxt) { + setup(options, nuxt) { // Create resolver to resolve relative paths const { resolve } = createResolver(import.meta.url) @@ -204,12 +204,32 @@ If your module will provide a CSS library, make sure to check if the user alread import { defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ - setup (options, nuxt) { + setup(options, nuxt) { nuxt.options.css.push('font-awesome/css/font-awesome.css') } }) ``` +### Adding Vue Components + +If your module should provide Vue components, you can use `addComponents` utility to add them as auto-imports for nuxt to resolve. + +```ts +import { defineNuxtModule, addComponent } from '@nuxt/kit' + +export default defineNuxtModule({ + setup(options, nuxt) { + addComponent({ + name: 'MyComponent', // name of the component + export: 'MyAwesomeComponent', // (optional) name of the component to be used in vue templates + // filePath should be package name or resolved path + // if the component is created locally, preferably in `runtime` dir + filePath: '@vue/awesome-components' // resolve(runtimeDir, 'components', 'MyComponent.vue') + }) + } +}) +``` + ### Clean Up Module If your module opens, handles or starts a watcher, you should close it when the Nuxt lifecycle is done. For this, use the `close` hook: @@ -218,10 +238,18 @@ If your module opens, handles or starts a watcher, you should close it when the import { defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ - setup (options, nuxt) { + setup(options, nuxt) { nuxt.hook('close', async nuxt => { // Your custom code here }) } }) ``` + +### Testing a Module + +Nuxt also has a testing library for testing nuxt apps, which includes modules. You can check out [testing example](/examples/advanced/testing), to see how `@nuxt/test-utils` utilize `playwright` to test nuxt app. + +If you wish to test your module outside of the module playground, recommended way is to use [npm-pack](https://docs.npmjs.com/cli/v7/commands/npm-pack), or your package manager equivalent, to create tarball from your module. Then in your test project, you can add module to `package.json` packages as: `"nuxt-module-name": "file:/path/to/tarball.tgz"` + +After that, you should be able to reference `nuxt-module-name` like in any regular project. From a834ed853f3b12cde5accff1730692c0adff0d4e Mon Sep 17 00:00:00 2001 From: Aleksa Date: Thu, 15 Sep 2022 11:44:19 +0200 Subject: [PATCH 2/5] docs: update to new auto-import utils --- docs/content/3.api/4.advanced/2.kit.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/3.api/4.advanced/2.kit.md b/docs/content/3.api/4.advanced/2.kit.md index ede041d8a64..fa45bd981b8 100644 --- a/docs/content/3.api/4.advanced/2.kit.md +++ b/docs/content/3.api/4.advanced/2.kit.md @@ -34,8 +34,8 @@ [source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/imports.ts) -- `addAutoImport(imports)` -- `addAutoImportDir(autoImportDirs)` +- `addImports(imports)` +- `addImportsDir(autoImportDirs)` ### Components From c19dee29717fc7d29791a24b5503f798fe25153c Mon Sep 17 00:00:00 2001 From: Daniel Roe Date: Thu, 15 Sep 2022 10:59:53 +0100 Subject: [PATCH 3/5] docs: small tweaks --- .../content/2.guide/4.going-further/3.modules.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/content/2.guide/4.going-further/3.modules.md b/docs/content/2.guide/4.going-further/3.modules.md index c6da7159d3d..ab469477288 100644 --- a/docs/content/2.guide/4.going-further/3.modules.md +++ b/docs/content/2.guide/4.going-further/3.modules.md @@ -184,7 +184,7 @@ Commonly, modules provide one or more run plugins to add runtime logic. import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit' export default defineNuxtModule({ - setup(options, nuxt) { + setup (options, nuxt) { // Create resolver to resolve relative paths const { resolve } = createResolver(import.meta.url) @@ -204,7 +204,7 @@ If your module will provide a CSS library, make sure to check if the user alread import { defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ - setup(options, nuxt) { + setup (options, nuxt) { nuxt.options.css.push('font-awesome/css/font-awesome.css') } }) @@ -212,7 +212,7 @@ export default defineNuxtModule({ ### Adding Vue Components -If your module should provide Vue components, you can use `addComponents` utility to add them as auto-imports for nuxt to resolve. +If your module should provide Vue components, you can use the `addComponent` utility to add them as auto-imports for Nuxt to resolve. ```ts import { defineNuxtModule, addComponent } from '@nuxt/kit' @@ -220,8 +220,8 @@ import { defineNuxtModule, addComponent } from '@nuxt/kit' export default defineNuxtModule({ setup(options, nuxt) { addComponent({ - name: 'MyComponent', // name of the component - export: 'MyAwesomeComponent', // (optional) name of the component to be used in vue templates + name: 'MyComponent', // name of the component to be used in vue templates + export: 'MyAwesomeComponent', // (optional) if the component is a named (rather than default) export // filePath should be package name or resolved path // if the component is created locally, preferably in `runtime` dir filePath: '@vue/awesome-components' // resolve(runtimeDir, 'components', 'MyComponent.vue') @@ -238,7 +238,7 @@ If your module opens, handles or starts a watcher, you should close it when the import { defineNuxtModule } from '@nuxt/kit' export default defineNuxtModule({ - setup(options, nuxt) { + setup (options, nuxt) { nuxt.hook('close', async nuxt => { // Your custom code here }) @@ -248,8 +248,8 @@ export default defineNuxtModule({ ### Testing a Module -Nuxt also has a testing library for testing nuxt apps, which includes modules. You can check out [testing example](/examples/advanced/testing), to see how `@nuxt/test-utils` utilize `playwright` to test nuxt app. +Nuxt also has a testing library for testing Nuxt apps, which includes modules. You can check out [testing example](/examples/advanced/testing), to see how `@nuxt/test-utils` utilizes `playwright` to test nuxt app. -If you wish to test your module outside of the module playground, recommended way is to use [npm-pack](https://docs.npmjs.com/cli/v7/commands/npm-pack), or your package manager equivalent, to create tarball from your module. Then in your test project, you can add module to `package.json` packages as: `"nuxt-module-name": "file:/path/to/tarball.tgz"` +If you wish to test your module outside of the module playground, the recommended way is to use [npm-pack](https://docs.npmjs.com/cli/v7/commands/npm-pack), 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: `"nuxt-module-name": "file:/path/to/tarball.tgz"` After that, you should be able to reference `nuxt-module-name` like in any regular project. From bbcd031b13604afa7398c26ba9e559f38a65dbf1 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Thu, 15 Sep 2022 13:18:37 +0200 Subject: [PATCH 4/5] update testing section --- .../2.guide/4.going-further/3.modules.md | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/content/2.guide/4.going-further/3.modules.md b/docs/content/2.guide/4.going-further/3.modules.md index ab469477288..b2017b13d4e 100644 --- a/docs/content/2.guide/4.going-further/3.modules.md +++ b/docs/content/2.guide/4.going-further/3.modules.md @@ -174,6 +174,19 @@ By moving your modules to [nuxt-community](https://github.com/nuxt-community), t If you have an already published and working module and want to transfer it to nuxt-community, open an issue in [nuxt/modules](https://github.com/nuxt/modules/issues/new). +## Testing + +### `@nuxt/test-utils` + +Nuxt 3 has a testing library for testing Nuxt apps and modules. You can check out [testing modules](/getting-started/testing#testing-modules) for more information and examples. + +### Testing Externally + +If you wish to test your module outside of the module playground before publishing to npm, you can use [`npm pack`](https://docs.npmjs.com/cli/v7/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: `"nuxt-module-name": "file:/path/to/tarball.tgz"`. + +After that, you should be able to reference `nuxt-module-name` like in any regular project. + + ## Examples ### Provide Nuxt Plugins @@ -246,10 +259,3 @@ export default defineNuxtModule({ }) ``` -### Testing a Module - -Nuxt also has a testing library for testing Nuxt apps, which includes modules. You can check out [testing example](/examples/advanced/testing), to see how `@nuxt/test-utils` utilizes `playwright` to test nuxt app. - -If you wish to test your module outside of the module playground, the recommended way is to use [npm-pack](https://docs.npmjs.com/cli/v7/commands/npm-pack), 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: `"nuxt-module-name": "file:/path/to/tarball.tgz"` - -After that, you should be able to reference `nuxt-module-name` like in any regular project. From 47e9d8eb272f5f16e320c6b687c540ad28eb48f9 Mon Sep 17 00:00:00 2001 From: Pooya Parsa Date: Thu, 15 Sep 2022 13:20:20 +0200 Subject: [PATCH 5/5] lint docs --- docs/content/2.guide/4.going-further/3.modules.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/content/2.guide/4.going-further/3.modules.md b/docs/content/2.guide/4.going-further/3.modules.md index b2017b13d4e..7901dd6516d 100644 --- a/docs/content/2.guide/4.going-further/3.modules.md +++ b/docs/content/2.guide/4.going-further/3.modules.md @@ -186,7 +186,6 @@ If you wish to test your module outside of the module playground before publishi After that, you should be able to reference `nuxt-module-name` like in any regular project. - ## Examples ### Provide Nuxt Plugins @@ -258,4 +257,3 @@ export default defineNuxtModule({ } }) ``` -