create-davbyte-mfe

Scaffold DavByte micro-frontends with Next.js. Cross-platform CLI for Windows, macOS, and Linux.

Designed for the DavByte Platform monorepo: MFEs mount at /apps/<slug> via the Cloudflare router Worker (no Next.js basePath), and auth uses shared/mfe + the HttpOnly auth_token cookie.

Usage

# From Platform root or apps/
pnpm dlx create-davbyte-mfe@latest <mfeName>
# or
npx create-davbyte-mfe@latest <mfeName>

Windows: If npm create fails with "not recognized", use npx create-davbyte-mfe@latest <mfeName> instead.

Options:

• --ci – Non-interactive: auto-assign port (3401–3499), overwrite if exists, Supabase=none. Still wires Platform files when run inside the monorepo.

Requirements

• Node.js 22+
• npm (or pnpm inside the Platform workspace)
• Platform workspace with shared (exports shared/mfe) for a buildable MFE

Generated Project

Each scaffolded project includes:

• TypeScript – Full TypeScript setup
• Next.js App Router – App Router + TypeScript (transpilePackages: ["shared"])
• Cloudflare – OpenNext Workers with preview / deploy; workers_dev and preview_urls are false (private; router service bindings only)
• Mount path – no Next basePath / assetPrefix. Leave NEXT_PUBLIC_MFE_MOUNT unset for standalone localhost:<port>; CI deploy sets /apps/<slug> for the router.
• Tailwind CSS – DavByte theme with company colors
• shadcn/ui – Bundled base-nova preset with lib/utils.ts, Button, and Card; dependencies resolved at scaffold time. In monorepos, install runs once at the workspace root via pnpm install. Add more components with pnpm dlx shadcn@latest add [component] (or npx outside a pnpm workspace).
• Auth – AuthProvider / useAuth / AuthGuard via verifyAuthWithCookie + handleAuthMe from shared/mfe; scope {kebab-slug}:user. Mobile shell (?host=mobile / ?mobile_token=) stays in-app on auth failure and mints a session via POST /api/auth/mobile-session.
• Mobile native tabs – useMobileShellTabs posts davbyte:mobile-shell-* to the parent webapp (not davbyte-mobile-bridge). icon is an Ionicons name. Do not render an HTML bottom bar when isMobileShellHost().
• Identity – mfe-info.json + lib/mfe-config.ts (MFE_NAME, MFE_SLUG, MFE_APP_SCOPE). Optional mobileTabs in mfe-info.json is documentation only; the runtime hook is the source of truth.
• Testing – Vitest with test and test:ci scripts, plus example tests

Dependencies (Next.js, React, Cloudflare, Tailwind, Vitest, Testing Library, etc.) are resolved from the npm registry when you scaffold — latest patch within the configured Next.js major, with React and related packages matched to Next peer requirements. Auto-fixable audit issues are applied with npm audit fix (or pnpm audit --fix in monorepos). Inside Platform, "shared": "workspace:*" is added automatically.

Monorepo behavior

In a pnpm workspace with an apps/ folder, the CLI always scaffolds to apps/<mfeName> — whether you run it from the repo root or from apps/. Dependencies install via pnpm install at the workspace root. If client/src/lib/mfe-config.ts exists, the MFE is autolinked with relative /apps/<slug> for all envs.

When router/wrangler.jsonc and .github/workflows/deploy-mfes.yml are present, the CLI also:

1. Adds router services[] + ROUTES (prod + staging)
2. Adds workflow_dispatch option + a Prepare env step (AUTH / OPS / PLATFORM + optional Supabase)
3. Optionally patches Auth supabaseProjectRegistry (+ types.ts Env for dedicated projects)

Prompts

Interactive runs inside Platform ask:

• Overwrite if the target directory exists
• Use Supabase? → none | central (Documents project) | dedicated (new project URL)

--ci skips prompts (Supabase=none).

Auth

• Token is read from the auth_token cookie (HttpOnly via GET /api/auth/me → handleAuthMe).
• App scope is {kebab-slug}:user (example: "My Cool App" → "my-cool-app:user").
• Browser verify uses getMfeBasePath() so API calls hit the MFE under the router mount, not the shell.
• The native/mobile shell iframe passes ?host=mobile and a one-shot ?mobile_token=. verifyAuthWithCookie POSTs that JWT to /api/auth/mobile-session (handleMobileSessionPost) and also sends Authorization: Bearer.
• Login redirect uses redirectToPlatformLogin from shared/mfe. On a mobile shell host (isMobileShellHost) that notifies the parent instead of navigating to website /login; AuthGuard shows “Couldn't open this app”.
• If you add authenticated app APIs later, wrap fetch with isSessionAuthFailure (401/403) and registerMfeSessionInvalidator so AuthGuard runs the same path.

Mobile native tabs

When this MFE is embedded in the Platform mobile webapp iframe, useMobileShellTabs (see lib/use-mobile-shell-tabs.ts) tells the parent which native bottom tabs to show:

• davbyte:mobile-shell-set-tabs / sync-tab / clear-tabs → parent → davbyte-mobile-bridge setTabs (1.20260917.0+)
• Parent → MFE: davbyte:mobile-shell-navigate-to

Do not import davbyte-mobile-bridge or call window.ReactNativeWebView from the MFE. Prefix tab ids with the slug (e.g. invoices:home) so they do not collide with platform home. Max 4 MFE tabs; icon values are Ionicons names (home-outline, settings-outline). The example in components/MobileApp.tsx announces Home / Settings and must not add a second HTML tab bar.

Environment

A .env.local file is created with AUTH / PLATFORM / OPS / mount (and placeholder SUPABASE_* when chosen). End-of-run console prints suggested api/auth/.dev.vars and GitHub secrets/vars.

After scaffold

The CLI prints suggested local .env / Auth .dev.vars and GitHub vars/secrets. For a dedicated Supabase project it also prints JWT signing setup steps. Link the MFE from admin when you create the app (as usual).