create-skit 0.1.0

package/templates/base-web/src/app/llms.txt/route.ts

@@ -0,0 +1,59 @@
+export function GET() {
+  const content = `# __PROJECT_NAME__
+
+> Built with Skit — opinionated Next.js 16 SaaS starter.
+
+## Tech Stack
+
+- Next.js 16 (App Router, React 19, TypeScript 5.9)
+- Drizzle ORM + PostgreSQL
+- Better Auth (email/password__AUTH_LLMS_EXTRA__)
+- Tailwind CSS 4
+- __BILLING_LLMS_LINE__
+- __EMAIL_LLMS_LINE__
+- Vitest + Playwright testing
+- ESLint 9, Prettier
+
+## Structure
+
+- src/app/ — Next.js pages (App Router)
+- src/lib/ — shared utilities (auth, db, billing, email, env)
+- src/db/ — Drizzle schema and seeds
+- AGENTS.md — AI agent rules
+- ARCHITECTURE.md — project architecture
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| src/lib/auth.ts | Better Auth server config |
+| src/lib/db.ts | Drizzle client |
+| src/lib/billing.ts | Billing provider |
+| src/lib/email.ts | Email client |
+| src/lib/env.ts | Environment validation |
+| src/middleware.ts | Route protection |
+| drizzle.config.ts | Drizzle Kit config |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| pnpm dev | Start dev server |
+| pnpm build | Production build |
+| pnpm lint | Lint with ESLint |
+| pnpm typecheck | TypeScript check |
+| pnpm test | Unit tests (Vitest) |
+| pnpm test:e2e | E2E tests (Playwright) |
+| pnpm db:push | Push schema to database |
+| pnpm db:seed | Seed demo data |
+| pnpm db:studio | Open Drizzle Studio |
+
+## Full Documentation
+
+See /llms-full.txt for the complete project context.
+`;
+
+  return new Response(content, {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  });
+}

package/templates/base-web/src/app/loading.tsx

@@ -0,0 +1,24 @@
+export default function Loading() {
+  return (
+    <main
+      style={{
+        display: "grid",
+        placeItems: "center",
+        minHeight: "100dvh",
+        background: "var(--bg, #09090b)"
+      }}
+    >
+      <div
+        style={{
+          width: 32,
+          height: 32,
+          border: "3px solid var(--border, rgba(255,255,255,0.06))",
+          borderTopColor: "var(--accent, #00d4aa)",
+          borderRadius: "50%",
+          animation: "spin 0.6s linear infinite"
+        }}
+      />
+      <style>{`@keyframes spin { to { transform: rotate(360deg) } }`}</style>
+    </main>
+  );
+}

package/templates/base-web/src/app/not-found.tsx

@@ -0,0 +1,16 @@
+import Link from "next/link";
+
+export default function NotFound() {
+  return (
+    <main className="shell">
+      <section className="hero">
+        <p className="eyebrow">404</p>
+        <h1>Page not found</h1>
+        <p className="lede">The page you are looking for does not exist or has been moved.</p>
+        <div className="hero-actions">
+          <Link href="/">Go home</Link>
+        </div>
+      </section>
+    </main>
+  );
+}

package/templates/base-web/src/app/page.tsx

@@ -0,0 +1,5 @@
+import Link from "next/link";
+
+export default function HomePage() {
+  return __HOME_PAGE_CONTENT__;
+}

package/templates/base-web/src/app/sign-in/page.tsx

@@ -0,0 +1,14 @@
+import { redirect } from "next/navigation";
+
+import { EmailAuthForm } from "@/components/auth/email-auth-form";
+import { getSession } from "@/lib/auth-session";
+
+export default async function SignInPage() {
+  const session = await getSession();
+
+  if (session) {
+    redirect("/dashboard");
+  }
+
+  return <EmailAuthForm mode="sign-in" />;
+}

package/templates/base-web/src/app/sign-up/page.tsx

@@ -0,0 +1,14 @@
+import { redirect } from "next/navigation";
+
+import { EmailAuthForm } from "@/components/auth/email-auth-form";
+import { getSession } from "@/lib/auth-session";
+
+export default async function SignUpPage() {
+  const session = await getSession();
+
+  if (session) {
+    redirect("/dashboard");
+  }
+
+  return <EmailAuthForm mode="sign-up" />;
+}

package/templates/base-web/src/components/auth/email-auth-form.test.tsx

@@ -0,0 +1,40 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { EmailAuthForm } from "@/components/auth/email-auth-form";
+
+import type { ReactNode } from "react";
+
+vi.mock("next/link", () => ({
+  default: ({ children, href }: { children: ReactNode; href: string }) => (
+    <a href={href}>{children}</a>
+  )
+}));
+
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({
+    push: vi.fn(),
+    refresh: vi.fn()
+  })
+}));
+
+vi.mock("@/lib/auth-client", () => ({
+  authClient: {
+    signIn: {
+      email: vi.fn()
+    },
+    signUp: {
+      email: vi.fn()
+    }
+  }
+}));
+
+describe("EmailAuthForm", () => {
+  it("renders preset-specific auth form copy", () => {
+    render(<EmailAuthForm mode="__AUTH_FORM_TEST_MODE__" />);
+
+    expect(screen.getByRole("heading", { name: /__AUTH_FORM_TEST_HEADING__/i })).toBeTruthy();
+    expect(screen.getByLabelText(/__AUTH_FORM_TEST_LABEL__/i)).toBeTruthy();
+__AUTH_SOCIAL_TEST_ASSERTION__
+  });
+});

package/templates/base-web/src/components/auth/email-auth-form.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+
+import { authClient } from "@/lib/auth-client";
+
+type EmailAuthFormProps = {
+  mode: "sign-in" | "sign-up";
+};
+
+export function EmailAuthForm({ mode }: EmailAuthFormProps) {
+  const isSignUp = mode === "sign-up";
+  const router = useRouter();
+  const [error, setError] = useState<string | null>(null);
+  const [isPending, setIsPending] = useState(false);
+  const [showPassword, setShowPassword] = useState(false);
+__AUTH_SOCIAL_BUTTON_HANDLER__
+
+  async function handleSubmit(formData: FormData) {
+    const email = String(formData.get("email") ?? "");
+    const password = String(formData.get("password") ?? "");
+    const name = String(formData.get("name") ?? "");
+
+    setIsPending(true);
+    setError(null);
+
+    try {
+      const result = isSignUp
+        ? await authClient.signUp.email({ email, password, name })
+        : await authClient.signIn.email({ email, password });
+
+      if (result.error) {
+        setError(result.error.message ?? "Authentication failed.");
+        return;
+      }
+
+      router.push("/dashboard");
+      router.refresh();
+    } catch {
+      setError("Authentication failed.");
+    } finally {
+      setIsPending(false);
+    }
+  }
+
+  return (
+    <div className="auth-container">
+      <div className="auth-card">
+        <div className="auth-brand">__PROJECT_NAME__</div>
+
+        <div className="auth-header">
+          <h1>{isSignUp ? "__AUTH_FORM_SIGN_UP_HEADING__" : "__AUTH_FORM_SIGN_IN_HEADING__"}</h1>
+          <p>{isSignUp ? "__AUTH_FORM_SIGN_UP_LEDE__" : "__AUTH_FORM_SIGN_IN_LEDE__"}</p>
+        </div>
+__AUTH_SOCIAL_BUTTON__
+
+        <div className="auth-tabs">
+          <Link href="/sign-in" className={`auth-tab ${!isSignUp ? "active" : ""}`}>
+            Sign in
+          </Link>
+          <Link href="/sign-up" className={`auth-tab ${isSignUp ? "active" : ""}`}>
+            Sign up
+          </Link>
+        </div>
+
+        <form
+          action={(formData) => { void handleSubmit(formData); }}
+          className="auth-form"
+        >
+          {isSignUp ? (
+            <label className="auth-field">
+              <span className="auth-label">NAME</span>
+              <div className="auth-input-wrap">
+                <svg className="auth-icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.5"><circle cx="10" cy="7" r="3.5" /><path d="M3.5 17.5c0-3.5 2.9-6 6.5-6s6.5 2.5 6.5 6" /></svg>
+                <input name="name" type="text" placeholder="Ada Lovelace" required />
+              </div>
+            </label>
+          ) : null}
+
+          <label className="auth-field">
+            <span className="auth-label">EMAIL</span>
+            <div className="auth-input-wrap">
+              <svg className="auth-icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.5"><rect x="2" y="4" width="16" height="12" rx="2" /><path d="M2 6l8 5 8-5" /></svg>
+              <input name="email" type="email" placeholder="you@example.com" required />
+            </div>
+          </label>
+
+          <label className="auth-field">
+            <span className="auth-label">PASSWORD</span>
+            <div className="auth-input-wrap">
+              <svg className="auth-icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.5"><rect x="4" y="9" width="12" height="8" rx="2" /><path d="M7 9V6a3 3 0 016 0v3" /></svg>
+              <input
+                name="password"
+                type={showPassword ? "text" : "password"}
+                placeholder="At least 8 characters"
+                minLength={8}
+                required
+              />
+              <button
+                type="button"
+                className="auth-toggle-pw"
+                onClick={() => setShowPassword(!showPassword)}
+                tabIndex={-1}
+              >
+                {showPassword ? (
+                  <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.5"><path d="M3 10s3-5 7-5 7 5 7 5-3 5-7 5-7-5-7-5z" /><circle cx="10" cy="10" r="2.5" /></svg>
+                ) : (
+                  <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.5"><path d="M3 10s3-5 7-5 7 5 7 5-3 5-7 5-7-5-7-5z" /><circle cx="10" cy="10" r="2.5" /><line x1="3" y1="17" x2="17" y2="3" /></svg>
+                )}
+              </button>
+            </div>
+          </label>
+
+          {error ? <p className="form-error">{error}</p> : null}
+
+          <button type="submit" className="auth-submit" disabled={isPending}>
+            {isPending ? "Working..." : isSignUp ? "Create account" : "Sign in"}{" "}
+            {!isPending && <span className="auth-submit-arrow">→</span>}
+          </button>
+        </form>
+
+        <p className="auth-footer">secured by better-auth</p>
+      </div>
+    </div>
+  );
+}

package/templates/base-web/src/components/auth/sign-out-button.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+
+import { authClient } from "@/lib/auth-client";
+
+export function SignOutButton() {
+  const router = useRouter();
+  const [isPending, setIsPending] = useState(false);
+
+  async function handleSignOut() {
+    setIsPending(true);
+
+    try {
+      await authClient.signOut();
+      router.push("/sign-in");
+      router.refresh();
+    } finally {
+      setIsPending(false);
+    }
+  }
+
+  return (
+    <button type="button" className="__SIGN_OUT_BUTTON_CLASS__" onClick={() => void handleSignOut()}>
+      {isPending ? "Signing out..." : "Sign out"}
+    </button>
+  );
+}

package/templates/base-web/src/db/index.ts

@@ -0,0 +1,16 @@
+import "server-only";
+
+import { drizzle } from "__DRIZZLE_DRIVER_IMPORT__";
+__DATABASE_CLIENT_IMPORT__
+
+import { env } from "@/lib/env";
+
+__DATABASE_GLOBAL_BLOCK__
+
+const client = __DATABASE_CLIENT_EXPRESSION__;
+
+if (env.NODE_ENV !== "production") {
+__DATABASE_DEV_CACHE__
+}
+
+export const db = __DATABASE_DRIZZLE_EXPRESSION__;

package/templates/base-web/src/db/schema/auth.ts

@@ -0,0 +1,4 @@
+// This file is intentionally minimal.
+// Run `pnpm auth:generate` to replace it with Better Auth's generated Drizzle schema.
+
+export {};

package/templates/base-web/src/db/schema/index.ts

@@ -0,0 +1,2 @@
+export * from "./auth";
+export * from "./projects";

package/templates/base-web/src/db/schema/projects.ts

@@ -0,0 +1,17 @@
+import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+export const projects = pgTable("projects", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  slug: text("slug").notNull().unique(),
+  createdAt: timestamp("created_at", {
+    withTimezone: true
+  })
+    .defaultNow()
+    .notNull(),
+  updatedAt: timestamp("updated_at", {
+    withTimezone: true
+  })
+    .defaultNow()
+    .notNull()
+});

package/templates/base-web/src/db/seeds/index.ts

@@ -0,0 +1,32 @@
+import { db } from "@/db";
+import { projects } from "@/db/schema";
+
+const shouldSeedDemoData = ["yes"].includes("__SEED_DEMO_DATA__");
+
+async function main() {
+  if (!shouldSeedDemoData) {
+    console.log("Demo seed data disabled.");
+    return;
+  }
+
+  await db
+    .insert(projects)
+    .values({
+      id: "project-demo",
+      name: "Demo Project",
+      slug: "demo-project"
+    })
+    .onConflictDoNothing();
+
+  console.log("Demo application data seed complete.");
+  console.log("Note: auth users are not created by db:seed. Sign up through Better Auth flows.");
+}
+
+main().catch((error) => {
+  console.error("Database seed failed.");
+  console.error(
+    "Make sure PostgreSQL is running, DATABASE_URL is set, and schema migrations have been applied first."
+  );
+  console.error(error);
+  process.exit(1);
+});

package/templates/base-web/src/lib/auth-client.ts

@@ -0,0 +1,5 @@
+"use client";
+
+import { createAuthClient } from "better-auth/react";
+
+export const authClient = createAuthClient();

package/templates/base-web/src/lib/auth-session.ts

@@ -0,0 +1,21 @@
+import "server-only";
+
+import { headers } from "next/headers";
+
+import { auth } from "./auth";
+import { env } from "./env";
+
+export async function getSession() {
+  try {
+    return await auth.api.getSession({
+      headers: await headers()
+    });
+  } catch (error) {
+    if (env.NODE_ENV !== "production") {
+      console.warn("Better Auth session lookup failed. Falling back to anonymous mode.", error);
+      return null;
+    }
+
+    throw error;
+  }
+}

package/templates/base-web/src/lib/auth.ts

@@ -0,0 +1,23 @@
+import "server-only";
+
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+
+import { db } from "../db";
+import { env } from "./env";
+import * as schema from "../db/schema";
+
+export const auth = betterAuth({
+  appName: "__PROJECT_NAME__",
+  baseURL: env.BETTER_AUTH_URL,
+  secret: env.BETTER_AUTH_SECRET,
+  trustedOrigins: [env.NEXT_PUBLIC_APP_URL],
+  database: drizzleAdapter(db, {
+    provider: "pg",
+    schema
+  }),
+  emailAndPassword: {
+    enabled: true,
+    autoSignIn: true
+  }__AUTH_SOCIAL_PROVIDERS_BLOCK__
+});

package/templates/base-web/src/lib/billing/index.ts

@@ -0,0 +1,37 @@
+import "server-only";
+
+import { env } from "@/lib/env";
+
+__BILLING_PROVIDER_IMPORTS__
+
+import type { BillingProvider, BillingProviderName } from "./types";
+
+export function getBillingProviderName(input?: string): BillingProviderName {
+  if (input === "stripe" || input === "polar") {
+    return input;
+  }
+
+  if (env.BILLING_PROVIDER === "stripe" || env.BILLING_PROVIDER === "polar") {
+    return env.BILLING_PROVIDER;
+  }
+
+  if (env.BILLING_PROVIDER === "both") {
+    return "stripe";
+  }
+
+  throw new Error("Billing is disabled for this project.");
+}
+
+export function getBillingProvider(input?: string): BillingProvider {
+  const provider = getBillingProviderName(input);
+  const billingProviderFactories: Partial<Record<BillingProviderName, () => BillingProvider>> = {
+__BILLING_PROVIDER_FACTORIES__
+  };
+  const factory = billingProviderFactories[provider];
+
+  if (!factory) {
+    throw new Error(`Billing provider is not installed: ${provider}.`);
+  }
+
+  return factory();
+}

package/templates/base-web/src/lib/billing/providers/polar.ts

@@ -0,0 +1,80 @@
+import "server-only";
+
+import { env } from "@/lib/env";
+
+import type {
+  BillingProvider,
+  CheckoutSessionInput,
+  PortalSessionInput,
+  WebhookInput
+} from "../types";
+
+function getPolarApiBaseUrl() {
+  return env.POLAR_SERVER === "production"
+    ? "https://api.polar.sh/v1"
+    : "https://sandbox-api.polar.sh/v1";
+}
+
+async function polarFetch<T>(pathname: string, body: Record<string, unknown>) {
+  if (!env.POLAR_ACCESS_TOKEN) {
+    throw new Error("POLAR_ACCESS_TOKEN is required for Polar billing.");
+  }
+
+  const response = await fetch(`${getPolarApiBaseUrl()}${pathname}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${env.POLAR_ACCESS_TOKEN}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+
+  if (!response.ok) {
+    const message = await response.text();
+    throw new Error(`Polar request failed: ${message}`);
+  }
+
+  return (await response.json()) as T;
+}
+
+export class PolarBillingProvider implements BillingProvider {
+  async createCheckoutSession(input: CheckoutSessionInput) {
+    if (!env.POLAR_PRODUCT_ID) {
+      throw new Error("POLAR_PRODUCT_ID is required for Polar checkout.");
+    }
+
+    const checkout = await polarFetch<{ url?: string }>("/checkouts", {
+      products: [env.POLAR_PRODUCT_ID],
+      external_customer_id: input.userId,
+      customer_email: input.customerEmail,
+      success_url: input.successUrl,
+      metadata: {
+        userId: input.userId
+      }
+    });
+
+    if (!checkout.url) {
+      throw new Error("Polar did not return a checkout URL.");
+    }
+
+    return { url: checkout.url };
+  }
+
+  async createCustomerPortalSession(input: PortalSessionInput) {
+    const session = await polarFetch<{ customer_portal_url?: string }>("/customer-sessions/", {
+      external_customer_id: input.userId
+    });
+
+    if (!session.customer_portal_url) {
+      throw new Error("Polar did not return a customer portal URL.");
+    }
+
+    return { url: session.customer_portal_url };
+  }
+
+  async handleWebhook(_input: WebhookInput) {
+    throw new Error(
+      "Polar webhook verification is intentionally left for follow-up implementation after confirming your webhook signing strategy."
+    );
+  }
+}

package/templates/base-web/src/lib/billing/providers/stripe.ts

@@ -0,0 +1,77 @@
+import "server-only";
+
+import Stripe from "stripe";
+
+import { env } from "@/lib/env";
+
+import type {
+  BillingProvider,
+  CheckoutSessionInput,
+  PortalSessionInput,
+  WebhookInput
+} from "../types";
+
+let stripeClient: Stripe | null = null;
+
+function getStripe() {
+  if (!env.STRIPE_SECRET_KEY) {
+    throw new Error("STRIPE_SECRET_KEY is required for Stripe billing.");
+  }
+
+  stripeClient ??= new Stripe(env.STRIPE_SECRET_KEY);
+  return stripeClient;
+}
+
+export class StripeBillingProvider implements BillingProvider {
+  async createCheckoutSession(input: CheckoutSessionInput) {
+    if (!env.STRIPE_PRICE_ID) {
+      throw new Error("STRIPE_PRICE_ID is required for Stripe checkout.");
+    }
+
+    const stripe = getStripe();
+    const session = await stripe.checkout.sessions.create({
+      mode: "subscription",
+      line_items: [
+        {
+          price: env.STRIPE_PRICE_ID,
+          quantity: 1
+        }
+      ],
+      customer_email: input.customerEmail,
+      success_url: input.successUrl,
+      cancel_url: input.cancelUrl,
+      allow_promotion_codes: true,
+      metadata: {
+        userId: input.userId
+      }
+    });
+
+    if (!session.url) {
+      throw new Error("Stripe did not return a checkout URL.");
+    }
+
+    return { url: session.url };
+  }
+
+  async createCustomerPortalSession(
+    _input: PortalSessionInput
+  ): Promise<{ url: string }> {
+    throw new Error(
+      "Stripe portal requires a persisted Stripe customer ID. Add customer mapping before enabling portal access."
+    );
+  }
+
+  async handleWebhook(input: WebhookInput) {
+    if (!env.STRIPE_WEBHOOK_SECRET) {
+      throw new Error("STRIPE_WEBHOOK_SECRET is required for Stripe webhooks.");
+    }
+
+    const signature = input.headers.get("stripe-signature");
+    if (!signature) {
+      throw new Error("Missing Stripe signature header.");
+    }
+
+    const stripe = getStripe();
+    stripe.webhooks.constructEvent(input.rawBody, signature, env.STRIPE_WEBHOOK_SECRET);
+  }
+}