Zengtudor/Nuxt
1
0
Fork 0
mirror of https://github.com/nuxt/nuxt.git synced 2025-01-18 01:15:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add advanced section for module authors (#2950)

Browse Source
This commit is contained in:
pooya parsa 2022-01-27 18:02:42 +01:00 committed by GitHub
parent 8ea6b652b9
commit 9ef94d19f7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 478 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/content/3.docs/1.usage/4.nuxt-app.md
View File

@ -39,39 +39,3 @@ In Nuxt 2 plugins, this was referred to as [inject function](https://nuxtjs.org/
::alert{icon=👉} ::alert{icon=👉}
It is possible to inject helpers by returning an object with a `provide` key. See the [plugins documentation](/docs/directory-structure/plugins) for more information. It is possible to inject helpers by returning an object with a `provide` key. See the [plugins documentation](/docs/directory-structure/plugins) for more information.
:: ::
## NuxtApp interface (advanced)
`nuxtApp` has the following properties: (note: this is an internal interface and some properties might change until stable release)
```js
const nuxtApp = {
vueApp, // the global Vue application: https://v3.vuejs.org/api/application-api.html
// These let you call and add runtime NuxtApp hooks
// https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts#L18
hooks,
hook,
callHook,
// Only accessible on server-side
ssrContext: {
url,
req,
res,
runtimeConfig,
noSSR,
},
// This will be stringified and passed from server to client
payload: {
serverRendered: true,
data: {},
state: {}
}
provide: (name: string, value: any) => void
}
```
For more information, check out [the source code](https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts#L28-L53).

98
docs/content/3.docs/2.directory-structure/8.modules.md
View File

@ -1,98 +0,0 @@
---
icon: IconDirectory
title: 'modules'
navigation: false
head.title: Local modules directory
---
# Local modules directory
Nuxt has a powerful modules engine.
# Creating Modules
Nuxt provides helper functions (accessed from `@nuxt/kit`) to assist in creating modules that can run on both Nuxt 2 and Nuxt 3.
```js
import { defineNuxtModule } from '@nuxt/kit'
export default defineNuxtModule({
meta: {
// The npm package name of your module
name: '@nuxtjs/sample-module',
// The key in `nuxt.config` that holds your module options
configKey: 'sample',
},
// Default configuration options for your module
defaults: {},
hooks: {},
setup (options, nuxt) {},
})
```
## Module options
Nuxt will automatically merge the configuration provided to your module (whether passed directly inline or in a configuration section in `nuxt.config`) with the defaults you provide.
```js
export default {
buildModules: [
['@nuxtjs/sample-module', { sampleOption: true }]
],
sample: {
anotherOption: 42
}
}
```
## Hooks
For simple modules, you may be able to implement all you need simply with several hooks in this section.
## Setup
If the `hooks` configuration is not enough, you can provide a full setup function, with access to `nuxt`. You will no longer have access to `this` as in the previous Nuxt module specification, but there are dedicated helper functions from `@nuxt/kit` to replace the module container methods from previously.
```js
import { defineNuxtModule, addPlugin } from '@nuxt/kit'
export default defineNuxtModule({
// ...
setup (options, nuxt) {
addPlugin({
src: path.resolve(__dirname, 'templates/foo.js')
})
},
})
```
## Advanced usage
In some cases you may need access to the Nuxt instance in order to define your module, for example, using other Nuxt options:
```js
import { defineNuxtModule } from '@nuxt/kit'
export default defineNuxtModule(nuxt => ({
// ...
defaults: {
root: nuxt.options.rootDir
},
}))
```
## Module helpers
A number of helpers are also provided for use within this context (with more coming - feature requests welcome) that ensure compatible behavior across Nuxt versions.
* addTemplate
* addErrorLayout
* addLayout
* addPlugin
* addServerMiddleware
* extendBuild
* extendRoutes
Each of these functions provides documentation via IDE hover/autocomplete.
## Publishing to NPM

77
docs/content/3.docs/4.advanced/1.nuxt.md Normal file
View File

@ -0,0 +1,77 @@
# Nuxt Internals
Nuxt is a minimal but highly customizable framework to build web applications. This guide helps you better understand Nuxt internals to develop new solutions and module integrations on top of Nuxt.
## The Nuxt interface
When you start nuxt in development mode with `nuxi dev` or building a production application with `nuxi build`,
a common context will be created, referred to as `nuxt` internally. It holds normalized options merged with `nuxt.config` file,
some internal state, and a powerful [hooking system](/docs/advanced/hooks) powered by [unjs/hookable](https://github.com/unjs/hookable)
allowing different components to communicate with each other. You can think of it as **Builder Core**.
This context is globally available to be used with [nuxt/kit](/docs/advanced/kit) composables.
Therefore only one instance of Nuxt is allowed to run per process.
To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt Modules](/docs/advanced/modules).
For more details, check out [the source code](https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/core/nuxt.ts).
## The NuxtApp interface
When rendering a page in Browser or server-side, a shared context will be created, referred to as `nuxtApp`.
This context keeps vue instance, runtime hooks, and internal states like ssrContext and payload for hydration.
You can think of it as **Runtime Core**.
This context can be accessed using `useNuxtApp()` composable within nuxt plugins and `<script setup>` and vue composables.
Global usage is only possible for Browser but not possible on the server-side to avoid sharing context between users.
To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/directory-structure/plugins).
Check [Nuxt App](http://localhost:4000/docs/usage/nuxt-app) for more information about this interface.
`nuxtApp` has the following properties:
Note: this is an internal interface, and some properties might change until stable release.
```js
const nuxtApp = {
vueApp, // the global Vue application: https://v3.vuejs.org/api/application-api.html
// These let you call and add runtime NuxtApp hooks
// https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts#L18
hooks,
hook,
callHook,
// Only accessible on server-side
ssrContext: {
url,
req,
res,
runtimeConfig,
noSSR,
},
// This will be stringified and passed from server to client
payload: {
serverRendered: true,
data: {},
state: {}
}
provide: (name: string, value: any) => void
}
```
For more details, check out [the source code](https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts).
## Runtime Context vs. Build Context
Nuxt builds and bundles project using Node.js but also has a runtime side.
While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!
`nuxt.config` and [Nuxt Modules](/docs/advanced/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/directory-structure/plugins) can be used to extend runtime.
When building an application for production `nuxi build` will generate a standalone build
in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/advanced/modules).

214
docs/content/3.docs/4.advanced/2.modules.md Normal file
View File

@ -0,0 +1,214 @@
# Nuxt Modules
Nuxt provides a zero-config experience with a preset of integrations and best practices to develop Web applications.
A powerful configuration and hooks system makes it possible to customize almost every aspect of Nuxt Framework and add endless possible integrations when it comes to customization. You can learn more about how nuxt works in [Nuxt internals](/docs/advanced/nuxt) section.
Nuxt exposes a powerful API called **Nuxt Modules**. Nuxt modules are simple async functions that sequentially run when starting nuxt in development mode using `nuxi dev` or building a project for production with `nuxi build`.
Using Nuxt Modules, we can encapsulate, properly test and share custom solutions as npm packages without adding unnecessary boilerplate to the Nuxt project itself.
Nuxt Modules can hook into lifecycle events of Nuxt builder, provide runtime app templates, update the configuration or do any other custom action based on needs.
## Quick Start
For the impatient ones, You can quickly start with [module-builder](https://github.com/nuxt/module-builder) and [module starter template](https://github.com/nuxt/starter/tree/module):
```bash
npx nuxi init -t module my-module
```
Starter template and module starter is a standard path of creating a Nuxt module.
**Next steps:**
- Open `my-module` in IDE of your choice (VSCode is recommended)
- Install dependencies using the package manager of your choice (Yarn is recommended)
- Ensure local files are generated using `npm run prepare`
- Start playground using `npm run dev`
- **Follow this document to learn more about Nuxt modules**
::alert{type=warning icon=🚧}
This is an under-the-progress guide. Please regularly check for updates.
::
## Module Anatomy
A Nuxt module is a simple function accepting inline user options and `nuxt` arguments.
It is totally up to you, as the module author, how to handle the rest of the logic.
Starting with Nuxt 3, modules can benefit all [Nuxt Kit](/docs/advanced/kit) utilities.
```ts [modules/example.ts]
// modules/module.mjs
export default async (inlineOptions, nuxt) => {
// You can do whatever you like here..
console.log(moduleOptions.token) // `123`
console.log(nuxt.options.dev) // `true` or `false`
nuxt.hook('ready', async nuxt => {
console.log('Nuxt is ready')
})
}
```
```ts [nuxt.config]
export default defineNuxtConfig({
modules: [
// Using package name (recommanded usage)
'@nuxtjs/example',
// Load a local module
'./modules/example',
// Add module with inline-options
['./modules/example', { token: '123' }]
// Inline module definition
async (inlineOptions, nuxt) => { }
]
})
```
## Defining Nuxt Modules
Creating Nuxt modules involves tedious and common tasks. [Nuxt Kit](/docs/advanced/kit), provides a convenient and standard API to define Nuxt modules using `defineNuxtModule`:
```js
export default defineNuxtModule({
meta: {
// Usually npm package name of your module
name: '@nuxtjs/example',
// The key in `nuxt.config` that holds your module options
configKey: 'sample',
// Compatibility constraints
compatibility: {
// Semver version of supported nuxt versions
nuxt: '^3.0.0'
}
},
// Default configuration options for your module
defaults: {},
hooks: {},
async setup(moduleOptions, nuxt) {
// -- Add your module logic here --
}
})
```
Result of `defineNuxtModule` is a wrapper function with `(inlineOptions, nuxt)` signature. It applies defaults and other necessary steps and calls the`setup` function when called.
**`defineNuxtModule` features:**
- Support `defaults` and `meta.configKey` for automatically merging module options
- Type hints and automated type inference
- Add shims for basic Nuxt 2 compatibility
- Ensure module get's installed only once using a unique key computed from `meta.name` or `meta.configKey`
- Automatically register Nuxt hooks
- Automatically check for compatibility issues based on module meta
- Expose `getOptions` and `getMeta` for internal usage of Nuxt
- Ensuring backward and upward compatibility as long as the module is using `defineNuxtmodule` from the latest version of `@nuxt/kit`
- Integration with module builder tooling
## Best practices
### Async Modules
Nuxt Modules can do asynchronous operations. For example, you may want to develop a module that needs fetching some API or calling an async function.
::alert{type="warning"}
Be careful that `nuxi dev` waits for your module setup before going to the next module and starting the development server. Do time-consuming logic using deferred Nuxt hooks.
::
### Always prefix exposed interfaces
Nuxt Modules should provide an explicit prefix for any exposed configuration, plugin, API, composable, or component to avoid conflict with other modules and internals.
Ideally you should prefix them with your module name (If your module is called `nuxt-foo`, expose `<FooButton>` and `useFooBar()` and **not** `<Foo>` and `useBar()`)
### Be Typescript Friendly
Nuxt 3, has first-class typescript integration for the best developer experience.
Exposing types and using typescript to develop modules can benefit users even when not using typescript directly.
### Avoid CommonJS syntax
Nuxt 3, relies on native ESM. Please read [/concepts/esm](/concepts/esm) for more information.
## Modules Ecosystem
Nuxt tends to have a healthy and rich ecosystem of Nuxt modules and integrations. Here are some best practices if you want to jump in and contribute!
### Document Module Usage
Consider documenting module usage in the readme file:
- Why use this module
- How to use this module
- What this module does?
Linking to the integration website and documentation is always a good idea.
### Use `nuxt-` prefix for npm packages
To make your modules discoverable, use `nuxt-` prefix for the npm package name. This is always the best starting point to draft and try an idea!
### Listing module to modules.nuxtjs.org
Do you have a working Module and want it listed in [modules.nuxtjs.org](modules.nuxtjs.org)? Open an issue in [nuxt/modules](https://github.com/nuxt/modules/issues/new) repository.
Nuxt team can help you to apply best practices before listing.
### Do not advertise with a specific Nuxt version
Nuxt 3, Nuxt Kit, and other new toolings are made to have both forward and backward compatibility in mind.
Please use "X for Nuxt" instead of "X for Nuxt 3" to avoid fragmentation in the ecosystem and prefer using `meta.compatibility` to set Nuxt version constraints.
### Joining nuxt-community
By moving your modules to [nuxt-community](https://github.com/nuxt-community), there is always someone else to help, and this way, we can join forces to make one perfect solution.
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).
## Examples
### Provide Nuxt Plugins
Commonly, modules provide one or more run plugins to add runtime logic.
```ts
import { resolve } from 'path'
import { fileURLToPath } from 'url'
import { defineNuxtModule, addPlugin } from '@nuxt/kit'
export default defineNuxtModule<ModuleOptions>({
setup (options, nuxt) {
const runtimeDir = fileURLToPath(new URL('./runtime', import.meta.url))
addPlugin(resolve(runtimeDir, 'plugin'))
}
})
```
### Add a CSS Library
If your module will provide a CSS library, make sure to check if the user already included the library to avoid duplicates and add an option to disable the CSS library in the module.
```ts
export default defineNuxtModule({
setup (options, nuxt) {
nuxt.options.css.push('font-awesome/css/font-awesome.css')
}
})
```
### Cleanup Module
If your module opens handles or starts a watcher, we should close it when the nuxt lifecycle is done. For this, we can use the `close` hook:
```ts
export default defineNuxtModule({
setup (options, nuxt) {
nuxt.hook('close', async nuxt => {
// Your custom code here
})
}
})
```

124
docs/content/3.docs/4.advanced/3.kit.md Normal file
View File

@ -0,0 +1,124 @@
# Nuxt Kit
> Nuxt Kit provides composable utilities to make interacting with [/docs/advanced/hooks](Nuxt Hooks) and [Nuxt Builder Core](/docs/advanced/nuxt#the-nuxt-interface) and developing [Nuxt Modules](/docs/advanced/modules) super easy!
## Usage
### Install dependency
You can install the latest nuxt kit by adding it to `dependencies` of `package.json`. However, please consider always explicitly installing the `@nuxt/kit` package even if it is already installed by nuxt.
```json [package.json]
{
"dependencies": {
"@nuxt/kit": "npm:@nuxt/kit-edge@latest"
}
}
```
### Import kit utilities
```js [test.mjs]
import { useNuxt } from '@nuxt/kit'
```
::alert{type="warning"}
Nuxt kit utilities are only available for modules and not meant to be imported in runtime (components, vue composables, pages, plugins, or server routes)
::
Nuxt kit, is an [esm-only package](/concepts/esm) meaning you **cannot** `require('@nuxt/kit')`. As a workaround, we can use dynamic import to use it in the CommonJS context:
```js [test.cjs]
// This does NOT work!
// const kit = require('@nuxt/kit')
async function main() {
const kit = await import('@nuxt/kit')
}
main()
```
### Use kit utilities
Nuxt context is globally available using [unjs/unctx](https://github.com/unjs/unctx). Because of this, most kit composables do not need to have `nuxt` instances explicitly passed.
```js [test.mjs]
import { getNuxtVersion } from '@nuxt/kit'
// 3.0.0
console.log(getNuxtVersion())
```
## Utilities
### Modules
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/module)
- `installModule(module, inlineOptions)`
### Programmatic usage
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/loader)
- `loadNuxt(loadOptions)`
- `buildNuxt(nuxt)`
- `loadNuxtConfig(loadOptions)`
### Compatibility
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/compatibility.ts)
- `checkNuxtCompatibility(constraints)`
- `assertNuxtCompatibility(constraints)`
- `hasNuxtCompatibility(constraints)`
- `isNuxt2()`
- `isNuxt3()`
- `getNuxtVersion()`
### Components
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/components.ts)
- `addComponentsDir(dir)`
- `addComponent(componentObject)`
### Context
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/context.ts)
- `useNuxt()`
### Plugins
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/plugin.ts)
- `addPlugin(pluginOptions, { append? })`
- `addPluginTemplate(pluginOptions, { append? })`
### Templates
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/template.ts)
- `addTemplate(templateOptions)`
### Server
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/server.ts)
- `addServerMiddleware(serverMiddleware)`
### Resolving
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/resolve.ts)
- `resolvePath (path, resolveOptions?)`
- `tryResolvePath (path, resolveOptions?)`
### Builder
[source code](https://github.com/nuxt/framework/blob/main/packages/kit/src/build.ts)
- `extendWebpackConfig(callback, options?)`
- `extendViteConfig(callback, options?)`
- `addWebpackPlugin(webpackPlugin, options?)`
- `addVitePlugin(vitePlugin, options?)`

63
docs/content/3.docs/4.advanced/4.hooks.md Normal file
View File

@ -0,0 +1,63 @@
# Lifecycle Hooks
Nuxt provides a powerful hooking system to expand almost every aspect using hooks powered by [unjs/hookable](https://github.com/unjs/hookable).
## Nuxt Hooks
This hooks are available for [Nuxt Modules](/docs/advanced/modules) and build context.
### Usage with `nuxt.config`
```js [nuxt.config]
export default defineNuxtConfig({
hooks: {
'close': () => { }
}
})
```
### Usage with Nuxt Modules
```js
import { defineNuxtModule } from '@nuxt/kit'
export default defineNuxtModule({
setup (options, nuxt) {
nuxt.hook('close', async () => { })
})
})
```
### Available hooks
Check the [source code](https://github.com/nuxt/framework/blob/main/packages/schema/src/types/hooks.ts#L55) for all available hooks.
## Runtime Hooks
App hooks can be mainly used by [Nuxt Plugins] (/docs/directory-structure/plugins) to hook into rendering lifecycle but could also be used in Vue composables.
### Usage with Modules
```js [plugins/test.ts]
export defineNuxtPlugin(nuxtApp) {
nuxtApp.hook('page:start', () => { })
}
```
### Available hooks
Check the [source code](https://github.com/nuxt/framework/blob/main/packages/nuxt3/src/app/nuxt.ts#L18) for all available hooks.
**Note:** Please note
Hook | Arguments | Description
-----------------------|-------------------|---------------
`app:created` | `vueApp` | When initial `vueApp` instance is created
`app:beforeMount` | `vueApp` | Same as `app:created`
`app:mounted` | `vueApp` | When Vue app is initialized and mounted in browser
`app:rendered` | - | When SSR rendering is done
`app:suspense:resolve` | `appComponent` | On [Suspense](https://v3.vuejs.org/guide/migration/suspense.html) resolved event
`page:start` | `pageComponent` | On [Suspense](https://v3.vuejs.org/guide/migration/suspense.html) pending event
`page:finish` | `pageComponent` | On [Suspense](https://v3.vuejs.org/guide/migration/suspense.html) resolved event
`meta:register` | `metaRenderers` | (internal)
`vue:setup` | - | (internal)