@clubedge/create-clubedge-app 0.3.0 → 0.4.0

package/template/apps/start/src/routes/login.tsx

@@ -0,0 +1,164 @@
+import { CircleAlert, Info, MailCheck } from "lucide-react";
+import { Link, createFileRoute } from "@tanstack/react-router";
+import type { ReactNode } from "react";
+
+import {
+  AuthForm,
+  EmailField,
+  PasswordField,
+  SubmitButton,
+} from "@/components/auth/auth-form-controls";
+import { ClubedgeMark } from "@/components/branding/clubedge-mark";
+import { siteConfig } from "@/config/site";
+import { safeRedirectPath } from "@clubedge/core";
+import { loginUrl } from "@/lib/login-url";
+import { getAuthStatus } from "@/server/auth.functions";
+import { Card, CardContent } from "@clubedge/ui/components/card";
+
+type LoginSearch = {
+  error?: string;
+  mode?: string;
+  "check-email"?: string;
+  next?: string;
+};
+
+const asString = (value: unknown) => (typeof value === "string" ? value : undefined);
+
+export const Route = createFileRoute("/login")({
+  validateSearch: (search: Record<string, unknown>): LoginSearch => ({
+    error: asString(search.error),
+    mode: asString(search.mode),
+    "check-email": asString(search["check-email"]),
+    next: asString(search.next),
+  }),
+  loader: () => getAuthStatus(),
+  component: LoginPage,
+});
+
+const errorMessages: Record<string, string> = {
+  "invalid-input": "Enter a valid email and a password with at least 8 characters.",
+  "invalid-credentials": "Those credentials could not be verified. Check your email and password.",
+  "signup-failed": "We could not create your account. Please check your details and try again.",
+  "auth-callback": "That sign-in link could not be verified. Request a new one.",
+  "rate-limited": "Too many attempts. Wait a minute and try again.",
+};
+
+type NoticeTone = "error" | "info" | "warning";
+
+const noticeStyles: Record<NoticeTone, string> = {
+  error: "border-destructive/30 bg-destructive/5 text-destructive",
+  info: "border-primary/30 bg-primary/5 text-foreground",
+  warning: "border-amber-500/30 bg-amber-500/5 text-foreground",
+};
+
+function Notice({
+  children,
+  icon,
+  role,
+  tone,
+}: {
+  children: ReactNode;
+  icon: ReactNode;
+  role: "alert" | "status";
+  tone: NoticeTone;
+}) {
+  return (
+    <div
+      className={`flex items-start gap-2.5 rounded-lg border px-3.5 py-3 text-sm leading-5 ${noticeStyles[tone]}`}
+      role={role}
+    >
+      <span aria-hidden="true" className="mt-0.5 shrink-0 [&>svg]:size-4">
+        {icon}
+      </span>
+      <div className="min-w-0">{children}</div>
+    </div>
+  );
+}
+
+function LoginPage() {
+  const params = Route.useSearch();
+  const { configured: hasSupabaseAuthConfig } = Route.useLoaderData();
+  const isSignUp = params.mode === "signup";
+  const error = params.error ? errorMessages[params.error] : undefined;
+  const checkEmail = Boolean(params["check-email"]);
+  const next = safeRedirectPath(params.next);
+
+  return (
+    <main className="flex min-h-svh flex-col items-center bg-background px-4 py-10 sm:justify-center">
+      <div className="w-full max-w-[26rem]">
+        <header className="mb-8 flex flex-col items-center gap-4 text-center">
+          <Link
+            aria-label={`${siteConfig.name} home`}
+            className="rounded-xl outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+            to="/"
+          >
+            <ClubedgeMark className="size-12 rounded-xl" />
+          </Link>
+          <div className="grid gap-1.5">
+            <h1 className="text-2xl font-semibold tracking-tight">
+              {isSignUp ? "Create your account" : `Sign in to ${siteConfig.shortName}`}
+            </h1>
+            <p className="text-sm text-muted-foreground">
+              {isSignUp
+                ? "Enter your email and choose a password."
+                : "Welcome back. Enter your details to continue."}
+            </p>
+          </div>
+        </header>
+
+        <Card className="rounded-xl border-border/70 p-0 shadow-sm">
+          <CardContent className="grid gap-5 p-6 sm:p-8">
+            {!hasSupabaseAuthConfig && (
+              <Notice icon={<Info />} role="status" tone="warning">
+                Authentication is not configured yet. Add your Supabase URL and publishable key to{" "}
+                <code className="rounded bg-muted px-1 py-0.5 font-mono text-xs">
+                  apps/web/.env.local
+                </code>
+                .
+              </Notice>
+            )}
+            {error && (
+              <Notice icon={<CircleAlert />} role="alert" tone="error">
+                {error}
+              </Notice>
+            )}
+            {checkEmail && (
+              <Notice icon={<MailCheck />} role="status" tone="info">
+                Account created. Check your inbox for the confirmation link to finish signing up.
+              </Notice>
+            )}
+
+            <AuthForm action={isSignUp ? "/auth/sign-up" : "/auth/sign-in"}>
+              <input name="next" type="hidden" value={next} />
+              <EmailField />
+              <PasswordField isSignUp={isSignUp} />
+              <SubmitButton disabled={!hasSupabaseAuthConfig}>
+                {isSignUp ? "Create account" : "Sign in"}
+              </SubmitButton>
+            </AuthForm>
+          </CardContent>
+        </Card>
+
+        <p className="mt-6 text-center text-sm text-muted-foreground">
+          {isSignUp ? "Already have an account?" : "Don't have an account?"}{" "}
+          <a
+            className="font-medium text-foreground underline-offset-4 hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            href={loginUrl({ mode: isSignUp ? "signin" : "signup", next })}
+          >
+            {isSignUp ? "Sign in" : "Create one"}
+          </a>
+        </p>
+      </div>
+
+      <footer className="mt-10 text-center text-xs text-muted-foreground sm:absolute sm:bottom-6">
+        <Link className="underline-offset-4 hover:underline" to="/">
+          Back to home
+        </Link>
+        <span aria-hidden="true" className="mx-2">
+          |
+        </span>
+        {siteConfig.name}, Apache-2.0
+      </footer>
+    </main>
+  );
+}

package/template/apps/start/src/server/auth-forms.test.ts

@@ -0,0 +1,169 @@
+import { err, ok } from "@clubedge/core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const auth = vi.hoisted(() => ({
+  signInWithPassword: vi.fn(),
+  signUp: vi.fn(),
+  signOut: vi.fn(),
+  exchangeCodeForSession: vi.fn(),
+}));
+const state = vi.hoisted(() => ({ configured: true }));
+const limit = vi.hoisted(() => vi.fn());
+const ensureUserProfile = vi.hoisted(() => vi.fn());
+
+vi.mock("./auth", () => ({
+  getAuth: () => auth,
+  isAuthConfigured: () => state.configured,
+}));
+vi.mock("./cache", () => ({ createRateLimiter: () => ({ limit }) }));
+vi.mock("./users", () => ({ ensureUserProfile }));
+vi.mock("@/env/server", () => ({ getAppUrl: () => "https://app.example" }));
+
+const { handleAuthCallback, handleFormEndpointVisit, handleSignIn, handleSignOut, handleSignUp } =
+  await import("./auth-forms");
+
+const user = { id: "user-1", email: "ada@example.com" };
+
+function formPost(path: string, fields: Record<string, string>) {
+  return new Request(`https://app.example${path}`, {
+    method: "POST",
+    body: new URLSearchParams(fields),
+    headers: { "x-forwarded-for": "203.0.113.9" },
+  });
+}
+
+const credentials = { email: "ada@example.com", password: "correct horse" };
+
+function expectRedirect(response: Response, location: string) {
+  expect(response.status).toBe(303);
+  expect(response.headers.get("Location")).toBe(location);
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  state.configured = true;
+  limit.mockResolvedValue({ success: true });
+});
+
+describe("handleSignIn", () => {
+  it("signs in, syncs the profile, and returns to the requested page", async () => {
+    auth.signInWithPassword.mockResolvedValue(ok(user));
+    const response = await handleSignIn(
+      formPost("/auth/sign-in", { ...credentials, next: "/projects?tab=a" }),
+    );
+    expectRedirect(response, "/projects?tab=a");
+    expect(auth.signInWithPassword).toHaveBeenCalledWith(credentials);
+    expect(ensureUserProfile).toHaveBeenCalledWith(user);
+    expect(limit).toHaveBeenCalledWith("auth:sign-in:203.0.113.9");
+  });
+
+  it("never redirects off-site", async () => {
+    auth.signInWithPassword.mockResolvedValue(ok(user));
+    const response = await handleSignIn(
+      formPost("/auth/sign-in", { ...credentials, next: "https://evil.example" }),
+    );
+    expectRedirect(response, "/dashboard");
+  });
+
+  it("reports invalid input and invalid credentials", async () => {
+    expectRedirect(
+      await handleSignIn(formPost("/auth/sign-in", { email: "nope", password: "short" })),
+      "/login?error=invalid-input",
+    );
+    auth.signInWithPassword.mockResolvedValue(err("invalid-credentials"));
+    expectRedirect(
+      await handleSignIn(formPost("/auth/sign-in", credentials)),
+      "/login?error=invalid-credentials",
+    );
+    expect(ensureUserProfile).not.toHaveBeenCalled();
+  });
+
+  it("stops at the rate limit before contacting the provider", async () => {
+    limit.mockResolvedValue({ success: false });
+    const response = await handleSignIn(formPost("/auth/sign-in", { ...credentials, next: "/x" }));
+    expectRedirect(response, "/login?error=rate-limited&next=%2Fx");
+    expect(auth.signInWithPassword).not.toHaveBeenCalled();
+  });
+
+  it("fails open when the rate limiter is unavailable", async () => {
+    limit.mockRejectedValue(new Error("redis down"));
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    auth.signInWithPassword.mockResolvedValue(ok(user));
+    expectRedirect(await handleSignIn(formPost("/auth/sign-in", credentials)), "/dashboard");
+  });
+
+  it("returns to the login page while authentication is not configured", async () => {
+    state.configured = false;
+    const response = await handleSignIn(formPost("/auth/sign-in", { ...credentials, next: "/x" }));
+    expectRedirect(response, "/login?next=%2Fx");
+    expect(auth.signInWithPassword).not.toHaveBeenCalled();
+  });
+});
+
+describe("handleSignUp", () => {
+  it("sends a confirmation link that returns through the callback", async () => {
+    auth.signUp.mockResolvedValue(ok({ user, needsConfirmation: true }));
+    const response = await handleSignUp(
+      formPost("/auth/sign-up", { ...credentials, next: "/projects" }),
+    );
+    expectRedirect(response, "/login?mode=signup&check-email=1&next=%2Fprojects");
+    expect(auth.signUp).toHaveBeenCalledWith({
+      ...credentials,
+      emailRedirectTo: "https://app.example/auth/callback?next=%2Fprojects",
+    });
+    expect(ensureUserProfile).not.toHaveBeenCalled();
+  });
+
+  it("signs the user in straight away when no confirmation is required", async () => {
+    auth.signUp.mockResolvedValue(ok({ user, needsConfirmation: false }));
+    expectRedirect(await handleSignUp(formPost("/auth/sign-up", credentials)), "/dashboard");
+    expect(ensureUserProfile).toHaveBeenCalledWith(user);
+  });
+
+  it("reports provider failures", async () => {
+    auth.signUp.mockResolvedValue(err("signup-failed"));
+    expectRedirect(
+      await handleSignUp(formPost("/auth/sign-up", credentials)),
+      "/login?mode=signup&error=signup-failed",
+    );
+  });
+});
+
+describe("handleAuthCallback", () => {
+  it("exchanges the code and continues to the requested page", async () => {
+    auth.exchangeCodeForSession.mockResolvedValue(ok(user));
+    const response = await handleAuthCallback(
+      new Request("https://app.example/auth/callback?code=abc&next=%2Fprojects"),
+    );
+    expectRedirect(response, "/projects");
+    expect(auth.exchangeCodeForSession).toHaveBeenCalledWith("abc");
+    expect(ensureUserProfile).toHaveBeenCalledWith(user);
+  });
+
+  it("reports missing and invalid codes", async () => {
+    expectRedirect(
+      await handleAuthCallback(new Request("https://app.example/auth/callback")),
+      "/login?error=auth-callback",
+    );
+    auth.exchangeCodeForSession.mockResolvedValue(err("invalid-code"));
+    expectRedirect(
+      await handleAuthCallback(new Request("https://app.example/auth/callback?code=bad")),
+      "/login?error=auth-callback",
+    );
+  });
+});
+
+describe("handleSignOut and direct visits", () => {
+  it("signs out and returns to the login page, even when the provider fails", async () => {
+    expectRedirect(await handleSignOut(), "/login");
+    expect(auth.signOut).toHaveBeenCalled();
+
+    auth.signOut.mockRejectedValue(new Error("network"));
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    expectRedirect(await handleSignOut(), "/login");
+  });
+
+  it("sends direct visits to the login page", () => {
+    expectRedirect(handleFormEndpointVisit(), "/login");
+  });
+});

package/template/apps/start/src/server/auth-forms.ts

@@ -0,0 +1,118 @@
+import "@tanstack/react-start/server-only";
+import { z } from "zod";
+import { getClientIp, safeRedirectPath } from "@clubedge/core";
+import { getAppUrl } from "@/env/server";
+import { loginUrl } from "@/lib/login-url";
+import { getAuth, isAuthConfigured } from "./auth";
+import { createRateLimiter } from "./cache";
+import { ensureUserProfile } from "./users";
+
+// Form endpoints for the login page. They answer with 303 redirects, so the forms work with
+// or without JavaScript, the same way the Next.js server actions do.
+
+const credentialsSchema = z.object({
+  email: z.email(),
+  password: z.string().min(8).max(128),
+});
+
+// Ten attempts per minute per client address and action.
+const authRateLimiter = createRateLimiter(10, 60);
+
+function seeOther(location: string): Response {
+  return new Response(null, { status: 303, headers: { Location: location } });
+}
+
+/** The form endpoints have no page of their own; send direct visits to the login page. */
+export function handleFormEndpointVisit(): Response {
+  return seeOther("/login");
+}
+
+function readCredentials(formData: FormData) {
+  return credentialsSchema.safeParse({
+    email: formData.get("email"),
+    password: formData.get("password"),
+  });
+}
+
+async function isRateLimited(request: Request, action: "sign-in" | "sign-up") {
+  const ip = getClientIp(request.headers);
+  try {
+    const result = await authRateLimiter.limit(`auth:${action}:${ip}`);
+    return !result.success;
+  } catch (error) {
+    // Fail open: an unavailable limiter backend should not lock every user out.
+    console.error("Rate limiter unavailable", error);
+    return false;
+  }
+}
+
+export async function handleSignIn(request: Request): Promise<Response> {
+  const formData = await request.formData();
+  const next = safeRedirectPath(formData.get("next"));
+  // The login page explains the missing configuration; never answer a form post with a 500.
+  if (!isAuthConfigured()) return seeOther(loginUrl({ next }));
+  if (await isRateLimited(request, "sign-in")) {
+    return seeOther(loginUrl({ error: "rate-limited", next }));
+  }
+
+  const parsed = readCredentials(formData);
+  if (!parsed.success) return seeOther(loginUrl({ error: "invalid-input", next }));
+
+  const result = await getAuth().signInWithPassword(parsed.data);
+  if (!result.ok) return seeOther(loginUrl({ error: "invalid-credentials", next }));
+
+  await ensureUserProfile(result.value);
+  return seeOther(next);
+}
+
+export async function handleSignUp(request: Request): Promise<Response> {
+  const formData = await request.formData();
+  const next = safeRedirectPath(formData.get("next"));
+  if (!isAuthConfigured()) return seeOther(loginUrl({ mode: "signup", next }));
+  if (await isRateLimited(request, "sign-up")) {
+    return seeOther(loginUrl({ mode: "signup", error: "rate-limited", next }));
+  }
+
+  const parsed = readCredentials(formData);
+  if (!parsed.success) return seeOther(loginUrl({ mode: "signup", error: "invalid-input", next }));
+
+  const callbackUrl = new URL("/auth/callback", getAppUrl());
+  callbackUrl.searchParams.set("next", next);
+  const result = await getAuth().signUp({
+    ...parsed.data,
+    emailRedirectTo: callbackUrl.toString(),
+  });
+  if (!result.ok) return seeOther(loginUrl({ mode: "signup", error: "signup-failed", next }));
+  if (result.value.needsConfirmation || !result.value.user) {
+    return seeOther(loginUrl({ mode: "signup", checkEmail: true, next }));
+  }
+
+  await ensureUserProfile(result.value.user);
+  return seeOther(next);
+}
+
+export async function handleSignOut(): Promise<Response> {
+  if (!isAuthConfigured()) return seeOther("/login");
+  try {
+    await getAuth().signOut();
+  } catch (error) {
+    console.error("Sign-out failed", error);
+  }
+  return seeOther("/login");
+}
+
+export async function handleAuthCallback(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+  const code = url.searchParams.get("code");
+  const next = safeRedirectPath(url.searchParams.get("next"));
+
+  if (code && isAuthConfigured()) {
+    const result = await getAuth().exchangeCodeForSession(code);
+    if (result.ok) {
+      await ensureUserProfile(result.value);
+      return seeOther(next);
+    }
+  }
+
+  return seeOther(loginUrl({ error: "auth-callback" }));
+}

package/template/apps/start/src/server/auth.functions.ts

@@ -0,0 +1,27 @@
+import { redirect } from "@tanstack/react-router";
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
+import { safeRedirectPath } from "@clubedge/core";
+import { loginUrl } from "@/lib/login-url";
+import { getCurrentUser, isAuthConfigured } from "./auth";
+
+// Server functions are RPC endpoints that route loaders call. The build replaces their
+// bodies with network stubs in the browser bundle, so this file is safe to import anywhere.
+
+/**
+ * For pages: redirects signed-out visitors to the login page and back afterwards.
+ * Returns null while authentication is not configured so the starter stays explorable.
+ */
+export const getPageUser = createServerFn({ method: "GET" })
+  .validator(z.object({ pathname: z.string() }))
+  .handler(async ({ data }) => {
+    if (!isAuthConfigured()) return null;
+    const user = await getCurrentUser();
+    if (!user) throw redirect({ href: loginUrl({ next: safeRedirectPath(data.pathname) }) });
+    return user;
+  });
+
+/** Lets the login page explain that authentication still needs configuring. */
+export const getAuthStatus = createServerFn({ method: "GET" }).handler(() => ({
+  configured: isAuthConfigured(),
+}));

package/template/apps/start/src/server/auth.ts

@@ -0,0 +1,51 @@
+import "@tanstack/react-start/server-only";
+import type { AuthProvider, AuthUser } from "@clubedge/auth";
+import { createSupabaseAuth, createSupabaseServerClient } from "@clubedge/auth/supabase";
+import { AppError } from "@clubedge/core";
+import { getSupabaseAuthEnv } from "@/env/server";
+import { requestCookieStore } from "./cookies";
+
+export type { AuthUser } from "@clubedge/auth";
+
+export function isAuthConfigured(): boolean {
+  return getSupabaseAuthEnv() !== null;
+}
+
+function supabaseConfig() {
+  const env = getSupabaseAuthEnv();
+  if (!env) throw new Error("Supabase Auth is not configured.");
+  return { ...env, cookies: requestCookieStore() };
+}
+
+/** Request-scoped auth provider. Throws when authentication is not configured. */
+export function getAuth(): AuthProvider {
+  return createSupabaseAuth(supabaseConfig());
+}
+
+/** Request-scoped Supabase client for provider features such as Storage. */
+export async function getSupabaseClient() {
+  return createSupabaseServerClient(supabaseConfig());
+}
+
+/** Validates the session and rotates its cookies. Runs once per request from src/start.ts. */
+export async function refreshAuthSession(): Promise<void> {
+  if (!isAuthConfigured()) return;
+  try {
+    await getAuth().refreshSession();
+  } catch (error) {
+    // Pages still render; protected handlers re-check the user and reject when needed.
+    console.error("Session refresh failed", error);
+  }
+}
+
+export async function getCurrentUser(): Promise<AuthUser | null> {
+  if (!isAuthConfigured()) return null;
+  return getAuth().getUser();
+}
+
+/** For server functions and routes: throws a 401 AppError when signed out. */
+export async function requireUser(): Promise<AuthUser> {
+  const user = await getCurrentUser();
+  if (!user) throw new AppError("Authentication required.", "UNAUTHENTICATED", 401);
+  return user;
+}

package/template/apps/start/src/server/cache.ts

@@ -0,0 +1,38 @@
+import "@tanstack/react-start/server-only";
+import {
+  createRateLimiter as createLimiter,
+  createRedisCache,
+  type RateLimiter,
+} from "@clubedge/cache";
+import { getRedisUrl } from "@/env/server";
+
+export type { RateLimiter, RateLimitResult } from "@clubedge/cache";
+
+/**
+ * Uses Redis when REDIS_URL is configured, otherwise a per-process memory limiter. The
+ * backend is chosen on first use so module-level limiters do not read env at import time.
+ */
+export function createRateLimiter(requests = 10, windowSeconds = 60): RateLimiter {
+  let limiter: RateLimiter | undefined;
+  return {
+    limit(identifier) {
+      limiter ??= createLimiter({
+        requests,
+        windowSeconds,
+        redisUrl: getRedisUrl(),
+      });
+      return limiter.limit(identifier);
+    },
+  };
+}
+
+/** Cache reads miss and writes are skipped while Redis is not configured. */
+export async function cacheGet<T>(key: string): Promise<T | null> {
+  const url = getRedisUrl();
+  return url ? createRedisCache(url).get<T>(key) : null;
+}
+
+export async function cacheSet(key: string, value: unknown, ttlSeconds: number): Promise<void> {
+  const url = getRedisUrl();
+  if (url) await createRedisCache(url).set(key, value, ttlSeconds);
+}

package/template/apps/start/src/server/cookies.test.ts

@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const server = vi.hoisted(() => ({
+  request: new Request("https://app.example/"),
+  cookies: {} as Record<string, string>,
+  setCookie: vi.fn(),
+}));
+
+vi.mock("@tanstack/react-start/server", () => ({
+  getRequest: () => server.request,
+  getCookies: () => server.cookies,
+  setCookie: server.setCookie,
+}));
+
+const { requestCookieStore } = await import("./cookies");
+
+beforeEach(() => {
+  server.request = new Request("https://app.example/");
+  server.cookies = { session: "old" };
+  server.setCookie.mockClear();
+});
+
+describe("requestCookieStore", () => {
+  it("reads the request cookies", () => {
+    expect(requestCookieStore().getAll()).toEqual([{ name: "session", value: "old" }]);
+  });
+
+  it("shares writes with later readers in the same request and sends them to the browser", () => {
+    const options = { httpOnly: true, path: "/" };
+    requestCookieStore().setAll([{ name: "session", value: "new", options }]);
+
+    expect(requestCookieStore().getAll()).toEqual([{ name: "session", value: "new" }]);
+    expect(server.setCookie).toHaveBeenCalledWith("session", "new", options);
+  });
+
+  it("starts fresh for every request", () => {
+    requestCookieStore().setAll([{ name: "session", value: "new" }]);
+    server.request = new Request("https://app.example/next");
+    expect(requestCookieStore().getAll()).toEqual([{ name: "session", value: "old" }]);
+  });
+});

package/template/apps/start/src/server/cookies.ts

@@ -0,0 +1,31 @@
+import "@tanstack/react-start/server-only";
+import { getCookies, getRequest, setCookie } from "@tanstack/react-start/server";
+import type { CookieStore } from "@clubedge/auth";
+
+const jars = new WeakMap<Request, CookieStore>();
+
+/**
+ * Bridges TanStack Start request cookies to the framework-agnostic CookieStore.
+ *
+ * There is one jar per request, so a session refreshed by the request middleware is visible
+ * to the server functions and routes that run later in the same request, and every write
+ * is also sent to the browser.
+ */
+export function requestCookieStore(): CookieStore {
+  const request = getRequest();
+  const existing = jars.get(request);
+  if (existing) return existing;
+
+  const values = new Map(Object.entries(getCookies()));
+  const store: CookieStore = {
+    getAll: () => Array.from(values, ([name, value]) => ({ name, value })),
+    setAll(cookies) {
+      for (const { name, value, options } of cookies) {
+        values.set(name, value);
+        setCookie(name, value, options);
+      }
+    },
+  };
+  jars.set(request, store);
+  return store;
+}

package/template/apps/start/src/server/db.ts

@@ -0,0 +1,16 @@
+import "@tanstack/react-start/server-only";
+import { createDb, type Database } from "@clubedge/db";
+import { getServerEnv } from "@/env/server";
+
+const globalForDb = globalThis as typeof globalThis & { clubedgeDb?: Database };
+
+/** Creates the connection pool on first use and reuses it across dev hot reloads. */
+export function getDb(): Database {
+  if (globalForDb.clubedgeDb) return globalForDb.clubedgeDb;
+  const env = getServerEnv();
+  globalForDb.clubedgeDb = createDb({
+    url: env.DATABASE_URL,
+    maxConnections: env.NODE_ENV === "production" ? 10 : 1,
+  });
+  return globalForDb.clubedgeDb;
+}