Skip to main content

File Shadowing

Archibald builds one codebase into multiple platforms (e.g. shop, app, portal) and tenants (brand or shop variants). File shadowing is how a platform or tenant customizes that codebase: it overrides any source file — component, style, asset — by placing a file at a matching path, without touching the original. The base implementation stays intact; the build picks the most specific file that exists.

The resolution chain​

For a given import, the compiler resolves most-specific-first and falls back down a fixed chain:

  1. platform + tenant — src/{platform}/…/tenant/{tenant}/…
  2. platform — src/{platform}/…
  3. tenant (on the default platform) — src/shop/…/tenant/{tenant}/…
  4. base — src/shop/… (the default-platform file)

The first platform in project.platforms is the default platform (here shop); its files are the base everything else falls back to.

Always import the base path​

Imports are always written against the base path — never against an override:

import { Foo } from 'shop/client/components/Foo/Foo';

The build rewrites this import to the winning override for the platform/tenant being built. Code never needs to know whether an override exists; adding or deleting an override file changes resolution without touching a single import.

Never edit base code for a tenant​

When a requirement is tenant-specific, the change belongs in the tenant's override path — not in the base file:

src/shop/client/components/Foo/Foo.tsx                        ← base: leave it alone
src/shop/client/tenant/netconomy-b2c/components/Foo/Foo.tsx   ← tenant override: change it here

Editing base code for one tenant leaks that tenant's behavior into every other platform and tenant. An override that only wants to extend the original imports it via the @original/ prefix instead of duplicating it.

Where the rules live​

The chain is configured under project.shadowing in archibald.json — one path template per rule, using {platform} and {tenant} tokens:

{
    "project": {
        "platforms": ["shop", "app", "portal"],
        "tenants": ["netconomy-b2c", "netconomy-b2b"],
        "shadowing": {
            "active": true,
            "config": ["src/{platform}/client(/tenant/{tenant})"]
        }
    }
}

The full reference — rule syntax, wildcards, tenant/platform inheritance with extends, @original/ imports, override markers, and live add/remove under serve — is File shadowing. How platforms and tenants are defined in the first place is covered in Tenants, Platforms & Environments.