Installation

Last updated

Source file

docs/foundations/installation.md

create-bw-app is the public BrightWeb scaffold for starting either a platform app or a standalone site.

Use the public CLI when you want a new project quickly without manual starter wiring.

Both templates generate normal Next.js App Router projects. After scaffolding, you work in the generated app like any other Next.js project, including the usual app/ route and page structure.

Generated apps also include local AI-agent handoff files in AGENTS.md, docs/ai/README.md, docs/ai/examples.md, and docs/ai/app-context.json so coding agents can orient themselves inside the scaffold without relying on repo-internal docs.

Quick start

Start the interactive scaffold:

Terminal
pnpm dlx create-bw-app

Common variants:

  • Show all options: pnpm dlx create-bw-app --help
  • Start from the site template directly: pnpm dlx create-bw-app --template site
  • Preconfigure a platform app and skip install: pnpm dlx create-bw-app --name client-portal --modules crm,marketing,projects --no-install
  • Use npm instead of pnpm: npm create bw-app@latest -- --template site

Choose the right template

  • Platform app: authenticated BrightWeb app shell with optional shared business modules such as CRM, Marketing, and Projects.
  • Site app: lighter standalone Next.js site starter without the full BrightWeb platform runtime.

If you are unsure, start with platform only when you need shared platform auth, shell, or module-backed product work. Otherwise choose site.

Immediate next steps

  1. From the parent directory where you want the new app to live, run pnpm dlx create-bw-app and choose the template.
  2. If creating a platform app, choose optional modules based on the product scope you want to validate right away.
  3. If you skipped install during scaffolding, change into the generated app directory and run your package manager install command.
  4. For platform apps, review config/brand.ts, config/modules.ts, and the generated .env.local, then fill in the real service values described in Environment and Services.
  5. Run the app and follow Validate Your Starter before you start customizing the generated routes.

Related