@davaux/multisite 0.8.0

package/CLAUDE.md

@@ -0,0 +1,133 @@
+<!-- pka-generated -->
+# @davaux/multisite
+
+> Generated by Project Knowledge Analyzer on 2026-06-06T21:53:10.370Z
+
+## Overview
+
+Multi-site hosting for Davaux — run multiple sites from a single codebase
+
+**Version**: 0.8.0
+**Author**: David L Dyess II
+**License**: MIT
+**Repository**: https://codeberg.org/davaux/davaux#readme
+
+## Tech Stack
+
+- **Language**: TypeScript
+- **Module System**: ESM (`type: module`)
+- **Build Tool**: esbuild
+
+## Commands
+
+- `npm run build` — tsc
+- `npm run typecheck` — tsc --noEmit
+- `npm run test` — node --import tsx/esm --test 'src/test/**/*.test.ts'
+
+## Project Structure
+
+```
+├── README.md
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── test/
+    │   ├── fixtures/
+    │   │   ├── base/
+    │   │   │   └── routes/
+    │   │   │       ├── _layout.ts
+    │   │   │       ├── about.page.ts
+    │   │   │       └── index.page.ts
+    │   │   ├── site-a/
+    │   │   │   └── routes/
+    │   │   │       ├── _layout.ts
+    │   │   │       ├── _middleware.ts
+    │   │   │       ├── config.page.ts
+    │   │   │       ├── index.page.ts
+    │   │   │       ├── shop.page.ts
+    │   │   │       └── state.page.ts
+    │   │   └── site-b/
+    │   │       └── routes/
+    │   │           ├── _error.ts
+    │   │           └── about.page.ts
+    │   └── multisite.test.ts
+    └── index.ts
+
+```
+
+## Entry Points
+
+- `src/index.ts`
+
+## Files by Type
+
+### Documentation (1)
+- `README.md`
+
+### Config (2)
+- `package.json`
+- `tsconfig.json`
+
+### Module (1)
+- `src/index.ts`
+
+
+## Git
+- **Branch**: main
+- **Last Commit**: chore: Add alpha status note to README
+- **Author**: David Dyess II
+- **Date**: 2026-06-06 15:52:27 -0600
+- **Remote**: https://codeberg.org/davaux/davaux.git
+
+### Recent Commits
+```
+f527031 chore: Add alpha status note to README
+90c819e chore: Add repo info to package.json files
+b200d9d feat(davaux)!: Add OmlCacheConfig - opt-in with includes option or opt-out with excludes option; Fix OML implementation to follow OML spec - use output instead of return
+3bce0c2 chore: Update and add READMEs to packages; update ROADMAP
+fc27c20 fix(davaux): Remove old dist folder on new builds; fix server port per DavauxConfig
+c760659 feat(davaux): Add minify CSS in production builds
+c899ab8 fix(davaux): Added method JS and JSX extenstion to scanner
+7d99f04 feat(davaux): Add support for declarative partial updates
+3b47f37 chore: Bump package versions to 0.8.0
+aa0460f chore: Add CHANGELOG.md
+```
+
+## Dependencies
+
+
+### Development
+@types/node, davaux, esbuild, tsx, typescript
+
+
+
+
+
+## Tests (12)
+
+### Test Suites (1)
+- `src/test/multisite.test.ts`
+
+### Fixtures (11)
+- `src/test/fixtures/base/routes/_layout.ts`
+- `src/test/fixtures/base/routes/about.page.ts`
+- `src/test/fixtures/base/routes/index.page.ts`
+- `src/test/fixtures/site-a/routes/_layout.ts`
+- `src/test/fixtures/site-a/routes/_middleware.ts`
+- `src/test/fixtures/site-a/routes/config.page.ts`
+- `src/test/fixtures/site-a/routes/index.page.ts`
+- `src/test/fixtures/site-a/routes/shop.page.ts`
+- `src/test/fixtures/site-a/routes/state.page.ts`
+- `src/test/fixtures/site-b/routes/_error.ts`
+- `src/test/fixtures/site-b/routes/about.page.ts`
+
+
+
+## Import Graph
+
+## Exported Symbols
+
+**`src/index.ts`**
+`mergeScanResults`, `defineSites`, `buildMultisiteApps`, `startMultisiteServer`, `dispatchToSite`, `startMultisiteDev`, `startMultisite`, `getSite`, `SiteDefinition`, `MultisiteConfig`, `BuildOptions`, `ServerOptions`, `StartMultisiteOptions`
+
+

package/README.md

@@ -0,0 +1,147 @@
+# @davaux/multisite
+
+Multi-site hosting for Davaux — run multiple sites from a single process, dispatched by `Host` header.
+
+## Installation
+
+```bash
+npm install @davaux/multisite
+```
+
+## Basic setup
+
+```ts
+// server.ts
+import { startMultisite } from '@davaux/multisite'
+
+startMultisite({
+  sites: [
+    {
+      name: 'main',
+      hostname: 'example.com',
+      routesDir: './src/routes/main',
+    },
+    {
+      name: 'blog',
+      hostname: 'blog.example.com',
+      routesDir: './src/routes/blog',
+    },
+  ],
+}, { port: 3000, cwd: import.meta.dirname })
+```
+
+`startMultisite` auto-detects `NODE_ENV` — dev mode with file watching and live reload when `NODE_ENV !== 'production'`, production dispatch otherwise. Pass `cwd: import.meta.dirname` from your `server.ts` for reliable path resolution.
+
+## Shared base + per-site overlay
+
+Use `baseDir` for routes shared across all sites. Each site's `routesDir` overlays on top — when both define the same URL pattern and type, the site-specific route wins:
+
+```ts
+startMultisite({
+  baseDir: './src/routes/base',
+  islandsDir: './src/islands/base',
+  publicDir: './public',
+  sites: [
+    { name: 'tenant-a', hostname: 'a.example.com', routesDir: './src/routes/tenant-a' },
+    { name: 'tenant-b', hostname: 'b.example.com', routesDir: './src/routes/tenant-b' },
+    { name: 'fallback', hostname: '*' },
+  ],
+}, { cwd: import.meta.dirname })
+```
+
+`'*'` as `hostname` is a catch-all for any host not explicitly registered.
+
+## Per-site config
+
+Attach arbitrary data to each site via `SiteDefinition.config`. Access it in any handler, layout, or middleware via `getSite<T>(ctx)`:
+
+```ts
+import { getSite } from '@davaux/multisite'
+
+// In server.ts:
+startMultisite({
+  sites: [
+    { name: 'acme', hostname: 'acme.example.com', config: { theme: 'blue', name: 'Acme' } },
+    { name: 'globex', hostname: 'globex.example.com', config: { theme: 'red', name: 'Globex' } },
+  ],
+})
+
+// In any route file:
+export default definePage((ctx) => {
+  const site = getSite<{ theme: string; name: string }>(ctx)
+  return <h1>Welcome to {site?.name}</h1>
+})
+```
+
+`getSite` returns `undefined` when called outside a multisite server (e.g. in tests).
+
+## `SiteDefinition` options
+
+| Option | Type | Description |
+|---|---|---|
+| `name` | `string` | Unique site identifier used in logging and asset paths |
+| `hostname` | `string \| string[]` | `Host` header value(s) that route to this site. `'*'` is a catch-all |
+| `routesDir` | `string?` | Site-specific routes directory, overlaid on `baseDir` |
+| `islandsDir` | `string?` | Site-specific islands directory, merged with shared `islandsDir` |
+| `publicDir` | `string?` | Site-specific static files directory (takes priority over shared `publicDir`) |
+| `clientEntry` | `string?` | Site-specific client bundle entry. Overrides shared `clientEntry` |
+| `config` | `T?` | Arbitrary per-site data, accessible via `getSite<T>(ctx)` |
+
+## `MultisiteConfig` options
+
+| Option | Type | Description |
+|---|---|---|
+| `sites` | `SiteDefinition[]` | Site definitions (required) |
+| `baseDir` | `string?` | Shared base routes directory |
+| `islandsDir` | `string?` | Shared islands directory — included in every site's client bundle |
+| `publicDir` | `string?` | Shared static files directory |
+| `clientEntry` | `string?` | Shared client bundle entry compiled to `/_davaux/client.js` |
+
+## Production build
+
+```ts
+// build.ts
+import { buildMultisite } from '@davaux/multisite/build'
+
+await buildMultisite({
+  sites: [
+    { name: 'main', hostname: 'example.com', routesDir: './src/routes/main' },
+  ],
+}, { cwd: import.meta.dirname })
+```
+
+Compiles all route files, per-site island bundles, and `server.ts` / `multisite.config.ts` to `dist/`. Run with `node dist/server.js`.
+
+## Advanced: embedding in a custom server
+
+```ts
+import { buildMultisiteApps, dispatchToSite } from '@davaux/multisite'
+import { createServer } from 'node:http'
+
+const apps = await buildMultisiteApps(config, { cwd: import.meta.dirname })
+
+const server = createServer(async (req, res) => {
+  const handled = await dispatchToSite(apps, req, res)
+  if (!handled) { res.writeHead(404); res.end('No site') }
+})
+```
+
+## TypeScript
+
+Use `defineSites<T>` to get type inference on `SiteDefinition.config` without a type annotation at every call site:
+
+```ts
+import { defineSites } from '@davaux/multisite'
+
+interface SiteConfig { theme: string }
+
+export const sites = defineSites<SiteConfig>({
+  sites: [
+    { name: 'acme', hostname: 'acme.example.com', config: { theme: 'blue' } },
+  ],
+})
+```
+
+## Documentation
+
+[davaux.codeberg.page/docs/multisite](https://davaux.codeberg.page/docs/multisite)

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@davaux/multisite",
+  "version": "0.8.0",
+  "description": "Multi-site hosting for Davaux — run multiple sites from a single codebase",
+  "type": "module",
+  "author": "David L Dyess II",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/davaux/davaux"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/davaux/davaux/issues"
+  },
+  "homepage": "https://codeberg.org/davaux/davaux#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./build": {
+      "import": "./dist/build.js",
+      "types": "./dist/build.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx/esm --test 'src/test/**/*.test.ts'"
+  },
+  "peerDependencies": {
+    "davaux": ">=0.8.0",
+    "esbuild": ">=0.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "davaux": "*",
+    "esbuild": "^0.28.0",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/build.ts

@@ -0,0 +1,183 @@
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { collectCss, generateIslandsEntry, islandServerPlugin } from 'davaux/build'
+import {
+  collectEsbuildPlugins,
+  collectScannerSuffixes,
+  type DavauxPlugin,
+  pathsToAlias,
+} from 'davaux/config'
+import { scanIslands, scanRoutes } from 'davaux/scanner'
+import type { MultisiteConfig } from './index.js'
+
+export interface BuildMultisiteOptions {
+  /** Project root directory. Defaults to `process.cwd()`. */
+  cwd?: string
+  /** Output directory. Defaults to `{cwd}/dist`. */
+  outDir?: string
+  /** Extra packages to mark as external in addition to `node:*`, `davaux`, and `@davaux/multisite`. */
+  external?: string[]
+  /**
+   * Davaux plugins to apply during the build — contributes esbuild transforms and scanner
+   * suffix extensions. Use the same plugins here as in your `davaux.config.ts`.
+   *
+   * @example
+   * import { mdx } from '@davaux/mdx'
+   * await buildMultisite(sites, { cwd: import.meta.dirname, plugins: [mdx()] })
+   */
+  plugins?: DavauxPlugin[]
+  /**
+   * tsconfig-style path aliases forwarded to esbuild `alias`. Same format as
+   * `compilerOptions.paths` — e.g. `{ '~/*': ['./src/*'] }`.
+   */
+  paths?: Record<string, string>
+}
+
+/**
+ * Compile a multisite project to JavaScript.
+ *
+ * Reads route and island directories directly from the `MultisiteConfig` so the
+ * config is the single source of truth. Discovers and compiles all route, layout,
+ * middleware, and error-page files, per-site client island bundles, plus
+ * `server.ts` / `multisite.config.ts` if they exist at the project root.
+ *
+ * Requires `esbuild` to be installed (it is present in any project that
+ * depends on `davaux`).
+ *
+ * @example
+ * // build.ts
+ * import { buildMultisite } from '@davaux/multisite/build'
+ * import { sites } from './multisite.config.js'
+ *
+ * await buildMultisite(sites, { cwd: import.meta.dirname })
+ */
+export async function buildMultisite<T>(
+  config: MultisiteConfig<T>,
+  options: BuildMultisiteOptions = {},
+): Promise<void> {
+  const { build } = await import('esbuild')
+  const cwd = options.cwd ?? process.cwd()
+  const outDir = options.outDir ?? resolve(cwd, 'dist')
+  const davauxPlugins = options.plugins ?? []
+  const extraSuffixes = [...(config.extraSuffixes ?? []), ...collectScannerSuffixes(davauxPlugins)]
+  const userAlias = pathsToAlias(options.paths ?? {})
+
+  // All island directories (for the server-side island plugin)
+  const allIslandDirs: string[] = [
+    ...(config.islandsDir ? [config.islandsDir] : []),
+    ...config.sites.flatMap((s) => (s.islandsDir ? [s.islandsDir] : [])),
+  ]
+
+  // Collect route directories directly from config — no re-discovery needed
+  const routeDirs: string[] = []
+  if (config.baseDir) routeDirs.push(config.baseDir)
+  for (const site of config.sites) {
+    if (site.routesDir) routeDirs.push(site.routesDir)
+  }
+
+  // Scan for compilable files in each routes directory
+  const routeFiles: string[] = []
+  for (const dir of routeDirs) {
+    if (!existsSync(dir)) continue
+    const { routes, layouts, middlewares, errorPage } = await scanRoutes(dir, extraSuffixes)
+    routeFiles.push(
+      ...routes.map((r) => r.filePath),
+      ...layouts.map((l) => l.filePath),
+      ...middlewares.map((m) => m.filePath),
+      ...(errorPage ? [errorPage] : []),
+    )
+  }
+
+  // Include server.ts and multisite.config.ts at the project root if present
+  const entryPoints: string[] = [...routeFiles]
+  for (const name of ['server.ts', 'multisite.config.ts']) {
+    const p = resolve(cwd, name)
+    if (existsSync(p)) entryPoints.push(p)
+  }
+
+  const baseExternal = ['node:*', 'davaux', '@davaux/multisite', ...(options.external ?? [])]
+
+  // Include src/middleware.ts if present (app-level middleware runs before route matching)
+  const middlewareSrc = resolve(cwd, 'src', 'middleware.ts')
+  if (existsSync(middlewareSrc)) entryPoints.push(middlewareSrc)
+
+  // Compile routes (with island server wrapping + plugin transforms)
+  await build({
+    entryPoints,
+    outdir: outDir,
+    outbase: cwd,
+    format: 'esm',
+    platform: 'node',
+    target: 'node22',
+    bundle: true,
+    jsx: 'automatic',
+    jsxImportSource: 'davaux',
+    external: baseExternal,
+    sourcemap: true,
+    alias: { ...userAlias, 'davaux/client': 'davaux/signal' },
+    plugins: [
+      ...(allIslandDirs.length > 0 ? [islandServerPlugin(allIslandDirs)] : []),
+      ...collectEsbuildPlugins(davauxPlugins),
+    ],
+  })
+
+  // Collect CSS side-effect outputs into dist/_davaux/styles.css
+  const stylesOutFile = join(outDir, '_davaux', 'styles.css')
+  await collectCss(outDir, stylesOutFile)
+
+  // Compile per-site client island bundles to dist/_davaux/<name>/islands.js
+  const baseIslands = config.islandsDir ? await scanIslands(config.islandsDir) : []
+  let islandBundles = 0
+
+  for (const site of config.sites) {
+    const siteIslands = site.islandsDir ? await scanIslands(site.islandsDir) : []
+    const allIslands = [...baseIslands, ...siteIslands]
+    if (allIslands.length === 0) continue
+
+    await build({
+      stdin: {
+        contents: generateIslandsEntry(allIslands),
+        loader: 'ts',
+        resolveDir: cwd,
+      },
+      outfile: join(outDir, '_davaux', site.name, 'islands.js'),
+      format: 'esm',
+      platform: 'browser',
+      target: 'es2022',
+      bundle: true,
+      jsx: 'automatic',
+      jsxImportSource: 'davaux/client',
+      sourcemap: true,
+      alias: userAlias,
+      plugins: collectEsbuildPlugins(davauxPlugins),
+    })
+    islandBundles++
+  }
+
+  // Compile per-site client bundles to dist/_davaux/<name>/client.js
+  let clientBundles = 0
+
+  for (const site of config.sites) {
+    const clientEntry = site.clientEntry ?? config.clientEntry
+    if (!clientEntry || !existsSync(clientEntry)) continue
+
+    await build({
+      entryPoints: [clientEntry],
+      outfile: join(outDir, '_davaux', site.name, 'client.js'),
+      format: 'esm',
+      platform: 'browser',
+      target: 'es2022',
+      bundle: true,
+      jsx: 'automatic',
+      jsxImportSource: 'davaux/client',
+      sourcemap: true,
+      alias: userAlias,
+      plugins: collectEsbuildPlugins(davauxPlugins),
+    })
+    clientBundles++
+  }
+
+  console.log(
+    `[davaux/multisite] Built ${routeFiles.length} route file(s), ${islandBundles} island bundle(s), ${clientBundles} client bundle(s)`,
+  )
+}