create-z3 0.0.47 → 0.0.48

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isaiah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -37,7 +37,7 @@ async function isDirectoryEmpty(dirPath) {
     return true;
   }
 }
-function resolveProjectName(input2, cwd) {
+function resolveProjectName(input2, _cwd) {
   return input2;
 }
 
@@ -1798,9 +1798,11 @@ function generateCredentialsValue(enabled) {
 }
 function generateAuthProvidersBlock(oauthProviders, emailPasswordEnabled) {
   const parts = [];
-  parts.push(`emailAndPassword: {
-      enabled: ${emailPasswordEnabled}
+  if (emailPasswordEnabled) {
+    parts.push(`emailAndPassword: {
+      enabled: true
     },`);
+  }
   if (oauthProviders.length > 0) {
     const providersObject = oauthProviders.map((providerId) => {
       const provider = getProvider(providerId);
@@ -2300,13 +2302,12 @@ var TanStackInstaller = class extends FrameworkInstaller {
   async updateEnvExample(selectedProviders) {
     const envFilePath = join2(this.targetPath, ".env.example");
     const envVarsBlock = generateEnvVarsBlock(selectedProviders, "tanstack");
-    if (envVarsBlock) {
-      await replacePlaceholder(
-        envFilePath,
-        "# {{ENV_OAUTH_VARS}}",
-        envVarsBlock
-      );
-    }
+    await replacePlaceholder(
+      envFilePath,
+      "# {{ENV_OAUTH_VARS}}",
+      envVarsBlock,
+      { graceful: true }
+    );
   }
   /**
    * Update README with OAuth provider setup guides
@@ -2319,14 +2320,12 @@ var TanStackInstaller = class extends FrameworkInstaller {
   async updateReadme(selectedProviders) {
     const readmeFilePath = join2(this.targetPath, "README.md");
     const readmeSection = generateReadmeSection(selectedProviders);
-    if (readmeSection) {
-      await replacePlaceholder(
-        readmeFilePath,
-        "<!-- {{OAUTH_SETUP_GUIDE}} -->",
-        readmeSection,
-        { graceful: true }
-      );
-    }
+    await replacePlaceholder(
+      readmeFilePath,
+      "<!-- {{OAUTH_SETUP_GUIDE}} -->",
+      readmeSection,
+      { graceful: true }
+    );
   }
   /**
    * Apply TweakCN theme to global CSS file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-z3",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "type": "module",
   "description": "CLI for scaffolding Z3 Stack applications (TanStack/Next.js + Convex + Better Auth)",
   "bin": {
@@ -10,13 +10,6 @@
     "dist",
     "templates"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
     "commander": "^12.0.0",
     "@inquirer/prompts": "^7.2.0",
@@ -55,7 +48,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/zayecq/create-z3-app"
+    "url": "https://github.com/ianyimi/create-z3-app"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/templates/nextjs/convex/auth/adapter/index.ts

@@ -50,6 +50,12 @@ export const convexAdapter = <DataModel extends GenericDataModel>(
 
       return {
         id: "convex",
+        // Tell the convex() plugin this context supports mutations. It checks
+        // ctx.context.adapter.options?.isRunMutationCtx — if falsy it replaces all
+        // adapter writes with silent no-ops. HTTP actions always have runMutation.
+        options: {
+          isRunMutationCtx: "runMutation" in ctx,
+        },
 
         create: async ({ data, model, select }): Promise<any> => {
           return await ctx.runMutation(internal.auth.db.dbCreate, {
@@ -189,34 +195,12 @@ export const convexAdapter = <DataModel extends GenericDataModel>(
         if (data && fieldAttributes.type === "date") {
           return new Date(data).getTime();
         }
-        // Handle array fields - Better Auth may send single values or arrays
-        if ((fieldAttributes.type as string)?.endsWith("[]")) {
-          // If already an array, return as-is
-          if (Array.isArray(data)) {
-            return data
-          }
-          // If it's a string that looks like JSON array, parse it
-          if (typeof data === "string") {
-            try {
-              const parsed = JSON.parse(data)
-              return Array.isArray(parsed) ? parsed : [data]
-            } catch {
-              // If parsing fails, wrap the string in an array
-              return [data]
-            }
-          }
-          // For any other value type, wrap in array
-          if (data !== null && data !== undefined) {
-            return [data]
-          }
-        }
         return data;
       },
       customTransformOutput: ({ data, fieldAttributes }) => {
         if (data && fieldAttributes.type === "date") {
           return new Date(data).getTime();
         }
-        // Arrays are stored natively in Convex, no transformation needed for output
         return data;
       },
       debugLogs: config.debugLogs ?? false,
@@ -230,6 +214,7 @@ export const convexAdapter = <DataModel extends GenericDataModel>(
       supportsDates: false,
       supportsJSON: true,
       supportsNumericIds: false,
+      supportsArrays: true,
       transaction: false,
       usePlural: false,
     },

package/templates/nextjs/convex/auth/index.ts

@@ -39,7 +39,7 @@ export const createAuth = (
     trustedOrigins: [process.env.SITE_URL!],
     user: {
       additionalFields: {
-        role: {
+        roles: {
           type: "string[]",
           defaultValue: [USER_ROLES.user],
           required: true

package/templates/nextjs/convex/auth/plugins/index.ts

@@ -1,14 +1,18 @@
 import { nextCookies } from "better-auth/next-js"
-import { admin, apiKey } from "better-auth/plugins"
+import { admin } from "better-auth/plugins"
+import { apiKey } from "@better-auth/api-key"
+import { convex } from "@convex-dev/better-auth/plugins"
 import { USER_ROLES } from "~/db/constants"
+import authConfig from "@convex/auth.config"
 
 const plugins = [
   admin({
     adminRoles: [USER_ROLES.admin],
-    defaultRole: USER_ROLES.user
+    defaultRole: USER_ROLES.user,
   }),
   apiKey(),
   nextCookies(),
+  convex({ authConfig }),
 ]
 
 export default plugins

package/templates/nextjs/convex/auth/sessions.ts

@@ -53,7 +53,7 @@ export const getSessionWithUser = query({
 				email: user.email,
 				emailVerified: user.emailVerified,
 				image: user.image,
-				role: user.role,
+				roles: user.roles,
 			},
 		};
 	},

package/templates/nextjs/convex/auth.config.ts

@@ -0,0 +1,7 @@
+import type { AuthConfig } from "convex/server"
+
+import { getAuthConfigProvider } from "@convex-dev/better-auth/auth-config"
+
+export default {
+  providers: [getAuthConfigProvider()],
+} satisfies AuthConfig

package/templates/nextjs/convex/schema.ts

@@ -1,7 +1,7 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values"
 
-import { TABLE_SLUG_ACCOUNTS, TABLE_SLUG_JWKS, TABLE_SLUG_SESSIONS, TABLE_SLUG_USERS, TABLE_SLUG_VERIFICATIONS } from "~/db/constants";
+import { TABLE_SLUG_ACCOUNTS, TABLE_SLUG_API_KEYS, TABLE_SLUG_JWKS, TABLE_SLUG_SESSIONS, TABLE_SLUG_USERS, TABLE_SLUG_VERIFICATIONS } from "~/db/constants";
 
 export default defineSchema({
   // Better Auth component tables (type definitions only - actual tables are in component)
@@ -19,7 +19,8 @@ export default defineSchema({
     isAnonymous: v.optional(v.union(v.null(), v.boolean())),
     phoneNumber: v.optional(v.union(v.null(), v.string())),
     phoneNumberVerified: v.optional(v.union(v.null(), v.boolean())),
-    role: v.array(v.string()), // admin plugin
+    role: v.optional(v.string()), // admin plugin — single string in BA 1.5
+    roles: v.array(v.string()), // our multi-role field via additionalFields
     twoFactorEnabled: v.optional(v.union(v.null(), v.boolean())),
     updatedAt: v.number(),
     userId: v.optional(v.union(v.null(), v.string()))
@@ -70,4 +71,31 @@ export default defineSchema({
     privateKey: v.optional(v.string()),
     publicKey: v.string(),
   }),
+
+  // Better Auth 1.5 — apiKey plugin (@better-auth/api-key)
+  [TABLE_SLUG_API_KEYS]: defineTable({
+    configId: v.string(),
+    name: v.optional(v.string()),
+    start: v.optional(v.string()),
+    referenceId: v.string(),
+    prefix: v.optional(v.string()),
+    key: v.string(),
+    refillInterval: v.optional(v.number()),
+    refillAmount: v.optional(v.number()),
+    lastRefillAt: v.optional(v.number()),
+    enabled: v.optional(v.boolean()),
+    rateLimitEnabled: v.optional(v.boolean()),
+    rateLimitTimeWindow: v.optional(v.number()),
+    rateLimitMax: v.optional(v.number()),
+    requestCount: v.optional(v.number()),
+    remaining: v.optional(v.number()),
+    lastRequest: v.optional(v.number()),
+    expiresAt: v.optional(v.number()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+    permissions: v.optional(v.string()),
+    metadata: v.optional(v.string()),
+  })
+    .index("by_referenceId", ["referenceId"])
+    .index("by_key", ["key"]),
 })

package/templates/nextjs/package.json

@@ -13,13 +13,14 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.1.0",
-    "@convex-dev/better-auth": "^0.10.10",
+    "@better-auth/api-key": "^1.0.0",
+    "@convex-dev/better-auth": "^0.11.0",
     "@convex-dev/react-query": "^0.1.0",
     "@daveyplate/better-auth-ui": "^3.3.15",
     "@t3-oss/env-nextjs": "^0.13.10",
     "@tanstack/react-form": "^1.27.7",
     "@tanstack/react-query": "^5.90.17",
-    "better-auth": "^1.4.9",
+    "better-auth": "^1.5.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "convex": "^1.31.5",

package/templates/nextjs/src/auth/client.tsx

@@ -2,10 +2,8 @@ import type { ReactNode } from "react";
 
 import { convexClient } from "@convex-dev/better-auth/client/plugins";
 import { AuthUIProvider } from "@daveyplate/better-auth-ui";
-import {
-  adminClient,
-  apiKeyClient,
-} from "better-auth/client/plugins";
+import { apiKeyClient } from "@better-auth/api-key/client";
+import { adminClient } from "better-auth/client/plugins";
 import { createAuthClient } from 'better-auth/react'
 import Link from "next/link";
 import { useRouter } from "next/navigation";

package/templates/nextjs/src/auth/permissions.ts

@@ -80,9 +80,9 @@ export function hasPermission<Resource extends keyof Permissions>({
   resource: Resource;
   user?: null | User;
 }): boolean {
-  if (!user?.role) { return false; }
+  if (!user?.roles) { return false; }
 
-  return user.role.some((role) => {
+  return user.roles.some((role) => {
     const permission = (ROLES as RolesWithPermissions)[role as UserRole][resource]?.[action]
 
     if (!permission) { return false }

package/templates/nextjs/src/db/constants/index.ts

@@ -6,6 +6,7 @@ export const TABLE_SLUG_ACCOUNTS = "account" as const;
 export const TABLE_SLUG_SESSIONS = "session" as const;
 export const TABLE_SLUG_VERIFICATIONS = "verification" as const;
 export const TABLE_SLUG_JWKS = "jwks" as const;
+export const TABLE_SLUG_API_KEYS = "apikey" as const;
 
 export const COLLECTION_SLUG_MEDIA = "media" as const;
 

package/templates/tanstack-start/convex/auth/adapter/index.ts

@@ -46,6 +46,12 @@ export const convexAdapter = <DataModel extends GenericDataModel>(
 
       return {
         id: "convex",
+        // Tell the convex() plugin this context supports mutations. It checks
+        // ctx.context.adapter.options?.isRunMutationCtx — if falsy it replaces all
+        // adapter writes with silent no-ops. HTTP actions always have runMutation.
+        options: {
+          isRunMutationCtx: "runMutation" in ctx,
+        },
 
         create: async ({ data, model, select }): Promise<any> => {
           return await ctx.runMutation(internal.auth.db.dbCreate, {
@@ -185,34 +191,12 @@ export const convexAdapter = <DataModel extends GenericDataModel>(
         if (data && fieldAttributes.type === "date") {
           return new Date(data).getTime();
         }
-        // Handle array fields - Better Auth may send single values or arrays
-        if ((fieldAttributes.type as string)?.endsWith("[]")) {
-          // If already an array, return as-is
-          if (Array.isArray(data)) {
-            return data
-          }
-          // If it's a string that looks like JSON array, parse it
-          if (typeof data === "string") {
-            try {
-              const parsed = JSON.parse(data)
-              return Array.isArray(parsed) ? parsed : [data]
-            } catch {
-              // If parsing fails, wrap the string in an array
-              return [data]
-            }
-          }
-          // For any other value type, wrap in array
-          if (data !== null && data !== undefined) {
-            return [data]
-          }
-        }
         return data;
       },
       customTransformOutput: ({ data, fieldAttributes }) => {
         if (data && fieldAttributes.type === "date") {
           return new Date(data).getTime();
         }
-        // Arrays are stored natively in Convex, no transformation needed for output
         return data;
       },
       debugLogs: config.debugLogs ?? false,
@@ -226,6 +210,7 @@ export const convexAdapter = <DataModel extends GenericDataModel>(
       supportsDates: false,
       supportsJSON: true,
       supportsNumericIds: false,
+      supportsArrays: true,
       transaction: false,
       usePlural: false,
     },

package/templates/tanstack-start/convex/auth/index.ts

@@ -39,7 +39,7 @@ export const createAuth = (
     trustedOrigins: [process.env.SITE_URL!],
     user: {
       additionalFields: {
-        role: {
+        roles: {
           type: "string[]",
           defaultValue: [USER_ROLES.user],
           required: true

package/templates/tanstack-start/convex/auth/plugins/index.ts

@@ -1,4 +1,7 @@
-import { admin, apiKey } from "better-auth/plugins"
+import { admin } from "better-auth/plugins"
+import { apiKey } from "@better-auth/api-key"
+import { convex } from "@convex-dev/better-auth/plugins"
+import authConfig from "@convex/auth.config"
 import { USER_ROLES } from "~/db/constants"
 
 const plugins = [
@@ -7,6 +10,7 @@ const plugins = [
     defaultRole: USER_ROLES.user
   }),
   apiKey(),
+  convex({ authConfig }),
 ]
 
 export default plugins

package/templates/tanstack-start/convex/auth/sessions.ts

@@ -53,7 +53,7 @@ export const getSessionWithUser = query({
 				email: user.email,
 				emailVerified: user.emailVerified,
 				image: user.image,
-				role: user.role,
+				roles: user.roles,
 			},
 		};
 	},

package/templates/tanstack-start/convex/auth.config.ts

@@ -0,0 +1,7 @@
+import type { AuthConfig } from "convex/server"
+
+import { getAuthConfigProvider } from "@convex-dev/better-auth/auth-config"
+
+export default {
+  providers: [getAuthConfigProvider()],
+} satisfies AuthConfig

package/templates/tanstack-start/convex/schema.ts

@@ -1,7 +1,14 @@
 import { defineSchema, defineTable } from "convex/server";
 import { v } from "convex/values"
 
-import { TABLE_SLUG_ACCOUNTS, TABLE_SLUG_JWKS, TABLE_SLUG_SESSIONS, TABLE_SLUG_USERS, TABLE_SLUG_VERIFICATIONS } from "~/db/constants";
+import {
+  TABLE_SLUG_ACCOUNTS,
+  TABLE_SLUG_API_KEYS,
+  TABLE_SLUG_JWKS,
+  TABLE_SLUG_SESSIONS,
+  TABLE_SLUG_USERS,
+  TABLE_SLUG_VERIFICATIONS,
+} from "~/db/constants";
 
 export default defineSchema({
   // Better Auth component tables (type definitions only - actual tables are in component)
@@ -22,7 +29,8 @@ export default defineSchema({
     banExpires: v.optional(v.number()), // admin plugin
     banned: v.optional(v.boolean()), // admin plugin
     banReason: v.optional(v.string()), // admin plugin
-    role: v.array(v.string()), // admin plugin
+    role: v.optional(v.string()), // admin plugin — single string in BA 1.5
+    roles: v.array(v.string()), // our multi-role field via additionalFields
   })
     .index("by_email", ["email"]),
 
@@ -70,4 +78,31 @@ export default defineSchema({
     privateKey: v.optional(v.string()),
     publicKey: v.string(),
   }),
+
+  // Better Auth 1.5 — apiKey plugin (@better-auth/api-key)
+  [TABLE_SLUG_API_KEYS]: defineTable({
+    configId: v.string(),           // new in 1.5, default "default"
+    name: v.optional(v.string()),
+    start: v.optional(v.string()),
+    referenceId: v.string(),        // replaces userId from 1.4
+    prefix: v.optional(v.string()),
+    key: v.string(),
+    refillInterval: v.optional(v.number()),
+    refillAmount: v.optional(v.number()),
+    lastRefillAt: v.optional(v.number()),
+    enabled: v.optional(v.boolean()),
+    rateLimitEnabled: v.optional(v.boolean()),
+    rateLimitTimeWindow: v.optional(v.number()),
+    rateLimitMax: v.optional(v.number()),
+    requestCount: v.optional(v.number()),
+    remaining: v.optional(v.number()),
+    lastRequest: v.optional(v.number()),
+    expiresAt: v.optional(v.number()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+    permissions: v.optional(v.string()),
+    metadata: v.optional(v.string()),
+  })
+    .index("by_referenceId", ["referenceId"])
+    .index("by_key", ["key"]),
 })

package/templates/tanstack-start/package.json

@@ -17,7 +17,8 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.0.0",
-    "@convex-dev/better-auth": "^0.10.9",
+    "@better-auth/api-key": "^1.0.0",
+    "@convex-dev/better-auth": "^0.11.0",
     "@convex-dev/react-query": "^0.1.0",
     "@daveyplate/better-auth-tanstack": "^1.3.6",
     "@daveyplate/better-auth-ui": "^3.3.10",
@@ -32,7 +33,7 @@
     "@tanstack/react-router-with-query": "^1.130.17",
     "@tanstack/react-start": "^1.132.0",
     "@tanstack/router-plugin": "^1.132.0",
-    "better-auth": "^1.4.9",
+    "better-auth": "^1.5.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "convex": "^1.31.2",

package/templates/tanstack-start/src/components/component-example.tsx

@@ -1,472 +1,53 @@
-import * as React from 'react'
-import {
-  BellIcon,
-  BluetoothIcon,
-  CreditCardIcon,
-  DownloadIcon,
-  EyeIcon,
-  FileCodeIcon,
-  FileIcon,
-  FileTextIcon,
-  FolderIcon,
-  FolderOpenIcon,
-  FolderSearchIcon,
-  HelpCircleIcon,
-  KeyboardIcon,
-  LanguagesIcon,
-  LayoutIcon,
-  LogOutIcon,
-  MailIcon,
-  MonitorIcon,
-  MoonIcon,
-  MoreHorizontalIcon,
-  MoreVerticalIcon,
-  PaletteIcon,
-  PlusIcon,
-  SaveIcon,
-  SettingsIcon,
-  ShieldIcon,
-  SunIcon,
-  UserIcon,
-} from 'lucide-react'
+import { Link } from '@tanstack/react-router'
+import { TerminalIcon, UserIcon } from 'lucide-react'
 
-import { Example, ExampleWrapper } from '~/components/example'
-import {
-  AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
-  AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
-  AlertDialogHeader,
-  AlertDialogMedia,
-  AlertDialogTitle,
-  AlertDialogTrigger,
-} from '~/components/ui/alert-dialog'
-import { Badge } from '~/components/ui/badge'
+import { signOut, useSession } from '~/lib/auth/client'
 import { Button } from '~/components/ui/button'
-import {
-  Card,
-  CardAction,
-  CardContent,
-  CardDescription,
-  CardFooter,
-  CardHeader,
-  CardTitle,
-} from '~/components/ui/card'
-import {
-  Combobox,
-  ComboboxContent,
-  ComboboxEmpty,
-  ComboboxInput,
-  ComboboxItem,
-  ComboboxList,
-} from '~/components/ui/combobox'
-import {
-  DropdownMenu,
-  DropdownMenuCheckboxItem,
-  DropdownMenuContent,
-  DropdownMenuGroup,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuPortal,
-  DropdownMenuRadioGroup,
-  DropdownMenuRadioItem,
-  DropdownMenuSeparator,
-  DropdownMenuShortcut,
-  DropdownMenuSub,
-  DropdownMenuSubContent,
-  DropdownMenuSubTrigger,
-  DropdownMenuTrigger,
-} from '~/components/ui/dropdown-menu'
-import { Field, FieldGroup, FieldLabel } from '~/components/ui/field'
-import { Input } from '~/components/ui/input'
-import {
-  Select,
-  SelectContent,
-  SelectGroup,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '~/components/ui/select'
-import { Textarea } from '~/components/ui/textarea'
-import { ThemeToggle } from '~/components/ui/theme-toggle'
 
 export function ComponentExample() {
-  return (
-    <ExampleWrapper>
-      <ThemeToggle className="absolute w-md:top-10 right-10 top-2" />
-      <CardExample />
-      <FormExample />
-    </ExampleWrapper>
-  )
-}
+  const { data: session } = useSession()
 
-function CardExample() {
   return (
-    <Example title="Card" className="items-center justify-center">
-      <Card className="relative w-full max-w-sm overflow-hidden pt-0">
-        <div className="bg-primary absolute inset-0 z-30 aspect-video opacity-50 mix-blend-color" />
-        <img
-          src="https://images.unsplash.com/photo-1604076850742-4c7221f3101b?q=80&w=1887&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
-          alt="Photo by mymind on Unsplash"
-          title="Photo by mymind on Unsplash"
-          className="relative z-20 aspect-video w-full object-cover brightness-60 grayscale"
-        />
-        <CardHeader>
-          <CardTitle>Observability Plus is replacing Monitoring</CardTitle>
-          <CardDescription>
-            Switch to the improved way to explore your data, with natural language. Monitoring will
-            no longer be available on the Pro plan in November, 2025
-          </CardDescription>
-        </CardHeader>
-        <CardFooter>
-          <AlertDialog>
-            <AlertDialogTrigger render={<Button />}>
-              <PlusIcon data-icon="inline-start" />
-              Show Dialog
-            </AlertDialogTrigger>
-            <AlertDialogContent size="sm">
-              <AlertDialogHeader>
-                <AlertDialogMedia>
-                  <BluetoothIcon />
-                </AlertDialogMedia>
-                <AlertDialogTitle>Allow accessory to connect?</AlertDialogTitle>
-                <AlertDialogDescription>
-                  Do you want to allow the USB accessory to connect to this device?
-                </AlertDialogDescription>
-              </AlertDialogHeader>
-              <AlertDialogFooter>
-                <AlertDialogCancel>Don&apos;t allow</AlertDialogCancel>
-                <AlertDialogAction>Allow</AlertDialogAction>
-              </AlertDialogFooter>
-            </AlertDialogContent>
-          </AlertDialog>
-          <Badge variant="secondary" className="ml-auto">
-            Warning
-          </Badge>
-        </CardFooter>
-      </Card>
-    </Example>
-  )
-}
-
-const frameworks = ['Next.js', 'SvelteKit', 'Nuxt.js', 'Remix', 'Astro'] as const
+    <div className="bg-background flex min-h-screen flex-col items-center justify-center gap-8 p-6 text-center">
+      {session?.user && (
+        <div className="absolute top-4 right-4 flex items-center gap-2">
+          <div className="bg-muted flex size-8 items-center justify-center rounded-full">
+            <UserIcon className="text-muted-foreground size-4" />
+          </div>
+          <span className="text-sm font-medium">{session.user.name}</span>
+        </div>
+      )}
 
-const roleItems = [
-  { label: 'Developer', value: 'developer' },
-  { label: 'Designer', value: 'designer' },
-  { label: 'Manager', value: 'manager' },
-  { label: 'Other', value: 'other' },
-]
+      <div className="flex flex-col items-center gap-4">
+        <div className="bg-foreground text-background flex size-14 items-center justify-center rounded-2xl">
+          <TerminalIcon className="size-7" />
+        </div>
+        <div className="flex flex-col gap-1">
+          <h1 className="text-3xl font-bold tracking-tight">create-z3-app</h1>
+          <p className="text-muted-foreground max-w-sm text-base">
+            A full-stack starter with TanStack Start, Convex, and Better Auth — ready to ship.
+          </p>
+        </div>
+      </div>
 
-function FormExample() {
-  const [notifications, setNotifications] = React.useState({
-    email: true,
-    sms: false,
-    push: true,
-  })
-  const [theme, setTheme] = React.useState('light')
+      <div className="flex gap-3">
+        {session?.user ? (
+          <Button variant="outline" onClick={() => signOut()}>Sign out</Button>
+        ) : (
+          <>
+            <Button asChild>
+              <Link to="/auth/$authView" params={{ authView: 'sign-up' }}>Sign up</Link>
+            </Button>
+            <Button variant="outline" asChild>
+              <Link to="/auth/$authView" params={{ authView: 'sign-in' }}>Sign in</Link>
+            </Button>
+          </>
+        )}
+      </div>
 
-  return (
-    <Example title="Form">
-      <Card className="w-full max-w-md">
-        <CardHeader>
-          <CardTitle>User Information</CardTitle>
-          <CardDescription>Please fill in your details below</CardDescription>
-          <CardAction>
-            <DropdownMenu>
-              <DropdownMenuTrigger render={<Button variant="ghost" size="icon" />}>
-                <MoreVerticalIcon />
-                <span className="sr-only">More options</span>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="end" className="w-56">
-                <DropdownMenuGroup>
-                  <DropdownMenuLabel>File</DropdownMenuLabel>
-                  <DropdownMenuItem>
-                    <FileIcon />
-                    New File
-                    <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
-                  </DropdownMenuItem>
-                  <DropdownMenuItem>
-                    <FolderIcon />
-                    New Folder
-                    <DropdownMenuShortcut>⇧⌘N</DropdownMenuShortcut>
-                  </DropdownMenuItem>
-                  <DropdownMenuSub>
-                    <DropdownMenuSubTrigger>
-                      <FolderOpenIcon />
-                      Open Recent
-                    </DropdownMenuSubTrigger>
-                    <DropdownMenuPortal>
-                      <DropdownMenuSubContent>
-                        <DropdownMenuGroup>
-                          <DropdownMenuLabel>Recent Projects</DropdownMenuLabel>
-                          <DropdownMenuItem>
-                            <FileCodeIcon />
-                            Project Alpha
-                          </DropdownMenuItem>
-                          <DropdownMenuItem>
-                            <FileCodeIcon />
-                            Project Beta
-                          </DropdownMenuItem>
-                          <DropdownMenuSub>
-                            <DropdownMenuSubTrigger>
-                              <MoreHorizontalIcon />
-                              More Projects
-                            </DropdownMenuSubTrigger>
-                            <DropdownMenuPortal>
-                              <DropdownMenuSubContent>
-                                <DropdownMenuItem>
-                                  <FileCodeIcon />
-                                  Project Gamma
-                                </DropdownMenuItem>
-                                <DropdownMenuItem>
-                                  <FileCodeIcon />
-                                  Project Delta
-                                </DropdownMenuItem>
-                              </DropdownMenuSubContent>
-                            </DropdownMenuPortal>
-                          </DropdownMenuSub>
-                        </DropdownMenuGroup>
-                        <DropdownMenuSeparator />
-                        <DropdownMenuGroup>
-                          <DropdownMenuItem>
-                            <FolderSearchIcon />
-                            Browse...
-                          </DropdownMenuItem>
-                        </DropdownMenuGroup>
-                      </DropdownMenuSubContent>
-                    </DropdownMenuPortal>
-                  </DropdownMenuSub>
-                  <DropdownMenuSeparator />
-                  <DropdownMenuItem>
-                    <SaveIcon />
-                    Save
-                    <DropdownMenuShortcut>⌘S</DropdownMenuShortcut>
-                  </DropdownMenuItem>
-                  <DropdownMenuItem>
-                    <DownloadIcon />
-                    Export
-                    <DropdownMenuShortcut>⇧⌘E</DropdownMenuShortcut>
-                  </DropdownMenuItem>
-                </DropdownMenuGroup>
-                <DropdownMenuSeparator />
-                <DropdownMenuGroup>
-                  <DropdownMenuLabel>View</DropdownMenuLabel>
-                  <DropdownMenuCheckboxItem
-                    checked={notifications.email}
-                    onCheckedChange={(checked) =>
-                      setNotifications({
-                        ...notifications,
-                        email: checked === true,
-                      })
-                    }
-                  >
-                    <EyeIcon />
-                    Show Sidebar
-                  </DropdownMenuCheckboxItem>
-                  <DropdownMenuCheckboxItem
-                    checked={notifications.sms}
-                    onCheckedChange={(checked) =>
-                      setNotifications({
-                        ...notifications,
-                        sms: checked === true,
-                      })
-                    }
-                  >
-                    <LayoutIcon />
-                    Show Status Bar
-                  </DropdownMenuCheckboxItem>
-                  <DropdownMenuSub>
-                    <DropdownMenuSubTrigger>
-                      <PaletteIcon />
-                      Theme
-                    </DropdownMenuSubTrigger>
-                    <DropdownMenuPortal>
-                      <DropdownMenuSubContent>
-                        <DropdownMenuGroup>
-                          <DropdownMenuLabel>Appearance</DropdownMenuLabel>
-                          <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
-                            <DropdownMenuRadioItem value="light">
-                              <SunIcon />
-                              Light
-                            </DropdownMenuRadioItem>
-                            <DropdownMenuRadioItem value="dark">
-                              <MoonIcon />
-                              Dark
-                            </DropdownMenuRadioItem>
-                            <DropdownMenuRadioItem value="system">
-                              <MonitorIcon />
-                              System
-                            </DropdownMenuRadioItem>
-                          </DropdownMenuRadioGroup>
-                        </DropdownMenuGroup>
-                      </DropdownMenuSubContent>
-                    </DropdownMenuPortal>
-                  </DropdownMenuSub>
-                </DropdownMenuGroup>
-                <DropdownMenuSeparator />
-                <DropdownMenuGroup>
-                  <DropdownMenuLabel>Account</DropdownMenuLabel>
-                  <DropdownMenuItem>
-                    <UserIcon />
-                    Profile
-                    <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
-                  </DropdownMenuItem>
-                  <DropdownMenuItem>
-                    <CreditCardIcon />
-                    Billing
-                  </DropdownMenuItem>
-                  <DropdownMenuSub>
-                    <DropdownMenuSubTrigger>
-                      <SettingsIcon />
-                      Settings
-                    </DropdownMenuSubTrigger>
-                    <DropdownMenuPortal>
-                      <DropdownMenuSubContent>
-                        <DropdownMenuGroup>
-                          <DropdownMenuLabel>Preferences</DropdownMenuLabel>
-                          <DropdownMenuItem>
-                            <KeyboardIcon />
-                            Keyboard Shortcuts
-                          </DropdownMenuItem>
-                          <DropdownMenuItem>
-                            <LanguagesIcon />
-                            Language
-                          </DropdownMenuItem>
-                          <DropdownMenuSub>
-                            <DropdownMenuSubTrigger>
-                              <BellIcon />
-                              Notifications
-                            </DropdownMenuSubTrigger>
-                            <DropdownMenuPortal>
-                              <DropdownMenuSubContent>
-                                <DropdownMenuGroup>
-                                  <DropdownMenuLabel>Notification Types</DropdownMenuLabel>
-                                  <DropdownMenuCheckboxItem
-                                    checked={notifications.push}
-                                    onCheckedChange={(checked) =>
-                                      setNotifications({
-                                        ...notifications,
-                                        push: checked === true,
-                                      })
-                                    }
-                                  >
-                                    <BellIcon />
-                                    Push Notifications
-                                  </DropdownMenuCheckboxItem>
-                                  <DropdownMenuCheckboxItem
-                                    checked={notifications.email}
-                                    onCheckedChange={(checked) =>
-                                      setNotifications({
-                                        ...notifications,
-                                        email: checked === true,
-                                      })
-                                    }
-                                  >
-                                    <MailIcon />
-                                    Email Notifications
-                                  </DropdownMenuCheckboxItem>
-                                </DropdownMenuGroup>
-                              </DropdownMenuSubContent>
-                            </DropdownMenuPortal>
-                          </DropdownMenuSub>
-                        </DropdownMenuGroup>
-                        <DropdownMenuSeparator />
-                        <DropdownMenuGroup>
-                          <DropdownMenuItem>
-                            <ShieldIcon />
-                            Privacy & Security
-                          </DropdownMenuItem>
-                        </DropdownMenuGroup>
-                      </DropdownMenuSubContent>
-                    </DropdownMenuPortal>
-                  </DropdownMenuSub>
-                </DropdownMenuGroup>
-                <DropdownMenuSeparator />
-                <DropdownMenuGroup>
-                  <DropdownMenuItem>
-                    <HelpCircleIcon />
-                    Help & Support
-                  </DropdownMenuItem>
-                  <DropdownMenuItem>
-                    <FileTextIcon />
-                    Documentation
-                  </DropdownMenuItem>
-                </DropdownMenuGroup>
-                <DropdownMenuSeparator />
-                <DropdownMenuGroup>
-                  <DropdownMenuItem variant="destructive">
-                    <LogOutIcon />
-                    Sign Out
-                    <DropdownMenuShortcut>⇧⌘Q</DropdownMenuShortcut>
-                  </DropdownMenuItem>
-                </DropdownMenuGroup>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          </CardAction>
-        </CardHeader>
-        <CardContent>
-          <form>
-            <FieldGroup>
-              <div className="grid grid-cols-2 gap-4">
-                <Field>
-                  <FieldLabel htmlFor="small-form-name">Name</FieldLabel>
-                  <Input id="small-form-name" placeholder="Enter your name" required />
-                </Field>
-                <Field>
-                  <FieldLabel htmlFor="small-form-role">Role</FieldLabel>
-                  <Select items={roleItems} defaultValue={null}>
-                    <SelectTrigger id="small-form-role">
-                      <SelectValue />
-                    </SelectTrigger>
-                    <SelectContent>
-                      <SelectGroup>
-                        {roleItems.map((item) => (
-                          <SelectItem key={item.value} value={item.value}>
-                            {item.label}
-                          </SelectItem>
-                        ))}
-                      </SelectGroup>
-                    </SelectContent>
-                  </Select>
-                </Field>
-              </div>
-              <Field>
-                <FieldLabel htmlFor="small-form-framework">Framework</FieldLabel>
-                <Combobox items={frameworks}>
-                  <ComboboxInput
-                    id="small-form-framework"
-                    placeholder="Select a framework"
-                    required
-                  />
-                  <ComboboxContent>
-                    <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
-                    <ComboboxList>
-                      {(item) => (
-                        <ComboboxItem key={item} value={item}>
-                          {item}
-                        </ComboboxItem>
-                      )}
-                    </ComboboxList>
-                  </ComboboxContent>
-                </Combobox>
-              </Field>
-              <Field>
-                <FieldLabel htmlFor="small-form-comments">Comments</FieldLabel>
-                <Textarea id="small-form-comments" placeholder="Add any additional comments" />
-              </Field>
-              <Field orientation="horizontal">
-                <Button type="submit">Submit</Button>
-                <Button variant="outline" type="button">
-                  Cancel
-                </Button>
-              </Field>
-            </FieldGroup>
-          </form>
-        </CardContent>
-      </Card>
-    </Example>
+      <code className="bg-muted text-muted-foreground rounded-lg px-4 py-2 text-sm font-mono">
+        npm create z3-app@latest
+      </code>
+    </div>
   )
 }

package/templates/tanstack-start/src/db/constants/index.ts

@@ -6,3 +6,4 @@ export const TABLE_SLUG_ACCOUNTS = "account" as const;
 export const TABLE_SLUG_SESSIONS = "session" as const;
 export const TABLE_SLUG_VERIFICATIONS = "verification" as const;
 export const TABLE_SLUG_JWKS = "jwks" as const;
+export const TABLE_SLUG_API_KEYS = "apikey" as const;

package/templates/tanstack-start/src/lib/auth/client.ts

@@ -1,5 +1,6 @@
 import { createAuthClient } from "better-auth/react"
-import { adminClient, apiKeyClient } from "better-auth/client/plugins"
+import { adminClient } from "better-auth/client/plugins"
+import { apiKeyClient } from "@better-auth/api-key/client"
 import { env } from '~/env';
 
 export const authClient = createAuthClient({

package/templates/tanstack-start/src/lib/auth/permissions.ts

@@ -80,9 +80,9 @@ export function hasPermission<Resource extends keyof Permissions>({
   resource: Resource;
   user?: null | User;
 }): boolean {
-  if (!user?.role) { return false; }
+  if (!user?.roles) { return false; }
 
-  return user.role.some((role) => {
+  return user.roles.some((role) => {
     const permission = (ROLES as RolesWithPermissions)[role as UserRole][resource]?.[action]
 
     if (!permission) { return false }

package/templates/tanstack-start/src/routes/auth/$authView.tsx

@@ -8,7 +8,7 @@ export const Route = createFileRoute('/auth/$authView')({
 function RouteComponent() {
   const { authView } = Route.useParams()
   return (
-    <main className="container mx-auto flex grow flex-col items-center justify-center gap-3 self-center p-4 md:p-6">
+    <main className="mx-auto flex h-[100svh] grow flex-col items-center justify-center gap-3 self-center p-4 md:p-6">
       <AuthView pathname={authView} />
     </main>
   )