feat(billing): integrate Stripe subscriptions via Better Auth (#2160)

Author: koistya

.env

@@ -57,6 +57,14 @@ GA_MEASUREMENT_ID=G-XXXXXXXX
 RESEND_API_KEY=xxxxx
 RESEND_EMAIL_FROM=onboarding@resend.dev
 
+# Stripe Billing (optional — app works without these, billing features disabled)
+# https://dashboard.stripe.com/apikeys
+# STRIPE_SECRET_KEY=sk_test_xxxxx
+# STRIPE_WEBHOOK_SECRET=whsec_xxxxx
+# STRIPE_STARTER_PRICE_ID=price_xxxxx
+# STRIPE_PRO_PRICE_ID=price_xxxxx
+# STRIPE_PRO_ANNUAL_PRICE_ID=price_xxxxx
+
 # Algolia Search
 # https://dashboard.algolia.com/account/api-keys/all
 ALGOLIA_APP_ID=xxxxx

README.md

@@ -17,7 +17,7 @@ A full-stack monorepo template for building SaaS applications with React 19, tRP
 
 - **Type-safe full stack** — TypeScript, tRPC, and Drizzle ORM create a single type contract from database to UI
 - **Edge-native** — Three Cloudflare Workers (web, app, api) connected via service bindings
-- **Auth included** — Better Auth with email OTP, passkey, Google OAuth, and organizations
+- **Auth + billing included** — Better Auth with email OTP, passkey, Google OAuth, organizations, and Stripe subscriptions
 - **Modern React** — React 19, TanStack Router (file-based), TanStack Query, Jotai, Tailwind CSS v4, shadcn/ui
 - **Database ready** — Drizzle ORM with Neon PostgreSQL, migrations, and seed data
 - **Fast DX** — Bun runtime, Vite, Vitest, ESLint, Prettier, and pre-configured VS Code settings
@@ -33,7 +33,7 @@ React Starter Kit is proudly supported by these amazing sponsors:
 | **Runtime**   | [Bun](https://bun.sh/), [Cloudflare Workers](https://workers.cloudflare.com/), [TypeScript](https://www.typescriptlang.org/) 5.9                                                              |
 | **Frontend**  | [React 19](https://react.dev/), [TanStack Router](https://tanstack.com/router), [Tailwind CSS v4](https://tailwindcss.com/), [shadcn/ui](https://ui.shadcn.com/), [Jotai](https://jotai.org/) |
 | **Marketing** | [Astro](https://astro.build/)                                                                                                                                                                 |
-| **Backend**   | [Hono](https://hono.dev/), [tRPC](https://trpc.io/), [Better Auth](https://www.better-auth.com/)                                                                                              |
+| **Backend**   | [Hono](https://hono.dev/), [tRPC](https://trpc.io/), [Better Auth](https://www.better-auth.com/), [Stripe](https://stripe.com/)                                                               |
 | **Database**  | [Drizzle ORM](https://orm.drizzle.team/), [Neon PostgreSQL](https://get.neon.com/HD157BR)                                                                                                     |
 | **Tooling**   | [Vite](https://vitejs.dev/), [Vitest](https://vitest.dev/), [ESLint](https://eslint.org/), [Prettier](https://prettier.io/)                                                                   |
 
@@ -125,6 +125,13 @@ Configure your production secrets in Cloudflare Workers:
 # Required secrets
 bun wrangler secret put BETTER_AUTH_SECRET
 
+# Stripe billing (optional — first 4 required to enable, annual is optional)
+bun wrangler secret put STRIPE_SECRET_KEY
+bun wrangler secret put STRIPE_WEBHOOK_SECRET
+bun wrangler secret put STRIPE_STARTER_PRICE_ID
+bun wrangler secret put STRIPE_PRO_PRICE_ID
+bun wrangler secret put STRIPE_PRO_ANNUAL_PRICE_ID  # optional
+
 # OAuth providers (as needed)
 bun wrangler secret put GOOGLE_CLIENT_ID
 bun wrangler secret put GOOGLE_CLIENT_SECRET

apps/api/dev.ts

@@ -62,12 +62,17 @@ app.use(async (c, next) => {
     "OPENAI_API_KEY",
     "RESEND_API_KEY",
     "RESEND_EMAIL_FROM",
+    "STRIPE_SECRET_KEY",
+    "STRIPE_WEBHOOK_SECRET",
+    "STRIPE_STARTER_PRICE_ID",
+    "STRIPE_PRO_PRICE_ID",
+    "STRIPE_PRO_ANNUAL_PRICE_ID",
   ] as const;
 
   const env = {
     ...cf.env,
     ...Object.fromEntries(
-      secretKeys.map((key) => [key, (process.env[key] || cf.env[key]) ?? ""]),
+      secretKeys.map((key) => [key, process.env[key] || cf.env[key]]),
     ),
     APP_NAME: process.env.APP_NAME || cf.env.APP_NAME || "Example",
     APP_ORIGIN:

apps/api/lib/app.ts

@@ -8,11 +8,13 @@ import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
 import { Hono } from "hono";
 import type { AppContext } from "./context.js";
 import { router } from "./trpc.js";
+import { billingRouter } from "../routers/billing.js";
 import { organizationRouter } from "../routers/organization.js";
 import { userRouter } from "../routers/user.js";
 
 // tRPC API router
 const appRouter = router({
+  billing: billingRouter,
   user: userRouter,
   organization: organizationRouter,
 });

apps/api/lib/auth.ts

@@ -1,13 +1,17 @@
 import { passkey } from "@better-auth/passkey";
+import { stripe } from "@better-auth/stripe";
 import { schema as Db } from "@repo/db";
 import { betterAuth } from "better-auth";
 import type { DB } from "better-auth/adapters/drizzle";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { createAuthMiddleware } from "better-auth/api";
 import { anonymous, organization } from "better-auth/plugins";
 import { emailOTP } from "better-auth/plugins/email-otp";
+import { and, eq } from "drizzle-orm";
 import { sendOTP, sendPasswordReset, sendVerificationEmail } from "./email";
 import type { Env } from "./env";
+import { planLimits } from "./plans";
+import { createStripeClient } from "./stripe";
 
 // Auth hint cookie for edge routing (see docs/adr/001-auth-hint-cookie.md)
 // NOT a security boundary - false positives are acceptable (causes one redirect)
@@ -28,8 +32,69 @@ type AuthEnv = Pick<
   | "GOOGLE_CLIENT_SECRET"
   | "RESEND_API_KEY"
   | "RESEND_EMAIL_FROM"
+  | "STRIPE_SECRET_KEY"
+  | "STRIPE_WEBHOOK_SECRET"
+  | "STRIPE_STARTER_PRICE_ID"
+  | "STRIPE_PRO_PRICE_ID"
+  | "STRIPE_PRO_ANNUAL_PRICE_ID"
 >;
 
+/**
+ * Stripe billing plugin — only enabled when all required env vars are set.
+ * Without Stripe config, the app works but billing endpoints return 404.
+ */
+function stripePlugin(db: DB, env: AuthEnv) {
+  if (
+    !env.STRIPE_SECRET_KEY ||
+    !env.STRIPE_WEBHOOK_SECRET ||
+    !env.STRIPE_STARTER_PRICE_ID ||
+    !env.STRIPE_PRO_PRICE_ID
+  ) {
+    return [];
+  }
+
+  return [
+    stripe({
+      stripeClient: createStripeClient(env),
+      stripeWebhookSecret: env.STRIPE_WEBHOOK_SECRET,
+      createCustomerOnSignUp: true,
+      subscription: {
+        enabled: true,
+        plans: [
+          {
+            name: "starter",
+            priceId: env.STRIPE_STARTER_PRICE_ID,
+            limits: planLimits.starter,
+          },
+          {
+            name: "pro",
+            priceId: env.STRIPE_PRO_PRICE_ID,
+            annualDiscountPriceId: env.STRIPE_PRO_ANNUAL_PRICE_ID,
+            limits: planLimits.pro,
+            freeTrial: { days: 14 },
+          },
+        ],
+        // Personal billing: user can manage their own subscription.
+        // Organization billing: only owner/admin can manage.
+        authorizeReference: async ({ user, referenceId }) => {
+          if (referenceId === user.id) return true;
+          const [row] = await db
+            .select({ role: Db.member.role })
+            .from(Db.member)
+            .where(
+              and(
+                eq(Db.member.organizationId, referenceId),
+                eq(Db.member.userId, user.id),
+              ),
+            );
+          return row?.role === "owner" || row?.role === "admin";
+        },
+      },
+      organization: { enabled: true },
+    }),
+  ];
+}
+
 /**
  * Creates a Better Auth instance configured for multi-tenant SaaS with organization support.
  *
@@ -42,7 +107,7 @@ type AuthEnv = Pick<
  * @param db Drizzle database instance - must include all required auth tables (user, session, identity, organization, member, invitation, verification)
  * @param env Environment variables containing auth secrets and OAuth credentials
  * @returns Configured Better Auth instance with email/password and Google OAuth
- * @throws Will fail silently if required database tables are missing from schema
+ * @remarks Missing database tables will cause runtime errors when auth endpoints are called.
  *
  * @example
  * ```ts
@@ -75,6 +140,7 @@ export function createAuth(
         organization: Db.organization,
         passkey: Db.passkey,
         session: Db.session,
+        subscription: Db.subscription,
         user: Db.user,
         verification: Db.verification,
       },
@@ -130,6 +196,7 @@ export function createAuth(
         expiresIn: 300, // 5 minutes
         allowedAttempts: 3,
       }),
+      ...stripePlugin(db, env),
     ],
 
     advanced: {
@@ -186,4 +253,7 @@ export type Auth = ReturnType<typeof betterAuth>;
 // Base session types from Better Auth - plugin-specific fields added at runtime
 type SessionResponse = Auth["$Infer"]["Session"];
 export type AuthUser = SessionResponse["user"];
-export type AuthSession = SessionResponse["session"];
+// Organization plugin adds activeOrganizationId at runtime
+export type AuthSession = SessionResponse["session"] & {
+  activeOrganizationId?: string;
+};

apps/api/lib/env.ts

@@ -17,6 +17,12 @@ export const envSchema = z.object({
   OPENAI_API_KEY: z.string(),
   RESEND_API_KEY: z.string(),
   RESEND_EMAIL_FROM: z.email(),
+  // Stripe billing (optional — app works without these, billing features disabled)
+  STRIPE_SECRET_KEY: z.string().startsWith("sk_").optional(),
+  STRIPE_WEBHOOK_SECRET: z.string().startsWith("whsec_").optional(),
+  STRIPE_STARTER_PRICE_ID: z.string().startsWith("price_").optional(),
+  STRIPE_PRO_PRICE_ID: z.string().startsWith("price_").optional(),
+  STRIPE_PRO_ANNUAL_PRICE_ID: z.string().startsWith("price_").optional(),
 });
 
 /**

apps/api/lib/plans.ts

@@ -0,0 +1,10 @@
+// Single source of truth for plan limits.
+// Referenced by auth plugin config (plan definitions) and tRPC router (query responses).
+
+export const planLimits = {
+  free: { members: 1 },
+  starter: { members: 5 },
+  pro: { members: 50 },
+} as const;
+
+export type PlanName = keyof typeof planLimits;

apps/api/lib/stripe.ts

@@ -0,0 +1,9 @@
+import Stripe from "stripe";
+import type { Env } from "./env";
+
+// Only called when STRIPE_SECRET_KEY is verified present (see auth.ts conditional)
+export function createStripeClient(env: Pick<Env, "STRIPE_SECRET_KEY">) {
+  return new Stripe(env.STRIPE_SECRET_KEY!, {
+    appInfo: { name: "React Starter Kit" },
+  });
+}

apps/api/lib/trpc.ts

@@ -17,6 +17,7 @@ const t = initTRPC.context<TRPCContext>().create({
 
 export const router = t.router;
 export const publicProcedure = t.procedure;
+export const createCallerFactory = t.createCallerFactory;
 
 // Derive type from publicProcedure to stay in sync with initTRPC config.
 // Explicit annotation required to avoid TS2742 (non-portable inferred type).

apps/api/package.json

@@ -20,6 +20,7 @@
   "dependencies": {
     "@ai-sdk/openai": "^3.0.29",
     "@better-auth/passkey": "^1.4.18",
+    "@better-auth/stripe": "^1.4.18",
     "@repo/core": "workspace:*",
     "@repo/db": "workspace:*",
     "@repo/email": "workspace:*",
@@ -29,7 +30,8 @@
     "dataloader": "^2.2.3",
     "drizzle-orm": "^0.45.1",
     "postgres": "^3.4.8",
-    "resend": "^6.9.2"
+    "resend": "^6.9.2",
+    "stripe": "^20.3.1"
   },
   "peerDependencies": {
     "hono": "^4.11.9",