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

Author: AmanVarshney01

apps/cli/src/constants.ts

@@ -13,7 +13,7 @@ export const DEFAULT_CONFIG_BASE = {
 	frontend: ["tanstack-router"],
 	database: "sqlite",
 	orm: "drizzle",
-	auth: true,
+	auth: "better-auth",
 	addons: ["turborepo"],
 	examples: [],
 	git: true,
@@ -43,6 +43,11 @@ export const dependencyVersionMap = {
 	"better-auth": "^1.3.7",
 	"@better-auth/expo": "^1.3.7",
 
+	"@clerk/nextjs": "^6.31.5",
+	"@clerk/clerk-react": "^5.45.0",
+	"@clerk/tanstack-react-start": "^0.23.1",
+	"@clerk/clerk-expo": "^2.14.25",
+
 	"drizzle-orm": "^0.44.2",
 	"drizzle-kit": "^0.31.2",
 

apps/cli/src/helpers/core/add-addons.ts

@@ -44,7 +44,7 @@ export async function addAddonsToProject(
 			frontend: detectedConfig.frontend || [],
 			addons: input.addons,
 			examples: detectedConfig.examples || [],
-			auth: detectedConfig.auth || false,
+			auth: detectedConfig.auth || "none",
 			git: false,
 			packageManager:
 				input.packageManager || detectedConfig.packageManager || "npm",

apps/cli/src/helpers/core/add-deployment.ts

@@ -68,7 +68,7 @@ export async function addDeploymentToProject(
 			frontend: detectedConfig.frontend || [],
 			addons: detectedConfig.addons || [],
 			examples: detectedConfig.examples || [],
-			auth: detectedConfig.auth || false,
+			auth: detectedConfig.auth || "none",
 			git: false,
 			packageManager:
 				input.packageManager || detectedConfig.packageManager || "npm",

apps/cli/src/helpers/addons/auth-setup.ts renamed to apps/cli/src/helpers/core/auth-setup.ts

@@ -7,7 +7,7 @@ import { addPackageDependency } from "../../utils/add-package-deps";
 
 export async function setupAuth(config: ProjectConfig) {
 	const { auth, frontend, backend, projectDir } = config;
-	if (backend === "convex" || !auth) {
+	if (!auth || auth === "none") {
 		return;
 	}
 
@@ -20,7 +20,48 @@ export async function setupAuth(config: ProjectConfig) {
 	const serverDirExists = await fs.pathExists(serverDir);
 
 	try {
-		if (serverDirExists) {
+		if (backend === "convex") {
+			if (auth === "clerk" && clientDirExists) {
+				const hasNextJs = frontend.includes("next");
+				const hasTanStackStart = frontend.includes("tanstack-start");
+				const hasViteReactOther = frontend.some((f) =>
+					["tanstack-router", "react-router"].includes(f),
+				);
+
+				if (hasNextJs) {
+					await addPackageDependency({
+						dependencies: ["@clerk/nextjs"],
+						projectDir: clientDir,
+					});
+				} else if (hasTanStackStart) {
+					await addPackageDependency({
+						dependencies: ["@clerk/tanstack-react-start"],
+						projectDir: clientDir,
+					});
+				} else if (hasViteReactOther) {
+					await addPackageDependency({
+						dependencies: ["@clerk/clerk-react"],
+						projectDir: clientDir,
+					});
+				}
+			}
+
+			const hasNativeWind = frontend.includes("native-nativewind");
+			const hasUnistyles = frontend.includes("native-unistyles");
+			if (
+				auth === "clerk" &&
+				nativeDirExists &&
+				(hasNativeWind || hasUnistyles)
+			) {
+				await addPackageDependency({
+					dependencies: ["@clerk/clerk-expo"],
+					projectDir: nativeDir,
+				});
+			}
+			return;
+		}
+
+		if (serverDirExists && auth === "better-auth") {
 			await addPackageDependency({
 				dependencies: ["better-auth"],
 				projectDir: serverDir,
@@ -40,26 +81,30 @@ export async function setupAuth(config: ProjectConfig) {
 		);
 
 		if (hasWebFrontend && clientDirExists) {
-			await addPackageDependency({
-				dependencies: ["better-auth"],
-				projectDir: clientDir,
-			});
+			if (auth === "better-auth") {
+				await addPackageDependency({
+					dependencies: ["better-auth"],
+					projectDir: clientDir,
+				});
+			}
 		}
 
 		if (
 			(frontend.includes("native-nativewind") ||
 				frontend.includes("native-unistyles")) &&
 			nativeDirExists
 		) {
-			await addPackageDependency({
-				dependencies: ["better-auth", "@better-auth/expo"],
-				projectDir: nativeDir,
-			});
-			if (serverDirExists) {
+			if (auth === "better-auth") {
 				await addPackageDependency({
-					dependencies: ["@better-auth/expo"],
-					projectDir: serverDir,
+					dependencies: ["better-auth", "@better-auth/expo"],
+					projectDir: nativeDir,
 				});
+				if (serverDirExists) {
+					await addPackageDependency({
+						dependencies: ["@better-auth/expo"],
+						projectDir: serverDir,
+					});
+				}
 			}
 		}
 	} catch (error) {

apps/cli/src/helpers/core/command-handlers.ts

@@ -103,7 +103,7 @@ export async function createProjectHandler(
 				frontend: [],
 				addons: [],
 				examples: [],
-				auth: false,
+				auth: "none",
 				git: false,
 				packageManager: "npm",
 				install: false,
@@ -154,11 +154,11 @@ export async function createProjectHandler(
 
 		if (config.backend === "convex") {
 			log.info(
-				"Due to '--backend convex' flag, the following options have been automatically set: auth=false, database=none, orm=none, api=none, runtime=none, dbSetup=none, examples=todo",
+				`Due to '--backend convex' flag, the following options have been automatically set: database=none, orm=none, api=none, runtime=none, dbSetup=none, examples=todo`,
 			);
 		} else if (config.backend === "none") {
 			log.info(
-				"Due to '--backend none', the following options have been automatically set: --auth=false, --database=none, --orm=none, --api=none, --runtime=none, --db-setup=none, --examples=none",
+				"Due to '--backend none', the following options have been automatically set: --auth none, --database=none, --orm=none, --api=none, --runtime=none, --db-setup=none, --examples=none",
 			);
 		}
 

apps/cli/src/helpers/core/create-project.ts

@@ -5,14 +5,14 @@ import { writeBtsConfig } from "../../utils/bts-config";
 import { exitWithError } from "../../utils/errors";
 import { formatProjectWithBiome } from "../../utils/format-with-biome";
 import { setupAddons } from "../addons/addons-setup";
-import { setupAuth } from "../addons/auth-setup";
 import { setupExamples } from "../addons/examples-setup";
 import { setupApi } from "../core/api-setup";
 import { setupBackendDependencies } from "../core/backend-setup";
 import { setupDatabase } from "../core/db-setup";
 import { setupRuntime } from "../core/runtime-setup";
 import { setupServerDeploy } from "../deployment/server-deploy-setup";
 import { setupWebDeploy } from "../deployment/web-deploy-setup";
+import { setupAuth } from "./auth-setup";
 import { runConvexCodegen } from "./convex-codegen";
 import { createReadme } from "./create-readme";
 import { setupEnvironmentVariables } from "./env-setup";
@@ -46,8 +46,8 @@ export async function createProject(options: ProjectConfig) {
 		if (!isConvex) {
 			await setupDbOrmTemplates(projectDir, options);
 			await setupDockerComposeTemplates(projectDir, options);
-			await setupAuthTemplate(projectDir, options);
 		}
+		await setupAuthTemplate(projectDir, options);
 		if (options.examples.length > 0 && options.examples[0] !== "none") {
 			await setupExamplesTemplate(projectDir, options);
 		}
@@ -70,7 +70,7 @@ export async function createProject(options: ProjectConfig) {
 			await setupAddons(options);
 		}
 
-		if (!isConvex && options.auth) {
+		if (options.auth && options.auth !== "none") {
 			await setupAuth(options);
 		}
 

apps/cli/src/helpers/core/create-readme.ts

@@ -4,6 +4,7 @@ import fs from "fs-extra";
 import type {
 	Addons,
 	API,
+	Auth,
 	Database,
 	DatabaseSetup,
 	Frontend,
@@ -98,7 +99,11 @@ This project uses Convex as a backend. You'll need to set up Convex before runni
 ${packageManagerRunCmd} dev:setup
 \`\`\`
 
-Follow the prompts to create a new Convex project and connect it to your application.`
+Follow the prompts to create a new Convex project and connect it to your application.${
+				auth === "clerk"
+					? " See [Convex + Clerk guide](https://docs.convex.dev/auth/clerk) for auth setup."
+					: ""
+			}`
 		: generateDatabaseSetup(
 				database,
 				auth,
@@ -135,6 +140,7 @@ ${generateProjectStructure(
 	addons,
 	isConvex,
 	api,
+	auth,
 )}
 \`\`\`
 
@@ -258,6 +264,7 @@ function generateProjectStructure(
 	addons: Addons[],
 	isConvex: boolean,
 	api: API,
+	auth: Auth,
 ): string {
 	const structure: string[] = [`${projectName}/`, "├── apps/"];
 
@@ -317,6 +324,12 @@ function generateProjectStructure(
 		structure.push(
 			"│   └── backend/     # Convex backend functions and schema",
 		);
+		if (auth === "clerk") {
+			structure.push(
+				"│       ├── convex/    # Convex functions and schema",
+				"│       └── .env.local # Convex environment variables",
+			);
+		}
 	} else if (!isBackendNone) {
 		const backendName = backend[0].toUpperCase() + backend.slice(1);
 		const apiName = api !== "none" ? api.toUpperCase() : "";
@@ -329,7 +342,7 @@ function generateProjectStructure(
 
 function generateFeaturesList(
 	database: Database,
-	auth: boolean,
+	auth: Auth,
 	addons: Addons[],
 	orm: ORM,
 	runtime: Runtime,
@@ -449,10 +462,9 @@ function generateFeaturesList(
 		);
 	}
 
-	if (auth && !isConvex) {
-		addonsList.push(
-			"- **Authentication** - Email & password authentication with Better Auth",
-		);
+	if (auth !== "none") {
+		const authLabel = auth === "clerk" ? "Clerk" : "Better-Auth";
+		addonsList.push(`- **Authentication** - ${authLabel}`);
 	}
 
 	for (const addon of addons) {
@@ -476,7 +488,7 @@ function generateFeaturesList(
 
 function generateDatabaseSetup(
 	database: Database,
-	_auth: boolean,
+	_auth: Auth,
 	packageManagerRunCmd: string,
 	orm: ORM,
 	dbSetup: DatabaseSetup,
@@ -575,7 +587,7 @@ function generateScriptsList(
 	packageManagerRunCmd: string,
 	database: Database,
 	orm: ORM,
-	_auth: boolean,
+	_auth: Auth,
 	hasNative: boolean,
 	addons: Addons[],
 	backend: string,

apps/cli/src/helpers/core/env-setup.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import fs from "fs-extra";
 import type { ProjectConfig } from "../../types";
-import { generateAuthSecret } from "../addons/auth-setup";
+import { generateAuthSecret } from "./auth-setup";
 
 export interface EnvVariable {
 	key: string;
@@ -143,6 +143,42 @@ export async function setupEnvironmentVariables(config: ProjectConfig) {
 					condition: true,
 				},
 			];
+
+			if (backend === "convex" && auth === "clerk") {
+				if (hasNextJs) {
+					clientVars.push(
+						{
+							key: "NEXT_PUBLIC_CLERK_FRONTEND_API_URL",
+							value: "",
+							condition: true,
+						},
+						{
+							key: "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY",
+							value: "",
+							condition: true,
+						},
+						{
+							key: "CLERK_SECRET_KEY",
+							value: "",
+							condition: true,
+						},
+					);
+				} else if (hasReactRouter || hasTanStackRouter || hasTanStackStart) {
+					clientVars.push({
+						key: "VITE_CLERK_PUBLISHABLE_KEY",
+						value: "",
+						condition: true,
+					});
+					if (hasTanStackStart) {
+						clientVars.push({
+							key: "CLERK_SECRET_KEY",
+							value: "",
+							condition: true,
+						});
+					}
+				}
+			}
+
 			await addEnvVariablesToFile(path.join(clientDir, ".env"), clientVars);
 		}
 	}
@@ -168,6 +204,14 @@ export async function setupEnvironmentVariables(config: ProjectConfig) {
 					condition: true,
 				},
 			];
+
+			if (backend === "convex" && auth === "clerk") {
+				nativeVars.push({
+					key: "EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY",
+					value: "",
+					condition: true,
+				});
+			}
 			await addEnvVariablesToFile(path.join(nativeDir, ".env"), nativeVars);
 		}
 	}