feat: add clerk auth support with convex (#548)

apps/web/content/docs/analytics.mdx

@@ -49,8 +49,8 @@ Add `export BTS_TELEMETRY_DISABLED=1` to your shell profile to make it permanent
 ## Where to view analytics
 
 - Charts: [`/analytics`](/analytics)
-- Raw JSON snapshot: `https://r2.amanv.dev/analytics-data.json`
-- CSV export: `https://r2.amanv.dev/export.csv`
+- Raw JSON snapshot: `https://r2.better-t-stack.dev/analytics-data.json`
+- CSV export: `https://r2.better-t-stack.dev/export.csv`
 
 Notes:
 

apps/web/content/docs/bts-config.mdx

@@ -37,7 +37,7 @@ The file is JSONC with comments enabled and includes a `$schema` URL for tooling
   "database": "sqlite",
   "orm": "drizzle",
   "api": "trpc",
-  "auth": true,
+  "auth": "better-auth",
   "addons": ["turborepo"],
   "examples": [],
   "dbSetup": "none",

apps/web/content/docs/cli/compatibility.mdx

@@ -59,7 +59,7 @@ create-better-t-stack --runtime workers --backend hono --database sqlite --orm d
 #### Convex Backend
 When using `--backend convex`, the following options are automatically set:
 
-- `--auth false` (Convex handles auth)
+- `--auth clerk` (if compatible frontends selected, otherwise `none`)
 - `--database none` (Convex provides database)
 - `--orm none` (Convex provides data layer)
 - `--api none` (Convex provides API)
@@ -67,10 +67,12 @@ When using `--backend convex`, the following options are automatically set:
 - `--db-setup none` (Convex manages hosting)
 - `--examples todo` (Todo example works with Convex)
 
+**Note:** Convex supports Clerk authentication with compatible frontends (React frameworks, Next.js, TanStack Start, and native frameworks). Nuxt, Svelte, and Solid are not compatible with Clerk.
+
 #### No Backend
 When using `--backend none`, the following options are automatically set:
 
-- `--auth false` (No backend for auth)
+- `--auth none` (No backend for auth)
 - `--database none` (No backend for database)
 - `--orm none` (No database)
 - `--api none` (No backend for API)
@@ -158,17 +160,30 @@ create-better-t-stack --frontend next native-nativewind
 
 ## Authentication Requirements
 
-Authentication requires:
+### Better-Auth Requirements
+Better-Auth authentication requires:
 - A backend framework (cannot be `none`)
 - A database (cannot be `none`)
 - An ORM (cannot be `none`)
 
-```bash
-# ❌ Invalid - Auth without database
-create-better-t-stack --auth --database none
+### Clerk Requirements
+Clerk authentication requires:
+- Convex backend (`--backend convex`)
+- Compatible frontends (React frameworks, Next.js, TanStack Start, native frameworks)
+- Not compatible with Nuxt, Svelte, or Solid
 
-# ✅ Valid - Auth with full stack
-create-better-t-stack --auth --database postgres --orm drizzle --backend hono
+```bash
+# ❌ Invalid - Better-Auth without database
+create-better-t-stack --auth better-auth --database none
+
+# ✅ Valid - Better-Auth with full stack
+create-better-t-stack --auth better-auth --database postgres --orm drizzle --backend hono
+
+# ✅ Valid - Clerk with Convex
+create-better-t-stack --auth clerk --backend convex --frontend tanstack-router
+
+# ❌ Invalid - Clerk without Convex
+create-better-t-stack --auth clerk --backend hono
 ```
 
 ## Example Compatibility
@@ -203,8 +218,11 @@ create-better-t-stack --frontend tanstack-router
 
 ### "Authentication requires a database"
 ```bash
-# Fix by adding database
-create-better-t-stack --auth --database postgres --orm drizzle
+# Fix by adding database for Better-Auth
+create-better-t-stack --auth better-auth --database postgres --orm drizzle
+
+# Or use Clerk with Convex (no database required)
+create-better-t-stack --auth clerk --backend convex
 ```
 
 ## Validation Strategy

apps/web/content/docs/cli/index.mdx

@@ -33,6 +33,7 @@ create-better-t-stack [project-directory] [options]
 - `--database <type>`: `none`, `sqlite`, `postgres`, `mysql`, `mongodb`
 - `--orm <type>`: `none`, `drizzle`, `prisma`, `mongoose`
 - `--api <type>`: `none`, `trpc`, `orpc`
+- `--auth <provider>`: `better-auth`, `clerk`, `none` (see [Options](/docs/cli/options#authentication))
 - `--db-setup <setup>`: `none`, `turso`, `d1`, `neon`, `supabase`, `prisma-postgres`, `mongodb-atlas`, `docker`
 - `--examples <types...>`: `none`, `todo`, `ai`
 - `--web-deploy <setup>`: `none`, `wrangler`, `alchemy`

apps/web/content/docs/cli/options.mdx

@@ -217,16 +217,24 @@ create-better-t-stack --frontend none
 
 ## Authentication
 
-### `--auth / --no-auth`
+### `--auth <provider>`
 
-Include or exclude authentication setup using Better-Auth.
+Choose authentication provider:
+
+- `better-auth`: Better-Auth authentication (default)
+- `clerk`: Clerk authentication (only with Convex backend)
+- `none`: No authentication
 
 ```bash
-create-better-t-stack --auth
-create-better-t-stack --no-auth
+create-better-t-stack --auth better-auth
+create-better-t-stack --auth clerk
+create-better-t-stack --auth none
 ```
 
-**Note:** Authentication requires both a database and backend framework to be selected. It is automatically disabled when using Convex backend or when no backend is selected.
+**Note:** 
+- `better-auth` requires both a database and backend framework
+- `clerk` is only available with Convex backend
+- Authentication is automatically set to `none` when using `--backend none` or `--database none` (unless using Convex)
 
 ## Addons
 
@@ -312,7 +320,7 @@ create-better-t-stack \
   --runtime bun \
   --frontend tanstack-router \
   --api trpc \
-  --auth \
+  --auth better-auth \
   --addons pwa biome \
   --examples todo \
   --package-manager bun \

apps/web/content/docs/cli/programmatic-api.mdx

@@ -33,7 +33,7 @@ async function createProject() {
     backend: "hono",
     database: "sqlite",
     orm: "drizzle",
-    auth: true,
+    auth: "better-auth",
     packageManager: "bun",
     install: false, // Don't install deps automatically
     disableAnalytics: true, // Disable analytics
@@ -258,7 +258,7 @@ create-better-t-stack my-app \
   --backend hono \
   --database postgres \
   --orm drizzle \
-  --auth \
+  --auth better-auth \
   --yes
 ```
 
@@ -269,7 +269,7 @@ const result = await init("my-app", {
   backend: "hono",
   database: "postgres",
   orm: "drizzle",
-  auth: true,
+  auth: "better-auth",
   yes: true
 });
 ```
@@ -286,7 +286,7 @@ const result = await init("my-app", {
   backend: "hono",
   database: "postgres",
   orm: "drizzle",
-  auth: true,
+  auth: "better-auth",
   addons: ["biome", "turborepo"],
   examples: ["todo"],
   packageManager: "bun",

apps/web/content/docs/compatibility.mdx

@@ -5,13 +5,14 @@ description: Valid and invalid combinations across frontend, backend, runtime, d
 
 ## Rules
 
-- **Convex backend**: Disables authentication, database, ORM, and API options
+- **Convex backend**: Sets database, ORM, and API to `none`; auth to `clerk` (if compatible frontends) or `none`
 - **Backend `none`**: Forces API, ORM, database, authentication, and runtime to `none`; disables examples
 - **Frontend `none`**: Backend-only project; PWA/Tauri/examples may be disabled
 - **API `none`**: No tRPC/oRPC setup; use framework-native APIs
-- **Database `none`**: Disables ORM and authentication
+- **Database `none`**: Disables ORM and Better-Auth (but allows Clerk with Convex)
 - **ORM `none`**: No ORM setup; manage DB manually
 - **Runtime `none`**: Only with Convex backend or when backend is `none`
+- **Auth `clerk`**: Only available with Convex backend and compatible frontends
 
 ## Cloudflare Workers
 

apps/web/content/docs/index.mdx

@@ -91,7 +91,7 @@ Skip prompts and use the default stack:
       --backend hono \
       --database sqlite \
       --orm drizzle \
-      --auth \
+      --auth better-auth \
       --addons turborepo
     ```
   </Tab>
@@ -102,7 +102,7 @@ Skip prompts and use the default stack:
       --backend hono \
       --database sqlite \
       --orm drizzle \
-      --auth \
+      --auth better-auth \
       --addons turborepo
     ```
   </Tab>
@@ -113,34 +113,37 @@ Skip prompts and use the default stack:
       --backend hono \
       --database sqlite \
       --orm drizzle \
-      --auth \
+      --auth better-auth \
       --addons turborepo
     ```
   </Tab>
 </Tabs>
 
-### Convex + React
+### Convex + React + Clerk
 
 <Tabs items={['bun', 'pnpm', 'npm']}>
   <Tab value="bun">
     ```bash
     bun create better-t-stack@latest my-convex-app \
       --frontend tanstack-router \
-      --backend convex
+      --backend convex \
+      --auth clerk
     ```
   </Tab>
   <Tab value="pnpm">
     ```bash
     pnpm create better-t-stack@latest my-convex-app \
       --frontend tanstack-router \
-      --backend convex
+      --backend convex \
+      --auth clerk
     ```
   </Tab>
   <Tab value="npm">
     ```bash
     npx create-better-t-stack@latest my-convex-app \
       --frontend tanstack-router \
-      --backend convex
+      --backend convex \
+      --auth clerk
     ```
   </Tab>
 </Tabs>
@@ -193,7 +196,7 @@ Skip prompts and use the default stack:
       --backend hono \
       --database sqlite \
       --orm drizzle \
-      --auth
+      --auth better-auth
     ```
   </Tab>
   <Tab value="pnpm">
@@ -203,7 +206,7 @@ Skip prompts and use the default stack:
       --backend hono \
       --database sqlite \
       --orm drizzle \
-      --auth
+      --auth better-auth
     ```
   </Tab>
   <Tab value="npm">
@@ -213,7 +216,7 @@ Skip prompts and use the default stack:
       --backend hono \
       --database sqlite \
       --orm drizzle \
-      --auth
+      --auth better-auth
     ```
   </Tab>
 </Tabs>
@@ -254,6 +257,7 @@ See the full list in the [CLI Reference](/docs/cli). Key flags:
 - `--database`: sqlite, postgres, mysql, mongodb, none
 - `--orm`: drizzle, prisma, mongoose, none
 - `--api`: trpc, orpc, none
+- `--auth`: better-auth, clerk, none
 - `--addons`: turborepo, pwa, tauri, biome, husky, starlight, fumadocs, ultracite, oxlint, ruler, none
 - `--examples`: todo, ai, none
 

apps/web/content/docs/project-structure.mdx

@@ -256,7 +256,7 @@ apps/docs/
   "frontend": ["<next|tanstack-router|react-router|tanstack-start|nuxt|svelte|solid>"] ,
   "addons": ["<turborepo|biome|husky|pwa|starlight>"] ,
   "examples": ["<ai|todo|none>"] ,
-  "auth": <true|false>,
+  "auth": <"better-auth"|"clerk"|"none">,
   "packageManager": "<bun|pnpm|npm>",
   "dbSetup": "<none|docker|d1>",
   "api": "<none|trpc|orpc>",
@@ -336,7 +336,9 @@ Notes:
 - **Monorepo**: `apps/*` always; `packages/*` only when needed (Convex)
 - **React web base**: shadcn/ui primitives, `components.json`, common utilities
 - **API clients**: `src/utils/trpc.ts` or `src/utils/orpc.ts` added to web/native when selected
-- **Auth**: Adds `src/lib/auth.ts` on the server and login/dashboard pages on the web app
+- **Auth**: Adds authentication setup based on provider:
+  - `better-auth`: `src/lib/auth.ts` on server and login/dashboard pages on web app
+  - `clerk`: Clerk provider setup and authentication components
 - **ORM/DB**: Drizzle/Prisma/Mongoose files added only when selected
 - **Extras**: `pnpm-workspace.yaml`, `bunfig.toml`, or `.npmrc` added based on package manager and choices
 - **Deploy**: Workers deploy adds `wrangler.jsonc` templates to the appropriate app(s)