diff --git a/docs/content/1.docs/2.guide/3.going-further/7.layers.md b/docs/content/1.docs/2.guide/3.going-further/7.layers.md index 0224958113..cca737eccc 100644 --- a/docs/content/1.docs/2.guide/3.going-further/7.layers.md +++ b/docs/content/1.docs/2.guide/3.going-further/7.layers.md @@ -61,7 +61,7 @@ Additionally, certain other files in the layer directory will be auto-scanned an :: -## Using Starter Templates +## Starter Template To get started you can initialize a layer with the [nuxt/starter/layer template](https://github.com/nuxt/starter/tree/layer). This will create a basic structure you can build upon. Execute this command within the terminal to get started: @@ -75,30 +75,30 @@ Follow up on the README instructions for the next steps. Check [nuxt-themes/starter](https://github.com/nuxt-themes/starter) for a more opinionated starter for authoring Nuxt themes. It can be initialized with: ```bash - npx nuxi init --template gh:nuxt-themes/starter my-theme +npx nuxi init --template gh:nuxt-themes/starter my-theme ``` :: -## Publishing layers +## Publishing Layers You can publish and share layers by either using a remote source or an npm package. -### Publishing via Git Repository +### Git Repository You can use a git repository to share your Nuxt layer. Some examples: -```ts{}[nuxt.config.ts] - export default defineNuxtConfig({ - extends: [ - 'github:username/repoName', // GitHub Remote Source - 'github:username/repoName/base', // GitHub Remote Source within /base directory - 'github:username/repoName#dev', // GitHub Remote Source from dev branch - 'github:username/repoName#v1.0.0', // GitHub Remote Source from v1.0.0 tag - 'gitlab:username/repoName', // GitLab Remote Source example - 'bitbucket:username/repoName', // Bitbucket Remote Source example - ] - }) +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + extends: [ + 'github:username/repoName', // GitHub Remote Source + 'github:username/repoName/base', // GitHub Remote Source within /base directory + 'github:username/repoName#dev', // GitHub Remote Source from dev branch + 'github:username/repoName#v1.0.0', // GitHub Remote Source from v1.0.0 tag + 'gitlab:username/repoName', // GitLab Remote Source example + 'bitbucket:username/repoName', // Bitbucket Remote Source example + ] +}) ``` ::alert{type="info"} @@ -109,36 +109,36 @@ If you want to extend a private remote source, you need to add the environment v Currently, with git remote sources, if a layer has npm dependencies, you will need to manually install them in the target project. We are working on this to auto-install layer dependencies with git sources. :: -### Publishing via npm package +### npm Package You can publish Nuxt layers as an npm package that contains the files and dependencies you want to extend. This allows you to share your config with others, use it in multiple projects or use it privately. To extend from an npm package, you need to make sure that the module is published to npm and installed in the user's project as a devDependency. Then you can use the module name to extend the current nuxt config: -```ts{}[nuxt.config.ts] - export default defineNuxtConfig({ - extends: [ - // Node Module with scope - '@scope/moduleName', - // or just the module name - 'moduleName' - ] - }) +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + extends: [ + // Node Module with scope + '@scope/moduleName', + // or just the module name + 'moduleName' + ] +}) ``` To publish a layer directory as an npm package, you want to make sure that the `package.json` has the correct properties filled out. This will make sure that the files are included when the package is published. -```json{}[package.json] - { - "name": "my-theme", - "version": "1.0.0", - "type": "module", - "main": "./nuxt.config.ts", - "dependencies": {}, - "devDependencies": { - "nuxt": "^3.0.0" - } +```json [package.json] +{ + "name": "my-theme", + "version": "1.0.0", + "type": "module", + "main": "./nuxt.config.ts", + "dependencies": {}, + "devDependencies": { + "nuxt": "^3.0.0" } +} ``` ::alert{type="info"} @@ -151,7 +151,7 @@ Now you can proceed to publish the module to npm, either publicly or privately. When publishing the layer as a private npm package, you need to make sure you log in, to authenticate with npm to download the node module. :: -## Tips for Authoring Layers +## Tips ### Relative Paths and Aliases @@ -159,19 +159,25 @@ When importing using aliases (such as `~/` and `@/`) in a layer components and c Also when using relative paths in `nuxt.config` file of a layer, (with exception of nested `extends`) they are resolved relative to user's project instead of the layer. As a workaround, use full resolved paths in `nuxt.config`: -```js -import { fileURLToPath } from 'node:url' +```js [nuxt.config.ts] +import { createResolver } from '@nuxt/kit' + +const { resolve } = createResolver(import.meta.url) export default defineNuxtConfig({ - css: [fileURLToPath(new URL('./assets/main.css', import.meta.url))] + css: [ + resolve('./assets/main.css') + ] }) ``` ## Multi-Layer Support for Nuxt Modules -You can use the internal array `nuxt.options._layers` to support custom multi-layer handling for your modules. Example: +You can use the internal array `nuxt.options._layers` to support custom multi-layer handling for your modules. -```js +Example: + +```js [modules/my-module.ts] export default defineNuxtModule({ setup(_options, nuxt) { for (const layer of nuxt.options._layers) { @@ -183,7 +189,6 @@ export default defineNuxtModule({ ``` **Notes:** - - Earlier items in the `_layers` array have higher priority and override later ones - The user's project is the first item in the `_layers` array