One host, N composable packages: a Layers primitive for RR7

[dlutsyk]

Background

I've been building a multi-brand application on RR7 and I kept running into the same wall: I have a base app that should be shared across N tenants, with each tenant overriding a few routes, components, and data sources. Today my options are all bad:

1. Vendor it – copy routes.ts and the components into each tenant repo, then watch them drift over the next six months.
2. Monorepo + shared package – fine for components, but routes.ts doesn't compose. Each tenant ends up redefining the route tree by hand and re-importing every shared module.
3. Hand-roll routes() – write JS to glob a shared package and merge route trees, then fight type generation, HMR, and route-file resolution to make it ergonomic.

I went with (3) and ended up needing to hook into framework internals (route-file resolver, typegen, dev watcher) to make it work. That work is the basis of this proposal.

Why this matters (it's not just multi-brand)

I want to be upfront: I came to this from a multi-brand use case, but layered composition is a general architecture primitive, not a multi-brand feature. It's already proven in the wider ecosystem – every framework that has matured past the "single-app" phase has shipped some version of it:

• Nuxt Layers – directories or npm packages contributing routes, components, config, and middleware; used in production for design-system inheritance, plugin distribution, white-label, and internationalization splits.
• Astro Integrations – packages that contribute routes, content sources, and middleware via well-defined hooks.
• Rails Engines – gems that contribute routes, views, controllers, and assets; the host app can override anything by file path.
• WordPress child themes – the original "cascade of overrides by file path" pattern, still going strong 20 years later.

In every one of these, the value isn't "swap brands" – it's that the framework lets a real-world app be composed from cleanly-separated pieces, each owned by a different team or package, each replaceable independently.

A real architecture I'm shipping today demonstrates this – a single component that spans four distinct packages, each owning one concern:

Package role	Responsibility
Platform entrypoint	Adapter that binds the abstract component to a specific platform
Abstract component	Platform-agnostic render component – defines the shape and behavior
Data layer	Content/data adapters; pluggable so the source can change
Theme layer	Visual concerns – typography, spacing, brand styling

None of those packages know about the others. The host app just declares the stack:

unstable_routeLayers: [
  "@org/abstract-component",
  "@org/data-adapter",
  "@org/platform-entrypoint",
  "@org/theme",
],

…and the same component is composed end-to-end. Swap the theme package to reskin. Swap the data adapter to migrate to a different content source without touching UI. Drop a feature-flags layer between the abstract and the theme to A/B without touching either side.

That's the shape of architecture this unlocks. Concrete examples it makes ergonomic in RR7:

• Design-system inheritance – base DS as a layer, product-specific overrides as a higher layer.
• CMS-agnostic apps – swap content providers without rewriting routes.
• Theme / white-label – same app, multiple visual identities.
• Plugin & extension architectures – third-party features as installable npm packages that contribute routes and components.
• Domain-Driven separation – UI / data / business / theme as distinct packages with hard boundaries.
• Monorepo team boundaries – each team ships a layer; the app is the composition.
• Multi-brand applications – the use case that started this.

The point is: the framework should provide the composition primitive, not require every team to invent their own. Other frameworks already concluded the same.

API Proposal

Two new experimental config fields. Both reuse existing routes.ts and react-router.config.ts surfaces – no new runtime, no new manifest.

Bare list

// react-router.config.ts
import type { Config } from "@react-router/dev/config";

export default {
  unstable_routeLayers: [
    "./layers/base",                 // local path
    { source: "./layers/brand" },    // object form, equivalent
    "@my-org/shared-ui",             // npm package
  ],
} satisfies Config;

Each layer is a directory that may contain:

• react-router.config.{ts,js} – merged below the app config (app always wins)
• app/routes.{ts,js} – composed additively under the app's root route
• Any source files reachable through the import aliases below

String entries and { source } entries are functionally identical. The object form exists so future per-entry options can be added without breaking the array shape.

Named variants

For apps that need to swap stacks at build time (multi-brand, dev-vs-prod data adapters, theme A/B):

export default {
  unstable_routeLayerVariants: {
    defaultVariant: "production",
    envVar: "VITE_LAYER", // optional, defaults to VITE_LAYER
    variants: {
      production: {
        layers: ["./layers/base", "./layers/brand", "./layers/cart"],
      },
      demo: {
        layers: [
          "./layers/base",
          "./layers/brand",
          "./layers/demo",
          "./layers/cart",
        ],
      },
    },
  },
} satisfies Config;

VITE_LAYER=demo npm run build selects the demo stack. Empty/unset env var falls back to defaultVariant. The same shape can also live in a sibling layers.config.json for projects that prefer variants out of the TS file.

Import aliases (inside any layer's source tree)

import { Header } from "@/components/Header";                     // top-down: highest layer wins
import { Header as BaseHeader } from "@parent/components/Header"; // strictly below importer's layer
import DemoHeader from "@layers/demo/components/Header";          // direct addressing by basename

Override semantics: any cross-layer file resolution that lands inside a registered layer's directory is shadow-eligible – the highest layer in the stack wins. Route modules and third-party packages are excluded.

Build-time / runtime introspection

declare const __LAYER_VARIANT__: string;
declare const __LAYER_ORDER__: readonly string[];

import { variant, layers } from "virtual:react-router/layer-stack";

How it looks on disk

Here's the directory layout from the consumer demo app I'm running locally — a real app composed from one host plus four layers, with overrides, layer-owned routes, and per-layer tsconfigs all visible:

my-app/
├── react-router.config.ts        # declares unstable_routeLayerVariants
├── tsconfig.json                 # extends .react-router/types/+layer-tsconfig.json
├── app/
│   ├── root.tsx                  # uses @/components/Header etc.
│   ├── routes.ts                 # host's own routes (just the index here)
│   ├── routes/
│   │   └── home.tsx
│   └── app.css
└── layers/
    ├── base/                     # lowest layer: shared baseline
    │   ├── app/
    │   │   ├── routes.ts         # contributes /about, /contact, /__layers
    │   │   ├── about.tsx
    │   │   ├── contact.tsx
    │   │   └── layers-debug.tsx
    │   ├── components/
    │   │   ├── Button.tsx
    │   │   ├── Footer.tsx
    │   │   ├── Greeting.tsx
    │   │   └── Header.tsx        # default Header
    │   └── tsconfig.json         # generated; extends per-layer composite
    │
    ├── brand/                    # wraps base; overrides Header + Greeting
    │   ├── app/
    │   │   ├── routes.ts         # contributes /brand
    │   │   └── brand.tsx
    │   ├── components/
    │   │   ├── CartProvider.tsx
    │   │   ├── Greeting.tsx      # shadows base/Greeting
    │   │   ├── Header.tsx        # imports @parent/Header (= base) and wraps it
    │   │   ├── PriceTag.tsx
    │   │   ├── ProductTile.tsx
    │   │   └── Providers.tsx
    │   └── tsconfig.json
    │
    ├── demo/                     # only active under VITE_LAYER=demo
    │   ├── app/
    │   │   ├── routes.ts         # contributes /fixtures
    │   │   └── fixtures.tsx
    │   └── components/
    │       ├── Header.tsx        # shadows brand/Header (which wraps base)
    │       └── ProductTile.tsx
    │
    └── minicart/                 # highest layer: cart UI
        ├── components/
        │   └── Header.tsx        # final Header in the chain
        └── tsconfig.json

A few things worth pointing out from this layout:

• Each layer mirrors the host's own shape. app/routes.ts and app/<route>.tsx inside a layer are just the application's structure repeated. There's no new convention to learn — if you can author an RR7 app, you can author a layer.
• Layers contribute routes additively. base adds /about, /contact, /__layers; brand adds /brand; demo adds /fixtures. The host's own routes.ts only needs to declare what's unique to the host (here, the index route). Duplicate IDs error at config-load with a layer-aware diagnostic.
• Overrides are file-path coincidences. base/components/Header.tsx, brand/components/Header.tsx, demo/components/Header.tsx, and minicart/components/Header.tsx all exist. The resolver walks top-down: under the production variant, @/components/Header resolves to minicart's; under demo, it resolves to minicart's but brand/components/Header can still reach @parent/components/Header (which is base's).
• Per-layer tsconfig.json is generated. Each layers/<name>/tsconfig.json is written by typegen with a "//" marker and gitignored. The host's root tsconfig.json extends the typegen-managed .react-router/types/+layer-tsconfig.json fragment.
• A layer can be a directory or an npm package. This demo uses local paths; the implementation accepts @scope/pkg entries identically (require.resolve + realpath).

Status

Implemented end-to-end against main:

• ~240 unit tests in react-router-dev (config, layer resolver, typegen, watcher) – passing
• Playwright integration tests for overrides, variants, typegen, and watcher behavior – passing
• Typecheck clean across the workspace
• A consumer app exercising the full surface (bare list, variants, all three aliases, file-level overrides, build-time globals, runtime virtual module, per-layer typegen) running locally

What is your thoughts here? Happy to open a draft PR.

[k-montgomery]

Nice job @dlutsyk, upvoted! 👍