@clubedge/create-clubedge-app 0.2.0 → 0.3.0

package/template/apps/web/src/app/page.tsx

@@ -0,0 +1,229 @@
+import { ArrowRight, ArrowUpRight, Github, LayoutDashboard } from "lucide-react";
+import Link from "next/link";
+
+import { Button } from "@clubedge/ui/components/button";
+import { ClubedgeMark } from "@/components/branding/clubedge-mark";
+import { CopyCommand } from "@/components/landing/copy-command";
+import { siteConfig } from "@/config/site";
+import { ThemeToggle } from "./theme-toggle";
+
+const REPO_URL = siteConfig.links.repository;
+const SETUP_URL = siteConfig.links.setupGuide;
+const CREATE_COMMAND = "pnpm dlx @clubedge/create-clubedge-app my-app";
+
+const included = [
+  {
+    name: "Next.js",
+    detail: "An App Router web app in apps/web, with server components by default.",
+  },
+  {
+    name: "Supabase Auth",
+    detail:
+      "Email and password sign-in, with sessions verified on the server and stored in secure cookies.",
+  },
+  {
+    name: "Drizzle and PostgreSQL",
+    detail: "Typed data access that you can extend or swap for your own infrastructure.",
+  },
+  {
+    name: "Base UI design system",
+    detail: "Shared, accessible components in @clubedge/ui, used across the whole repo.",
+  },
+  {
+    name: "TypeScript",
+    detail: "Typed from the database layer through to the UI.",
+  },
+  {
+    name: "Dashboard",
+    detail: "A starting point for your product, ready to open at /dashboard.",
+  },
+];
+
+const steps = [
+  "Create your project with the command above.",
+  "Add your Supabase URL and publishable key to apps/web/.env.local.",
+  "Start the app, create an account, and sign in.",
+];
+
+export default function LandingPage() {
+  return (
+    <div className="flex min-h-svh flex-col">
+      <header className="sticky top-0 z-20 border-b bg-background/85 backdrop-blur-xl">
+        <nav
+          aria-label="Main navigation"
+          className="mx-auto flex h-16 max-w-6xl items-center justify-between gap-4 px-4 sm:px-6 lg:px-8"
+        >
+          <Link
+            aria-label={`${siteConfig.name} home`}
+            className="flex shrink-0 items-center gap-2.5 rounded-md outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            href="/"
+          >
+            <ClubedgeMark alt="" className="size-9 rounded-xl" priority />
+            <span className="hidden text-sm font-semibold tracking-tight min-[380px]:inline">
+              {siteConfig.name}
+            </span>
+          </Link>
+
+          <div className="hidden items-center gap-6 text-sm text-muted-foreground md:flex">
+            <a className="transition-colors hover:text-foreground" href="#stack">
+              Stack
+            </a>
+            <Link
+              className="inline-flex items-center gap-1 transition-colors hover:text-foreground"
+              href={SETUP_URL}
+              rel="noreferrer"
+              target="_blank"
+            >
+              Documentation <ArrowUpRight aria-hidden="true" className="size-3.5" />
+            </Link>
+            <Link
+              className="transition-colors hover:text-foreground"
+              href={REPO_URL}
+              rel="noreferrer"
+              target="_blank"
+            >
+              GitHub
+            </Link>
+          </div>
+
+          <div className="flex shrink-0 items-center gap-2 sm:gap-3">
+            <ThemeToggle />
+            <Button
+              aria-label="Go to dashboard"
+              className="sm:hidden"
+              render={<Link href="/dashboard" />}
+              size="icon"
+              variant="ghost"
+            >
+              <LayoutDashboard aria-hidden="true" />
+            </Button>
+            <Button
+              className="hidden sm:inline-flex"
+              render={<Link href="/dashboard" />}
+              size="sm"
+              variant="ghost"
+            >
+              Dashboard
+            </Button>
+            <Button render={<Link href="/login" />} size="sm">
+              Sign in
+            </Button>
+          </div>
+        </nav>
+      </header>
+
+      <main className="flex-1">
+        <section className="mx-auto w-full max-w-6xl px-4 pb-16 pt-16 sm:px-6 sm:pb-24 sm:pt-24 lg:px-8">
+          <div className="max-w-3xl">
+            <h1 className="text-balance text-4xl font-semibold tracking-tight sm:text-5xl lg:text-6xl">
+              Start with the foundation. Build what matters.
+            </h1>
+            <p className="mt-6 max-w-2xl text-pretty text-base leading-7 text-muted-foreground sm:text-lg sm:leading-8">
+              A modular Next.js starter with a shared Base UI design system, typed data access, and
+              replaceable infrastructure. Spend your time on the product, not the setup.
+            </p>
+
+            <div className="mt-8 max-w-xl">
+              <CopyCommand command={CREATE_COMMAND} />
+            </div>
+
+            <div className="mt-6 flex flex-col gap-3 sm:flex-row">
+              <Button className="h-11 px-5" render={<Link href="/dashboard" />}>
+                Explore the dashboard <ArrowRight aria-hidden="true" />
+              </Button>
+              <Button
+                className="h-11 px-5"
+                render={<Link href={SETUP_URL} rel="noreferrer" target="_blank" />}
+                variant="outline"
+              >
+                Read the setup guide <ArrowUpRight aria-hidden="true" />
+              </Button>
+            </div>
+          </div>
+        </section>
+
+        <section
+          aria-labelledby="stack-heading"
+          className="scroll-mt-16 border-t bg-muted/30"
+          id="stack"
+        >
+          <div className="mx-auto w-full max-w-6xl px-4 py-16 sm:px-6 sm:py-20 lg:px-8">
+            <h2 className="text-2xl font-semibold tracking-tight" id="stack-heading">
+              What you get
+            </h2>
+            <p className="mt-2 max-w-xl text-sm leading-6 text-muted-foreground">
+              Every layer is wired together and replaceable, so you can keep what fits and change
+              the rest.
+            </p>
+
+            <dl className="mt-10 grid gap-px overflow-hidden rounded-xl border bg-border sm:grid-cols-2 lg:grid-cols-3">
+              {included.map((item) => (
+                <div className="bg-background p-6" key={item.name}>
+                  <dt className="text-sm font-semibold">{item.name}</dt>
+                  <dd className="mt-2 text-sm leading-6 text-muted-foreground">{item.detail}</dd>
+                </div>
+              ))}
+            </dl>
+          </div>
+        </section>
+
+        <section
+          aria-labelledby="start-heading"
+          className="mx-auto w-full max-w-6xl px-4 py-16 sm:px-6 sm:py-20 lg:px-8"
+        >
+          <h2 className="text-2xl font-semibold tracking-tight" id="start-heading">
+            Up and running in three steps
+          </h2>
+          <ol className="mt-8 grid max-w-2xl gap-5">
+            {steps.map((step, index) => (
+              <li className="flex items-start gap-4" key={step}>
+                <span
+                  aria-hidden="true"
+                  className="grid size-7 shrink-0 place-items-center rounded-full border text-xs font-medium text-muted-foreground"
+                >
+                  {index + 1}
+                </span>
+                <p className="pt-0.5 text-sm leading-6">{step}</p>
+              </li>
+            ))}
+          </ol>
+          <div className="mt-8">
+            <Button
+              render={<Link href={SETUP_URL} rel="noreferrer" target="_blank" />}
+              variant="outline"
+            >
+              Read the full setup guide <ArrowUpRight aria-hidden="true" />
+            </Button>
+          </div>
+        </section>
+      </main>
+
+      <footer className="border-t">
+        <div className="mx-auto flex max-w-6xl flex-col items-center justify-between gap-3 px-4 py-5 text-xs text-muted-foreground sm:flex-row sm:px-6 lg:px-8">
+          <span>
+            © {new Date().getFullYear()} {siteConfig.name}. Licensed under Apache-2.0.
+          </span>
+          <div className="flex items-center gap-5">
+            <Link
+              className="transition-colors hover:text-foreground"
+              href={SETUP_URL}
+              rel="noreferrer"
+              target="_blank"
+            >
+              Documentation
+            </Link>
+            <Link
+              className="inline-flex items-center gap-1.5 transition-colors hover:text-foreground"
+              href={REPO_URL}
+              rel="noreferrer"
+              target="_blank"
+            >
+              <Github aria-hidden="true" className="size-3.5" />
+              Contribute on GitHub
+            </Link>
+          </div>
+        </div>
+      </footer>
+    </div>
+  );
+}

package/template/apps/web/src/app/theme-provider.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+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/web/src/app/theme-toggle.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+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/web/src/components/branding/clubedge-mark.tsx

@@ -0,0 +1,25 @@
+import Image from "next/image";
+
+type ClubedgeMarkProps = {
+  alt?: string;
+  className?: string;
+  priority?: boolean;
+};
+
+export function ClubedgeMark({
+  alt = "Clubedge",
+  className = "size-10",
+  priority = false,
+}: ClubedgeMarkProps) {
+  return (
+    <Image
+      alt={alt}
+      className={className}
+      height={512}
+      priority={priority}
+      src="/.well-known/logo.svg"
+      unoptimized
+      width={512}
+    />
+  );
+}

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

@@ -0,0 +1,48 @@
+"use client";
+
+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/web/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/web/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;

package/template/apps/web/src/env/client.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+const clientSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.url().default("http://localhost:3000"),
+  NEXT_PUBLIC_SUPABASE_URL: z.url().optional().or(z.literal("")),
+  NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: z.string().optional().or(z.literal("")),
+});
+
+const parsed = clientSchema.safeParse({
+  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+  NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
+  NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY,
+});
+
+if (!parsed.success) {
+  throw new Error("Client environment validation failed. Check your NEXT_PUBLIC_* variables.");
+}
+
+export const clientEnv = parsed.data;
+export const hasSupabaseAuthConfig = Boolean(
+  clientEnv.NEXT_PUBLIC_SUPABASE_URL && clientEnv.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY,
+);

package/template/apps/web/src/env/server.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+async function loadFreshModule() {
+  vi.resetModules();
+  return import("./server");
+}
+
+describe("getServerEnv", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("does not validate at import time", async () => {
+    vi.stubEnv("DATABASE_URL", "");
+    await expect(loadFreshModule()).resolves.toBeDefined();
+  });
+
+  it("throws on first use when required variables are missing", async () => {
+    vi.stubEnv("DATABASE_URL", "");
+    const { getServerEnv } = await loadFreshModule();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    expect(() => getServerEnv()).toThrow("Server environment validation failed");
+  });
+
+  it("parses and applies defaults once variables are present", async () => {
+    vi.stubEnv("DATABASE_URL", "postgresql://localhost/app");
+    vi.stubEnv("STORAGE_PROVIDER", undefined);
+    const { getServerEnv } = await loadFreshModule();
+    expect(getServerEnv()).toMatchObject({
+      DATABASE_URL: "postgresql://localhost/app",
+      STORAGE_PROVIDER: "s3",
+      STORAGE_REGION: "auto",
+    });
+  });
+});

package/template/apps/web/src/env/server.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+const serverSchema = z.object({
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  DATABASE_URL: z.string().min(1, "DATABASE_URL is required"),
+  REDIS_URL: z
+    .url({ protocol: /^rediss?$/ })
+    .optional()
+    .or(z.literal("")),
+  STORAGE_PROVIDER: z.enum(["s3", "supabase"]).default("s3"),
+  STORAGE_BUCKET: z.string().optional().or(z.literal("")),
+  STORAGE_REGION: z.string().default("auto"),
+  STORAGE_ENDPOINT: z.url().optional().or(z.literal("")),
+  STORAGE_ACCESS_KEY_ID: z.string().optional().or(z.literal("")),
+  STORAGE_SECRET_ACCESS_KEY: z.string().optional().or(z.literal("")),
+  STORAGE_PUBLIC_URL: z.url().optional().or(z.literal("")),
+  SUPABASE_STORAGE_BUCKET: z.string().optional().or(z.literal("")),
+});
+
+export type ServerEnv = z.infer<typeof serverSchema>;
+
+let cached: ServerEnv | undefined;
+
+/**
+ * Validates server variables on first use rather than at import, so pages that never touch
+ * the database or providers can build and render without them.
+ */
+export function getServerEnv(): ServerEnv {
+  if (cached) return cached;
+
+  const parsed = serverSchema.safeParse(process.env);
+  if (!parsed.success) {
+    console.error("Invalid server environment:", z.treeifyError(parsed.error));
+    throw new Error("Server environment validation failed. Check your .env.local file.");
+  }
+  cached = parsed.data;
+  return cached;
+}
+
+/** Validates only REDIS_URL, so cache and rate limiting work without the rest of the env. */
+export function getRedisUrl(): string | undefined {
+  const parsed = serverSchema.shape.REDIS_URL.safeParse(process.env.REDIS_URL);
+  if (!parsed.success) throw new Error("REDIS_URL must be a redis:// or rediss:// URL.");
+  return parsed.data || undefined;
+}

package/template/apps/web/src/lib/login-url.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { loginUrl } from "./login-url";
+
+describe("loginUrl", () => {
+  it("builds the plain login path", () => {
+    expect(loginUrl()).toBe("/login");
+  });
+
+  it("omits the default destination and encodes everything else", () => {
+    expect(loginUrl({ next: "/dashboard" })).toBe("/login");
+    expect(loginUrl({ mode: "signup", error: "invalid-input", next: "/a?b=c" })).toBe(
+      "/login?mode=signup&error=invalid-input&next=%2Fa%3Fb%3Dc",
+    );
+    expect(loginUrl({ mode: "signup", checkEmail: true })).toBe("/login?mode=signup&check-email=1");
+  });
+});

package/template/apps/web/src/lib/login-url.ts

@@ -0,0 +1,16 @@
+type LoginUrlOptions = {
+  mode?: "signin" | "signup";
+  error?: string;
+  next?: string;
+  checkEmail?: boolean;
+};
+
+export function loginUrl({ mode = "signin", error, next, checkEmail }: LoginUrlOptions = {}) {
+  const params = new URLSearchParams();
+  if (mode === "signup") params.set("mode", "signup");
+  if (error) params.set("error", error);
+  if (checkEmail) params.set("check-email", "1");
+  if (next && next !== "/dashboard") params.set("next", next);
+  const query = params.toString();
+  return query ? `/login?${query}` : "/login";
+}

package/template/apps/web/src/lib/utils.ts

@@ -0,0 +1 @@
+export { cn } from "@clubedge/ui/lib/utils";

package/template/apps/web/src/proxy.ts

@@ -0,0 +1,31 @@
+import { NextResponse, type NextRequest } from "next/server";
+import type { CookieStore } from "@clubedge/auth";
+import { createSupabaseAuth } from "@clubedge/auth/supabase";
+import { clientEnv, hasSupabaseAuthConfig } from "@/env/client";
+
+export async function proxy(request: NextRequest) {
+  let response = NextResponse.next({ request });
+  if (!hasSupabaseAuthConfig) return response;
+
+  // Refreshed cookies must reach both the downstream request and the browser response.
+  const cookies: CookieStore = {
+    getAll: () => request.cookies.getAll(),
+    setAll(values) {
+      values.forEach(({ name, value }) => request.cookies.set(name, value));
+      response = NextResponse.next({ request });
+      values.forEach(({ name, value, options }) => response.cookies.set(name, value, options));
+    },
+  };
+
+  const auth = createSupabaseAuth({
+    url: clientEnv.NEXT_PUBLIC_SUPABASE_URL!,
+    publishableKey: clientEnv.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
+    cookies,
+  });
+  await auth.refreshSession();
+  return response;
+}
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"],
+};

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

@@ -0,0 +1,69 @@
+import "server-only";
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+import type { AuthProvider, AuthUser, CookieStore } from "@clubedge/auth";
+import { createSupabaseAuth, createSupabaseServerClient } from "@clubedge/auth/supabase";
+import { AppError } from "@clubedge/core";
+import { clientEnv, hasSupabaseAuthConfig } from "@/env/client";
+import { loginUrl } from "@/lib/login-url";
+
+export type { AuthUser } from "@clubedge/auth";
+
+export const isAuthConfigured = hasSupabaseAuthConfig;
+
+/** Bridges Next.js request cookies to the framework-agnostic CookieStore. */
+async function nextCookieStore(): Promise<CookieStore> {
+  const cookieStore = await cookies();
+  return {
+    getAll: () => cookieStore.getAll(),
+    setAll(values) {
+      try {
+        values.forEach(({ name, value, options }) => cookieStore.set(name, value, options));
+      } catch {
+        // Server Components cannot write cookies. The proxy refreshes sessions instead.
+      }
+    },
+  };
+}
+
+function supabaseConfig(cookieStore: CookieStore) {
+  if (!hasSupabaseAuthConfig) throw new Error("Supabase Auth is not configured.");
+  return {
+    url: clientEnv.NEXT_PUBLIC_SUPABASE_URL!,
+    publishableKey: clientEnv.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
+    cookies: cookieStore,
+  };
+}
+
+/** Request-scoped auth provider. Throws when authentication is not configured. */
+export async function getAuth(): Promise<AuthProvider> {
+  return createSupabaseAuth(supabaseConfig(await nextCookieStore()));
+}
+
+/** Request-scoped Supabase client for provider features such as Storage. */
+export async function getSupabaseClient() {
+  return createSupabaseServerClient(supabaseConfig(await nextCookieStore()));
+}
+
+export async function getCurrentUser(): Promise<AuthUser | null> {
+  if (!isAuthConfigured) return null;
+  return (await getAuth()).getUser();
+}
+
+/** For route handlers and server actions: 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;
+}
+
+/**
+ * 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 async function getPageUser(pathname: string): Promise<AuthUser | null> {
+  if (!isAuthConfigured) return null;
+  const user = await getCurrentUser();
+  if (!user) redirect(loginUrl({ next: pathname }));
+  return user;
+}