pnpm dlx @clubedge/create-clubedge-app my-app

Why create-clubedge-app

Copying a starter is easy; living with it is not. You delete the services you don't use by hand, and once you've changed the code, every later improvement to the starter has to be copied over by hand too.

create-clubedge-app generates a project from a tested release of Clubedge Starter with only the modules you choose. A module you leave out is removed completely: its package, its provider SDK, its environment variables, its documentation, and its lockfile entries. The project records exactly what it was generated from, so later the CLI can add a module, remove one, or upgrade to a newer Starter release by merging the change into your code. Files you never touched are updated; your edits are kept.

Every CLI release is pinned to one Starter release and verified against it, so the same command always produces the same project.

Quick start

You need Node.js 22.12 or newer and pnpm 10.9.0 or newer. Git is used for the default repository initialization.

pnpm dlx @clubedge/create-clubedge-app my-app
cd my-app
pnpm dev

Or start it with npm: npx @clubedge/create-clubedge-app my-app. The generated project is a pnpm workspace, so dependencies are installed with pnpm either way; the CLI falls back to corepack pnpm when pnpm is not on your path. Without a destination, the CLI asks where to create the project.

The generated project includes apps/web/.env.local, created from the example and pointing at the local services you chose. Its SETUP.md describes every variable and provider. The root route is a landing page named after your project, and the dashboard is at /dashboard.

The default Starter release ships inside the CLI package, so GitHub is only contacted when you pass --ref. Internet access is needed to install dependencies.

Choosing a framework

The Starter ships the same application for two React frameworks. Next.js is the default; pick TanStack Start with --framework, or choose interactively:

pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start

Either way, the app lives in apps/web and uses the same shared packages, so the project layout, root scripts, and Docker commands are identical.

Choosing modules

Authentication, file storage, caching, email, payments, background jobs, observability, local infrastructure, and deployment are modules. Each has a default, and anything you leave out is removed completely. The Starter's clubedge.template.json defines the modules, so a module a newer Starter adds gets its --<module> flag without a CLI change; --help lists the modules of the Starter this CLI release creates.

# Only the monorepo, UI, database, and tooling
pnpm dlx @clubedge/create-clubedge-app my-app --auth none --storage none --cache memory --email none

# A SaaS starting point: your own auth, payments, and background jobs, no Docker needed
pnpm dlx @clubedge/create-clubedge-app my-app --auth better-auth --payments stripe --jobs pg-boss --infra local

Interactive runs ask whether to customize these after the framework question.

Options

Usage:
  pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
  pnpm dlx @clubedge/create-clubedge-app add [module option]...  (inside a project)
  pnpm dlx @clubedge/create-clubedge-app remove [module]...      (inside a project)
  pnpm dlx @clubedge/create-clubedge-app upgrade [--ref <tag>]   (inside a project)

Options:
  --framework <id>        App framework, such as next or tanstack-start
  --<module> <option>     A module option, such as --auth none; the Starter lists its modules
  --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
                          (upgrade: the Starter to upgrade to)
  --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
  --dry-run               Show what would be created or changed without writing anything
  --force                 add/remove: change a project with uncommitted changes or without Git
  -y, --yes               Accept defaults and never prompt (default directory: my-app)
  --no-install            Skip dependency installation
  --no-git                Skip Git repository initialization
  -h, --help              Show this help
  -v, --version           Show the CLI version

The target directory must be empty or not exist. The CLI never deletes or overwrites existing files, and if scaffolding fails it removes whatever it wrote, so a failed run leaves nothing behind.

# Preview the files and edits without writing anything
pnpm dlx @clubedge/create-clubedge-app my-app --dry-run

# Non-interactive, for scripts and CI
pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstack-start

# Try an unreleased Starter change
pnpm dlx @clubedge/create-clubedge-app my-app --ref main

# Reproduce a specific Starter release or commit
pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.14.0
pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>

# Test local Starter changes before releasing them
pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter

Change an existing project

Inside a project created by the CLI, add and remove change modules, and upgrade moves the project to a newer Starter release. Projects from Starter v0.8.0 on have a clubedge script, so pnpm clubedge add cache redis works too. Without a module or option, add and remove ask for them:

pnpm clubedge add                                            # choose a module and option from a list
pnpm dlx @clubedge/create-clubedge-app add cache redis      # or switch: add auth better-auth
pnpm dlx @clubedge/create-clubedge-app remove storage
pnpm clubedge add email resend payments stripe              # several modules as one change
pnpm clubedge remove storage payments
pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.14.0 # or a specific tag, branch, or commit

The CLI renders the project twice, from the Starter commit and modules recorded in your package.json and from the new state, and merges the difference into your project. The new state has other modules for add and remove, and the newer Starter with the same modules for upgrade. Modules a newer Starter introduces start as none where possible, so an upgrade never adds a service on its own.

• Files you never changed are updated, added, or deleted.
• Files you changed keep your edits. Where the module change touches the same lines, the file gets conflict markers (<<<<<<< yours ... >>>>>>> clubedge) for you to resolve.
• Your own files are never touched.
• apps/web/.env.local keeps your values. Values still at their generated defaults follow the new selection, and new variables are added.
• pnpm-lock.yaml is replaced if you never changed your dependencies; otherwise pnpm install reconciles it.

Several modules in one command are applied as one change, and their requirements are checked together, so add auth supabase storage supabase works even though Supabase Storage needs Supabase Auth. When lines conflict, the CLI lists each file with its number of conflict blocks. Before an upgrade, it lists the Starter releases it crosses with the sections of their release notes, such as v0.13.0 Observability, Tests, Also.

The project must be a Git repository without uncommitted changes, so you can review the result with git diff and undo it. Pass --force to skip this check. Add --no-install to skip pnpm install. Afterward, run pnpm db:migrate and pnpm check:services if the change added tables or services.

Check a project

Two read-only commands help you keep a project healthy:

pnpm clubedge status    # Starter release, modules, Git state, and whether a newer Starter exists
pnpm clubedge doctor    # Node.js, pnpm, dependencies, lockfile, env file, and pnpm check:services

status ends with the command to run next, such as pnpm clubedge upgrade when a newer Starter release is available; it asks npm for the newest CLI and still works offline. doctor checks that Node.js and pnpm meet the project's versions, that dependencies are installed, that pnpm-lock.yaml matches every package.json, and that apps/web/.env.local has every variable in .env.example, then runs pnpm check:services (skip it with --no-services). It exits with an error when a check fails, so it also works in CI.

Version relationship

Each CLI release is tested against one specific Starter release:

create-clubedge-app v0.16.0
        |
        v
Clubedge Starter v0.14.0
commit 2219a21c2eb237b7d8ee004ea8bbeb098b70106e

The current relationship is:

This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter main.

The v0.14.0 tag is expected to resolve to commit 2219a21c2eb237b7d8ee004ea8bbeb098b70106e. The CLI verifies this before scaffolding with the default reference and fails rather than silently using a moved tag.

When the Starter changes, its maintainers first publish a new versioned release, such as v0.14.0. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.

Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in package.json and README.md.

How it works

Each CLI release bundles one Starter release. When the release is built, scripts/bundle-template.mjs clones the pinned Starter tag, verifies that it resolves to the pinned commit, and copies its tracked files into the package (template/ and template.lock.json). Running the CLI then needs no GitHub access for the default Starter.

The Starter describes itself in clubedge.template.json: its app directory, site config, environment files, Docker image name, and files that stay out of generated projects. Schema 2 manifests also list each framework's app directory, environment example, and Dockerfile. The CLI moves the selected framework's app to apps/web (renaming its package to @clubedge/web), moves its environment example and Dockerfile to the project root, leaves the other frameworks out, and removes their entries from pnpm-lock.yaml so pnpm install --frozen-lockfile keeps working. Schema 3 adds modules: for each option, the workspace packages it uses, the files it owns, the variant files that replace defaults, the root package.json scripts it sets, and the options it requires. Files listed under conditional contain clubedge:if <condition> / clubedge:end blocks (in #, //, <!-- -->, or JSX comments) that the CLI keeps or drops for the selection, always removing the markers; clubedge:if starter-repository marks sections for Starter maintainers only. The CLI refuses a Starter whose manifest schema is newer than it understands and asks you to update. Starters before v0.3.0 have no manifest and use the previous layout.

The CLI first builds a plan (the files to copy and the edits to make), which --dry-run prints, and then applies it. The source is organized the same way:

src/
  cli/      argument parsing and terminal output
  core/     manifest, template sources, customizations, planning, merging, and execution
  steps/    Git initialization and dependency installation
  utils/    file listing and copying, processes, and naming

Documentation

Development

corepack enable
pnpm install
pnpm check            # type-check sources and tests
pnpm test             # unit and scaffolding tests
pnpm build            # compile src/ to dist/
node ./bin/create.mjs my-app --template-dir ../clubedge-starter --dry-run

Without a bundled template, a local build downloads the pinned Starter release from GitHub and verifies its commit. Run pnpm bundle-template to bundle it, or pnpm bundle-template --from ../clubedge-starter to bundle a local checkout.

CI packs the CLI with npm pack, scaffolds clean projects from the packed tarball, installs their dependencies, runs linting, typechecking, unit tests, browser checks, and a production build, then starts each generated app and checks the landing page, sign-up page, dashboard, health endpoint, logo, and favicon. It also adds and removes modules in an existing project and upgrades a project from an older Starter. A scheduled, non-blocking compatibility job checks Starter main.

Release workflow

Starter maintainers

1. Make and validate changes in clubedge-starter.
2. Run lint, typecheck, unit tests, browser tests, and production build.
3. Update the Starter package versions.
4. Commit main, create a release tag such as v0.14.0, and publish the Starter release.

CLI maintainers

1. Set clubedge.starterRef and clubedge.starterCommit in package.json to the new tested Starter tag, and bump version.
2. Update the version relationship table and changelog.
3. Generate a clean project from that exact tag.
4. Run install, lint, typecheck, unit tests, browser tests, production build, and runtime smoke checks.
5. Publish a new CLI version only after the generated-project verification passes.

The required CI job always tests the pinned default. The scheduled compatibility job tests Starter main early, but unreleased Starter changes must not change the stable CLI default.

Roadmap

Each phase ends with a Starter release and a CLI release pinned to it. The full plan is in ROADMAP.md.

Community

• Issues for problems creating, changing, or upgrading a project.
• Clubedge Starter issues for problems in the generated application itself.
• Pull requests are welcome; start with CONTRIBUTING.md.
• Security problems go through the private process in SECURITY.md, not public issues.

Everyone taking part is expected to follow the code of conduct.

License

Copyright 2026 Clubedge Digital Systems. Licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.