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 mode: auto-assign port (3401–3499), overwrite if exists. Useful for CI/automation.

Requirements

• Node.js 20+
• 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 – NEXT_PUBLIC_MFE_MOUNT=/apps/<kebab-slug> for getMfeBasePath(); no Next basePath / assetPrefix
• 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
• Identity – mfe-info.json + lib/mfe-config.ts (MFE_NAME, MFE_SLUG, MFE_APP_SCOPE)
• 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 router /apps/<slug> URLs (not public MFE workers.dev hosts).

Prompts

When scaffolding interactively, you are only prompted if port allocation fails or the target directory already exists.

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.

Environment

A .env.local file is created with:

AUTH_API_URL="http://localhost:3201/api/auth"
NEXT_PUBLIC_AUTH_API_URL="http://localhost:3201/api/auth"
NEXT_PUBLIC_MFE_MOUNT="/apps/<slug>"
NEXT_PUBLIC_PLATFORM_URL="http://localhost:3111"

After scaffold (Platform checklist)

1. Router — add ROUTES + service binding in router/wrangler.jsonc for /apps/<slug>
2. Auth — register app in supabase-exchange / JWKS registry if the MFE uses Supabase
3. Operations — app_definitions + subscription scope
4. Secrets — set Worker secrets (AUTH_API_URL, etc.); MFE is not public on workers.dev
5. Client — confirm autolink entry in client/src/lib/mfe-config.ts (MFE_APPS)