create-bw-app

Scaffold a new BrightWeb app from either the platform or site starter.

The package also installs the bw lifecycle CLI for generated apps.

Workspace usage

From the BrightWeb platform repo root:

pnpm create:client
pnpm create:client -- --help
pnpm create:client -- --template site

The workspace wrapper delegates to this package with workspace:* dependency wiring and BrightWeb-specific output rules.

Published usage

Once this package is published to npm:

pnpm dlx create-bw-app
pnpm dlx create-bw-app --template site
pnpm dlx create-bw-app update
npm create bw-app@latest

From a generated app, use bw to manage the machine-readable .brightweb/app-manifest.json contract:

bw add projects
bw upgrade
bw upgrade projects --through-migration 20260811121700_project_client_meta_preview.sql
bw doctor
bw admin create --email [email protected]

• bw add <moduleKey> resolves requirements, installs thin package mounts and module wiring, and appends migrations.
• bw upgrade [moduleKey] includes the existing managed update flow plus forward-only module migrations. For a staged database rollout, bw upgrade <moduleKey> --through-migration <filename> still updates packages and managed files but appends and records that module only through the named migration.
• Destructive migrations are held at the preceding safe boundary. After compatible code is deployed and affected data is backed up, apply a held migration with an explicit module-scoped bw upgrade <moduleKey> --include-destructive-migrations. A destructive --through-migration target also requires that opt-in.
• bw doctor checks package, config, scaffold, environment-name, migration, configured function-region, and deployed function-region consistency. App-owned scaffold files are preserved on upgrade; doctor warns when their recorded template baseline is outdated and their contents differ from the current template. Use bw diff, reconcile relevant changes, and verify behavior before recording the reviewed baseline with bw scaffold manage <path> followed by bw scaffold own <path> (neither replaces file contents). Live database objects, applied migrations, and authenticated permissions are explicitly NOT VERIFIED by doctor; a successful local result does not certify deployed behavior. Pass --deployment-url to inspect the deployed x-vercel-id; add --report to stamp the result in the app manifest.
• bw admin create --email <email> creates a passwordless Supabase Auth user, transactionally ensures its profile and admin assignment, then sends the Core Auth /reset-password flow. It always refuses when the project already has an admin (use the in-app admin role controls to add administrators) and never promotes an existing Auth user.
• All mutating commands support --dry-run.

Update existing apps

Run the updater from an existing generated app directory, or point it at one with --target-dir:

pnpm dlx create-bw-app update
pnpm dlx create-bw-app update --dry-run
pnpm dlx create-bw-app update --refresh-starters
pnpm dlx create-bw-app update --target-dir ./apps/client-portal

Current updater behavior:

• updates installed @brightweblabs/* packages only
• in published mode, resolves those @brightweblabs/* target versions from npm at update time
• fails the update if npm resolution fails unless you pass --allow-stale-fallback
• re-syncs managed BrightWeb config files such as next.config.ts, config/modules.ts, and config/shell.ts
• preserves app-owned shell customizations in the scaffolded config/shell.overrides.ts
• reports missing or drifted scaffold mounts and only rewrites them with --refresh-starters; tracked owned and skipped files remain protected, including managed config routes
• prints the follow-up install command unless --install is passed
• preserves unrelated third-party dependencies and app-owned product pages

Template behavior

• prompts for app type: platform or site
• prompts for project name
• prompts for optional platform modules: admin, crm, marketing, and projects
• accepts or prompts for the Supabase project region and writes the nearest verified Vercel Functions region to vercel.json
• leaves vercel.json valid but unpinned, with a commented setup placeholder in the generated runbook, when the Supabase region is absent or unknown
• prompts to install dependencies immediately
• copies a clean Next.js App Router starter template
• platform apps include BrightWeb auth, shell wiring, and optional direct package mounts
• generated route files are direct @brightweblabs/* re-exports or one-line exports from an app-owned dependency adapter such as Marketing's delivery handler composition
• platform apps in published mode also write supabase/config.toml, a CLI-ready flat supabase/migrations/ folder, supabase/module-registry.json, supabase/clients/<slug>/stack.json, and the resolved shared SQL migrations under supabase/modules/<module>/migrations
• site apps include a thin Next.js and Tailwind CSS shell with no default feature page or local component library
• writes package.json, next.config.ts, .gitignore, and README.md for both templates
• platform apps also write .env.local, AGENTS.md, docs/ai/README.md, docs/ai/examples.md, docs/ai/app-context.json, and generated config files for brand and module state
• site apps also write AGENTS.md, docs/ai/README.md, docs/ai/examples.md, and docs/ai/app-context.json for app-local AI handoff
• supports repo-local workspace:* wiring and future published dependency wiring
• writes .brightweb/app-manifest.json as the machine-authoritative scaffold and module record

Workspace mode extras

When this package runs in BrightWeb workspace mode, it can:

• write the new app under apps/<slug>
• keep internal dependencies on workspace:*
• create supabase/clients/<slug>/stack.json
• create a client-only migrations folder so database planning stays aligned with scaffolded modules

Platform mode always resolves to the Core + Admin database baseline. Selecting admin affects the Admin package mount and wiring, not whether the Admin database layer exists.

The scaffold records SUPABASE_PROJECT_REGION in .env.local and infrastructure metadata. Keep it aligned when replacing a Supabase project so bw doctor --deployment-url <url> can compare the current database location with the region observed from Vercel's x-vercel-id response header.

Related references

• packages/create-bw-app/src/generator.mjs
• packages/create-bw-app/src/constants.mjs
• packages/create-bw-app/template/base
• packages/create-bw-app/template/site/base
• packages/create-bw-app/template/modules
• packages/create-bw-app/template/supabase

Opt-in social media viewer

For a platform app with marketing enabled, first install a marketing release that exports social-media and withSocialMediaNavigation, then run:

bw setup social-media --dry-run
bw setup social-media

Use --target-dir <path> to select another app directory. Setup creates config/social-media-plan.json with an empty, neutral plan and the thin page at app/(shell)/marketing/social-media/page.tsx. All client copy belongs in that app-owned JSON; components, styles, validation, and interactions stay in marketing. No database or publishing service is created.

Setup appends navigation wiring to the standard app-owned config/shell.overrides.ts, which must declare export const shellRegistrationOverrides: ShellRegistrationOverrides = { ... };. Existing marketing overrides are composed through the shared helper:

import { withSocialMediaNavigation } from "@brightweblabs/module-marketing/registration";
shellRegistrationOverrides.marketing = withSocialMediaNavigation(shellRegistrationOverrides.marketing);

Custom shell export shapes require manual wiring before adopting the standard shape. Setup checks prerequisites and paths before writing and rejects symlinks on generated paths. Existing JSON and page files are never replaced, even when empty or customized; reruns preserve them. These files are not managed templates or refreshable starters, and bw update --refresh-starters preserves them and shell overrides. New marketing apps do not receive this feature until opted in.

File and compatibility safety

Lifecycle commands resolve the selected app root and reject symlinks or invalid file types beneath it before writing planned outputs. Root aliases are supported; concurrent filesystem edits are outside this preflight guarantee. App-owned brand, theme, shell override and social content seeds are preserved. The generated app context lists exact generated/scaffold paths, defaults unknown paths to app ownership, and shares its generated inventory with the CLI.

Upgrade refuses unknown migration cursors and uses standard semantic-version ranges. Module removal refuses surviving literal imports of the removed package before changing files; reconcile the app-owned dependents explicitly. This conservative scan is not a complete bundler analysis.

Forced re-adoption and module removal preserve exact-path owned and skipped decisions. Re-adding a module respects retained decisions; use bw scaffold manage after re-adding to reset a path deliberately. Every pending destructive migration requires opt-in, even after a previous destructive step was approved. Managed platform outputs share one renderer across scaffolding, add, remove, and update, with enforced ownership-inventory parity.