Pods

[stevenle]

Description

A root site should consist of one or more "pods" where a pod represents a directory that can have "elements", "routes", etc. By default, the directory run with root dev is the "main pod", but plugins should be able to register themselves as pods as well, and when developing a plugin, you should be able to simply run root dev on that directory.

We should have some first-party tools for building and publishing pods so that it's easy for a developer to build plugins that extend a root site and to be able to build that plugin as if it were any other root site.

[stevenle]

fyi planning this with claude:

I'm interested in providing a way for plugins to create a mini version of a root site, where routes/elements/bundles are automatically added to the site if the plugin registers itself. Considering calling the collection of routes/elements/bundles (and collections for root-cms enabled sites) as "pods". Can you plan what this feature would look like?

[stevenle]

claude asked me some pretty good questions about the implementation, here's what i answered for them:

[stevenle]

claude proposed plan:

Plugin Pods

Context

Today, rootjs plugins can contribute SSR entries (ssrInput()), Vite
plugins, server middleware (configureServer), and build hooks. But they
cannot ship the three things that make up the public surface of a
rootjs site: routes, elements, bundles — and, for root-cms sites, CMS
collections. All of those are discovered via compile-time
import.meta.glob calls rooted at the user's project directory:

• Routes — packages/root/src/render/router.ts:7-10
• Bundles — scanned at packages/root/src/cli/build.ts:74-83
• Elements — runtime glob in getElementsDirs()
  (packages/root/src/node/element-graph.ts:128-146), but the include
  paths are guarded to stay inside rootDir.
• Collections — packages/root-cms/core/project.ts:14-22

As a result, middleware-style plugins like root-cms can exist, but you
can't publish a drop-in plugin that ships, say, a blog (routes + post
collection + <blog-card> element + search bundle), a docs site, or an
auth flow. Users have to hand-copy those pieces into their site.

A pod is a mini rootjs site — routes/, elements/, bundles/, and
(optionally) collections/ — that a plugin contributes. When the plugin
is installed and added to root.config.ts, its pod merges into the host
site: pod routes are reachable, pod elements ship with the client, pod
collections appear in the CMS, all flowing through the existing 3-pass
build with correct asset tracking and HMR.

Decisions (resolved with user)

• URL mounting: flat merge — a pod's routes/blog/[slug].tsx serves
  /blog/[slug] on the host. Pods may declare a mount suggestion, and
  the user can override it per-pod in root.config.ts.
• Collection id conflicts: flat ids; the user's project collection
  wins over a pod collection with the same id (silent shadowing, logged
  as info). Two pods defining the same id error out unless the user
  renames one via config.
• Pod layout: convention. Plugin packages ship a pod/ directory
  with standard subdirs (routes/, elements/, bundles/,
  collections/, translations/). The plugin factory just points
  rootjs at it.
• root-cms refactor: do not refactor /cms to be a pod in this
  pass. Ship the pod API first; root-cms continues to wire /cms via
  configureServer. However, root-cms's collection loader gets swapped
  from import.meta.glob to the pods virtual module so pods can ship
  CMS collections.

Approach

Replace the three compile-time import.meta.glob call sites (routes,
collections, translations) with a Vite virtual module populated by a
first-party rootjs Vite plugin, rootPodsVitePlugin. At dev-server and
build time, the plugin walks pod registrations + user project files and
emits an ESM module containing static import statements for each
contributed file. Because the virtual module uses real static imports,
Vite's module graph, HMR, CSS side-effect tracking, and the 3-pass SSR /
routes-CSS / client pipeline all keep working.
Elements and bundles stay on the existing runtime-glob model but now
accept plugin-contributed absolute paths (bypassing the rootDir
containment guard only for plugin-sourced paths, which are trusted).
Pod route files are resolved via bare-specifier imports
(@blinkk/root-docs-pod/pod/routes/overview.tsx), so pod packages must
declare "exports": {"./pod/*": "./pod/*"} in their package.json.

Why a virtual module instead of…

• Writing a bootstrap file to .root/: creates race conditions with
  vite build --watch and stale-file bugs; no good HMR story.
• Relaxing import.meta.glob to support cross-root / absolute
  patterns: that glob is compile-time and hard-rooted at
  vite.config.root; there is no supported Vite API to point it at
  multiple roots or at node_modules.

Public API

Plugin.pod (extension, packages/root/src/core/plugin.ts ~line 85)

export interface Plugin {
  // ...existing fields
  /** Register a pod (a mini root.js site) contributed by this plugin. */
  pod?: Pod | Pod[] | ((ctx: {rootConfig: RootConfig}) => Pod | Promise<Pod>);
}

Pod (new file packages/root/src/core/pod.ts)

export interface Pod {
  /** Unique pod name, e.g. '@blinkk/root-docs-pod'. */
  name: string;
  /** URL prefix for pod routes. Default '/'. */
  mount?: string;
  /** Tie-breaker when multiple pods register the same URL. Higher wins. */
  priority?: number;
  /** Absolute path to the pod's routes/ dir. */
  routesDir?: string;
  /** Absolute path(s) to the pod's elements/ dir(s). */
  elementsDirs?: string[];
  /** Absolute path to the pod's bundles/ dir. */
  bundlesDir?: string;
  /** Absolute path to the pod's collections/ dir (root-cms only). */
  collectionsDir?: string;
  /** Absolute path to the pod's translations/ dir. */
  translationsDir?: string;
}

RootUserConfig.pods (new packages/root/src/core/config.ts ~line 105)

export type PodConfig = {
  enabled?: boolean;                       // default true
  mount?: string;                          // override Pod.mount
  priority?: number;                       // override Pod.priority
  routes?: {exclude?: (string | RegExp)[]};
  collections?: {
    exclude?: string[];
    rename?: Record<string, string>;       // oldId → newId
  };
};

export interface RootUserConfig {
  // ...
  pods?: Record<string /* pod name */, PodConfig>;
}

Conflict rules

• Routes: user site always wins (priority +Infinity). Pod vs. pod:
  higher priority wins, tiebreak by pod name. The RouteTrie already
  supports matchAll; extend route-handling so a winner that calls
  render404({nextRoute: true}) falls through to the next pod match.
• Collections: user /collections/*.schema.ts wins over any pod
  collection with the same id — log at info level on startup. Pod vs.
  pod collision with the same id throws at collectPods() with a
  message pointing the user to pods[name].collections.rename.
• Elements (custom element tag names): user wins, then highest
  priority pod. Log collisions.

Critical files

Modify

File	Change
packages/root/src/core/plugin.ts	Add pod field to Plugin after line 85.
packages/root/src/core/config.ts	Add PodConfig and pods field after ~line 105.
packages/root/src/core/types.ts	Add podName?: string to Route (~line 189).
packages/root/src/render/router.ts:7-10	Remove import.meta.glob; import ROUTE_MODULES from virtual:root/routes. Route entries carry pre-resolved routePath (mount already applied), so initRouteTrie (lines 33-102) no longer derives it from the file path.
packages/root/src/node/element-graph.ts:128-146	Accept pods arg; bypass the directoryContains(rootDir, …) check only for pod-supplied elementsDirs.
packages/root/src/node/vite.ts:78-82	Inject rootPodsVitePlugin(rootConfig) into the Vite plugins list.
packages/root/src/cli/build.ts:58-83, 165-193, 196-225	Call collectPods(); extend route-file glob (line 59), bundle glob (line 75), and pass pods into getElements() (line 69). All three passes then include pod files.
packages/root/src/cli/dev.ts:197-239	Call collectPods(); include pod dirs in element/bundle discovery; add pod dirs to viteServer.watcher.add(...) for HMR.
packages/root/src/core/hooks/useI18nContext.ts:26-38	Replace translations glob with virtual:root/translations.
packages/root-cms/core/project.ts:14-22	Replace SCHEMA_MODULES = import.meta.glob(...) with import {SCHEMA_MODULES} from 'virtual:root/schemas'. User collections override pod collections with the same id (handled in the virtual module generator).
packages/root-cms/core/plugin.ts:68-92	writeCollectionSchemasToJson reads per-collection podName (from the virtual module's manifest) and writes it into the emitted JSON so the CMS UI can group-by-pod later. No functional change to /cms in this PR.

Create

File	Purpose
packages/root/src/core/pod.ts	Pod type + helper definePod().
packages/root/src/node/pod-collector.ts	collectPods(rootConfig) → normalized ResolvedPod[]. Applies user overrides (enabled, mount, priority, rename, exclude), glob-scans each pod subdir, detects duplicate pod names and duplicate collection ids. Cached; invalidated by dev watcher.
packages/root/src/node/pods-vite-plugin.ts	Vite plugin resolving virtual:root/routes, virtual:root/schemas, virtual:root/translations; emits static-import ESM source; wires handleHotUpdate to invalidate the virtual modules and emit a full reload when a pod file is added/removed.
packages/root/src/node/pod-collector.test.ts	Unit tests for pod resolution, overrides, conflict detection.
packages/root/src/node/pods-vite-plugin.test.ts	Unit tests: virtual module content, determinism, user-wins-over-pod collection shadowing.
examples/pods-basic/	Minimal consumer site.
examples/pods-basic/packages/demo-pod/	Workspace-linked example pod with routes + element + bundle.

Reusable pieces to lean on

• ssrInput() pattern in build.ts:115-122 — the mental model for
  pods is identical: a plugin contributes inputs that get merged into
  Vite's graph.
• configureServerPlugins() in plugin.ts:93-123 — no change needed;
  pods don't need their own server lifecycle.
• RouteTrie.matchAll — already supports sequential fallback; the
  priority + fallthrough behavior reuses it.
• BuildAssetMap.fromViteManifest — already tolerates relPath
  entries with ../ prefixes, which is what pod elements will produce.

Example: @blinkk/root-docs-pod

Package layout

@blinkk/root-docs-pod/
  package.json      # "exports": {"./pod/*": "./pod/*"}, "files": ["dist", "pod"]
  dist/index.js     # compiled plugin factory
  pod/
    routes/
      index.tsx
      [slug].tsx
    elements/
      docs-sidebar.ts
    bundles/
      docs-search.ts
    collections/
      DocsPages.schema.ts
    translations/
      en.json

Plugin factory

import path from 'node:path';
import {fileURLToPath} from 'node:url';
import type {Plugin} from '@blinkk/root';
const POD_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../pod');
export function docsPod(opts: {mount?: string} = {}): Plugin {
  return {
    name: '@blinkk/root-docs-pod',
    pod: {
      name: '@blinkk/root-docs-pod',
      mount: opts.mount ?? '/docs',
      routesDir: path.join(POD_DIR, 'routes'),
      elementsDirs: [path.join(POD_DIR, 'elements')],
      bundlesDir: path.join(POD_DIR, 'bundles'),
      collectionsDir: path.join(POD_DIR, 'collections'),
      translationsDir: path.join(POD_DIR, 'translations'),
    },
  };
}

Consumer site

// root.config.ts
import {defineConfig} from '@blinkk/root';
import {cmsPlugin} from '@blinkk/root-cms/plugin';
import {docsPod} from '@blinkk/root-docs-pod';
export default defineConfig({
  plugins: [
    cmsPlugin({/* ... */}),
    docsPod({mount: '/help'}),
  ],
  pods: {
    '@blinkk/root-docs-pod': {
      routes: {exclude: ['legal/**']},
      collections: {rename: {DocsPages: 'HelpPages'}},
    },
  },
});

After install + root dev, the site serves /help/ and /help/:slug,
ships <docs-sidebar> as a client element, and shows HelpPages in the
CMS admin UI. A user routes/help/index.tsx in their own project would
shadow the pod's index.

Phasing

1. Phase 1: Pod types, collectPods, rootPodsVitePlugin; swap
   router.ts and useI18nContext.ts to virtual modules. No user API
   yet. Full test coverage. Invisible change.
2. Phase 2: Swap root-cms/core/project.ts to the virtual schemas
   module; add conflict detection, rename, and user-wins shadowing.
3. Phase 3: Surface Plugin.pod and RootUserConfig.pods. Document.
4. Phase 4: Reference @blinkk/root-docs-pod + examples/pods-*/.

Phase 1 is invisible but touches the router and SSR loader — it needs
its own release cycle before later phases ship.

Verification

• pnpm --filter @blinkk/root test with new unit tests for
  pod-collector and pods-vite-plugin (virtual-module output,
  overrides, conflict handling, user-wins shadowing).
• pnpm --filter @blinkk/root-cms test passes after the virtual
  schemas swap.
• pnpm -r typecheck clean.
• New examples/pods-basic:
  • pnpm --filter pods-basic dev — serves both user routes and a
    pod route; editing a file in the linked pod package triggers
    reload; adding a new pod route file triggers full reload and is
    picked up; user-shadowing a pod route works.
  • pnpm --filter pods-basic build && pnpm --filter pods-basic start
    — dist/html/ contains pod routes; dist/.root/manifest.json
    contains pod elements and bundles; served pages load pod element
    CSS and JS.
• Root-cms integration (manual): install a pod that contributes a
  collection; confirm /cms sidebar lists it, documents can be
  edited, generated root-cms.d.ts includes the pod collection types,
  dist/collections/*.schema.json is produced on build.
• Conflict handling:
  • User route at /help/ shadows pod route — verified with curl
    plus a route-inspector log.
  • Two pods registering the same collection id without rename → build
    fails with a message naming both pods.
  • User collection with same id as pod collection → pod entry is
    dropped, startup logs the shadow.
• i18n: /[locale]/help/overview resolves for pod routes when
  i18n.locales is set.