@clubedge/create-clubedge-app 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.4.0
+
+- Default to Starter `v0.4.0`, which adds the TanStack Start app and template schema 2.
+- Add `--framework next|tanstack-start`, and ask which framework to use when the Starter offers several. Next.js stays the default.
+- Read template schema 2, which describes each framework's app, environment example, and Dockerfile. The selected app is moved to `apps/web`, the others are left out, and `pnpm-lock.yaml` is kept in step so frozen installs work.
+- Record the chosen framework in the generated `package.json` and `README.md`.
+- Test generated projects for both frameworks in CI and in the release smoke test.
+
 ## 0.3.0
 
 - Default to Starter `v0.3.0`, which adds the `clubedge.template.json` template manifest.

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/create-clubedge-app/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 
-Create a Next.js application from the [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) reference implementation.
+Create a Next.js or TanStack Start application from the [Clubedge Starter](https://github.com/Clubedge/clubedge-starter) reference implementation.
 
 The CLI downloads a tested Starter release, names the generated project, creates `apps/web/.env.local` from the example, initializes Git, and installs dependencies. The Starter remains the source of truth for the generated architecture.
 
@@ -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.3.0
+create-clubedge-app v0.4.0
         |
         v
-Clubedge Starter v0.3.0
-commit 60f1691920c91a5cf83e480a3ce98c3ddefdef55
+Clubedge Starter v0.4.0
+commit fc01d33bb1a3944e099a1750679be87a96ff9a22
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.3.0` | `clubedge-starter@v0.3.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.4.0` | `clubedge-starter@v0.4.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.3.0` tag is expected to resolve to commit
-`60f1691920c91a5cf83e480a3ce98c3ddefdef55`. The CLI verifies this before
+The `v0.4.0` tag is expected to resolve to commit
+`fc01d33bb1a3944e099a1750679be87a96ff9a22`. 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.3.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.4.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
 
@@ -68,11 +68,27 @@ When no destination is provided, the CLI asks where to create the project:
 pnpm dlx @clubedge/create-clubedge-app
 ```
 
+### 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 when the Starter offers more than one:
+
+```sh
+pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start
+```
+
+| `--framework`    | App                         | Production output             |
+| ---------------- | --------------------------- | ----------------------------- |
+| `next`           | Next.js App Router          | Next.js standalone build      |
+| `tanstack-start` | TanStack Start with Vite    | Nitro `.output` server bundle |
+
+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.
+
 ## Options
 
 ```text
 Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 
+--framework <id>        App framework: next (default) or tanstack-start
 --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
@@ -85,20 +101,20 @@ Usage: pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 
 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.
 
-Every generated project records its CLI version, Starter repository, Starter ref, and Starter commit in `package.json` and `README.md`.
+Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, and framework in `package.json` and `README.md`.
 
 ```sh
 # 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
+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.3.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.4.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -109,7 +125,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. 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. 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:
 
@@ -143,7 +159,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.3.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.4.0`, and publish the Starter release.
 
 ### CLI maintainers
 

package/dist/cli/args.js

@@ -11,6 +11,7 @@ export function parseCliArgs(argv) {
             allowNegative: true,
             strict: true,
             options: {
+                framework: { type: "string" },
                 ref: { type: "string" },
                 "template-dir": { type: "string" },
                 install: { type: "boolean", default: true },
@@ -29,6 +30,9 @@ export function parseCliArgs(argv) {
     const { values, positionals } = parsed;
     if (positionals.length > 1)
         throw new UsageError("Only one project directory can be provided.");
+    if (values.framework !== undefined && !values.framework.trim()) {
+        throw new UsageError("--framework requires a framework id, such as next or tanstack-start.");
+    }
     if (values.ref !== undefined && !values.ref.trim()) {
         throw new UsageError("--ref requires a tag, branch, or commit.");
     }
@@ -37,6 +41,7 @@ export function parseCliArgs(argv) {
     }
     return {
         projectDirectory: positionals[0],
+        framework: values.framework?.trim(),
         ref: values.ref,
         templateDir: values["template-dir"],
         install: values.install,

package/dist/cli/ui.js

@@ -63,6 +63,7 @@ Usage:
   pnpm dlx @clubedge/create-clubedge-app [project-directory] [options]
 
 Options:
+  --framework <id>        App framework: next (default) or tanstack-start
   --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
@@ -74,6 +75,7 @@ Options:
 
 Examples:
   pnpm dlx @clubedge/create-clubedge-app my-app
+  pnpm dlx @clubedge/create-clubedge-app my-app --framework tanstack-start
   pnpm dlx @clubedge/create-clubedge-app my-app --dry-run
   pnpm dlx @clubedge/create-clubedge-app my-app --ref main
   pnpm dlx @clubedge/create-clubedge-app my-app --template-dir ../clubedge-starter

package/dist/core/customize.js

@@ -9,6 +9,7 @@ export function customizeRootManifest(source, { packageName }, provenance, docke
         starterRepository: provenance.starterRepository,
         starterRef: provenance.starterRef,
         ...(provenance.starterCommit ? { starterCommit: provenance.starterCommit } : {}),
+        ...(provenance.framework ? { framework: provenance.framework } : {}),
     };
     for (const script of ["docker:build", "docker:start"]) {
         if (typeof manifest.scripts?.[script] === "string") {
@@ -21,9 +22,10 @@ export function customizeReadme(source, { displayName }, provenance) {
     const commitLine = provenance.starterCommit
         ? `\n- Starter commit: \`${provenance.starterCommit}\``
         : "";
+    const frameworkLine = provenance.frameworkName ? `\n- Framework: ${provenance.frameworkName}` : "";
     const origin = `## Generated from\n\n` +
         `- Starter repository: \`${provenance.starterRepository}\`\n` +
-        `- Starter ref: \`${provenance.starterRef}\`${commitLine}\n` +
+        `- Starter ref: \`${provenance.starterRef}\`${commitLine}${frameworkLine}\n` +
         `- CLI version: \`${provenance.cliVersion}\``;
     // Only the first heading is the project title; leave every other line as written.
     return source.replace(/^# .+$/m, `# ${displayName}\n\n${origin}`);
@@ -54,3 +56,40 @@ export function customizeLegacySource(source, { displayName }) {
         .replaceAll(">Clubedge<", `>${displayName}<`)
         .replaceAll("Starter workspace", "Application workspace");
 }
+/** Gives the selected framework's app the package name generated projects use. */
+export function customizeAppManifest(source, appPackage) {
+    const manifest = JSON.parse(source);
+    manifest.name = appPackage;
+    return json(manifest);
+}
+/**
+ * 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.
+ */
+export function customizeLockfile(source, { remove, rename }) {
+    const output = [];
+    let inImporters = false;
+    let skipping = false;
+    for (const line of source.split("\n")) {
+        if (/^\S/.test(line)) {
+            inImporters = line === "importers:";
+            skipping = false;
+        }
+        else if (inImporters) {
+            // An importer key, with its value on the next lines or inline ("packages/core: {}").
+            const key = /^ {2}([^\s:][^:]*):(?: |$)/.exec(line)?.[1];
+            if (key !== undefined) {
+                skipping = remove.includes(key);
+                if (!skipping && key === rename?.from) {
+                    output.push(`  ${rename.to}:`);
+                    continue;
+                }
+            }
+            if (skipping)
+                continue;
+        }
+        output.push(line);
+    }
+    return output.join("\n");
+}

package/dist/core/manifest.js

@@ -1,7 +1,14 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 export const MANIFEST_FILE = "clubedge.template.json";
-export const SUPPORTED_SCHEMA_VERSION = 1;
+export const SUPPORTED_SCHEMA_VERSION = 2;
+/** Schema 1 Starters ship a single Next.js app at the generated location. */
+function singleNextFramework(app, envExample) {
+    return {
+        defaultFramework: "next",
+        frameworks: { next: { name: "Next.js", app, envExample, dockerfile: "Dockerfile" } },
+    };
+}
 /** Starter releases before v0.3.0 have no manifest; this describes their layout. */
 export const legacyManifest = {
     schemaVersion: 1,
@@ -11,6 +18,7 @@ export const legacyManifest = {
     siteConfig: "apps/web/src/config/site.json",
     env: { example: ".env.example", target: "apps/web/.env.local" },
     dockerImage: "clubedge-starter",
+    ...singleNextFramework("apps/web", ".env.example"),
     exclude: [],
 };
 export class ManifestError extends Error {
@@ -43,17 +51,47 @@ export function parseTemplateManifest(source) {
     if (data.exclude !== undefined && !isStringArray(data.exclude)) {
         throw new ManifestError(`${MANIFEST_FILE}: exclude must be an array of paths.`);
     }
+    const app = requireString(data, "app");
+    const envExample = requireString(env, "example", "env.");
     return {
         schemaVersion,
         name: requireString(data, "name"),
         packageManager: "pnpm",
-        app: requireString(data, "app"),
+        app,
+        ...(schemaVersion >= 2 ? { appPackage: requireString(data, "appPackage") } : {}),
         siteConfig: requireString(data, "siteConfig"),
-        env: { example: requireString(env, "example", "env."), target: requireString(env, "target", "env.") },
+        env: { example: envExample, target: requireString(env, "target", "env.") },
         dockerImage: requireString(data, "dockerImage"),
+        ...(schemaVersion >= 2 ? parseFrameworks(data) : singleNextFramework(app, envExample)),
         exclude: data.exclude ?? [],
     };
 }
+function parseFrameworks(data) {
+    const { frameworks } = data;
+    if (!isRecord(frameworks) || Object.keys(frameworks).length === 0) {
+        throw new ManifestError(`${MANIFEST_FILE}: frameworks must describe at least one framework.`);
+    }
+    const parsed = {};
+    for (const [id, entry] of Object.entries(frameworks)) {
+        if (!/^[a-z][a-z0-9-]*$/.test(id)) {
+            throw new ManifestError(`${MANIFEST_FILE}: "${id}" is not a valid framework id.`);
+        }
+        if (!isRecord(entry))
+            throw new ManifestError(`${MANIFEST_FILE}: frameworks.${id} must be an object.`);
+        const prefix = `frameworks.${id}.`;
+        parsed[id] = {
+            name: requireString(entry, "name", prefix),
+            app: requireString(entry, "app", prefix),
+            envExample: requireString(entry, "envExample", prefix),
+            dockerfile: requireString(entry, "dockerfile", prefix),
+        };
+    }
+    const defaultFramework = requireString(data, "defaultFramework");
+    if (!parsed[defaultFramework]) {
+        throw new ManifestError(`${MANIFEST_FILE}: defaultFramework "${defaultFramework}" is not in frameworks.`);
+    }
+    return { defaultFramework, frameworks: parsed };
+}
 export async function readTemplateManifest(templateRoot) {
     let source;
     try {

package/dist/core/plan.js

@@ -1,16 +1,59 @@
-import { customizeLegacySource, customizeReadme, customizeRootManifest, customizeSiteConfig, legacyBrandedFiles, } from "./customize.js";
+import { customizeAppManifest, customizeLegacySource, customizeLockfile, customizeReadme, customizeRootManifest, customizeSiteConfig, legacyBrandedFiles, } from "./customize.js";
+export class FrameworkError extends Error {
+    name = "FrameworkError";
+}
+const LOCKFILE = "pnpm-lock.yaml";
+const isWithin = (path, directory) => path === directory || path.startsWith(`${directory.replace(/\/$/, "")}/`);
 function isExcluded(path, exclude) {
-    return exclude.some((entry) => path === entry || path.startsWith(`${entry.replace(/\/$/, "")}/`));
+    return exclude.some((entry) => isWithin(path, entry));
+}
+/** Resolves the requested framework, or the default, with a helpful error for unknown ids. */
+export function selectFramework(manifest, requested) {
+    const id = requested ?? manifest.defaultFramework;
+    const framework = manifest.frameworks[id];
+    if (!framework) {
+        const choices = Object.keys(manifest.frameworks).join(", ");
+        throw new FrameworkError(`Unknown framework "${id}". This Starter offers: ${choices}.`);
+    }
+    return { id, ...framework };
+}
+/**
+ * Where a Starter file lands in the generated project, or null when it belongs to a framework
+ * that was not selected. The selected app moves to `manifest.app`, and its environment example
+ * and Dockerfile move to the generated project's locations.
+ */
+function relocate(path, manifest, selected, others) {
+    if (path === selected.envExample)
+        return manifest.env.example;
+    if (path === selected.dockerfile)
+        return "Dockerfile";
+    if (isWithin(path, selected.app))
+        return manifest.app + path.slice(selected.app.length);
+    const belongsToOther = others.some((other) => isWithin(path, other.app) || path === other.envExample || path === other.dockerfile);
+    return belongsToOther ? null : path;
 }
 export function createPlan(input) {
     const { manifest, identity, source } = input;
+    const framework = selectFramework(manifest, input.framework);
+    const others = Object.entries(manifest.frameworks)
+        .filter(([id]) => id !== framework.id)
+        .map(([, other]) => other);
+    const multipleFrameworks = others.length > 0;
     const provenance = {
         cliVersion: input.cliVersion,
         starterRepository: source.repository,
         starterRef: source.ref,
         ...(source.commit ? { starterCommit: source.commit } : {}),
+        ...(multipleFrameworks ? { framework: framework.id, frameworkName: framework.name } : {}),
     };
-    const files = source.files.filter(({ to }) => !isExcluded(to, manifest.exclude) && to !== manifest.env.target);
+    const files = [];
+    for (const file of source.files) {
+        if (isExcluded(file.to, manifest.exclude))
+            continue;
+        const to = relocate(file.to, manifest, framework, others);
+        if (to !== null && to !== manifest.env.target)
+            files.push({ from: file.from, to });
+    }
     const has = (path) => files.some(({ to }) => to === path);
     const edits = [];
     if (has("package.json")) {
@@ -20,6 +63,26 @@ export function createPlan(input) {
             apply: (text) => customizeRootManifest(text, identity, provenance, manifest.dockerImage),
         });
     }
+    const appManifest = `${manifest.app}/package.json`;
+    if (manifest.appPackage && framework.app !== manifest.app && has(appManifest)) {
+        const appPackage = manifest.appPackage;
+        edits.push({
+            path: appManifest,
+            description: `Name the ${framework.name} app "${appPackage}"`,
+            apply: (text) => customizeAppManifest(text, appPackage),
+        });
+    }
+    if (multipleFrameworks && has(LOCKFILE)) {
+        const changes = {
+            remove: others.map((other) => other.app).filter((app) => app !== framework.app),
+            ...(framework.app !== manifest.app ? { rename: { from: framework.app, to: manifest.app } } : {}),
+        };
+        edits.push({
+            path: LOCKFILE,
+            description: `Keep only the ${framework.name} app in the lockfile`,
+            apply: (text) => customizeLockfile(text, changes),
+        });
+    }
     if (has("README.md")) {
         edits.push({
             path: "README.md",
@@ -47,6 +110,7 @@ export function createPlan(input) {
         targetDirectory: input.targetDirectory,
         identity,
         provenance,
+        framework: { id: framework.id, name: framework.name },
         files,
         edits,
         envFile: has(manifest.env.example) ? { from: manifest.env.example, to: manifest.env.target } : null,
@@ -57,6 +121,7 @@ export function createPlan(input) {
 export function describePlan(plan) {
     return [
         `Create ${plan.targetDirectory}`,
+        ...(plan.provenance.framework ? [`Use ${plan.framework.name}`] : []),
         `Copy ${plan.files.length} files from ${plan.provenance.starterRepository}@${plan.provenance.starterRef}` +
             (plan.provenance.starterCommit ? ` (${plan.provenance.starterCommit.slice(0, 8)})` : ""),
         ...plan.edits.map((edit) => `Edit ${edit.path}: ${edit.description}`),

package/dist/index.js

@@ -1,11 +1,11 @@
-import { cancel, intro, isCancel, log, outro, spinner, text } from "@clack/prompts";
+import { cancel, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
 import { relative, resolve } from "node:path";
 import process from "node:process";
 import { parseCliArgs, UsageError } from "./cli/args.js";
 import { dim, helpText, showBanner } from "./cli/ui.js";
 import { assertTargetIsUsable, executePlan } from "./core/execute.js";
 import { readTemplateManifest } from "./core/manifest.js";
-import { createPlan, describePlan } from "./core/plan.js";
+import { createPlan, describePlan, selectFramework } from "./core/plan.js";
 import { resolveTemplateSource } from "./core/source.js";
 import { cliUrl, cliVersion, siteUrl } from "./package-info.js";
 import { initializeGit } from "./steps/git.js";
@@ -30,6 +30,27 @@ async function askProjectDirectory() {
     }
     return value;
 }
+/**
+ * The framework from --framework, a prompt when the Starter offers several, or the default.
+ * Returns null when the prompt is cancelled.
+ */
+async function chooseFramework(manifest, requested, interactive) {
+    if (requested)
+        return selectFramework(manifest, requested).id;
+    const ids = Object.keys(manifest.frameworks);
+    if (!interactive || ids.length < 2)
+        return manifest.defaultFramework;
+    const value = await select({
+        message: "Which framework should the app use?",
+        initialValue: manifest.defaultFramework,
+        options: ids.map((id) => ({
+            value: id,
+            label: manifest.frameworks[id].name,
+            ...(id === manifest.defaultFramework ? { hint: "default" } : {}),
+        })),
+    });
+    return isCancel(value) ? null : value;
+}
 async function createProject(args) {
     const interactive = Boolean(process.stdin.isTTY) && !args.yes;
     const requested = args.projectDirectory ?? (interactive ? await askProjectDirectory() : "my-app");
@@ -43,29 +64,43 @@ async function createProject(args) {
         progress.stop("Could not prepare the Starter");
         throw error;
     });
+    // The spinner runs while the manifest is read and again while files are written.
+    let spinning = "preparing";
     try {
         const manifest = await readTemplateManifest(source.root);
+        progress.stop(`Starter ${source.ref} ready`);
+        spinning = null;
+        const framework = await chooseFramework(manifest, args.framework, interactive);
+        if (framework === null) {
+            cancel("Operation cancelled.");
+            return;
+        }
         const plan = createPlan({
             targetDirectory,
             identity,
             source,
             manifest,
+            framework,
             cliVersion,
             git: args.git,
             install: args.install,
         });
         if (args.dryRun) {
-            progress.stop("Dry run: nothing was written");
             log.message(describePlan(plan).map((line) => `• ${line}`).join("\n"));
-            outro("Run again without --dry-run to create the project.");
+            outro("Dry run: nothing was written. Run again without --dry-run to create the project.");
             return;
         }
-        progress.message(`Writing ${plan.files.length} files`);
+        spinning = "writing";
+        progress.start(`Writing ${plan.files.length} files`);
         await executePlan(plan, source);
-        progress.stop(`Created ${identity.packageName} from Starter ${source.ref}`);
+        progress.stop(`Created ${identity.packageName} with ${plan.framework.name} from Starter ${source.ref}`);
+        spinning = null;
     }
     catch (error) {
-        progress.stop("Project scaffold failed; nothing was left behind");
+        if (spinning === "preparing")
+            progress.stop("Could not read the Starter");
+        if (spinning === "writing")
+            progress.stop("Project scaffold failed; nothing was left behind");
         throw error;
     }
     finally {

package/dist/utils/fs.js

@@ -33,6 +33,9 @@ function mapBasename(path, map) {
 const ignoredDirectories = new Set([
     ".git",
     ".next",
+    ".nitro",
+    ".output",
+    ".tanstack",
     ".turbo",
     ".pnpm-store",
     "node_modules",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.3.0",
-  "description": "Create an application from the Clubedge Starter reference implementation.",
+  "version": "0.4.0",
+  "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
   "bin": {
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.3.0",
-    "starterCommit": "60f1691920c91a5cf83e480a3ce98c3ddefdef55"
+    "starterRef": "v0.4.0",
+    "starterCommit": "fc01d33bb1a3944e099a1750679be87a96ff9a22"
   },
   "license": "Apache-2.0",
   "repository": {
@@ -38,6 +38,7 @@
     "create-clubedge-app",
     "clubedge",
     "nextjs",
+    "tanstack-start",
     "starter",
     "scaffolding"
   ],

package/template/.dockerignore

@@ -6,3 +6,6 @@ node_modules
 .env*
 coverage
 playwright-report
+.output
+.nitro
+.tanstack

package/template/.github/workflows/ci.yml

@@ -23,21 +23,68 @@ jobs:
       - run: pnpm lint
       - run: pnpm typecheck
       - run: pnpm test
-      - run: pnpm exec playwright install --with-deps chromium
-      - run: pnpm test:e2e
+      # Generated projects build with the env example copied into place; build the same way.
+      - run: cp .env.example apps/web/.env.local && cp apps/start/.env.example apps/start/.env.local
       - run: pnpm build
+      - name: Serve both production builds
+        run: |
+          set -euo pipefail
+          PORT=3001 pnpm --filter @clubedge/web start > "$RUNNER_TEMP/web.log" 2>&1 &
+          PORT=3002 pnpm --filter @clubedge/start start > "$RUNNER_TEMP/start.log" 2>&1 &
+          trap 'tail -n 50 "$RUNNER_TEMP/web.log" "$RUNNER_TEMP/start.log"' EXIT
+          for port in 3001 3002; do
+            for attempt in $(seq 1 30); do
+              curl --fail --silent --output /dev/null "http://127.0.0.1:$port/api/health" && break
+              sleep 1
+            done
+            for path in / /login /dashboard /api/health; do
+              curl --fail --silent --show-error --output /dev/null "http://127.0.0.1:$port$path"
+            done
+          done
       - run: pnpm audit --audit-level high
 
+  # The same browser suite runs against every framework.
+  e2e:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        app: [web, start]
+    env:
+      E2E_APP: ${{ matrix.app }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm test:e2e
+
   docker:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - app: web
+            build: docker build --tag clubedge-starter:ci .
+          - app: start
+            build: >-
+              docker build --tag clubedge-starter:ci --file apps/start/Dockerfile
+              --build-arg APP_DIR=apps/start --build-arg APP_PACKAGE=@clubedge/start .
     steps:
       - uses: actions/checkout@v4
       - name: Build the production image
-        run: docker build --tag clubedge-starter:ci .
+        run: ${{ matrix.build }}
       - name: Start the image and check health
         run: |
           set -euo pipefail
-          docker run --detach --name app --publish 3000:3000             --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres             clubedge-starter:ci
+          docker run --detach --name app --publish 3000:3000 \
+            --env DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres \
+            clubedge-starter:ci
           trap 'docker logs app; docker rm --force app' EXIT
           for attempt in $(seq 1 30); do
             if curl --fail --silent http://127.0.0.1:3000/api/health; then

package/template/.prettierignore

@@ -1 +1,2 @@
 pnpm-lock.yaml
+**/routeTree.gen.ts

package/template/AGENTS.md

@@ -4,9 +4,10 @@
 
 - `packages/{core,auth,cache,db,storage}` are framework-agnostic. Never import `next`, `react`, `server-only`, `@tanstack/*`, or app code (`@/…`) there. Accept configuration, clients, and cookies as function arguments.
 - `packages/core` depends on no other workspace package.
-- `apps/web/src/server/` is the composition root: the only place that reads environment variables, bridges Next.js cookies to `CookieStore`, and picks providers. Routes, server actions, and components import from `@/server/*`, never from `@supabase/*`, `@aws-sdk/*`, `redis`, or `postgres`.
+- Each app's `src/server/` is its composition root: the only place that reads environment variables, bridges the framework's cookies to `CookieStore`, and picks providers. Routes, server actions, server functions, and components import from `@/server/*`, never from `@supabase/*`, `@aws-sdk/*`, `redis`, or `postgres`.
+- `apps/web` (Next.js) and `apps/start` (TanStack Start) are the same product. Make user-facing changes in both, keep their markup and redirects identical, and run the shared browser suite against each (`E2E_APP=start pnpm test:e2e`).
 - Expected failures (bad credentials, invalid codes) are returned as `Result` values from `@clubedge/core`; exceptions are for unexpected errors.
-- Project identity (name, description, links) lives in `apps/web/src/config/site.json`; `create-clubedge-app` rewrites that file, so do not hard-code the project name elsewhere.
+- Project identity (name, description, links) lives in each app's `src/config/site.json` (keep them identical); `create-clubedge-app` rewrites that file, so do not hard-code the project name elsewhere.
 - `pnpm lint` enforces these boundaries. Run `pnpm lint`, `pnpm typecheck`, and `pnpm test` before finishing a change.
 
 <!-- BEGIN:nextjs-agent-rules -->

package/template/CONTRIBUTING.md

@@ -33,8 +33,8 @@ Run `pnpm test:e2e` for changes that affect browser behavior. It requires a loca
 
 ## Project conventions
 
-- Keep application code in `apps/web`, reusable shadcn/ui code in `packages/ui`, and framework-agnostic infrastructure in `packages/{core,auth,db,storage,cache}`.
-- Reach providers through `apps/web/src/server` rather than scattering provider SDK calls through routes and components. `pnpm lint` enforces these boundaries.
+- Keep application code in `apps/web` (Next.js) and `apps/start` (TanStack Start), reusable shadcn/ui code in `packages/ui`, and framework-agnostic infrastructure in `packages/{core,auth,db,storage,cache}`. A user-facing change belongs in both apps.
+- Reach providers through each app's `src/server` rather than scattering provider SDK calls through routes and components. `pnpm lint` enforces these boundaries.
 - Keep server secrets out of client code and out of committed files. Update `.env.example` when adding configuration, using placeholders only.
 - For database changes, update the Drizzle schema and generate, review, and commit the migration. Do not maintain a second migration history for the same application tables.
 - For shared UI changes, preserve compatibility between both `components.json` files and use the established package exports.