create-orb

Scaffolds a new project from the Orbit SaaS starter kit.

npm create orb@latest my-app
# or
npx create-orb my-app
# or
pnpm create orb my-app

What it does

1. Asks which optional features you want. Four y/n prompts:
   • Teams + per-team PBAC — nested role scope inside a workspace
   • Billing — Stripe subscriptions, webhooks, customer portal
   • File uploads — UploadThing-backed avatars/images
   • Waitlist — gated signups behind an allowlist
2. Clones the upstream Orbit repo at the chosen ref.
3. Runs a strip pass that removes any feature you said no to. It uses // +feature:<name> / // -feature:<name> fence markers inside source files plus a repo-root features.json manifest to know what to delete.
4. Optionally runs npm install.
5. Prints next steps.

Nothing is written until after you confirm the summary.

Flags

create-orb [<target>] [options]

  --from <url|path>          Template source. Git URL or local directory.
                             Default: upstream Orbit repo.
  --ref <branch>             Branch, tag, or commit to clone. Default: main.

  --teams=yes|no             Include per-team PBAC.
  --billing=yes|no           Include billing (Stripe).
  --billing-provider=stripe  Pick a billing provider. Only stripe today.
  --uploads=yes|no           Include file uploads (UploadThing).
  --waitlist=yes|no          Include the waitlist flow.

  --no-install               Skip `npm install` after scaffolding.
  -y, --yes                  Accept defaults for anything not given as a flag.
  -h, --help
  -v, --version

Env-var equivalents: ORBIT_TEMPLATE_SOURCE, ORBIT_TEMPLATE_REF.

Headless / CI example

create-orb ./out \
  --from ~/code/orbit \
  --teams=yes --billing=no --uploads=yes --waitlist=no \
  --no-install -y

How the strip works

Every optional feature declares itself in features.json at the root of the template:

{
  "features": {
    "teams": {
      "files": ["apps/api/src/teams/", "apps/api/src/interfaces/http/controllers/teams.controller.ts", ...],
      "envKeys": []
    }
  }
}

For each feature the user opts out of, the strip pass:

1. Deletes every files path recursively (directories or single files).
2. Walks the whole repo once and removes every line between // +feature:<name> and // -feature:<name> markers, inclusive. The walker skips node_modules/, .git/, build outputs, etc. This means contributors can add fences in new files without having to update features.json — the walk is the source of truth.
3. Scrubs every envKeys entry from apps/*/.env.example.

Three fence syntaxes are accepted so the same markers work across TS, TSX, Prisma, and JSX contexts:

// +feature:teams
// -feature:teams

/* +feature:teams */
/* -feature:teams */

{/* +feature:teams */}
{/* -feature:teams */}

Fences must live on their own line, paired, at the same nesting. Nested SAME-name fences are disallowed; nested DIFFERENT-name fences are fine.

Development

# in the Orbit monorepo
cd packages/create-orb
npm run dev -- ./tmp-app --from /Users/you/code/orbit -y --no-install

--from accepts a local path for fast dev loops (no git round-trip).