@clubedge/create-clubedge-app 0.3.0 → 0.4.0

package/template/README.md

@@ -3,13 +3,13 @@
 [![CI](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 
-Clubedge Starter is a production-oriented, modular Next.js application foundation. It brings together a pnpm monorepo, shared shadcn/ui components, PostgreSQL access through Drizzle, Supabase Auth, optional Redis and storage adapters, and a working example dashboard. It provides engineering conventions and a reference implementation; review its security and deployment choices for your application before production use.
+Clubedge Starter is a production-oriented, modular React application foundation, available for Next.js and TanStack Start. It brings together a pnpm monorepo, shared shadcn/ui components, PostgreSQL access through Drizzle, Supabase Auth, optional Redis and storage adapters, and a working example dashboard. It provides engineering conventions and a reference implementation; review its security and deployment choices for your application before production use.
 
 This is a starter, not a hosted service or a one-command app generator. Fork it or use it as a reference, then adapt the app and provider configuration to your project. Contributions and bug reports are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Repository maintainers can use [PUBLISHING.md](PUBLISHING.md) for the GitHub launch checklist.
 
 ## Features
 
-- Next.js App Router, React, TypeScript, Tailwind CSS 4, and shadcn/ui using Base UI primitives.
+- Next.js App Router or TanStack Start, with React, TypeScript, Tailwind CSS 4, and shadcn/ui using Base UI primitives.
 - pnpm workspaces and Turborepo, with the web app in `apps/web` and reusable UI source in `packages/ui`.
 - Drizzle ORM and PostgreSQL schema, migrations, and seed commands.
 - Supabase Auth using cookie based server clients from `@supabase/ssr`.
@@ -22,13 +22,13 @@ This is a starter, not a hosted service or a one-command app generator. Fork it
 
 | Capability              | Included choice                                      | Other supported options                                               |
 | ----------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
-| Web app                 | Next.js App Router, React, TypeScript                | —                                                                     |
+| Web app                 | Next.js App Router, React, TypeScript                | TanStack Start (`apps/start`), sharing every package.                 |
 | UI                      | Tailwind CSS 4, shadcn/ui, and Base UI               | Add or replace components in your app or shared UI package.           |
 | Database                | PostgreSQL through Drizzle ORM                       | Any reachable PostgreSQL provider; Supabase PostgreSQL is documented. |
 | Authentication          | Supabase Auth with `@supabase/ssr`                   | No alternate auth adapter is currently included.                      |
 | Cache and rate limiting | Optional Redis protocol client                       | Upstash, self-hosted Redis, or a compatible Redis service.            |
 | Object storage          | S3-compatible adapter or Supabase Storage            | AWS S3, Cloudflare R2, and other S3-compatible services.              |
-| Local runtime           | Docker and Next.js standalone output                 | Run directly with Node.js during development.                         |
+| Local runtime           | Docker and Next.js standalone or Nitro output        | Run directly with Node.js during development.                         |
 | Verification            | Vitest, Playwright, ESLint, Prettier, GitHub Actions | —                                                                     |
 
 ## Architecture
@@ -53,7 +53,7 @@ Drizzle manages application data in PostgreSQL. Supabase Auth manages identity a
 - **Infrastructure dependencies stay optional where practical.** Redis is only needed for distributed cache and rate limiting. Without Redis, the rate limiter falls back to a per-process memory window, which is suitable for a single server instance only.
 - **Storage has a provider boundary.** Application code can use the storage interface with S3-compatible services or Supabase Storage; authorization and upload validation remain the caller's responsibility.
 - **Shared packages are framework-agnostic.** Packages under `packages/` receive configuration and request cookies as arguments and never import Next.js, so another app (for example a TanStack Start app) can reuse them unchanged. ESLint enforces these boundaries.
-- **One composition root per app.** `apps/web/src/server/` is the only place that reads environment variables and chooses providers. Routes, actions, and components call it rather than a provider SDK.
+- **One composition root per app.** Each app's `src/server/` is the only place that reads environment variables and chooses providers. Routes, actions, and components call it rather than a provider SDK.
 - **Keep the baseline focused.** Additional providers, queues, and generator tooling should be added when a real use case calls for them.
 
 ## Quick start
@@ -117,11 +117,24 @@ 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.
 
+## Frameworks
+
+This repository contains the same application twice, so both stay tested against the shared packages:
+
+| App          | Framework          | Run it                              |
+| ------------ | ------------------ | ----------------------------------- |
+| `apps/web`   | Next.js App Router | `pnpm dev`                          |
+| `apps/start` | TanStack Start     | `pnpm --filter @clubedge/start dev` |
+
+Projects generated by `create-clubedge-app` contain only the framework you choose, always in `apps/web`. The TanStack Start app reads `apps/start/.env.local`; copy `apps/start/.env.example` there. Its variables have no browser prefix (`APP_URL`, `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`) because authentication runs on the server. Run the browser suite against it with `E2E_APP=start pnpm test:e2e`, and build its image with `docker build -f apps/start/Dockerfile --build-arg APP_DIR=apps/start --build-arg APP_PACKAGE=@clubedge/start .`.
+
 ## Repository structure
 
 ```text
 apps/web/            Next.js app: routes, actions, UI, and the composition root
   src/server/        Wires environment, cookies, and providers into the packages
+apps/start/          TanStack Start app with the same pages, built on the same packages
+e2e/                 Playwright suite shared by both apps (E2E_APP selects one)
 packages/core/       Errors, Result type, and HTTP helpers (no dependencies)
 packages/auth/       AuthProvider and CookieStore interfaces, Supabase adapter
 packages/db/         Drizzle schema, client factory, migrations, and seed script

package/template/SETUP.md

@@ -150,7 +150,29 @@ pnpm exec playwright install chromium
 pnpm test:e2e
 ```
 
-The Playwright configuration starts the local app with a placeholder database URL; browser scenarios should not require real provider credentials.
+The Playwright configuration starts the local app with a placeholder database URL; browser scenarios should not require real provider credentials. Set `E2E_APP=start` to run the same suite against the TanStack Start app.
+
+## 9. TanStack Start app
+
+`apps/start` is the same application built with TanStack Start. It reuses every package and differs only in its framework layer:
+
+| Concern               | Next.js (`apps/web`)                   | TanStack Start (`apps/start`)                                   |
+| --------------------- | -------------------------------------- | --------------------------------------------------------------- |
+| Environment file      | `apps/web/.env.local`                  | `apps/start/.env.local`, from `apps/start/.env.example`         |
+| App URL and Supabase  | `NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_*` | `APP_URL`, `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`           |
+| Sign-in and sign-up   | Server actions                         | Form posts to `/auth/sign-in` and `/auth/sign-up` server routes |
+| Session refresh       | `src/proxy.ts`                         | Request middleware in `src/start.ts`                            |
+| Cross-site protection | Built into server actions              | `createCsrfMiddleware` in `src/start.ts`                        |
+| Production output     | Next.js standalone (`pnpm start`)      | Nitro `.output` (`pnpm --filter @clubedge/start start`)         |
+| Docker image          | `Dockerfile`                           | `apps/start/Dockerfile` (see below)                             |
+
+Run it with `pnpm --filter @clubedge/start dev`. The database commands still read `DATABASE_URL` from `apps/web/.env.local`. Build its image from the repository root:
+
+```sh
+docker build -f apps/start/Dockerfile --build-arg APP_DIR=apps/start --build-arg APP_PACKAGE=@clubedge/start -t clubedge-starter .
+```
+
+In projects generated with the TanStack Start option, the app lives in `apps/web`, its Dockerfile is the root `Dockerfile`, and the build arguments are not needed.
 
 ## Before deploying
 

package/template/_gitignore

@@ -11,3 +11,7 @@ test-results/
 !.env.example
 !.env.test.example
 *.tsbuildinfo
+.output/
+.nitro/
+.tanstack/
+dist/

package/template/apps/start/.env.example

@@ -0,0 +1,27 @@
+# Do not set NODE_ENV here: Vite reads it from env files, and vite build would then compile
+# development JSX that crashes the production server. `vite dev` and `vite build` set it.
+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 Auth (publishable key only; never use a service role key here).
+# All auth runs on the server, so these need no browser prefix.
+SUPABASE_URL=
+SUPABASE_PUBLISHABLE_KEY=
+
+# Optional cache and rate limits (Redis protocol; rediss:// enables TLS)
+# Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
+REDIS_URL=
+
+# Storage adapter: s3 (works with AWS S3 and Cloudflare R2) or supabase
+STORAGE_PROVIDER=s3
+STORAGE_BUCKET=
+STORAGE_REGION=auto
+STORAGE_ENDPOINT=
+STORAGE_ACCESS_KEY_ID=
+STORAGE_SECRET_ACCESS_KEY=
+STORAGE_PUBLIC_URL=
+
+# Supabase Storage adapter
+SUPABASE_STORAGE_BUCKET=

package/template/apps/start/AGENTS.md

@@ -0,0 +1,11 @@
+# TanStack Start app
+
+This app mirrors `apps/web` with TanStack Start. Follow the root `AGENTS.md`, plus:
+
+- Read the skills bundled with the installed packages before changing framework code: `node_modules/@tanstack/react-start/skills/` and `node_modules/@tanstack/start-client-core/skills/`. They match the installed version; APIs change often.
+- Route loaders run on the server and in the browser. Keep database, provider, and secret access in `src/server/`, reached from loaders through `createServerFn` (see `src/server/auth.functions.ts`).
+- Every server function and server route that touches private data must check the user itself. A route guard only protects the page, not the endpoint.
+- Modules in `src/server/` start with `import "@tanstack/react-start/server-only";` so they can never reach the browser bundle.
+- Forms post to server routes that answer with 303 redirects (`src/server/auth-forms.ts`), so they work before hydration. Do not throw a router `redirect` from a POST handler; it uses 307 and repeats the POST.
+- Search params are plain strings (`src/router.tsx`). Build login links with `loginUrl()` so they match the Next.js app.
+- `src/routeTree.gen.ts` is generated by `vite dev` and `vite build`. Commit it, but do not edit it by hand.

package/template/apps/start/Dockerfile

@@ -0,0 +1,38 @@
+# Production image for the TanStack Start app. Build it from the repository root.
+# Generated projects keep the app in apps/web; the starter repository builds it with
+#   docker build -f apps/start/Dockerfile --build-arg APP_DIR=apps/start \
+#     --build-arg APP_PACKAGE=@clubedge/start .
+ARG APP_DIR=apps/web
+ARG APP_PACKAGE=@clubedge/web
+
+FROM node:22-alpine AS base
+RUN corepack enable
+WORKDIR /app
+
+# Reduce the workspace to the app and the packages it depends on, split into manifests
+# (for a cacheable install layer) and full sources. New packages are picked up automatically.
+FROM base AS pruner
+ARG APP_PACKAGE
+COPY . .
+RUN pnpm dlx turbo@^2.5.0 prune ${APP_PACKAGE} --docker
+
+FROM base AS deps
+COPY --from=pruner /app/out/json/ .
+RUN pnpm install --frozen-lockfile
+
+FROM base AS builder
+COPY --from=deps /app/ .
+COPY --from=pruner /app/out/full/ .
+COPY tsconfig.base.json ./
+RUN pnpm build
+
+# Nitro bundles the server and its dependencies into .output, so no node_modules are needed.
+FROM node:22-alpine AS runner
+ARG APP_DIR
+ENV NODE_ENV=production HOST=0.0.0.0 PORT=3000
+WORKDIR /app
+RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 app
+COPY --from=builder --chown=app:nodejs /app/${APP_DIR}/.output ./.output
+USER app
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]

package/template/apps/start/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@clubedge/start",
+  "version": "0.4.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "start": "node --env-file-if-exists=.env.local .output/server/index.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clubedge/auth": "workspace:*",
+    "@clubedge/cache": "workspace:*",
+    "@clubedge/core": "workspace:*",
+    "@clubedge/db": "workspace:*",
+    "@clubedge/storage": "workspace:*",
+    "@clubedge/ui": "workspace:*",
+    "@tanstack/react-router": "1.170.42",
+    "@tanstack/react-start": "1.168.61",
+    "lucide-react": "^0.468.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "use-sync-external-store": "^1.7.0",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/react": "^19.1.13",
+    "@types/react-dom": "^19.1.9",
+    "@vitejs/plugin-react": "^6.1.2",
+    "nitro": "3.0.260903-beta",
+    "tailwindcss": "^4.1.13",
+    "vite": "^8.3.4"
+  }
+}

package/template/apps/start/public/.well-known/logo.svg

@@ -0,0 +1 @@
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><defs><style>.cls-1{fill:#2563eb;}.cls-2,.cls-3{fill:#fff;}.cls-2{fill-rule:evenodd;}</style></defs><rect class="cls-1" width="512" height="512"/><path class="cls-2" d="M364.36,283a359.51,359.51,0,0,0-43.5-10.18,364.29,364.29,0,0,1,5.24-55.17l30-15.13,20.83,5.63v34.6A43.79,43.79,0,0,0,364.36,283Zm-66.88-13.4a395.53,395.53,0,0,0-82.94,0,390.43,390.43,0,0,0-3-39L256,253l44.45-22.42A390.43,390.43,0,0,0,297.48,269.6Zm-106.32,3.22c-39.75,6.75-76,19.56-106.55,36.9a175.47,175.47,0,0,1-2.52-29.64,173.14,173.14,0,0,1,31-99.15l72.81,36.72a364.29,364.29,0,0,1,5.24,55.17Zm230.41,60.63A174.34,174.34,0,0,1,352.17,425c-17.72-36.5-28.9-80.53-31-128.34,37.9,6.89,72.13,19.67,100.42,36.78Zm-89.78,103.2a174.19,174.19,0,0,1-151.57,0c20-40.75,32.48-90.09,34.24-143.46a373.23,373.23,0,0,1,83.1,0C299.32,346.56,311.75,395.9,331.79,436.65ZM159.85,425a174.36,174.36,0,0,1-69.41-91.56c28.3-17.11,62.53-29.89,100.42-36.78-2.11,47.81-13.3,91.84-31,128.34Z"/><path class="cls-2" d="M256,58l173,84.17-33.81,17.05L280.05,128.07c-6.92-4.44-16-6.2-24-6.2-7.37,0-15.32,1.45-21.88,4.94s-11.85,9.19-11.85,16.9,5.42,13.48,11.85,16.9,14.51,4.94,21.88,4.94a54.52,54.52,0,0,0,9.29-.78l77.41,20.93L256,229.42,83,142.17,256,58Z"/><path class="cls-2" d="M256,130.18c8.43,0,15.9,2.18,20.52,5.55l140,37.84v72.75a29.68,29.68,0,0,0-18.51,0V192l-132.36-35.8a45,45,0,0,1-9.6,1c-14,0-25.42-6.05-25.42-13.53S242,130.18,256,130.18Z"/><circle class="cls-3" cx="407.23" cy="274.28" r="22.68"/></svg>

package/template/apps/start/src/components/auth/auth-form-controls.tsx

@@ -0,0 +1,108 @@
+import { ArrowRight, Eye, EyeOff, Loader2 } from "lucide-react";
+import { createContext, useContext, useState, type ReactNode } from "react";
+
+import { Button } from "@clubedge/ui/components/button";
+import { Input } from "@clubedge/ui/components/input";
+import { Label } from "@clubedge/ui/components/label";
+
+// The form posts natively to a server route, so it works before hydration and without
+// JavaScript. Once hydrated, the pending state disables repeat submissions.
+const PendingContext = createContext(false);
+
+export function AuthForm({ action, children }: { action: string; children: ReactNode }) {
+  const [pending, setPending] = useState(false);
+
+  return (
+    <form
+      action={action}
+      className="grid gap-5"
+      method="post"
+      onSubmit={(event) => {
+        if (pending) event.preventDefault();
+        else setPending(true);
+      }}
+    >
+      <PendingContext.Provider value={pending}>{children}</PendingContext.Provider>
+    </form>
+  );
+}
+
+export function PasswordField({ isSignUp }: { isSignUp: boolean }) {
+  const [visible, setVisible] = useState(false);
+  const pending = useContext(PendingContext);
+
+  return (
+    <div className="grid gap-2">
+      <Label htmlFor="password">Password</Label>
+      <div className="relative">
+        <Input
+          aria-describedby={isSignUp ? "password-hint" : undefined}
+          autoComplete={isSignUp ? "new-password" : "current-password"}
+          className="h-11 pr-11"
+          id="password"
+          maxLength={128}
+          minLength={8}
+          name="password"
+          placeholder={isSignUp ? "Create a password" : "Enter your password"}
+          // readOnly rather than disabled: disabled fields are left out of the submitted form.
+          readOnly={pending}
+          required
+          type={visible ? "text" : "password"}
+        />
+        <button
+          aria-label={visible ? "Hide password" : "Show password"}
+          aria-pressed={visible}
+          className="absolute inset-y-0 right-0 grid w-11 place-items-center rounded-r-md text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+          onClick={() => setVisible((v) => !v)}
+          type="button"
+        >
+          {visible ? (
+            <EyeOff aria-hidden="true" className="size-4" />
+          ) : (
+            <Eye aria-hidden="true" className="size-4" />
+          )}
+        </button>
+      </div>
+      {isSignUp && (
+        <p className="text-xs text-muted-foreground" id="password-hint">
+          Use at least 8 characters.
+        </p>
+      )}
+    </div>
+  );
+}
+
+export function EmailField() {
+  const pending = useContext(PendingContext);
+
+  return (
+    <div className="grid gap-2">
+      <Label htmlFor="email">Email</Label>
+      <Input
+        autoComplete="email"
+        autoFocus
+        className="h-11"
+        id="email"
+        name="email"
+        placeholder="you@example.com"
+        readOnly={pending}
+        required
+        type="email"
+      />
+    </div>
+  );
+}
+
+export function SubmitButton({ children, disabled }: { children: ReactNode; disabled?: boolean }) {
+  const pending = useContext(PendingContext);
+
+  return (
+    <Button className="h-11 w-full justify-center" disabled={disabled || pending} type="submit">
+      {pending ? (
+        <Loader2 aria-hidden="true" className="animate-spin motion-reduce:animate-none" />
+      ) : null}
+      {children}
+      {!pending && <ArrowRight aria-hidden="true" />}
+    </Button>
+  );
+}

package/template/apps/start/src/components/branding/clubedge-mark.tsx

@@ -0,0 +1,24 @@
+type ClubedgeMarkProps = {
+  alt?: string;
+  className?: string;
+  priority?: boolean;
+};
+
+export function ClubedgeMark({
+  alt = "Clubedge",
+  className = "size-10",
+  priority = false,
+}: ClubedgeMarkProps) {
+  return (
+    <img
+      alt={alt}
+      className={className}
+      decoding="async"
+      fetchPriority={priority ? "high" : "auto"}
+      height={512}
+      loading={priority ? "eager" : "lazy"}
+      src="/.well-known/logo.svg"
+      width={512}
+    />
+  );
+}

package/template/apps/start/src/components/dashboard/account-button.tsx

@@ -0,0 +1,33 @@
+import { Link } from "@tanstack/react-router";
+
+import type { AuthUser } from "@clubedge/auth";
+import { Button } from "@clubedge/ui/components/button";
+
+type AccountButtonProps = {
+  user: AuthUser | null;
+  className?: string;
+};
+
+export function AccountButton({ user, className }: AccountButtonProps) {
+  if (!user) {
+    return (
+      <Button className={className} render={<Link to="/login" />} size="sm" variant="outline">
+        Sign in
+      </Button>
+    );
+  }
+
+  return (
+    <form action="/auth/sign-out" className={className} method="post">
+      <Button
+        className="w-full"
+        size="sm"
+        title={user.email ?? undefined}
+        type="submit"
+        variant="outline"
+      >
+        Sign out
+      </Button>
+    </form>
+  );
+}

package/template/apps/start/src/components/dashboard/app-sidebar.tsx

@@ -0,0 +1,90 @@
+import { Activity, ArrowUpRight, Blocks, Github, LayoutDashboard } from "lucide-react";
+
+import { ClubedgeMark } from "@/components/branding/clubedge-mark";
+import { siteConfig } from "@/config/site";
+import type { AuthUser } from "@clubedge/auth";
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarSeparator,
+} from "@clubedge/ui/components/sidebar";
+
+import { AccountButton } from "./account-button";
+
+const navigation = [
+  { href: "#overview", label: "Overview", icon: LayoutDashboard },
+  { href: "#modules", label: "Modules", icon: Blocks },
+  { href: "#activity", label: "Setup status", icon: Activity },
+];
+
+export function AppSidebar({ user }: { user: AuthUser | null }) {
+  return (
+    <Sidebar collapsible="icon" variant="inset">
+      <SidebarHeader>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton
+              className="h-12"
+              render={<a href="#overview" aria-label={`${siteConfig.name} home`} />}
+              size="lg"
+              tooltip={siteConfig.name}
+            >
+              <ClubedgeMark alt="" className="size-8 shrink-0 rounded-lg" />
+              <span className="grid min-w-0 text-start leading-tight">
+                <span className="truncate font-semibold">{siteConfig.shortName}</span>
+                <span className="truncate text-xs text-sidebar-foreground/70">
+                  {siteConfig.workspaceLabel}
+                </span>
+              </span>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarHeader>
+
+      <SidebarSeparator />
+
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupLabel>Workspace</SidebarGroupLabel>
+          <SidebarMenu>
+            {navigation.map(({ href, label, icon: Icon }, index) => (
+              <SidebarMenuItem key={href}>
+                <SidebarMenuButton
+                  render={<a href={href} aria-current={index === 0 ? "page" : undefined} />}
+                  isActive={index === 0}
+                  tooltip={label}
+                >
+                  <Icon aria-hidden="true" />
+                  <span>{label}</span>
+                </SidebarMenuButton>
+              </SidebarMenuItem>
+            ))}
+          </SidebarMenu>
+        </SidebarGroup>
+      </SidebarContent>
+
+      <SidebarFooter>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton
+              render={<a href={siteConfig.links.repository} target="_blank" rel="noreferrer" />}
+              tooltip="Starter repository"
+            >
+              <Github aria-hidden="true" />
+              <span>Starter repository</span>
+              <ArrowUpRight aria-hidden="true" className="ms-auto" />
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+        <AccountButton className="w-full" user={user} />
+      </SidebarFooter>
+    </Sidebar>
+  );
+}

package/template/apps/start/src/components/landing/copy-command.tsx

@@ -0,0 +1,46 @@
+import { Check, Copy } from "lucide-react";
+import { useEffect, useState } from "react";
+
+export function CopyCommand({ command }: { command: string }) {
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    if (!copied) return;
+    const timer = setTimeout(() => setCopied(false), 2000);
+    return () => clearTimeout(timer);
+  }, [copied]);
+
+  async function handleCopy() {
+    try {
+      await navigator.clipboard.writeText(command);
+      setCopied(true);
+    } catch {
+      // Clipboard can be unavailable (insecure context, denied permission).
+      // The command stays selectable, so we fail silently.
+    }
+  }
+
+  return (
+    <div className="flex items-center gap-2 rounded-xl border bg-card py-2 pl-4 pr-2 shadow-sm">
+      <code className="min-w-0 flex-1 overflow-x-auto whitespace-nowrap py-1.5 font-mono text-sm text-foreground">
+        <span aria-hidden="true" className="select-none text-muted-foreground">
+          ${" "}
+        </span>
+        {command}
+      </code>
+      <button
+        aria-label={copied ? "Command copied" : "Copy command"}
+        className="inline-flex h-9 shrink-0 items-center gap-1.5 rounded-lg px-3 text-xs font-medium text-muted-foreground outline-none transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+        onClick={handleCopy}
+        type="button"
+      >
+        {copied ? (
+          <Check aria-hidden="true" className="size-4 text-primary" />
+        ) : (
+          <Copy aria-hidden="true" className="size-4" />
+        )}
+        <span aria-live="polite">{copied ? "Copied" : "Copy"}</span>
+      </button>
+    </div>
+  );
+}

package/template/apps/start/src/components/theme/theme-provider.tsx

@@ -0,0 +1,41 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+
+type Theme = "light" | "dark";
+
+type ThemeContextValue = {
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setThemeState] = useState<Theme>("light");
+
+  useEffect(() => {
+    setThemeState(document.documentElement.classList.contains("dark") ? "dark" : "light");
+  }, []);
+
+  const setTheme = useCallback((nextTheme: Theme) => {
+    document.documentElement.classList.toggle("dark", nextTheme === "dark");
+    document.documentElement.style.colorScheme = nextTheme;
+    try {
+      window.localStorage.setItem("clubedge-theme", nextTheme);
+    } catch {
+      // Keep the in-memory theme usable when browser storage is unavailable.
+    }
+    setThemeState(nextTheme);
+  }, []);
+
+  const value = useMemo(() => ({ theme, setTheme }), [theme, setTheme]);
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error("useTheme must be used within ThemeProvider.");
+  }
+  return context;
+}

package/template/apps/start/src/components/theme/theme-toggle.tsx

@@ -0,0 +1,21 @@
+import { Moon, Sun } from "lucide-react";
+
+import { Switch } from "@clubedge/ui/components/switch";
+import { useTheme } from "./theme-provider";
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <div className="flex items-center gap-2">
+      <Sun aria-hidden="true" className="size-4 text-muted-foreground" />
+      <Switch
+        aria-label="Toggle dark theme"
+        checked={theme === "dark"}
+        onCheckedChange={(checked) => setTheme(checked ? "dark" : "light")}
+      />
+      <Moon aria-hidden="true" className="size-4 text-muted-foreground" />
+      <span className="sr-only">Theme: {theme}</span>
+    </div>
+  );
+}

package/template/apps/start/src/config/site.json

@@ -0,0 +1,11 @@
+{
+  "name": "Clubedge Starter",
+  "shortName": "Clubedge",
+  "description": "A production-minded foundation for Clubedge applications.",
+  "serviceId": "clubedge-starter",
+  "workspaceLabel": "Starter workspace",
+  "links": {
+    "repository": "https://github.com/Clubedge/clubedge-starter",
+    "setupGuide": "https://github.com/Clubedge/clubedge-starter/blob/main/SETUP.md"
+  }
+}

package/template/apps/start/src/config/site.ts

@@ -0,0 +1,20 @@
+import site from "./site.json";
+
+/**
+ * Project identity. Values live in site.json so tooling such as create-clubedge-app
+ * can rename a project by editing data instead of rewriting source files.
+ */
+export interface SiteConfig {
+  name: string;
+  shortName: string;
+  description: string;
+  /** Machine-readable service name reported by health checks and logs. */
+  serviceId: string;
+  workspaceLabel: string;
+  links: {
+    repository: string;
+    setupGuide: string;
+  };
+}
+
+export const siteConfig: SiteConfig = site;