Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 32 ยท Plugins, modules and layers

Layers and Code Organization

Learn how Nuxt layers let projects extend each other, how configuration and app.config merge, how to share code in a monorepo and how to organize a large app.

A Nuxt project is a folder with pages/, components/, composables/, server/ and a few config files. A layer is exactly that: another Nuxt project, usually smaller, that your project extends. Everything the layer contains, its components, pages, composables, server routes, plugins and configuration, is merged into yours as if you had written it there. This is how teams share a design system, a starter template, or the common parts of several sites without copying files around.

This lesson shows how to extend a layer, which side wins when both define the same thing, how app.config.ts and nuxt.config.ts are merged, how layers fit into a monorepo, and how to keep a large app understandable. Real Nuxt cannot run on this site, so every Nuxt file is read-only. The runnable examples are JavaScript stand-ins that reproduce the merging rules with a small deep-merge function.

A layer is a Nuxt project

Same folders components, pages, composables, server, plugins.
Own config A nuxt.config.ts marks the folder as a layer.
Extended Listed under extends in another project.

The result is one merged app.

1 / 2

Extending a layer

Say a company has a base project with its logo component, a few composables and a color scheme. Another project uses it with one line:

TypeScript
// nuxt.config.ts of the site (read-only)
export default defineNuxtConfig({
  extends: ["../base"],
});

The entry can be a relative folder, an installed package (extends: ["@acme/nuxt-base"]), or a remote source such as a GitHub repository, which Nuxt downloads when it starts. The extended folder must be a Nuxt project, which in practice means it has its own nuxt.config.ts (it can be nearly empty).

The base layer might look like this:

Terminal
# read-only
base/
  nuxt.config.ts
  app.config.ts
  components/
    AppLogo.vue
  composables/
    useBrand.ts
  server/
    api/
      health.get.ts

Now the site's pages can use <AppLogo />, call useBrand() and serve /api/health without importing or copying anything. Auto-imports (see Auto-imports) and file-based routing (see File-based routing) both see the combined set of files.

Nuxt can also find layers on its own: projects can keep local layers as folders inside a top-level layers/ directory, and Nuxt registers them without any extends entry. That is handy for splitting one app into feature areas (see below).

Who wins when both define the same thing?

Layers are merged in priority order. Your own project has the highest priority. For files, if two layers contain the same path (say components/AppLogo.vue), the higher priority one is used, so your project can override a single component of the base without touching the rest. Between several layers, priority follows the order in the extends list: an entry listed earlier wins over one listed later. Check the documentation for the Nuxt version you use if the order matters to you; this lesson's stand-ins assume "project first, then the list from the top".

Configuration is not replaced wholesale. Objects are merged key by key, deeply, and the higher priority layer wins each individual key. Arrays are usually combined (concatenated) instead of replaced. So if the base config has css: ["~/assets/base.css"] and the site adds css: ["~/assets/site.css"], you normally end up with both entries. When you really need to remove something from a layer, you must override it explicitly, or use a function-style option where the module provides one.

A stand-in for config merging

Real Nuxt merges with a library in the same spirit as the function below (a "defaults" style merge: the first object wins, nested objects are merged, arrays are concatenated). The stand-in is not that library: it ignores special cases such as functions and undefined values. It shows what a layer stack produces.

JS Merging a layer stack: project first, then layers

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The title comes from the project, while htmlAttrs comes from the design layer because only that layer defines it. The css and modules arrays contain entries from every layer, with the project's own first. apiBase is /api/v2 (project wins), yet analyticsId is still there from the base. Swap design and base in the stack array to see how the order changes which layer fills the gaps.

app.config.ts across layers

nuxt.config.ts holds build-time and runtime settings. app.config.ts holds app-level values that can be read in components, such as theme colors, feature switches or UI defaults. Every layer may ship its own app.config.ts, and Nuxt merges them in the same way, with your project on top:

TypeScript
// base/app.config.ts (read-only)
export default defineAppConfig({
  brand: { name: "Acme", color: "indigo" },
  nav: { showSearch: true },
});

// site/app.config.ts (read-only)
export default defineAppConfig({
  brand: { color: "emerald" },
});

In a component, useAppConfig() returns the merged result: brand.name is "Acme" from the base, brand.color is "emerald" from the site, and nav.showSearch is still true. The difference from runtime config is that app.config is bundled into the app and is not changed by environment variables, and it must never hold secrets (see Runtime config and environment variables).

Sharing code in a monorepo

When several apps live in one repository, layers are the clean way to share. A typical layout with a workspace tool (pnpm, npm or Yarn workspaces) looks like this:

Terminal
# read-only
repo/
  package.json
  packages/
    ui/              # a layer: components, composables, app.config.ts
      nuxt.config.ts
    base/            # a layer: auth composables, server utils
      nuxt.config.ts
  apps/
    shop/
      nuxt.config.ts # extends: ["../../packages/ui", "../../packages/base"]
    admin/
      nuxt.config.ts # extends: ["../../packages/base"]

Each app picks the layers it needs. A fix in packages/ui reaches every app that extends it. Keep a few rules in mind:

  • Use relative imports inside a layer for files of that layer. The ~ and @ aliases point at the project that is being built, not at the layer, so a layer that writes ~/utils/x can break or pick up the wrong file when extended.
  • Give shared components a clear prefix (UiButton, AdminTable) because all layers share one auto-import namespace and two files named Button.vue in different layers would clash.
  • Publish a layer as a package when apps live in separate repositories. A layer installed from a registry is extended by its package name.
  • Declare dependencies (modules the layer needs) in the layer's own nuxt.config.ts. They are merged into the final app.

What a clash looks like

Components in layers are registered by their name, so a duplicate shows up as one overriding the other. The stand-in below resolves a set of files from several layers by path, with "project first". It is a simplification (real Nuxt scans the folders and derives component names from paths), but the rule it shows is the same.

JS Which layer supplies each file?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The project's own AppHeader.vue hides the one in ui, while the ui layer's UiButton.vue hides the base version. Files with a unique path, such as server/api/health.get.ts, pass through untouched.

Organizing a large app

Layers are not only for sharing. In a large single app they help you split by feature instead of by file type. Instead of one huge components/ folder with 200 files, you can keep each area together:

Terminal
# read-only
layers/
  blog/
    components/
    composables/
    pages/blog/
    nuxt.config.ts
  billing/
    components/
    pages/account/billing.vue
    server/api/billing/
    nuxt.config.ts
app/
  pages/
  components/
nuxt.config.ts

A few habits keep this manageable:

  • Put code that is used everywhere in a base layer, and let feature layers depend on it, never the other way around.
  • Keep one direction of dependency: feature layers must not import each other's internals. If two features need the same thing, move it down to the base.
  • Use folders inside components/ for nesting (components/billing/InvoiceRow.vue becomes BillingInvoiceRow), as described in Components and composables in Nuxt.
  • Move server logic into server/utils/ so API routes stay thin (see Server middleware, plugins and utils).
  • Do not create a layer for the sake of it. A project with ten files does not need layers; start splitting when a folder becomes hard to scan or a second app needs the same code.

A layer hides or overrides by file path, silently. If a page suddenly looks different after adding an extends entry, a file with the same path in the new layer may now be winning. Check the order of extends first.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does extends: ['../base'] do?

    A layer is a whole Nuxt project. Extending it merges its files and configuration with your project, so its components and routes are available as if you had written them.
  2. 2. Both a layer and your project contain components/AppHeader.vue. Which one is used?

    Your project always wins over its layers for files with the same path. This lets you override a single component from a shared base.
  3. 3. The layer config has css: ['a.css'] and your project has css: ['b.css']. What is the usual result?

    Objects are merged key by key with the higher priority value winning, but arrays are normally concatenated, so both files are included.
  4. 4. Why should a layer use relative imports for its own files instead of the ~ alias?

    Aliases resolve against the final project, so code that works inside the layer can break once the layer is extended by another app.

Summary

  • A layer is a Nuxt project that another project lists under extends (a folder, a package or a remote source); a local layers/ directory is picked up automatically.
  • Your project has the highest priority; for files with the same path one replaces the other, and for config objects keys are merged deeply with arrays combined.
  • app.config.ts is merged across layers too and is read with useAppConfig(); it is public and bundled, so no secrets.
  • In a monorepo, shared layers live in packages that apps extend; use relative imports inside layers and prefixed component names.
  • For big apps, split by feature into layers with a one-way dependency on a base layer, and only when the folder structure starts to hurt.

Next: Forms, validation and auth flows