roninoss · DaveVaval · Nov 30, 2025 · Dec 1, 2025 · Dec 1, 2025 · Dec 1, 2025
diff --git a/.changeset/sour-brooms-fail.md b/.changeset/sour-brooms-fail.md
@@ -0,0 +1,5 @@
+---
+'create-expo-stack': minor
+---
+
+Added Convex + Better Auth in the authentication choices
diff --git a/cli/src/commands/create-expo-stack.ts b/cli/src/commands/create-expo-stack.ts
@@ -307,6 +307,14 @@ const command: GluegunCommand = {
  });
  }
 
+ if (options.convex) {
+ // Add convex package
+ cliResults.packages.push({
+ name: 'convex',
+ type: 'authentication'
+ });
+ }
+
  // State Management packages
  if (options.zustand) {
  // Add zustand package

diff --git a/cli/src/templates/base/.gitignore.ejs b/cli/src/templates/base/.gitignore.ejs
@@ -9,12 +9,21 @@ npm-debug.*
 *.mobileprovision
 *.orig.*
 web-build/
-<% if (props.navigationPackage?.name === "expo-router") { %># expo router
-expo-env.d.ts<% } %>
-<% if (props.stylingPackage?.name === "tamagui") { %># tamagui
-.tamagui/<% } %>
-<% if ((props.authenticationPackage?.name === "supabase") || (props.authenticationPackage?.name === "firebase" || (props.analyticsPackage?.name === 'vexo-analytics'))) { %># firebase/supabase/vexo
-.env<% } %>
+<% if (props.navigationPackage?.name === "expo-router") { %>
+# expo router
+expo-env.d.ts
+<% } %>
+<% if (props.stylingPackage?.name === "tamagui") { %>
+# tamagui
+.tamagui/
+<% } %>
+<% if ((props.authenticationPackage?.name === "supabase") || (props.authenticationPackage?.name === "firebase" || (props.analyticsPackage?.name === 'vexo-analytics'))) { %>
+# firebase/supabase/vexo
+.env
+<% } %>
+<% if (props.authenticationPackage?.name === "convex") { %>
+.env.local
+<% } %>
 
 ios
 android

diff --git a/cli/src/templates/base/App.tsx.ejs b/cli/src/templates/base/App.tsx.ejs
@@ -21,17 +21,39 @@ import { StatusBar } from 'expo-status-bar';
 
  vexo(process.env.EXPO_PUBLIC_VEXO_API_KEY);
 <% } %>
+<% if (props.authenticationPackage?.name === "convex") { %>
+ import { ConvexReactClient } from "convex/react";
+ import { ConvexBetterAuthProvider } from "@convex-dev/better-auth/react";
+ import { authClient } from "@/lib/auth-client";
+
+ const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL as string, {
+ // Optionally pause queries until the user is authenticated
+ expectAuth: true, 
+ unsavedChangesWarning: false, 
+ });
+<% } %>
 
 export default function App() {
  return (
- <>
- <ScreenContent title="Home" path="App.tsx">
- <% if (props.internalizationPackage?.name === "i18next") { %>
- <InternalizationExample />
- <% } %>
- </ScreenContent>
- <StatusBar style="auto" />
+ <% if (props.authenticationPackage?.name === "convex") { %>
+ <ConvexBetterAuthProvider client={convex} authClient={authClient}>
+ <ScreenContent title="Home" path="App.tsx">
+ <% if (props.internalizationPackage?.name === "i18next") { %>
+ <InternalizationExample />
+ <% } %>
+ </ScreenContent>
+ <StatusBar style="auto" />
+ </ConvexBetterAuthProvider>
+ <% } else {%>
+ <>
+ <ScreenContent title="Home" path="App.tsx">
+ <% if (props.internalizationPackage?.name === "i18next") { %>
+ <InternalizationExample />
+ <% } %>
+ </ScreenContent>
+ <StatusBar style="auto" />
  </>
+ <%}%>
  );
 }
 
diff --git a/cli/src/templates/base/app.json.ejs b/cli/src/templates/base/app.json.ejs
@@ -6,8 +6,8 @@
  <% if (props.stylingPackage?.name === "unistyles") { %>
  "newArchEnabled": true,
  <% } %>
+ "scheme": "<%= props.projectName %>",
  <% if (props.navigationPackage?.name === 'expo-router') { %>
- "scheme": "<%= props.projectName %>",
  "platforms": ["ios", "android"],
  "web": {
  "bundler": "metro",

diff --git a/cli/src/templates/base/babel.config.js.ejs b/cli/src/templates/base/babel.config.js.ejs
@@ -12,6 +12,19 @@ module.exports = function(api) {
  ]);
  <% } %>
 
+ <% if (props.authenticationPackage?.name === "convex") { %>
+ plugins.push([
+ "module-resolver",
+ {
+ alias: {
+ "better-auth/react": "./node_modules/better-auth/dist/client/react/index.cjs",
+ "better-auth/client/plugins": "./node_modules/better-auth/dist/client/plugins/index.cjs",
+ "@better-auth/expo/client": "./node_modules/@better-auth/expo/dist/client.cjs",
+ },
+ },
+ ]);
+ <% } %>
+
  plugins.push('react-native-worklets/plugin');
 
  return {

diff --git a/cli/src/templates/base/eslint.config.js.ejs b/cli/src/templates/base/eslint.config.js.ejs
@@ -5,7 +5,12 @@ const expoConfig = require('eslint-config-expo/flat');
 module.exports = defineConfig([
  expoConfig,
  {
- ignores: ['dist/*'],
+ ignores: [
+ 'dist/*',
+ <% if (props.authenticationPackage?.name === "convex") { %>
+ 'convex/*'
+ <% } %>
+ ],
  },
  {
  rules: {

diff --git a/cli/src/templates/base/package.json.ejs b/cli/src/templates/base/package.json.ejs
@@ -116,6 +116,14 @@
  "firebase": "^10.5.2",
 <% } %>
 
+ <% if (props.authenticationPackage?.name === "convex") { %>
+ "@convex-dev/better-auth": "^0.9.7",
+ "@better-auth/expo": "1.3.34",
+ "better-auth": "1.3.34",
+ "convex": "^1.29.3",
+ "expo-secure-store": "~15.0.7",
+<% } %> 
+
  <% if (props.internalizationPackage?.name === "i18next") { %>
  "i18next": "^23.7.20",
  "react-i18next": "^14.0.1",
@@ -138,6 +146,9 @@
  "devDependencies": {
  "@babel/core": "^7.20.0",
  "@types/react": "~19.1.10",
+ <% if (props.authenticationPackage?.name === "convex") { %>
+ "babel-plugin-module-resolver": "^5.0.2",
+ <% } %>
  "eslint": "^9.25.1",
  "eslint-config-expo": "~10.0.0",
  "eslint-config-prettier": "^10.1.2",

diff --git a/cli/src/templates/base/tsconfig.json.ejs b/cli/src/templates/base/tsconfig.json.ejs
@@ -11,7 +11,7 @@
  <% if (props.navigationPackage?.name === "expo-router" && props.flags.importAlias === true) { %>
  "@/*": ["*"]
  <% } else if (props.flags.importAlias === true) { %>
- "@/*": ["src/*"]
+ "@/*": ["src/*", "*"]
  <% } else { %>
  "<%= props.flags.importAlias %>": ["src/*"]
  <% } %>

diff --git a/cli/src/templates/packages/convex/.env.local.ejs b/cli/src/templates/packages/convex/.env.local.ejs
@@ -0,0 +1,4 @@
+# Start by running: npx convex dev, to login and create your Convex backend
+# Then set EXPO_PUBLIC_CONVEX_URL_SITE as the same as EXPO_PUBLIC_CONVEX_URL but ends in .site, it can also be found as the HTTP Actions URL in the URL & Deploy Key tab of your Convex dashboard
+# Finaly run this command once to set your better auth secret in your convex dashboard: npx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
+EXPO_PUBLIC_CONVEX_SITE_URL=
diff --git a/cli/src/templates/packages/convex/convex/auth.config.ts.ejs b/cli/src/templates/packages/convex/convex/auth.config.ts.ejs
@@ -0,0 +1,8 @@
+export default {
+ providers: [
+ {
+ domain: process.env.CONVEX_SITE_URL,
+ applicationID: "convex",
+ },
+ ],
+};
diff --git a/cli/src/templates/packages/convex/convex/auth.ts.ejs b/cli/src/templates/packages/convex/convex/auth.ts.ejs
@@ -0,0 +1,47 @@
+import { createClient, type GenericCtx } from "@convex-dev/better-auth";
+import { convex } from "@convex-dev/better-auth/plugins";
+import { betterAuth } from "better-auth";
+import { expo } from '@better-auth/expo';
+import { components } from "./_generated/api";
+import { DataModel } from "./_generated/dataModel";
+import { query } from "./_generated/server";
+
+// The component client has methods needed for integrating Convex with Better Auth,
+// as well as helper methods for general use.
+export const authComponent = createClient<DataModel>(components.betterAuth);
+const siteUrl = process.env.CONVEX_SITE_URL || "";
+
+export const createAuth = (
+ ctx: GenericCtx<DataModel>,
+ { optionsOnly } = { optionsOnly: false },
+) => {
+ return betterAuth({
+ baseURL: siteUrl,
+ // disable logging when createAuth is called just to generate options.
+ // this is not required, but there's a lot of noise in logs without it.
+ logger: {
+ disabled: optionsOnly,
+ },
+ trustedOrigins: ["your-scheme://", siteUrl],
+ database: authComponent.adapter(ctx),
+ // Configure simple, non-verified email/password to get started
+ emailAndPassword: {
+ enabled: true,
+ requireEmailVerification: false,
+ },
+ plugins: [
+ // The Expo and Convex plugins are required
+ expo(),
+ convex(),
+ ],
+ });
+};
+
+// Example function for getting the current user
+// Feel free to edit, omit, etc.
+export const getCurrentUser = query({
+ args: {},
+ handler: async (ctx) => {
+ return authComponent.getAuthUser(ctx);
+ },
+});
diff --git a/cli/src/templates/packages/convex/convex/convex.config.ts.ejs b/cli/src/templates/packages/convex/convex/convex.config.ts.ejs
@@ -0,0 +1,7 @@
+import { defineApp } from "convex/server";
+import betterAuth from "@convex-dev/better-auth/convex.config";
+
+const app = defineApp();
+app.use(betterAuth);
+
+export default app;
diff --git a/cli/src/templates/packages/convex/convex/http.ts.ejs b/cli/src/templates/packages/convex/convex/http.ts.ejs
@@ -0,0 +1,8 @@
+import { httpRouter } from "convex/server";
+import { authComponent, createAuth } from "./auth";
+
+const http = httpRouter();
+
+authComponent.registerRoutes(http, createAuth);
+
+export default http;
diff --git a/cli/src/templates/packages/convex/lib/auth-client.ts.ejs b/cli/src/templates/packages/convex/lib/auth-client.ts.ejs
@@ -0,0 +1,17 @@
+import { createAuthClient } from "better-auth/react";
+import { convexClient } from "@convex-dev/better-auth/client/plugins";
+import { expoClient } from '@better-auth/expo/client';
+import Constants from 'expo-constants';
+import * as SecureStore from 'expo-secure-store';
+
+export const authClient = createAuthClient({
+ baseURL: process.env.EXPO_PUBLIC_CONVEX_SITE_URL,
+ plugins: [
+ expoClient({
+ scheme: Constants.expoConfig?.scheme as string,
+ storagePrefix: Constants.expoConfig?.scheme as string,
+ storage: SecureStore,
+ }),
+ convexClient(),
+ ],
+});
diff --git a/cli/src/templates/packages/convex/metro.config.js.ejs b/cli/src/templates/packages/convex/metro.config.js.ejs
@@ -0,0 +1,16 @@
+const { getDefaultConfig } = require('expo/metro-config');
+<% if (props.stylingPackage?.name === "nativewind") { %>
+ const { withNativeWind } = require("nativewind/metro");
+<% } %>
+
+/** @type {import('expo/metro-config').MetroConfig} */
+// eslint-disable-next-line no-undef
+const config = getDefaultConfig(__dirname);
+
+config.resolver.unstable_enablePackageExports = true; 
+
+<% if (props.stylingPackage?.name === "nativewind") { %>
+ module.exports = withNativeWind(config, { input: "./global.css" });
+<% } else { %>
+ module.exports = config;
+<% } %>
diff --git a/cli/src/templates/packages/expo-router/stack/app/_layout.tsx.ejs b/cli/src/templates/packages/expo-router/stack/app/_layout.tsx.ejs
@@ -1,41 +1,70 @@
 <% if (props.stylingPackage?.name === "nativewind") { %>
  import '../global.css';
 <% } %>
-
 <% if (props.stylingPackage?.name === "unistyles") { %>
  import { useUnistyles } from "react-native-unistyles";
 <% } %>
 <% if (props.internalizationPackage?.name === "i18next") { %>
  import '../translation';
 <% } %>
 import { Stack } from "expo-router";
-
 <% if (props.analyticsPackage?.name === "vexo-analytics") { %>
  import { vexo } from 'vexo-analytics';
 
  vexo(process.env.EXPO_PUBLIC_VEXO_API_KEY);
 <% } %>
+<% if (props.authenticationPackage?.name === "convex") { %>
+ import { ConvexReactClient } from "convex/react";
+ import { ConvexBetterAuthProvider } from "@convex-dev/better-auth/react";
+ import { authClient } from "@/lib/auth-client";
+
+ const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL as string, {
+ // Optionally pause queries until the user is authenticated
+ expectAuth: true, 
+ unsavedChangesWarning: false, 
+ });
+<% } %>
 
 export default function Layout() {
  <% if (props.stylingPackage?.name === "unistyles") { %>
  const { theme } = useUnistyles();
  <% } %>
 
 return (
- <% if (props.stylingPackage?.name === "unistyles") { %>
- <Stack
- screenOptions={{
- headerStyle: {
- backgroundColor: theme.colors.background,
- },
- headerTitleStyle: {
- color: theme.colors.typography,
- },
- headerTintColor: theme.colors.typography
- }}
- />
- <% } else { %>
- <Stack />
- <% } %>
+ <% if (props.authenticationPackage?.name === "convex") { %>
+ <ConvexBetterAuthProvider client={convex} authClient={authClient}>
+ <% if (props.stylingPackage?.name === "unistyles") { %>
+ <Stack
+ screenOptions={{
+ headerStyle: {
+ backgroundColor: theme.colors.background,
+ },
+ headerTitleStyle: {
+ color: theme.colors.typography,
+ },
+ headerTintColor: theme.colors.typography
+ }}
+ />
+ <% } else { %>
+ <Stack />
+ <% } %>
+ </ConvexBetterAuthProvider>
+ <% } else {%>
+ <% if (props.stylingPackage?.name === "unistyles") { %>
+ <Stack
+ screenOptions={{
+ headerStyle: {
+ backgroundColor: theme.colors.background,
+ },
+ headerTitleStyle: {
+ color: theme.colors.typography,
+ },
+ headerTintColor: theme.colors.typography
+ }}
+ />
+ <% } else { %>
+ <Stack />
+ <% } %>
+ <%}%>
 );
 }