Vercel Microfrontends — activation runbook (Phase 3)

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

What this PR ships

• microfrontends.json at the repo root — the proposed split. Two applications:
  • encoreos-app (default; receives every un-routed path; today this is the entire app)
  • encoreos-public (peeled off: /auth, /employee-setup, /pending-activation, /pm/kiosk/:siteId/*, /portal/*, /p/:token, /packet/:token, /gr/whistleblower-report, /chatbot/widget)
• Turborepo workspace mapping: Turborepo resolves microfrontends.json application keys to npm workspace packages by matching the application key to package.json name. The keys encoreos-app / encoreos-public therefore have minimal placeholder packages at packages/encoreos-app and packages/encoreos-public (private, no source — the real app remains the root Vite SPA). When Phase 3 splits into real deployables, replace these placeholders with actual package roots or add packageName per the Turborepo microfrontends schema.
• scripts/audit/validate-microfrontends-config.ts — fast structural validator (kebab-case names, single default app, paths start with /, literal-overlap detection, soft check that paths exist in src/App.tsx / src/routes/). Wired to npm run audit:microfrontends.
• docs/architecture/decisions/ADR-017-microfrontends-pwa-scoping.md — formal ADR amending ADR-013 to handle per-zone PWA scopes.
• This runbook — step-by-step activation instructions, env-var layout, CI wiring, Playwright proxy invocation, rollback plan.

• The @vercel/microfrontends Vite plugin is not installed and not wired into vite.config.ts. Adding it without a corresponding Vercel project + microfrontends group does nothing useful and would only add a transitive dep. The activation steps below cover the install.
• No new Vercel projects exist yet. Creation is a dashboard action only a project owner can perform.
• The microfrontends.json file is inert until a Vercel Microfrontends Group exists in the Vercel team and the application names there match the names in this file.

⚠️ Editing microfrontends.json — strict-keys gotcha Both Turborepo (turbo 2.9+) and the Vercel runtime parse microfrontends.json and reject any unknown keys — including JSON-comment-style fields like _comment, _comment_*, etc. If an unknown key slips in, turbo run … aborts with Unable to parse JSON: Found an unknown key … and every Turborepo task fails before it starts. This regression was introduced once already (PR #145, fixed in the verification PR) when this runbook’s author shipped Vercel-style _comment_* keys. Allowed top-level keys: $schema, applications, options. Allowed per-application keys: routing, development, packageName, assetPrefix. Allowed per-routing-rule keys: group, paths, flag. Allowed development keys: fallback, local, task. Keep narrative notes here (in this runbook), not in microfrontends.json. The npm run audit:microfrontends validator now hard-fails on unknown keys to prevent this from ever shipping again.

​

Activation overview (project-owner steps)

​

Step 1 — Create the second Vercel project

1. Add New… → Project → Continue with this Repository (Encore-OS/encoreos).
2. Project name: encoreos-public.
3. Framework preset: Vite. Root directory: . (same monorepo root).
4. Build & Development Settings:
   • Build command: npm run build (same as the main project; the Vite plugin handles asset prefixing once installed).
   • Output directory: dist.
   • Install command: npm ci --legacy-peer-deps.
5. Environment variables: none for now. Build-time Supabase URL/key are statically defined in vite.config.ts per VERCEL_PROJECT_ID (see AGENTS.md § Cursor Cloud caveats and docs/development/VERCEL_ENV_REMOVAL_EXECUTION_2026-04-20.md).
6. Important: before adding encoreos-public’s prj_* ID to vite.config.ts’s VERCEL_PROJECT_TO_SUPABASE map, decide which Supabase target it points to. Recommend same as the parent project’s environment so encoreos_dev’s public zone hits dev Supabase, and encoreos_prod’s public zone hits prod Supabase.
7. Do not deploy yet. Pause auto-deploy under Settings → Git → Deploy Hooks if the project tries to build immediately.

​

Step 2 — Create the Microfrontends Group

1. Team Settings → Microfrontends → Create Group.
2. Group name: encoreos.
3. Default application: encoreos-app (the original project).
4. Add encoreos-public to the group.
5. Fallback environment: Same Environment (so preview builds without a matching encoreos-public build fall back to the production deployment of encoreos-public rather than the production deployment of encoreos-app).
6. Confirm pricing acknowledgement: 2 microfrontend projects per group are included on Pro; the proposed split fits in the free tier as long as we never add a third zone.

⚠️ Sequence matters. Create the group before merging the wiring PR (step 3). If the wiring PR merges first while the group does not exist, Vercel logs a deployment warning but does no harm — the file is treated as inert.

​

Step 3 — Land the wiring PR

# Install the Vite plugin (one new dep)
npm install --save @vercel/microfrontends --legacy-peer-deps

import { microfrontends } from '@vercel/microfrontends/experimental/vite';

// inside the plugins array:
microfrontends({
  // The Vite plugin auto-detects the application name from VERCEL_PROJECT_ID
  // matched against the Vercel project names in microfrontends.json.
  // No options needed for the basic case.
}),

{
  "scripts": {
    "mf:proxy": "microfrontends proxy --local-apps encoreos-app encoreos-public",
    "mf:port": "microfrontends port"
  }
}

npm run audit:microfrontends    # validate the config
npm run build                   # confirm Vite plugin doesn't break the build
npm run mf:proxy                # in one terminal
npm run dev                     # in another
# Visit the proxy URL printed by `mf:proxy` (typically http://localhost:3024)
# Try /, /auth, /pm/kiosk/test, /portal/login — all should resolve

• Update .github/workflows/build.yml to run npm run audit:microfrontends as a blocking step.
• Update .github/workflows/build.yml to set MFE_DISABLE_LOCAL_PROXY_REWRITE=1 so existing E2E tests that hit individual project URLs continue to work.
• Add TURBO_TOKEN / TURBO_TEAM GitHub Actions secrets if you also want Vercel Remote Cache active for the encoreos-public project (see docs/development/TURBOREPO_USAGE.md).

​

Step 4 — Preview soak

1. After the wiring PR merges, open a fresh PR (any small change). Vercel will build BOTH encoreos-app AND encoreos-public for the preview commit.
2. Visit the preview URL of encoreos-app. You should see:
   • / → main app (HR, etc.) — same as today.
   • /auth → routed to encoreos-public. Look for the small “M” badge on the deployment page (Vercel Microfrontends indicator).
   • /pm/kiosk/test → routed to encoreos-public.
3. Open the Vercel Toolbar on the preview, expand the Microfrontends Panel, and confirm the routing table matches microfrontends.json.
4. Run the smoke E2E suite against the preview:
   npm run test:e2e:smoke
   
   If any test asserts a hard navigation between /auth and any authenticated route, expect it to still pass but to take an extra ~200 ms (the cross-zone hard-navigation cost). If any test relies on shared client state across zones, it will fail — those tests need to be rewritten or marked skip-on-microfrontends.

​

Step 5 — Production cutover

1. Promote the soaked preview deployment to production via the Vercel dashboard’s “Promote to Production” button.
2. Watch Sentry for new error volume in the first 30 minutes — particularly:
   • Hydration mismatches (none expected; Vite SPA, no SSR).
   • Auth-redirect loops (the /auth zone now lives behind microfrontends path routing; verify useCurrentUser still works after the hard-nav from /auth → /).
   • PWA service worker registration errors (covered by ADR-017; both zones must agree on SW scope).
3. If anything looks off, hit Vercel Instant Rollback on the default application (encoreos-app). Microfrontends routing reverts to the previous microfrontends.json (which, before this whole rollout, was implicit — single app — so the old behavior is fully restored).

​

Local development

# Terminal 1: run the local proxy that knows about the routing config
npm run mf:proxy

# Terminal 2: run the dev server for the zone you're working on
npm run dev    # encoreos-app
# OR
npm run dev    # if you're working on encoreos-public, run the same; the
               # plugin auto-targets based on VERCEL_PROJECT_ID, defaulting to encoreos-app

# Visit the proxy URL printed in terminal 1 (typically http://localhost:3024)

​

Environment variable layout

​

Rollback plan

​

What this scaffolding does NOT solve

1. Cross-zone shared state. OrganizationProvider, QueryClientProvider, Sentry, Sonner, nuqs, and the PWA service worker all bootstrap per zone. A user moving between /auth and the authenticated app pays a cold cache penalty. Mitigations to evaluate at step 4: BroadcastChannel for cross-zone state sync, or accept the cold cache (the public→authenticated transition only happens at sign-in time anyway).
2. PWA scope. Each Vercel project generates its own service worker. Only one can install at scope /. ADR-017 (companion to this PR) defines the per-zone scope strategy: encoreos-app keeps scope: '/'; encoreos-public either uses sub-scopes (scope: '/portal/', etc.) or disables the SW for that zone entirely.
3. Dependency duplication. Each zone bundles its own React, Radix, Supabase client. For a 2-zone split this adds ~300 KB of duplicate vendor code on first hard-nav between zones. Acceptable for the proposed split (the public zone is a thin set of pages); not acceptable for a 12-zone split.
4. Cross-zone link prefetching. Vercel’s PrefetchCrossZoneLinks is Next.js only. Any prefetch-on-hover behavior we want has to be implemented manually using Chromium Speculation Rules, the same way Vercel.com does it.

​

See also

• MICROFRONTENDS_ACTIVATION_CHECKLIST.md — short pre-flight checklist (this runbook remains canonical)
• PERFORMANCE_BASELINE.md — bundle / Vitals baselines before cutover
• microfrontends.json (repo root) — the proposed routing
• scripts/audit/validate-microfrontends-config.ts
• docs/architecture/decisions/ADR-017-microfrontends-pwa-scoping.md
• docs/recommendations/DEV_VELOCITY_AND_ARCHITECTURE_PLAN_2026-04-22.md § 3 (deep review of Vercel Microfrontends) and § 5.5 (the proposed split) — lands via PR #137
• Vercel Microfrontends docs
• Vercel Microfrontends local dev
• vite.config.ts — the file the wiring PR will modify
• vercel.json — the file the wiring PR may modify (ignoreCommand may need to consider microfrontends.json changes)