@nuxt/docs-nightly 4.2.1-29372339.038f9d9f → 4.2.1-29372549.6b6ea5fa

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/1.getting-started/14.layers.md +28 -9
  2. package/2.guide/3.going-further/7.layers.md +30 -13
  3. package/package.json +1 -1
package/1.getting-started/14.layers.md CHANGED
@@ -80,27 +80,46 @@ Nuxt uses [unjs/c12](https://github.com/unjs/c12) and [unjs/giget](https://githu
80
80
 
81
81
  ## Layer Priority
82
82
 
83
- When using multiple layers, it's important to understand how they override each other:
83
+ When using multiple layers, it's important to understand the override order. Layers with **higher priority** override layers with lower priority when they define the same files or components.
84
84
 
85
- 1. **Layers in `extends`** - earlier entries have higher priority (first overrides second)
86
- 2. **Auto-scanned local layers** from `~~/layers` directory in alphabetical order (Z overrides A)
87
- 3. **Your project** has the highest priority in the stack - it will always override other layers
85
+ The priority order from highest to lowest is:
86
+
87
+ 1. **Your project files** - always have the highest priority
88
+ 2. **Auto-scanned layers** from `~~/layers` directory - sorted alphabetically (Z has higher priority than A)
89
+ 3. **Layers in `extends`** config - first entry has higher priority than second
90
+
91
+ ### When to Use Each
92
+
93
+ - **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
94
+ - **`~~/layers` directory** - Use for local layers that are part of your project
95
+
96
+ ::tip
97
+ If you need to control the order of auto-scanned layers, you can prefix them with numbers: `~/layers/1.z-layer`, `~/layers/2.a-layer`. This way `2.a-layer` will have higher priority than `1.z-layer`.
98
+ ::
99
+
100
+ ### Example
88
101
 
89
102
  ```ts [nuxt.config.ts]
90
103
  export default defineNuxtConfig({
91
104
  extends: [
92
- // Highest priority (among extends)
105
+ // Local layer outside the project
93
106
  '../base',
94
- // Medium priority
107
+ // NPM package
95
108
  '@my-themes/awesome',
96
- // Lower priority
109
+ // Remote repository
97
110
  'github:my-themes/awesome#v1',
98
111
  ],
99
- // Your project has the highest priority
100
112
  })
101
113
  ```
102
114
 
103
- This means if multiple layers define the same component, configuration, or file, the one with higher priority will be used.
115
+ If you also have `~~/layers/custom`, the priority order is:
116
+ - Your project files (highest)
117
+ - `~~/layers/custom`
118
+ - `../base`
119
+ - `@my-themes/awesome`
120
+ - `github:my-themes/awesome#v1` (lowest)
121
+
122
+ This means your project files will override any layer, and `~~/layers/custom` will override anything in `extends`.
104
123
 
105
124
  ::read-more{to="/docs/4.x/guide/going-further/layers"}
106
125
  Read more about layers in the **Layer Author Guide**.
package/2.guide/3.going-further/7.layers.md CHANGED
@@ -68,29 +68,46 @@ Additionally, certain other files in the layer directory will be auto-scanned an
68
68
 
69
69
  ## Layer Priority
70
70
 
71
- When extending from multiple layers, it's important to understand the priority order:
71
+ When extending from multiple layers, it's important to understand the override order. Layers with **higher priority** override layers with lower priority when they define the same files or components.
72
72
 
73
- 1. **Layers in `extends`** - earlier entries have higher priority (first overrides second)
74
- 2. **Auto-scanned local layers** from `~~/layers` directory in alphabetical order (Z overrides A)
75
- 3. **Your project** has the highest priority in the stack - it will always override other layers
73
+ The priority order from highest to lowest is:
76
74
 
77
- For example:
75
+ 1. **Your project files** - always have the highest priority
76
+ 2. **Auto-scanned layers** from `~~/layers` directory - sorted alphabetically (Z has higher priority than A)
77
+ 3. **Layers in `extends`** config - first entry has higher priority than second
78
+
79
+ ### When to Use Each
80
+
81
+ - **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
82
+ - **`~~/layers` directory** - Use for local layers that are part of your project
83
+
84
+ ::tip
85
+ If you need to control the order of auto-scanned layers, you can prefix them with numbers: `~/layers/1.z-layer`, `~/layers/2.a-layer`. This way `2.a-layer` will have higher priority than `1.z-layer`.
86
+ ::
87
+
88
+ ### Example
78
89
 
79
90
  ```ts [nuxt.config.ts]
80
91
  export default defineNuxtConfig({
81
92
  extends: [
82
- // Highest priority (among extends)
83
- './layers/base',
84
- // Medium priority
85
- './layers/theme',
86
- // Lower priority
87
- './layers/custom',
93
+ // Local layer outside the project
94
+ '../base',
95
+ // NPM package
96
+ '@my-themes/awesome',
97
+ // Remote repository
98
+ 'github:my-themes/awesome#v1',
88
99
  ],
89
- // Your project has the highest priority
90
100
  })
91
101
  ```
92
102
 
93
- If you also have auto-scanned layers like `~~/layers/a` and `~~/layers/z`, the complete override order would be: `base` > `theme` > `custom` > `z` > `a` > your project.
103
+ If you also have `~~/layers/custom`, the priority order is:
104
+ - Your project files (highest)
105
+ - `~~/layers/custom`
106
+ - `../base`
107
+ - `@my-themes/awesome`
108
+ - `github:my-themes/awesome#v1` (lowest)
109
+
110
+ This means your project files will override any layer, and `~~/layers/custom` will override anything in `extends`.
94
111
 
95
112
  ## Starter Template
96
113
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nuxt/docs-nightly",
3
- "version": "4.2.1-29372339.038f9d9f",
3
+ "version": "4.2.1-29372549.6b6ea5fa",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/nuxt/nuxt.git",