@clubedge/create-clubedge-app 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.7.0
+
+- Default to Starter `v0.7.0`, which adds `--infra local`: PostgreSQL through PGlite and a local folder for files, so `pnpm dev` runs with nothing installed.
+- Remove optional peer links to packages that only left-out modules installed, so generated projects no longer install them. For example, a project without `--infra local` no longer installs PGlite through drizzle-orm, and a project without Better Auth no longer installs its optional peers.
+
+## 0.6.0
+
+- Default to Starter `v0.6.0`, which adds the local infrastructure module and `pnpm check:services`.
+- Add `--infra docker|supabase|none`: Docker Compose services, the Supabase CLI's local stack, or no local services. The environment examples point at the chosen services.
+- Let module options set root `package.json` scripts; scripts that only left-out options define are removed, so each project gets the `infra:*` scripts for its option.
+- Fix Starter tag verification on Windows, where an annotated tag resolved to the tag object instead of its commit and scaffolding a downloaded Starter release failed.
+
 ## 0.5.0
 
 - Default to Starter `v0.5.0`, which adds optional modules, Better Auth, and template schema 3.

package/README.md

@@ -12,27 +12,27 @@ The CLI downloads a tested Starter release, names the generated project, creates
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.5.0
+create-clubedge-app v0.7.0
         |
         v
-Clubedge Starter v0.5.0
-commit d9375c2c3b520323ff0255ef8ec65da19251c3c1
+Clubedge Starter v0.7.0
+commit 3b8114760b8151c2538b57c06620ff2b884f2d56
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.5.0` | `clubedge-starter@v0.5.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.7.0` | `clubedge-starter@v0.7.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.5.0` tag is expected to resolve to commit
-`d9375c2c3b520323ff0255ef8ec65da19251c3c1`. The CLI verifies this before
+The `v0.7.0` tag is expected to resolve to commit
+`3b8114760b8151c2538b57c06620ff2b884f2d56`. 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.5.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.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.7.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.
 
 ## Requirements
 
@@ -92,6 +92,7 @@ Authentication, file storage, and caching are modules. Each has a default, and a
 | `--auth`    | `supabase`, `better-auth`, `none`          | `supabase` |
 | `--storage` | `s3`, `supabase` (needs Supabase Auth), `none` | `s3`   |
 | `--cache`   | `redis` (falls back to memory without `REDIS_URL`), `memory` | `redis` |
+| `--infra`   | `docker` (Docker Compose), `supabase` (Supabase CLI), `local` (no Docker: PGlite and a local folder), `none` | `docker` |
 
 ```sh
 # Only the monorepo, UI, database, and tooling
@@ -109,6 +110,7 @@ Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 --auth <id>             Authentication: supabase (default), better-auth, or none
 --storage <id>          File storage: s3 (default), supabase, or none
 --cache <id>            Cache and rate limits: redis (default) or memory
+--infra <id>            Local services: docker (default), supabase, local, or none
 --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
 --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
 --dry-run               Show what would be created without writing anything
@@ -134,7 +136,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 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.5.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.7.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -145,7 +147,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter
 
 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, 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 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:
 
@@ -179,7 +181,7 @@ CI packs the CLI with `npm pack`, scaffolds a clean project from the packed tarb
 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.5.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.7.0`, and publish the Starter release.
 
 ### CLI maintainers
 

package/dist/cli/args.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 /** Module flags the CLI accepts. Which options exist is up to the Starter's manifest. */
-export const MODULE_FLAGS = ["auth", "storage", "cache"];
+export const MODULE_FLAGS = ["auth", "storage", "cache", "infra"];
 export class UsageError extends Error {
     name = "UsageError";
 }
@@ -17,6 +17,7 @@ export function parseCliArgs(argv) {
                 auth: { type: "string" },
                 storage: { type: "string" },
                 cache: { type: "string" },
+                infra: { type: "string" },
                 ref: { type: "string" },
                 "template-dir": { type: "string" },
                 install: { type: "boolean", default: true },

package/dist/cli/ui.js

@@ -67,6 +67,7 @@ Options:
   --auth <id>             Authentication: supabase (default), better-auth, or none
   --storage <id>          File storage: s3 (default), supabase, or none
   --cache <id>            Cache and rate limits: redis (default) or memory
+  --infra <id>            Local services: docker (default), supabase, local, or none
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
   --template-dir <path>   Scaffold from a local Starter checkout (for Starter development)
   --dry-run               Show what would be created without writing anything

package/dist/core/customize.js

@@ -1,9 +1,16 @@
 // Pure text transforms applied to template files. Keeping them free of I/O makes each one easy
 // to test and lets --dry-run describe them without touching the disk.
+import { pruneOptionalPeers } from "./lockfile-peers.js";
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
-export function customizeRootManifest(source, { packageName }, provenance, dockerImage) {
+export function customizeRootManifest(source, { packageName }, provenance, dockerImage, scripts = { set: {}, remove: [] }) {
     const manifest = JSON.parse(source);
     manifest.name = packageName;
+    if (manifest.scripts && typeof manifest.scripts === "object") {
+        for (const name of scripts.remove)
+            delete manifest.scripts[name];
+    }
+    if (Object.keys(scripts.set).length)
+        manifest.scripts = { ...manifest.scripts, ...scripts.set };
     manifest.clubedge = {
         cliVersion: provenance.cliVersion,
         starterRepository: provenance.starterRepository,
@@ -69,7 +76,9 @@ export function customizeAppManifest(source, appPackage) {
 /**
  * Keeps pnpm-lock.yaml in step with the selected framework so `pnpm install --frozen-lockfile`
  * works. Importers are keyed by workspace path at two-space indentation; package entries that
- * are no longer used are harmless, and pnpm prunes them on the next lockfile update.
+ * are no longer used are harmless, and pnpm prunes them on the next lockfile update. Optional
+ * peer links to packages that only left-out importers installed are removed, so those packages
+ * are not installed either.
  */
 export function customizeLockfile(source, { remove, rename, removeDependencies = [] }) {
     const output = [];
@@ -129,7 +138,7 @@ export function customizeLockfile(source, { remove, rename, removeDependencies =
         skippingDependency = false;
         output.push(line);
     }
-    return output.join("\n");
+    return pruneOptionalPeers(output.join("\n"));
 }
 export class ConditionalError extends Error {
     name = "ConditionalError";

package/dist/core/lockfile-peers.js

@@ -0,0 +1,174 @@
+// pnpm links a package's optional peer dependency whenever that peer is installed anywhere in the
+// workspace, and records the link in lockfile keys: drizzle-orm@0.45.4(@electric-sql/pglite@0.5.8).
+// When a left-out workspace package was the only reason the peer was installed, the link would
+// keep installing it, so these helpers remove such links from the lockfile.
+function unquote(text) {
+    return text.replace(/^(['"])(.*)\1$/, "$2");
+}
+/** "drizzle-orm@0.45.4(pglite@0.5.8)" -> "drizzle-orm@0.45.4"; "0.45.4(x@1)" -> "0.45.4". */
+function withoutSuffix(text) {
+    const start = text.indexOf("(");
+    return start === -1 ? text : text.slice(0, start);
+}
+function parse(source) {
+    const roots = [];
+    const optionalPeers = new Map();
+    const snapshots = new Map();
+    let section = "";
+    let key = "";
+    let group = "";
+    let entry = "";
+    for (const line of source.split("\n")) {
+        if (/^\S/.test(line)) {
+            section = line.replace(/:.*$/, "");
+            continue;
+        }
+        const keyMatch = /^ {2}(\S.*?):(?: \{\})?$/.exec(line);
+        if (keyMatch) {
+            key = unquote(keyMatch[1]);
+            group = entry = "";
+            if (section === "snapshots")
+                snapshots.set(key, snapshots.get(key) ?? []);
+            continue;
+        }
+        const groupMatch = /^ {4}(\S+):$/.exec(line);
+        if (groupMatch) {
+            group = groupMatch[1];
+            entry = "";
+            continue;
+        }
+        const entryMatch = /^ {6}(\S.*?):(?: (.*))?$/.exec(line);
+        if (entryMatch) {
+            entry = unquote(entryMatch[1]);
+            const value = entryMatch[2] ? unquote(entryMatch[2]) : "";
+            if (section === "snapshots" && (group === "dependencies" || group === "optionalDependencies")) {
+                snapshots.get(key).push({ name: entry, ref: value });
+            }
+            continue;
+        }
+        const fieldMatch = /^ {8}(\S+): (.*)$/.exec(line);
+        if (!fieldMatch)
+            continue;
+        const [, field, value] = fieldMatch;
+        if (section === "importers" && field === "version")
+            roots.push(`${entry}@${unquote(value)}`);
+        if (section === "packages" && group === "peerDependenciesMeta" && field === "optional" && value === "true") {
+            const peers = optionalPeers.get(key) ?? new Set();
+            peers.add(entry);
+            optionalPeers.set(key, peers);
+        }
+    }
+    return { roots, optionalPeers, snapshots };
+}
+/**
+ * Finds optional peers that only optional-peer links keep installed: packages that no importer
+ * reaches through regular or required dependencies. Returns them as "name@version".
+ */
+export function findUnneededOptionalPeers(source) {
+    const { roots, optionalPeers, snapshots } = parse(source);
+    const reached = new Set();
+    const peerLinks = new Set();
+    const queue = roots.filter((key) => snapshots.has(key));
+    while (queue.length) {
+        const key = queue.pop();
+        if (reached.has(key))
+            continue;
+        reached.add(key);
+        const peers = optionalPeers.get(withoutSuffix(key));
+        for (const { name, ref } of snapshots.get(key) ?? []) {
+            if (peers?.has(name)) {
+                peerLinks.add(`${name}@${withoutSuffix(ref)}`);
+                continue;
+            }
+            const target = `${name}@${ref}`;
+            if (snapshots.has(target))
+                queue.push(target);
+        }
+    }
+    const reachedPackages = new Set([...reached].map(withoutSuffix));
+    return [...peerLinks].filter((peer) => !reachedPackages.has(peer)).sort();
+}
+/** Removes every "(peer)" or "(peer(...))" segment from lockfile keys and versions. */
+function removeSuffixSegments(text, peer) {
+    const marker = `(${peer}`;
+    let result = "";
+    let index = 0;
+    for (let found = text.indexOf(marker); found !== -1; found = text.indexOf(marker, index)) {
+        const next = text[found + marker.length];
+        if (next !== ")" && next !== "(") {
+            // A different package whose name merely starts with this one.
+            result += text.slice(index, found + marker.length);
+            index = found + marker.length;
+            continue;
+        }
+        let depth = 0;
+        let end = found;
+        for (; end < text.length; end++) {
+            if (text[end] === "(")
+                depth++;
+            else if (text[end] === ")" && --depth === 0)
+                break;
+        }
+        result += text.slice(index, found);
+        index = end + 1;
+    }
+    return result + text.slice(index);
+}
+/**
+ * Drops optional-peer links to packages nothing else installs (see findUnneededOptionalPeers),
+ * so `pnpm install --frozen-lockfile` no longer installs them. Snapshot entries that become
+ * identical are merged.
+ */
+export function pruneOptionalPeers(source) {
+    const peers = findUnneededOptionalPeers(source);
+    if (!peers.length)
+        return source;
+    let text = source;
+    for (const peer of peers)
+        text = removeSuffixSegments(text, peer);
+    const output = [];
+    const seenKeys = new Set();
+    let section = "";
+    let skippingEntry = false;
+    let pendingGroup = null;
+    for (const line of text.split("\n")) {
+        if (/^\S/.test(line)) {
+            section = line.replace(/:.*$/, "");
+            skippingEntry = false;
+            pendingGroup = null;
+            output.push(line);
+            continue;
+        }
+        if (section !== "snapshots") {
+            output.push(line);
+            continue;
+        }
+        const keyMatch = /^ {2}(\S.*?):(?: \{\})?$/.exec(line);
+        if (keyMatch) {
+            pendingGroup = null;
+            // Removing a link can make two snapshot keys identical; keep the first entry.
+            skippingEntry = seenKeys.has(keyMatch[1]);
+            seenKeys.add(keyMatch[1]);
+            if (!skippingEntry)
+                output.push(line);
+            continue;
+        }
+        if (skippingEntry)
+            continue;
+        if (/^ {4}\S+:$/.test(line)) {
+            // Held until the group gets an entry, so a group whose only entry was removed disappears.
+            pendingGroup = line;
+            continue;
+        }
+        const dependency = /^ {6}(\S.*?): (.*)$/.exec(line);
+        if (dependency && peers.includes(`${unquote(dependency[1])}@${withoutSuffix(unquote(dependency[2]))}`)) {
+            continue;
+        }
+        if (pendingGroup !== null && line.trim() !== "") {
+            output.push(pendingGroup);
+            pendingGroup = null;
+        }
+        output.push(line);
+    }
+    return output.join("\n");
+}

package/dist/core/manifest.js

@@ -102,6 +102,7 @@ function parseModules(value) {
                 files: optionalStringArray(option, "files", optionPrefix),
                 replace: optionalStringRecord(option, "replace", optionPrefix),
                 requires: parseRequires(option.requires, optionPrefix),
+                scripts: optionalStringRecord(option, "scripts", optionPrefix),
             };
         }
         const defaultOption = requireString(entry, "default", prefix);

package/dist/core/plan.js

@@ -97,8 +97,22 @@ function resolveModuleFiles(manifest, selection) {
             }
         }
     }
+    // Selected options set their scripts; scripts only left-out options define are removed.
+    const scripts = { set: {}, remove: [] };
+    const offeredScripts = new Set();
+    for (const [id, module] of Object.entries(manifest.modules)) {
+        for (const [optionId, option] of Object.entries(module.options)) {
+            for (const [name, command] of Object.entries(option.scripts)) {
+                offeredScripts.add(name);
+                if (selection[id] === optionId)
+                    scripts.set[name] = command;
+            }
+        }
+    }
+    scripts.remove = [...offeredScripts].filter((name) => !(name in scripts.set));
     const removedPackages = [...offeredPackages].filter(([name]) => !usedPackages.has(name));
     return {
+        scripts,
         removedPackageNames: removedPackages.map(([name]) => name),
         removedPackageDirectories: removedPackages.map(([, directory]) => directory),
         replacedTargets: new Set(replacements.values()),
@@ -165,7 +179,7 @@ export function createPlan(input) {
         edits.push({
             path: "package.json",
             description: `Name the package "${identity.packageName}" and record its origin`,
-            apply: (text) => customizeRootManifest(text, identity, provenance, manifest.dockerImage),
+            apply: (text) => customizeRootManifest(text, identity, provenance, manifest.dockerImage, moduleFiles.scripts),
         });
     }
     const appManifest = `${manifest.app}/package.json`;

package/dist/core/source.js

@@ -50,15 +50,18 @@ export async function readDirectoryTemplate(directory) {
 }
 /** Resolves a tag to its commit with `git ls-remote`, following annotated tags. */
 export async function resolveTagCommit(repository, tag) {
-    const output = await runCapture("git", [
-        "ls-remote",
-        `https://github.com/${repository}.git`,
-        `refs/tags/${tag}^{}`,
-        `refs/tags/${tag}`,
-    ]);
-    const lines = output.split("\n").map((line) => line.split(/\s+/));
-    const peeled = lines.find(([, ref]) => ref?.endsWith("^{}"));
-    return (peeled ?? lines[0])?.[0] || undefined;
+    // List every tag rather than passing a `refs/tags/<tag>^{}` pattern: on Windows the command
+    // runs through cmd.exe, which strips `^`, so the peeled ref would never match.
+    const output = await runCapture("git", ["ls-remote", "--tags", `https://github.com/${repository}.git`]);
+    return pickTagCommit(output, tag);
+}
+/** Picks a tag's commit from `git ls-remote` output, preferring the peeled ref of an annotated tag. */
+export function pickTagCommit(output, tag) {
+    const refs = new Map(output
+        .split("\n")
+        .map((line) => line.trim().split(/\s+/))
+        .map(([id, ref]) => [ref, id]));
+    return refs.get(`refs/tags/${tag}^{}`) ?? refs.get(`refs/tags/${tag}`);
 }
 export async function downloadGitHubTemplate(ref, { repository = starterPin.starterRepository, expectedCommit } = {}) {
     if (expectedCommit) {

package/dist/index.js

@@ -61,7 +61,7 @@ async function chooseModules(manifest, requested, interactive) {
     if (!interactive || unasked.length === 0)
         return requested;
     const customize = await confirm({
-        message: "Customize the included services (auth, storage, cache)?",
+        message: "Customize the included services (auth, storage, cache, local infrastructure)?",
         initialValue: false,
     });
     if (isCancel(customize))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.5.0",
-    "starterCommit": "d9375c2c3b520323ff0255ef8ec65da19251c3c1"
+    "starterRef": "v0.7.0",
+    "starterCommit": "3b8114760b8151c2538b57c06620ff2b884f2d56"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.env.example

@@ -1,12 +1,20 @@
 NODE_ENV=development
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 
-# Supabase PostgreSQL: use the transaction pooler with prepare disabled (configured in packages/db).
-DATABASE_URL=postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
+# Supabase PostgreSQL: use the transaction pooler with prepare disabled (configured in packages/db). # clubedge:only infra=none
+DATABASE_URL=postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres # clubedge:only infra=none
+# Local Supabase database, started by pnpm infra:up. # clubedge:only infra=supabase
+DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres # clubedge:only infra=supabase
+# Local PostgreSQL from docker-compose.dev.yml, started by pnpm infra:up. # clubedge:only infra=docker
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app # clubedge:only infra=docker
+# Local PostgreSQL (PGlite) that pnpm dev starts; no Docker needed. # clubedge:only infra=local
+DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5433/postgres # clubedge:only infra=local
 
 # clubedge:if auth=supabase
 # Supabase Auth (publishable key only; never put a service role key in the browser)
-NEXT_PUBLIC_SUPABASE_URL=
+NEXT_PUBLIC_SUPABASE_URL= # clubedge:only infra!=supabase
+# Local Supabase Auth. pnpm infra:status prints the publishable key to copy below. # clubedge:only infra=supabase
+NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321 # clubedge:only infra=supabase
 NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
 # clubedge:end
 
@@ -19,20 +27,30 @@ BETTER_AUTH_SECRET=
 # clubedge:if cache=redis
 # Optional cache and rate limits (Redis protocol; rediss:// enables TLS). Without it, both use
 # process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
-REDIS_URL=
+REDIS_URL= # clubedge:only infra!=docker
+REDIS_URL=redis://localhost:6379 # clubedge:only infra=docker
 # clubedge:end
 
 # clubedge:if storage=s3
 # S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
-STORAGE_BUCKET=
-STORAGE_REGION=auto
-STORAGE_ENDPOINT=
-STORAGE_ACCESS_KEY_ID=
-STORAGE_SECRET_ACCESS_KEY=
+STORAGE_BUCKET= # clubedge:only infra!=docker
+STORAGE_REGION=auto # clubedge:only infra!=docker
+STORAGE_ENDPOINT= # clubedge:only infra!=docker
+STORAGE_ACCESS_KEY_ID= # clubedge:only infra!=docker
+STORAGE_SECRET_ACCESS_KEY= # clubedge:only infra!=docker
+# Local S3-compatible storage from docker-compose.dev.yml; it accepts any credentials. # clubedge:only infra=docker
+STORAGE_BUCKET=app # clubedge:only infra=docker
+STORAGE_REGION=us-east-1 # clubedge:only infra=docker
+STORAGE_ENDPOINT=http://localhost:9090 # clubedge:only infra=docker
+STORAGE_ACCESS_KEY_ID=local # clubedge:only infra=docker
+STORAGE_SECRET_ACCESS_KEY=local-secret # clubedge:only infra=docker
 STORAGE_PUBLIC_URL=
+# Without an S3 service, files are stored in this folder (relative to the app). # clubedge:only infra=local
+STORAGE_DIRECTORY=../../.data/storage # clubedge:only infra=local
 # clubedge:end
 
 # clubedge:if storage=supabase
 # Supabase Storage bucket, accessed with the signed-in user's Supabase session
-SUPABASE_STORAGE_BUCKET=
+SUPABASE_STORAGE_BUCKET= # clubedge:only infra!=supabase
+SUPABASE_STORAGE_BUCKET=app # clubedge:only infra=supabase
 # clubedge:end

package/template/README.md

@@ -93,7 +93,41 @@ macOS/Linux:
 cp .env.example apps/web/.env.local
 ```
 
-Set `DATABASE_URL` in `apps/web/.env.local`, then start the app. [SETUP.md](SETUP.md) describes every variable and provider.
+<!-- clubedge:if infra=docker -->
+
+Start PostgreSQL and the other local services with Docker, apply the migrations, and check that the app can reach every service. The example environment already points at them.
+
+```sh
+pnpm infra:up
+pnpm db:migrate
+pnpm check:services
+```
+
+<!-- clubedge:end -->
+<!-- clubedge:if infra=supabase -->
+
+Start the local Supabase stack (it needs Docker), copy the publishable key that `pnpm infra:status` prints into `apps/web/.env.local`, and apply the migrations.
+
+```sh
+pnpm infra:up
+pnpm infra:status
+pnpm db:migrate
+pnpm check:services
+```
+
+<!-- clubedge:end -->
+<!-- clubedge:if infra=local -->
+
+Nothing else to install: `pnpm dev` starts a local PostgreSQL database (PGlite, stored in `.data/`) next to the app and applies the migrations. Files go to a local folder until you configure object storage.
+
+<!-- clubedge:end -->
+<!-- clubedge:if infra=none -->
+
+Set `DATABASE_URL` and your providers' settings in `apps/web/.env.local`, then run `pnpm db:migrate` and `pnpm check:services`.
+
+<!-- clubedge:end -->
+
+Then start the app. [SETUP.md](SETUP.md) describes every variable and provider.
 
 ```sh
 pnpm dev
@@ -125,6 +159,16 @@ Run these from the repository root:
 
 Playwright's first run may require installing Chromium with `pnpm exec playwright install chromium`. CI runs the browser checks automatically.
 
+Local services:
+
+- `pnpm check:services`: check every configured service with a real round trip.
+- `pnpm infra:up` and `pnpm infra:down`: start and stop the local services from `docker-compose.dev.yml`. <!-- clubedge:only infra=docker -->
+- `pnpm infra:reset`: stop them and delete their data. `pnpm infra:logs` follows their logs. <!-- clubedge:only infra=docker -->
+- `pnpm infra:up` and `pnpm infra:down`: start and stop the local Supabase stack. <!-- clubedge:only infra=supabase -->
+- `pnpm infra:status`: print its URLs and keys. `pnpm infra:reset` stops it and deletes its data. <!-- clubedge:only infra=supabase -->
+- `pnpm infra:up`: run only the local database, for example for `pnpm check:services` or browser tests. <!-- clubedge:only infra=local -->
+- `pnpm infra:reset`: delete the local database and files in `.data/` (stop `pnpm dev` first). <!-- clubedge:only infra=local -->
+
 <!-- clubedge:if starter-repository -->
 
 ## Working on this repository

package/template/SETUP.md

@@ -31,7 +31,10 @@ macOS/Linux:
 cp .env.example apps/web/.env.local
 ```
 
-The example file leaves provider URLs and keys blank so the app can build and start without connecting to real services. At minimum, set `DATABASE_URL`. The variables are:
+The example file points at the local services described in [Local services](#local-services) and leaves provider keys blank, so the app builds and starts before anything is configured. <!-- clubedge:only infra!=none -->
+The example file leaves provider URLs and keys blank so the app can build and start without connecting to real services. At minimum, set `DATABASE_URL`. <!-- clubedge:only infra=none -->
+
+The variables are:
 
 - `DATABASE_URL` (required): PostgreSQL connection URL, such as a Supabase transaction pooler URL.
 - `NEXT_PUBLIC_APP_URL` (recommended): the app's origin, defaulting to `http://localhost:3000`. <!-- clubedge:only framework=next -->
@@ -83,6 +86,56 @@ Put the result in `BETTER_AUTH_SECRET`. Until it is set, the dashboard stays vie
 
 <!-- clubedge:end -->
 
+## Local services
+
+<!-- clubedge:if infra=docker -->
+
+`docker-compose.dev.yml` runs the services this project uses on your machine, listening on `127.0.0.1` only. Install Docker Desktop (or Docker Engine with Compose), then:
+
+```sh
+pnpm infra:up      # start and wait until every service is healthy
+pnpm db:migrate    # create the tables
+pnpm check:services
+```
+
+- PostgreSQL 17 on port 5432, database `app`, user and password `postgres`. Data survives restarts in a Docker volume.
+- Redis on port 6379. <!-- clubedge:only cache=redis -->
+- S3-compatible storage (adobe/s3mock) on port 9090 with the bucket `app`. It accepts any credentials and is for development only. <!-- clubedge:only storage=s3 -->
+
+`pnpm infra:down` stops the services, `pnpm infra:reset` also deletes their data, and `pnpm infra:logs` follows their logs. The file is for development; in production, point the same variables at managed services.
+
+<!-- clubedge:end -->
+<!-- clubedge:if infra=supabase -->
+
+`supabase/config.toml` configures the Supabase CLI's local stack: PostgreSQL, Auth, Storage, the Studio dashboard, and an inbox that captures emails. The CLI runs it in Docker, so install Docker Desktop first. Then:
+
+```sh
+pnpm infra:up       # start the stack (the first run downloads its images)
+pnpm infra:status   # print the local URLs and keys
+pnpm db:migrate
+pnpm check:services
+```
+
+The database is on port 54322 and the API on port 54321, matching the example environment. Copy the publishable key from `pnpm infra:status` into the Supabase variables. Email confirmation is off locally, so sign-up signs the user in directly. `pnpm infra:down` stops the stack and `pnpm infra:reset` also deletes its data.
+
+<!-- clubedge:end -->
+<!-- clubedge:if infra=local -->
+
+This project runs its development services without Docker or any other installation:
+
+- **PostgreSQL:** `pnpm dev` also starts [PGlite](https://pglite.dev), PostgreSQL compiled to WebAssembly, and serves it on `127.0.0.1:5433`. Each start applies the migrations. Data is kept in `.data/pglite`. `pnpm infra:up` runs the database on its own, for `pnpm check:services` or browser tests.
+- **Files:** while `STORAGE_DIRECTORY` is set, uploads are stored in that folder (`.data/storage`) instead of S3. Set the S3 variables and remove `STORAGE_DIRECTORY` to use object storage. <!-- clubedge:only storage=s3 -->
+- **Cache:** without `REDIS_URL`, the cache and rate limits use process memory. <!-- clubedge:only cache=redis -->
+
+PGlite runs a single database session, so connections take turns. That is plenty for development but not for production: deploy against a managed PostgreSQL by setting `DATABASE_URL`. Supabase Auth and Supabase Storage need a Supabase project, local or hosted. Better Auth works fully offline. `pnpm infra:reset` deletes everything in `.data/`.
+
+<!-- clubedge:end -->
+<!-- clubedge:if infra=none -->
+
+This project does not include local service definitions. Point `DATABASE_URL` and the provider variables at services you run yourself or at hosted ones, such as Supabase or Neon for PostgreSQL and Upstash for Redis, then run `pnpm check:services` to confirm the app can reach them.
+
+<!-- clubedge:end -->
+
 ## Set up the database
 
 Application tables are managed with Drizzle. Keep one migration source of truth for application tables: do not also create an independent Supabase migration history for those same tables.

package/template/_gitignore

@@ -17,3 +17,8 @@ test-results/
 dist/
 # Generated by TanStack Router during dev, build, and typecheck
 routeTree.gen.ts
+# Supabase CLI working files
+supabase/.temp/
+supabase/.branches/
+# Local database and files for --infra local
+.data/