@nuxt/docs-nightly 4.3.0-29481280.f3d5bc5f → 4.3.0-29481694.51da8e68

package/1.getting-started/14.layers.md

@@ -86,32 +86,60 @@ Nuxt uses [unjs/c12](https://github.com/unjs/c12) and [unjs/giget](https://githu
 
 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.
 
-The priority order from highest to lowest is:
+### Priority Order
+
+From highest to lowest priority:
 
 1. **Your project files** - always have the highest priority
 2. **Auto-scanned layers** from `~~/layers` directory - sorted alphabetically (Z has higher priority than A)
 3. **Layers in `extends`** config - first entry has higher priority than second
 
-### When to Use Each
+### Practical Example
 
-- **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
-- **`~~/layers` directory** - Use for local layers that are part of your project
+Consider multiple layers defining the same component:
+
+```bash [Directory structure]
+layers/
+  1.base/
+    app/components/Button.vue    # Base button style
+  2.theme/
+    app/components/Button.vue    # Themed button (overrides base)
+app/
+  components/Button.vue          # Project button (overrides all layers)
+```
+
+In this case:
+- If only layers exist, `2.theme/Button.vue` is used (higher alphabetically)
+- If `app/components/Button.vue` exists in your project, it overrides all layers
+
+### Controlling Priority
+
+You can prefix layer directories with numbers to control the order:
+
+```bash [Directory structure]
+layers/
+  1.base/        # Lowest priority
+  2.features/    # Medium priority
+  3.admin/       # Highest priority (among layers)
+```
 
 ::tip
-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`.
+This pattern is useful for creating base layers with defaults that can be progressively overridden by more specific layers.
 ::
 
-### Example
+### When to Use Each
+
+- **`~~/layers` directory** - Use for local layers that are part of your project
+- **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
+
+### Full Example with extends
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   extends: [
-    // Local layer outside the project
-    '../base',
-    // NPM package
-    '@my-themes/awesome',
-    // Remote repository
-    'github:my-themes/awesome#v1',
+    '../base', // Local layer outside project
+    '@my-themes/awesome', // NPM package
+    'github:my-themes/awesome#v1', // Remote repository
   ],
 })
 ```
@@ -123,7 +151,9 @@ If you also have `~~/layers/custom`, the priority order is:
 - `@my-themes/awesome`
 - `github:my-themes/awesome#v1` (lowest)
 
-This means your project files will override any layer, and `~~/layers/custom` will override anything in `extends`.
+::read-more{to="/docs/4.x/directory-structure/layers"}
+Learn about the **layers/ directory** to organize and share reusable code, components, composables, and configurations across your Nuxt application.
+::
 
 ::read-more{to="/docs/4.x/guide/going-further/layers"}
 Read more about layers in the **Layer Author Guide**.

package/2.directory-structure/1.layers.md

@@ -0,0 +1,87 @@
+---
+title: 'layers'
+head.title: 'layers/'
+description: Use the layers/ directory to organize and auto-register local layers within your application.
+navigation.icon: i-vscode-icons-folder-type-nuxt
+---
+
+The `layers/` directory allows you to organize and share reusable code, components, composables, and configurations across your Nuxt application. Any layers within your project in the `layers/` directory will be automatically registered.
+
+::note
+The `layers/` directory auto-registration is available in Nuxt v3.12.0+.
+::
+
+::tip{icon="i-lucide-lightbulb"}
+Layers are ideal for organizing large codebases with **Domain-Driven Design (DDD)**, creating reusable **UI libraries** or **themes**, sharing **configuration presets** across projects, and separating concerns like **admin panels** or **feature modules**.
+::
+
+## Structure
+
+Each subdirectory within `layers/` is treated as a separate layer. A layer can contain the same structure as a standard Nuxt application.
+
+::important
+Every layer **must have** a `nuxt.config.ts` file to be recognized as a valid layer, even if it's empty.
+::
+
+```bash [Directory structure]
+-| layers/
+---| base/
+-----| nuxt.config.ts
+-----| app/
+-------| components/
+---------| BaseButton.vue
+-------| composables/
+---------| useBase.ts
+-----| server/
+-------| api/
+---------| hello.ts
+---| admin/
+-----| nuxt.config.ts
+-----| app/
+-------| pages/
+---------| admin.vue
+-------| layouts/
+---------| admin.vue
+```
+
+## Automatic Aliases
+
+Named layer aliases to the `srcDir` of each layer are automatically created. You can access a layer using the `#layers/[name]` alias:
+
+```ts
+// Access the base layer
+import something from '#layers/base/path/to/file'
+
+// Access the admin layer
+import { useAdmin } from '#layers/admin/composables/useAdmin'
+```
+
+::note
+Named layer aliases were introduced in Nuxt v3.16.0.
+::
+
+## Layer Content
+
+Each layer can include:
+
+- [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) - Layer-specific configuration that will be merged with the main config
+- [`app.config.ts`](/docs/4.x/directory-structure/app/app-config) - Reactive application configuration
+- [`app/components/`](/docs/4.x/directory-structure/app/components) - Vue components (auto-imported)
+- [`app/composables/`](/docs/4.x/directory-structure/app/composables) - Vue composables (auto-imported)
+- [`app/utils/`](/docs/4.x/directory-structure/app/utils) - Utility functions (auto-imported)
+- [`app/pages/`](/docs/4.x/directory-structure/app/pages) - Application pages
+- [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) - Application layouts
+- [`app/middleware/`](/docs/4.x/directory-structure/app/middleware) - Route middleware
+- [`app/plugins/`](/docs/4.x/directory-structure/app/plugins) - Nuxt plugins
+- [`server/`](/docs/4.x/directory-structure/server) - Server routes, middleware, and utilities
+- [`shared/`](/docs/4.x/directory-structure/shared) - Shared code between app and server
+
+## Priority Order
+
+When multiple layers define the same resource (component, composable, page, etc.), the layer with **higher priority wins**. Layers are sorted alphabetically, with later letters having higher priority (Z > A).
+
+To control the order, prefix directories with numbers: `1.base/`, `2.features/`, `3.admin/`.
+
+:read-more{to="/docs/4.x/getting-started/layers#layer-priority"}
+
+:video-accordion{title="Watch a video from Learn Vue about Nuxt Layers" videoId="lnFCM7c9f7I"}

package/2.directory-structure/1.modules.md

@@ -18,7 +18,7 @@ You don't need to add those local modules to your [`nuxt.config.ts`](/docs/4.x/d
 ```ts twoslash [modules/hello/index.ts]
 // `nuxt/kit` is a helper subpath import you can use when defining local modules
 // that means you do not need to add `@nuxt/kit` to your project's dependencies
-import { addServerHandler, createResolver, defineNuxtModule, addComponentsDir } from 'nuxt/kit'
+import { addComponentsDir, addServerHandler, createResolver, defineNuxtModule } from 'nuxt/kit'
 
 export default defineNuxtModule({
   meta: {
@@ -36,7 +36,7 @@ export default defineNuxtModule({
     // Add components
     addComponentsDir({
       path: resolver.resolve('./runtime/app/components'),
-      pathPrefix: true // Prefix your exports to avoid conflicts with user code or other modules
+      pathPrefix: true, // Prefix your exports to avoid conflicts with user code or other modules
     })
   },
 })

package/2.directory-structure/index.md

@@ -54,6 +54,10 @@ The [`content/`](/docs/4.x/directory-structure/content) directory is enabled by
 
 The [`modules/`](/docs/4.x/directory-structure/modules) directory is the directory that contains the local modules of the Nuxt application. Modules are used to extend the functionality of the Nuxt application.
 
+## Layers Directory
+
+The [`layers/`](/docs/4.x/directory-structure/layers) directory allows you to organize and share reusable code, components, composables, and configurations. Layers within this directory are automatically registered in your project.
+
 ## Nuxt Files
 
 - [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file is the main configuration file for the Nuxt application.

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

@@ -229,3 +229,15 @@ Nuxt automatically includes your module's directories in the appropriate type co
 ---| module.ts
 ---| augments.node.d.ts
 ```
+
+### Known Limitations
+
+#### Type-Checking Server Routes in App Context
+
+Server routes are also type-checked using `tsconfig.app.json` in addition to `tsconfig.server.json`.
+
+This is required because Nuxt infers the return types of your server endpoints to provide response types in [`$fetch`](/docs/4.x/api/utils/dollarfetch) and [`useFetch`](/docs/4.x/api/composables/use-fetch).
+
+::warning
+This can cause issues when using **server-only types** in your route files. For example, if a module creates a server-only virtual file using [`addServerTemplate`](/docs/api/kit/templates#addservertemplate) and you declare types for it in `tsconfig.server.json`, those type declarations will only be available in the server context. When the app context type-checks your server routes, it won't recognize these server-only types and will report errors.  To resolve this, you unfortunately need to declare such types in the app context as well.
+::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.3.0-29481280.f3d5bc5f",
+  "version": "4.3.0-29481694.51da8e68",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",