create-aphex 0.1.0

package/templates/base/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+	"version": "7",
+	"dialect": "postgresql",
+	"entries": [
+		{
+			"idx": 0,
+			"version": "7",
+			"when": 1776958642085,
+			"tag": "0000_tiny_redwing",
+			"breakpoints": true
+		}
+	]
+}

package/templates/base/drizzle.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'drizzle-kit';
+// import { pgConnectionUrl } from '@aphexcms/postgresql-adapter';
+
+// Note: Ideally we'd use pgConnectionUrl from @aphexcms/postgresql-adapter,
+// but drizzle-kit has issues resolving workspace dependencies in monorepos.
+// Inlining the connection URL logic as a workaround.
+const databaseUrl =
+	process.env.DATABASE_URL ||
+	`postgresql://${process.env.PG_USER || 'root'}:${process.env.PG_PASSWORD || 'mysecretpassword'}@${process.env.PG_HOST || 'localhost'}:${process.env.PG_PORT || '5432'}/${process.env.PG_DATABASE || 'local'}`;
+
+export default defineConfig({
+	schema: './src/lib/server/db/schema.ts',
+	dialect: 'postgresql',
+	dbCredentials: { url: databaseUrl },
+	verbose: true,
+	strict: true
+});

package/templates/base/package.json

@@ -0,0 +1,81 @@
+{
+	"name": "@aphexcms/base",
+	"version": "0.0.2",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"dev": "vite dev --force --host",
+		"build": "vite build",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+		"db:start": "docker compose up -d",
+		"db:delete": "docker compose down -v",
+		"db:push": "drizzle-kit push",
+		"db:generate": "drizzle-kit generate",
+		"db:migrate": "drizzle-kit migrate",
+		"db:studio": "drizzle-kit studio",
+		"generate:types": "aphex generate:types ./src/lib/schemaTypes/index.ts ./src/lib/generated-types.ts",
+		"test": "vitest run",
+		"test:verbose": "vitest run --reporter=verbose",
+		"test:watch": "vitest",
+		"test:ui": "vitest --ui",
+		"test:local": "vitest run comprehensive-local-api",
+		"test:http": "vitest run comprehensive-http-api",
+		"test:graphql": "vitest run comprehensive-graphql-api",
+		"test:all": "vitest run comprehensive",
+		"test:coverage": "vitest run --coverage",
+		"test:date": "tsx scripts/test-date-localapi.ts"
+	},
+	"dependencies": {
+		"@aphexcms/cms-core": "^5.0.0",
+		"@aphexcms/nodemailer-adapter": "^7.0.0",
+		"@aphexcms/postgresql-adapter": "^6.0.0",
+		"@aphexcms/resend-adapter": "^6.0.0",
+		"@aphexcms/storage-s3": "^6.0.0",
+		"@aphexcms/ui": "^0.4.0",
+		"@better-auth/api-key": "^1.5.3",
+		"@better-auth/drizzle-adapter": "^1.5.3",
+		"@envelop/graphql-jit": "^11.0.0",
+		"@graphql-yoga/render-graphiql": "^5.16.2",
+		"better-auth": "^1.5.3",
+		"better-svelte-email": "^1.4.0",
+		"drizzle-orm": "^0.44.7",
+		"graphql": "^16.12.0",
+		"graphql-yoga": "^5.16.2",
+		"mode-watcher": "^1.1.0",
+		"postgres": "^3.4.7",
+		"sharp": "^0.34.5",
+		"svelte-sonner": "^1.0.7"
+	},
+	"devDependencies": {
+		"@hono/zod-validator": "^0.7.6",
+		"@internationalized/date": "^3.10.0",
+		"@lucide/svelte": "^0.554.0",
+		"@sveltejs/adapter-auto": "^7.0.0",
+		"@sveltejs/adapter-node": "^5.4.0",
+		"@sveltejs/kit": "^2.49.0",
+		"@sveltejs/vite-plugin-svelte": "^6.2.1",
+		"@tailwindcss/vite": "^4.1.17",
+		"@types/node": "^22.0.0",
+		"@vitest/ui": "^4.0.14",
+		"bits-ui": "^2.14.4",
+		"clsx": "^2.1.1",
+		"dotenv": "^17.2.3",
+		"drizzle-kit": "^0.31.7",
+		"hono": "^4.12.15",
+		"mdsvex": "^0.12.6",
+		"svelte": "^5.44.0",
+		"svelte-check": "^4.3.4",
+		"tailwind-merge": "^3.4.0",
+		"tailwind-variants": "^3.2.2",
+		"tailwindcss": "^4.1.17",
+		"tsx": "^4.20.6",
+		"tw-animate-css": "^1.4.0",
+		"typescript": "^5.9.3",
+		"vite": "^7.2.4",
+		"vitest": "^4.0.14",
+		"zod": "^4.3.6"
+	}
+}

package/templates/base/prod.docker-compose.yml

@@ -0,0 +1,61 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: aphex-postgres
+    restart: unless-stopped
+    env_file:
+      - .env.production
+    environment:
+      POSTGRES_USER: ${DB_USER}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_DB: ${DB_NAME}
+    ports:
+      - '5433:5432'
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U ${DB_USER:-aphex} -d ${DB_NAME:-aphex_cms}']
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  studio:
+    build:
+      context: ../..
+      dockerfile: apps/studio/Dockerfile
+      args:
+        ACCESS_API_KEY: ${ACCESS_API_KEY}
+        GITHUB_TOKEN: ${GITHUB_TOKEN}
+        RESEND_API_KEY: ${RESEND_API_KEY}
+        AUTH_SECRET: ${AUTH_SECRET}
+        AUTH_URL: ${AUTH_URL}
+        DATABASE_URL: ${DATABASE_URL}
+    container_name: aphex-studio
+    restart: unless-stopped
+    env_file:
+      - .env.production
+    ports:
+      - '3020:3000'
+    environment:
+      - .env.production
+    depends_on:
+      postgres:
+        condition: service_healthy
+    volumes:
+      - ./storage:/app/apps/studio/storage
+
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    container_name: aphex-cloudflared
+    restart: unless-stopped
+    command: tunnel run
+    environment:
+      TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN}
+    depends_on:
+      - studio
+    profiles:
+      - cloudflare
+
+volumes:
+  postgres_data:
+    driver: local

package/templates/base/src/app.css

@@ -0,0 +1,32 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import '@aphexcms/ui/shadcn/css';
+@source '../node_modules/@aphexcms/ui/dist/**/*.{html,js,svelte,ts}'; /*Import shadcn tailwind styles*/
+@source '../node_modules/@aphexcms/cms-core/dist/**/*.{html,js,svelte,ts}'; /*Import cms-core component styles*/
+
+/* Ensure full height layout */
+html,
+body {
+	height: 100%;
+}
+
+/* Custom utility classes */
+@layer utilities {
+	.full-height-layout {
+		height: 100vh;
+		display: flex;
+		flex-direction: column;
+	}
+
+	.admin-content-height {
+		height: calc(100vh - 3rem); /* Desktop: subtract top navbar */
+		display: flex;
+		flex-direction: column;
+	}
+
+	.admin-content-height-mobile {
+		height: calc(100vh - 6rem); /* Mobile: subtract top navbar + breadcrumb */
+		display: flex;
+		flex-direction: column;
+	}
+}

package/templates/base/src/app.d.ts

@@ -0,0 +1,26 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+// for information about these interfaces
+//
+import type { CMSInstances } from '@aphexcms/cms-core/server';
+import type { Auth } from '@aphexcms/cms-core/server';
+
+// Side-effect imports that activate module augmentations globally:
+// - generated-types: schema-derived document/collection types
+// - @aphexcms/cms-core/app-augment: PageData.rbac typing
+import '$lib/generated-types';
+import '@aphexcms/cms-core/app-augment';
+
+declare global {
+	namespace App {
+		// interface Error {}
+		interface Locals {
+			aphexCMS: CMSInstances;
+			auth?: Auth; // Available in protected routes
+		}
+		// interface PageData {}
+		// interface PageState {}
+		// interface Platform {}
+	}
+}
+
+export {};

package/templates/base/src/app.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

package/templates/base/src/hooks.server.ts

@@ -0,0 +1,52 @@
+import { sequence } from '@sveltejs/kit/hooks';
+import { redirect } from '@sveltejs/kit';
+import type { Handle } from '@sveltejs/kit';
+import { svelteKitHandler } from 'better-auth/svelte-kit';
+import { building, dev } from '$app/environment';
+import { createCMSHook } from '@aphexcms/cms-core/server';
+import { auth } from '$lib/server/auth';
+
+// Better Auth hook (handles /api/auth/* routes)
+const authHook: Handle = async ({ event, resolve }) => {
+	return svelteKitHandler({ event, resolve, auth, building });
+};
+
+// CMS hook for dependency injection and route protection
+// Schema changes invalidate the module graph and set __aphexSchemasDirty,
+// which resets the hook instance so the next request re-initializes.
+let aphexHookInstance: Handle | null = null;
+
+const aphexHook: Handle = async ({ event, resolve }) => {
+	// Check if schemas changed (set by Vite plugin)
+	if ((global as any).__aphexSchemasDirty) {
+		(global as any).__aphexSchemasDirty = false;
+		aphexHookInstance = null;
+	}
+
+	if (!aphexHookInstance) {
+		// Cache-bust so Vite returns a freshly evaluated module after HMR —
+		// plain `import('../aphex.config.ts')` returns the cached instance even
+		// after module-graph invalidation, so the schemaTypes array stays stale.
+		const cacheBust = dev ? `?t=${Date.now()}` : '';
+		const cmsConfig = (await import(/* @vite-ignore */ `../aphex.config.ts${cacheBust}`)).default;
+		// During HMR, the module graph may be partially invalidated and the
+		// dynamic import can resolve before the config module has re-executed,
+		// yielding undefined.  Skip this request and let the next one retry.
+		if (!cmsConfig) {
+			if (dev) console.warn('[CMS] Config not ready during HMR, skipping request');
+			return resolve(event);
+		}
+		aphexHookInstance = createCMSHook(cmsConfig);
+	}
+	return aphexHookInstance({ event, resolve });
+};
+
+const routingHook: Handle = async ({ event, resolve }) => {
+	if (event.url.pathname === '/') {
+		throw redirect(302, '/admin');
+	}
+	return resolve(event);
+};
+
+// Combine hooks - authHook must be first, then CMS for DB access and auth protection
+export const handle = sequence(authHook, aphexHook, routingHook);

package/templates/base/src/lib/assets/favicon.svg

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" width="512" height="512">
+<path d="M0 0 C17.1474496 14.16905616 25.92496627 35.45820085 34.56640625 55.4140625 C35.34334316 57.19720923 36.12053079 58.98024674 36.89794922 60.76318359 C51.78722595 94.97195072 66.32335778 129.32882671 80.31640625 163.9140625 C80.6444928 164.72450012 80.97257935 165.53493774 81.31060791 166.36993408 C99.98913061 212.53216334 117.78569191 259.01293728 134.00390625 306.1015625 C134.36190811 307.13669983 134.36190811 307.13669983 134.72714233 308.19274902 C137.32766526 315.72906515 139.80262285 323.3004011 142.1171875 330.9296875 C142.43800545 331.95940926 142.43800545 331.95940926 142.76530457 333.00993347 C145.2565569 341.39135358 146.09964488 351.05219488 142.44140625 359.23046875 C139.92789443 362.992009 136.34564423 365.89944351 132.31640625 367.9140625 C124.8558052 368.61421121 118.36839373 368.62364314 112.31640625 363.9140625 C105.53664487 356.69699976 100.652558 348.68983785 95.94140625 340.0390625 C90.47619491 330.29913602 84.93335438 322.05287151 77.31640625 313.9140625 C75.27331056 311.57880549 73.26394666 309.2152832 71.25390625 306.8515625 C70.24519648 305.67152884 69.23608749 304.49183631 68.2265625 303.3125 C67.73816895 302.74112305 67.24977539 302.16974609 66.74658203 301.58105469 C65.40017275 300.01169952 64.04454028 298.45078423 62.6875 296.890625 C48.81582552 280.69615056 38.44623629 261.89870442 27.89111328 243.45849609 C-8.42360388 178.69858879 -8.42360388 178.69858879 -68.08203125 137.78515625 C-79.11186673 135.11741947 -89.899608 136.09230489 -99.68359375 141.9140625 C-115.46806791 152.47947666 -122.3076261 172.13261849 -126.43359375 189.7890625 C-126.73185059 191.06136719 -126.73185059 191.06136719 -127.03613281 192.359375 C-130.16760015 206.71148601 -131.06828893 221.08194412 -130.99609375 235.7265625 C-130.9939386 236.51966827 -130.99178345 237.31277405 -130.98956299 238.12991333 C-131.31394288 266.6844263 -131.31394288 266.6844263 -123.23828125 293.5859375 C-112.95312656 315.60340432 -111.26097095 345.34400812 -119.5 368.0390625 C-124.86779615 381.07766965 -132.78250397 390.79435644 -145.68359375 396.9140625 C-155.27731384 400.41943083 -164.20346687 401.56551213 -174.37109375 401.4140625 C-176.32958252 401.39702271 -176.32958252 401.39702271 -178.32763672 401.37963867 C-197.70054192 400.99323331 -215.16231823 397.0095896 -230.68359375 384.9140625 C-231.37066406 384.41519531 -232.05773437 383.91632813 -232.765625 383.40234375 C-244.80767188 373.97296976 -251.15090869 358.63090674 -253.68359375 343.9140625 C-253.9270261 339.66653687 -253.91464574 335.41789154 -253.93359375 331.1640625 C-253.96453125 329.45089844 -253.96453125 329.45089844 -253.99609375 327.703125 C-254.00125 326.58164062 -254.00640625 325.46015625 -254.01171875 324.3046875 C-254.02106445 323.29438477 -254.03041016 322.28408203 -254.04003906 321.24316406 C-253.25260131 313.88871121 -250.02140677 307.08532381 -247.0859375 300.359375 C-246.73986954 299.55749252 -246.39380157 298.75561005 -246.0372467 297.9294281 C-245.29136983 296.20150738 -244.54396437 294.47424582 -243.79516602 292.74758911 C-241.75797546 288.04789133 -239.73451175 283.34229198 -237.7109375 278.63671875 C-237.0834108 277.17808662 -237.0834108 277.17808662 -236.44320679 275.68998718 C-232.12759637 265.64489937 -227.89599701 255.56528394 -223.68359375 245.4765625 C-223.31303864 244.58933502 -222.94248352 243.70210754 -222.56069946 242.78799438 C-221.05624911 239.1852842 -219.55230259 235.58236459 -218.04930115 231.97904968 C-215.45620988 225.7624217 -212.85713855 219.54832537 -210.25390625 213.3359375 C-199.87599396 188.56875674 -189.53860671 163.78483086 -179.21582031 138.99462891 C-176.70326253 132.96093438 -174.18966694 126.92767262 -171.67578125 120.89453125 C-171.2632309 119.90436005 -170.85068054 118.91418884 -170.42562866 117.89401245 C-168.35461551 112.92351005 -166.28304289 107.95324201 -164.21044922 102.98339844 C-160.33953189 93.69973915 -156.47385511 84.41400336 -152.62658691 75.12051392 C-150.82992691 70.78139762 -149.03030349 66.44351312 -147.23046875 62.10571289 C-146.38199036 60.05847127 -145.53492768 58.01064218 -144.68945312 55.9621582 C-140.72547669 46.35880091 -136.72273166 36.78723512 -132.3203125 27.375 C-132.00310242 26.69433975 -131.68589233 26.0136795 -131.35906982 25.31239319 C-123.25124472 8.26154126 -109.39227096 -6.16254505 -91.68359375 -13.0859375 C-59.99340229 -22.6620319 -26.67593546 -20.59334511 0 0 Z " fill="#FFFFFF" transform="translate(308.68359375,64.0859375)"/>
+<path d="M0 0 C18.24717952 9.79342293 31.4582424 26.28742033 37.6171875 45.97265625 C39.90862161 58.10790422 38.62948747 76.77026254 32.3125 87.5625 C31.23887442 89.06398132 30.13305826 90.54284625 29 92 C28.04867187 93.39798828 28.04867187 93.39798828 27.078125 94.82421875 C22.05477616 102.1158627 16.59613089 108.96607145 8 112 C-4.55244493 113.74100692 -12.66496084 107.03937869 -22.140625 99.87890625 C-25.14482573 97.61370274 -28.2068393 95.46853473 -31.33056641 93.37231445 C-44.35072813 84.61921656 -53.55106508 73.69367426 -57 58 C-59.27762162 41.63399726 -53.36243485 19.43955677 -44.1875 5.9375 C-32.8352893 -8.66127096 -15.43371672 -7.37348527 0 0 Z " fill="#FFFFFF" transform="translate(254,240)"/>
+</svg>

package/templates/base/src/lib/auth-client.ts

@@ -0,0 +1,19 @@
+// Better Auth client for Svelte
+import { createAuthClient } from 'better-auth/svelte';
+import { apiKeyClient } from '@better-auth/api-key/client';
+
+export const authClient = createAuthClient({
+	// Base URL is same domain, so we don't need to specify it
+	plugins: [
+		apiKeyClient() // Enable API key management from client
+	]
+});
+
+// Export specific methods for convenience
+export const {
+	signIn,
+	signUp,
+	signOut,
+	useSession,
+	apiKey // API key management methods
+} = authClient;

package/templates/base/src/lib/index.ts

@@ -0,0 +1 @@
+// place files you want to import through the `$lib` alias in this folder.

package/templates/base/src/lib/schemaTypes/index.ts

@@ -0,0 +1,11 @@
+// Schema Registry
+// ================
+// Define your content schemas here and add them to the array below.
+// Each schema is either a 'document' (top-level entity) or an 'object' (reusable nested structure).
+//
+// See the Aphex CMS docs for available field types:
+// string, text, number, boolean, slug, image, date, datetime, url, array, object, reference
+
+import post from './post.js';
+
+export const schemaTypes = [post];

package/templates/base/src/lib/schemaTypes/post.ts

@@ -0,0 +1,47 @@
+import type { SchemaType } from '@aphexcms/cms-core';
+
+const post: SchemaType = {
+	type: 'document',
+	name: 'post',
+	title: 'Post',
+	description: 'Blog posts',
+	fields: [
+		{
+			name: 'title',
+			type: 'string',
+			title: 'Title',
+			validation: (Rule) => Rule.required()
+		},
+		{
+			name: 'slug',
+			type: 'slug',
+			title: 'Slug',
+			source: 'title',
+			validation: (Rule) => Rule.required()
+		},
+		{
+			name: 'excerpt',
+			type: 'text',
+			title: 'Excerpt',
+			description: 'A short summary of the post'
+		},
+		{
+			name: 'content',
+			type: 'text',
+			title: 'Content'
+		},
+		{
+			name: 'coverImage',
+			type: 'image',
+			title: 'Cover Image'
+		},
+		{
+			name: 'published',
+			type: 'boolean',
+			title: 'Published',
+			initialValue: false
+		}
+	]
+};
+
+export default post;

package/templates/base/src/lib/server/auth/better-auth/instance.ts

@@ -0,0 +1,165 @@
+// apps/studio/src/lib/server/auth/better-auth/instance.ts
+
+import { env } from '$env/dynamic/private';
+import { betterAuth } from 'better-auth';
+import { apiKey } from '@better-auth/api-key';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { createAuthMiddleware } from 'better-auth/api';
+import type { DatabaseAdapter } from '@aphexcms/cms-core/server';
+import type { EmailAdapter } from '@aphexcms/cms-core/server';
+import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import { cmsLogger } from '@aphexcms/cms-core';
+import { emailConfig } from '../../email';
+import { cacheAdapter } from '../../cache';
+
+// Support both AUTH_* (preferred) and BETTER_AUTH_* (backwards-compatible)
+const authSecret = env.AUTH_SECRET || env.BETTER_AUTH_SECRET;
+const authUrl = env.AUTH_URL || env.BETTER_AUTH_URL;
+
+// This function creates the Better Auth instance, injecting the necessary dependencies.
+export function createAuthInstance(
+	db: DatabaseAdapter,
+	drizzleDb: PostgresJsDatabase<any>,
+	emailAdapter?: EmailAdapter | null
+) {
+	const userSyncHooks = createAuthMiddleware(async (ctx) => {
+		// Sync: Create CMS user profile when user signs up
+		// Note: Invitation processing is handled in hooks.server.ts
+		if (ctx.path === '/sign-up/email' && ctx.context.user) {
+			try {
+				await db.createUserProfile({
+					userId: ctx.context.user.id,
+					role: 'editor' // Default role
+				});
+				cmsLogger.info('[Auth]', 'Created user profile');
+			} catch (error) {
+				cmsLogger.error('[Auth]', 'Error creating user profile:', error);
+			}
+		}
+
+		// Sync: Clean up CMS data when user is deleted
+		if (ctx.path === '/user/delete-user' && ctx.context.user) {
+			try {
+				await db.deleteUserProfile(ctx.context.user.id);
+				cmsLogger.info('[Auth]', 'Deleted user profile');
+			} catch (error) {
+				cmsLogger.error('[Auth]', 'Error deleting user profile:', error);
+			}
+		}
+	});
+
+	return betterAuth({
+		baseURL: authUrl,
+		secret: authSecret,
+		advanced: {
+			backgroundTasks: {
+				handler: (task) => {
+					Promise.resolve(typeof task === 'function' ? task() : task).catch(() => {});
+				}
+			}
+		},
+		// Better Auth's internal adapter needs the raw Drizzle client.
+		database: drizzleAdapter(drizzleDb, {
+			provider: 'pg'
+		}),
+		emailAndPassword: {
+			enabled: true,
+			requireEmailVerification: true,
+			sendResetPassword: async ({ user, url, token }) => {
+				// Manually construct the correct URL format
+				// Better Auth URL: http://localhost:5173/reset-password?token=xxx&callbackURL=...
+				// We want: http://localhost:5173/reset-password/xxx
+				const baseUrl = authUrl || 'http://localhost:5173';
+				const resetUrl = `${baseUrl}/reset-password/${token}`;
+
+				// Send password reset email if adapter is configured
+				if (emailAdapter && emailConfig) {
+					try {
+						const { html, text } = await emailConfig.passwordReset.render(
+							user.name || user.email,
+							resetUrl
+						);
+						const result = await emailAdapter.send({
+							from: emailConfig.from,
+							to: user.email,
+							subject: emailConfig.passwordReset.subject,
+							html,
+							text
+						});
+
+						if (result.error) {
+							cmsLogger.error('[Auth]', 'Failed to send password reset email:', result.error);
+						} else {
+							cmsLogger.info('[Auth]', 'Password reset email sent');
+						}
+					} catch (error) {
+						cmsLogger.error('[Auth]', 'Error sending password reset email:', error);
+					}
+				} else {
+					cmsLogger.warn('[Auth]', 'Email adapter not configured. Password reset email not sent.');
+				}
+			}
+		},
+		emailVerification: {
+			enabled: true,
+			sendOnSignUp: true,
+			autoSignInAfterVerification: true,
+			verifyEmailPath: '/verify-email',
+			sendVerificationEmail: async ({ user, url, token }) => {
+				// Send verification email if adapter is configured
+				if (emailAdapter && emailConfig) {
+					try {
+						const { html, text } = await emailConfig.emailVerification.render(
+							user.name || user.email,
+							url
+						);
+						const result = await emailAdapter.send({
+							from: emailConfig.from,
+							to: user.email,
+							subject: emailConfig.emailVerification.subject,
+							html,
+							text
+						});
+
+						if (result.error) {
+							cmsLogger.error('[Auth]', 'Failed to send verification email:', result.error);
+						} else {
+							cmsLogger.info('[Auth]', 'Verification email sent');
+						}
+					} catch (error) {
+						cmsLogger.error('[Auth]', 'Error sending verification email:', error);
+					}
+				} else {
+					cmsLogger.warn('[Auth]', 'Email adapter not configured. Verification email not sent.');
+				}
+			}
+		},
+		plugins: [
+			apiKey({
+				apiKeyHeaders: ['x-api-key'],
+				deferUpdates: true,
+				rateLimit: {
+					enabled: true,
+					timeWindow: 1000 * 60 * 60 * 24,
+					maxRequests: 10000
+				},
+				enableMetadata: true,
+				...(cacheAdapter
+					? {
+							storage: 'secondary-storage' as const,
+							fallbackToDatabase: true,
+							customStorage: {
+								get: async (key: string) => cacheAdapter.get(key),
+								set: async (key: string, value: string, ttl?: number) =>
+									cacheAdapter.set(key, value, ttl),
+								delete: async (key: string) => cacheAdapter.delete(key)
+							}
+						}
+					: {})
+			})
+		],
+		hooks: {
+			after: userSyncHooks
+		}
+	});
+}

package/templates/base/src/lib/server/auth/index.ts

@@ -0,0 +1,25 @@
+// apps/studio/src/lib/server/auth/index.ts
+
+import type { AuthProvider } from '@aphexcms/cms-core/server';
+import { authService } from './service';
+
+// This file is the clean, public-facing API for the app's auth module.
+
+// 1. Export the auth instance (from separate file to avoid circular dependency)
+export { auth } from './instance.js';
+
+// 2. Export the authService (which uses the 'auth' instance).
+export { authService } from './service';
+
+// 3. Export the authProvider, which connects the authService to the CMS core hook.
+export const authProvider: AuthProvider = {
+	getSession: (request, db) => authService.getSession(request, db),
+	requireSession: (request, db) => authService.requireSession(request, db),
+	validateApiKey: (request) => authService.validateApiKey(request),
+	requireApiKey: (request, db, permission) => authService.requireApiKey(request, db, permission),
+	getUserById: (userId) => authService.getUserById(userId),
+	getUserByEmail: (email) => authService.getUserByEmail(email),
+	changeUserName: (userId, name) => authService.changeUserName(userId, name),
+	requestPasswordReset: (email, redirectTo) => authService.requestPasswordReset(email, redirectTo),
+	resetPassword: (token, newPassword) => authService.resetPassword(token, newPassword)
+};

package/templates/base/src/lib/server/auth/instance.ts

@@ -0,0 +1,7 @@
+// Separate file for auth instance to avoid circular dependency
+import { db, drizzleDb } from '$lib/server/db';
+import { email } from '$lib/server/email';
+import { createAuthInstance } from './better-auth/instance.js';
+
+// Create the Better Auth instance by injecting the database and email adapter.
+export const auth = createAuthInstance(db, drizzleDb, email);