Skip to content
Kumiko

host-routing

Host- and path-based tenant routing: an authoritative tenant resolver from the subdomain (tenantBy host), a tenant existence check against enabled, active tenants, and the tenant-key query behind createHostDispatch, which picks the HTML file, CSP, locale redirect or 404 per host for runProdApp’s hostDispatch.

Quick example

Section titled “Quick example”

From recipes-host-routing — the smallest working mount:

// Host routing: one options object drives both halves. The feature makes the
// Host header the only source of the anonymous tenant; the dispatch picks the
// HTML file per host for runProdApp's `hostDispatch` (and, through
// toDevHostDispatch, for the dev server).


import {
  createHostDispatch,
  createHostRoutingFeature,
  type HostRoutingOptions,
} from "@cosmicdrift/kumiko-bundled-features/host-routing";
import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
import { z } from "zod";


export const routingOptions: HostRoutingOptions = {
  tenantBy: "host",
  baseDomain: "shop.test",
  apex: { file: "index.html", localeFiles: { en: "en/index.html" } },
  tenant: { file: "shop.html", csp: "default-src 'self'; frame-ancestors 'none'" },
  unknownTenant: { file: "unknown-shop.html" },
  locales: { default: "de", prefixed: ["en"] },
};


export const hostRoutingFeature = createHostRoutingFeature(routingOptions);
export const hostDispatch = createHostDispatch(routingOptions);


// A public query that reports which tenant the request landed on.
export const storefrontFeature = defineFeature("storefront", (r) => {
  r.queryHandler({
    name: "whoami",
    schema: z.object({}),
    access: { roles: ["anonymous"] },
    rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
    handler: async (query) => ({ tenantId: query.user.tenantId }),
  });
});

📄 On GitHub: samples/recipes/host-routing/src/feature.ts

How it fits

Section titled “How it fits”

What this feature needs to run (Requires).

flowchart TB
  n_host_routing["host-routing"]
  subgraph how_reqs["Requires"]
    n_auth_foundation["auth-foundation"]
    n_tenant["tenant"]
  end
  n_auth_foundation --> n_host_routing
  n_tenant --> n_host_routing

Getting started

Section titled “Getting started”

Start with recipes-host-routing for a step-by-step walkthrough with runnable code and integration tests.

Dependencies

Section titled “Dependencies”

Extensions & cross-feature APIs

Section titled “Extensions & cross-feature APIs”
  • Registers extension: tenantExistence → active-tenant