create-atsdc-stack 1.2.1 → 1.3.1

package/.claude/settings.local.json

@@ -5,7 +5,8 @@
       "Bash(git mv:*)",
       "Bash(git add:*)",
       "Bash(test:*)",
-      "Bash(npm install:*)"
+      "Bash(npm install:*)",
+      "mcp__ide__getDiagnostics"
     ]
   }
 }

package/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-The ATSDC Stack is a full-stack web application framework built with Astro, TypeScript, SCSS, Drizzle ORM, and Clerk. It's designed as both a production-ready template and a CLI tool for scaffolding new projects.
+The ATSDC Stack is a full-stack web application framework built with Astro, TypeScript, SCSS, Drizzle ORM, and BetterAuth. It's designed as both a production-ready template and a CLI tool for scaffolding new projects.
 
 This is a monorepo with two main parts:
 
@@ -53,7 +53,7 @@ npx drizzle-kit studio        # Open Drizzle Studio GUI for database
 - All IDs are `varchar(21)` with `.$defaultFn(() => nanoid())`
 - TypeScript types are inferred: `typeof posts.$inferSelect` and `typeof posts.$inferInsert`
 - Zod validation schemas mirror database schemas but add runtime validation
-- Use `@vercel/postgres` for connection pooling, wrapped by Drizzle
+- Use `@neondatabase/serverless` for connection pooling, wrapped by Drizzle
 
 ### API Routes
 
@@ -151,12 +151,12 @@ import { posts } from '@/db/schema';
 import '@/styles/components/card.scss';
 ```
 
-### Authentication (Clerk)
+### Authentication (BetterAuth)
 
-- Pre-configured in `app/astro.config.mjs`
-- Middleware: Create `app/src/middleware.ts` with `clerkMiddleware()` to protect routes
+- Configured via `app/src/lib/auth.ts` using the `better-auth` package
+- Auth API routes at `app/src/pages/api/auth/[...all].ts`
+- Middleware: Create `app/src/middleware.ts` using `auth.api.getSession()` to protect routes
 - User IDs stored as `authorId` in database (varchar 255)
-- React components available via `@clerk/clerk-react`
 
 ### Progressive Web App (PWA)
 
@@ -170,8 +170,8 @@ import '@/styles/components/card.scss';
 **Required:**
 
 - `DATABASE_URL` - PostgreSQL connection string
-- `PUBLIC_CLERK_PUBLISHABLE_KEY` - Clerk publishable key
-- `CLERK_SECRET_KEY` - Clerk secret key
+- `BETTER_AUTH_SECRET` - BetterAuth secret key (min 32 chars)
+- `BETTER_AUTH_URL` - App URL for BetterAuth (e.g. <http://localhost:4321>)
 - `OPENAI_API_KEY` - OpenAI API key (for AI features)
 
 **Setup:** Copy `.env.example` to `.env` and fill in values
@@ -179,7 +179,7 @@ import '@/styles/components/card.scss';
 ## Key Design Decisions
 
 1. **NanoID over UUID/auto-increment:** URL-safe, shorter, equally collision-resistant
-2. **Vercel Postgres over node-postgres:** Better connection pooling for serverless
+2. **Neon Serverless over node-postgres:** Better connection pooling for serverless/edge
 3. **Drizzle over Prisma:** Closer to SQL, better TypeScript inference, lighter weight
 4. **Zod validation separate from schema:** Allows different validation rules for create/update operations
 5. **SCSS over Tailwind:** Enforces semantic naming, better for large teams and maintainability

package/INSTALLATION.md

@@ -44,16 +44,16 @@ npm install astro@latest typescript@latest
 npm install @astrojs/react@latest @astrojs/vercel@latest @astrojs/check@latest
 ```
 
-### Authentication (Clerk)
+### Authentication (BetterAuth)
 
 ```bash
-npm install @clerk/astro@latest @clerk/clerk-react@latest
+npm install better-auth@latest
 ```
 
 ### Database (Drizzle ORM + PostgreSQL)
 
 ```bash
-npm install drizzle-orm@latest postgres@latest @vercel/postgres@latest
+npm install drizzle-orm@latest @neondatabase/serverless@latest
 npm install -D drizzle-kit@latest
 ```
 
@@ -87,7 +87,7 @@ npm install nanoid@latest
 npm install -D vite-plugin-pwa@latest @vite-pwa/assets-generator@latest
 ```
 
-### React Dependencies (for Clerk components)
+### React Dependencies
 
 ```bash
 npm install react@latest react-dom@latest
@@ -110,9 +110,8 @@ npm install \
   @astrojs/react@latest \
   @astrojs/vercel@latest \
   @astrojs/check@latest \
-  @clerk/astro@latest \
-  @clerk/clerk-react@latest \
-  @vercel/postgres@latest \
+  @neondatabase/serverless@latest \
+  better-auth@latest \
   ai@latest \
   @ai-sdk/openai@latest \
   drizzle-orm@latest \
@@ -191,13 +190,12 @@ cat > astro.config.mjs << 'EOF'
 import { defineConfig } from 'astro/config';
 import react from '@astrojs/react';
 import vercel from '@astrojs/vercel/serverless';
-import clerk from '@clerk/astro';
 import { VitePWA } from 'vite-plugin-pwa';
 
 export default defineConfig({
   output: 'server',
   adapter: vercel(),
-  integrations: [react(), clerk()],
+  integrations: [react()],
   vite: {
     plugins: [VitePWA({ registerType: 'autoUpdate' })],
   },
@@ -210,8 +208,8 @@ EOF
 ```bash
 cat > .env.example << 'EOF'
 DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
-PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
-CLERK_SECRET_KEY="sk_test_..."
+BETTER_AUTH_SECRET="your-secret-key-min-32-chars"
+BETTER_AUTH_URL="http://localhost:4321"
 OPENAI_API_KEY="sk-..."
 EOF
 ```
@@ -319,7 +317,7 @@ npm install
 1. Review the [README.md](./README.md) for architecture details
 2. Explore the example code in `src/pages/api/`
 3. Customize your database schema in `src/db/schema.ts`
-4. Set up your Clerk authentication
+4. Set up your BetterAuth authentication
 5. Deploy to Vercel
 
 ## Production Deployment
@@ -344,7 +342,8 @@ vercel --prod
 
 ```bash
 vercel env add DATABASE_URL
-vercel env add CLERK_SECRET_KEY
+vercel env add BETTER_AUTH_SECRET
+vercel env add BETTER_AUTH_URL
 vercel env add OPENAI_API_KEY
 ```
 

package/README.md

@@ -10,7 +10,7 @@ The **ATSDC Stack** is a carefully curated combination of modern web technologie
 - **T** - [TypeScript](https://www.typescriptlang.org) - Full type safety across your entire application
 - **S** - [SCSS](https://sass-lang.com) - Powerful styling with variables, mixins, and modules
 - **D** - [Drizzle ORM](https://orm.drizzle.team) - Type-safe database operations with PostgreSQL
-- **C** - [Clerk](https://clerk.com) - Complete authentication and user management
+- **C** - [BetterAuth](https://betterauth.dev) - Complete authentication and user management
 
 ### Additional Technologies
 
@@ -75,8 +75,8 @@ cp .env.example .env
 Required environment variables:
 
 - `DATABASE_URL` - PostgreSQL connection string
-- `PUBLIC_CLERK_PUBLISHABLE_KEY` - Clerk publishable key
-- `CLERK_SECRET_KEY` - Clerk secret key
+- `BETTER_AUTH_SECRET` - BetterAuth secret key (min 32 chars)
+- `BETTER_AUTH_URL` - App URL for BetterAuth (e.g. http://localhost:4321)
 - `OPENAI_API_KEY` - OpenAI API key (for AI features)
 
 ### 2. Database Setup
@@ -331,13 +331,38 @@ export const POST: APIRoute = async ({ request }) => {
 
 ## 🔐 Authentication
 
-Clerk is pre-configured for authentication. Protect routes with middleware:
+BetterAuth is pre-configured for authentication. Set up auth and protect routes:
+
+```typescript
+// src/lib/auth.ts
+import { betterAuth } from 'better-auth';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { db } from '@/db/initialize';
+
+export const auth = betterAuth({
+    database: drizzleAdapter(db, { provider: 'pg' }),
+    emailAndPassword: { enabled: true },
+});
+```
+
+```typescript
+// src/pages/api/auth/[...all].ts
+import type { APIRoute } from 'astro';
+import { auth } from '@/lib/auth';
+
+export const ALL: APIRoute = ({ request }) => auth.handler(request);
+```
 
 ```typescript
 // src/middleware.ts
-import { clerkMiddleware } from '@clerk/astro/server';
+import { auth } from '@/lib/auth';
+import { defineMiddleware } from 'astro:middleware';
 
-export const onRequest = clerkMiddleware();
+export const onRequest = defineMiddleware(async (context, next) => {
+    const session = await auth.api.getSession({ headers: context.request.headers });
+    context.locals.user = session?.user ?? null;
+    return next();
+});
 ```
 
 ## 🚀 Deployment
@@ -359,14 +384,15 @@ npx vercel --prod
 Set these in your Vercel project settings:
 
 - `DATABASE_URL`
-- `CLERK_SECRET_KEY`
+- `BETTER_AUTH_SECRET`
+- `BETTER_AUTH_URL`
 - `OPENAI_API_KEY`
 
 ## 📚 Documentation
 
 - [Astro Documentation](https://docs.astro.build)
 - [Drizzle ORM Documentation](https://orm.drizzle.team/docs)
-- [Clerk Documentation](https://clerk.com/docs)
+- [BetterAuth Documentation](https://betterauth.dev/docs)
 - [Zero Sync Documentation](https://zero.rocicorp.dev)
 - [Zod Documentation](https://zod.dev)
 - [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)
@@ -398,7 +424,7 @@ Contributions are welcome! Please open an issue or submit a pull request.
 3. **Real-time Sync** - Zero provides local-first data synchronization for responsive UIs
 4. **Developer Experience** - Modern tooling with excellent IDE support and automated setup
 5. **Scalability** - PostgreSQL + serverless architecture scales effortlessly
-6. **Security** - Clerk handles authentication, Zod validates inputs
+6. **Security** - BetterAuth handles authentication, Zod validates inputs
 7. **AI-Ready** - Vercel AI SDK integration for modern AI features
 8. **PWA Support** - Offline-first capabilities with Vite PWA
 9. **Clean Architecture** - Enforced separation of concerns, especially for styles

package/app/.env.example

@@ -1,9 +1,9 @@
 # Database
 DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
 
-# Clerk Authentication
-PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
-CLERK_SECRET_KEY="sk_test_..."
+# BetterAuth
+BETTER_AUTH_SECRET="your-secret-key-min-32-chars"
+BETTER_AUTH_URL="http://localhost:4321"
 
 # OpenAI and other AI model providers (for Vercel AI SDK)
 OPENAI_API_KEY="sk-..."

package/app/.github/workflows/browser-tests.yml

@@ -14,8 +14,8 @@ on:
 
 env:
     DATABASE_URL: ${{ secrets.DATABASE_URL }}
-    PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ secrets.PUBLIC_CLERK_PUBLISHABLE_KEY }}
-    CLERK_SECRET_KEY: ${{ secrets.CLERK_SECRET_KEY }}
+    BETTER_AUTH_SECRET: ${{ secrets.BETTER_AUTH_SECRET }}
+    BETTER_AUTH_URL: ${{ secrets.BETTER_AUTH_URL }}
     OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
     GOOGLE_GENERATIVE_AI_API_KEY: ${{ secrets.GOOGLE_GENERATIVE_AI_API_KEY }}
     EXA_API_KEY: ${{ secrets.EXA_API_KEY }}

package/app/README.md

@@ -8,7 +8,7 @@ This is the main Astro application for the ATSDC Stack.
 
 - Node.js >= 18.0.0
 - PostgreSQL database (Vercel Postgres, Neon, or local)
-- API keys for Clerk, OpenAI, and optionally Exa
+- API keys for BetterAuth, OpenAI, and optionally Exa
 
 ### Installation
 
@@ -30,9 +30,9 @@ Create a `.env` file with the following variables:
 # Database
 DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
 
-# Clerk Authentication
-PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
-CLERK_SECRET_KEY="sk_test_..."
+# BetterAuth
+BETTER_AUTH_SECRET="your-secret-key-min-32-chars"
+BETTER_AUTH_URL="http://localhost:4321"
 
 # OpenAI (for Vercel AI SDK)
 OPENAI_API_KEY="sk-..."
@@ -154,13 +154,17 @@ export const createPostSchema = z.object({
 
 ## 🔐 Authentication
 
-Authentication is handled by Clerk. Configure in `astro.config.mjs`:
+Authentication is handled by BetterAuth. Configure in `src/lib/auth.ts`:
 
-```javascript
-clerk({
-    afterSignInUrl: '/',
-    afterSignUpUrl: '/',
-})
+```typescript
+import { betterAuth } from 'better-auth';
+import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { db } from '@/db/initialize';
+
+export const auth = betterAuth({
+    database: drizzleAdapter(db, { provider: 'pg' }),
+    emailAndPassword: { enabled: true },
+});
 ```
 
 ## 🤖 AI Features
@@ -204,8 +208,8 @@ vercel
 Make sure to set these environment variables in your Vercel project settings:
 
 - `DATABASE_URL`
-- `PUBLIC_CLERK_PUBLISHABLE_KEY`
-- `CLERK_SECRET_KEY`
+- `BETTER_AUTH_SECRET`
+- `BETTER_AUTH_URL`
 - `OPENAI_API_KEY`
 - `EXA_API_KEY` (optional)
 
@@ -213,7 +217,7 @@ Make sure to set these environment variables in your Vercel project settings:
 
 - [Astro Documentation](https://docs.astro.build)
 - [Drizzle ORM](https://orm.drizzle.team)
-- [Clerk](https://clerk.com/docs)
+- [BetterAuth](https://betterauth.dev/docs)
 - [Vercel AI SDK](https://sdk.vercel.ai/docs)
 - [Zod](https://zod.dev)
 - [Exa Search](https://docs.exa.ai)

package/app/astro.config.mjs

@@ -1,7 +1,6 @@
 import { defineConfig } from 'astro/config';
 import react from '@astrojs/react';
 import vercel from '@astrojs/vercel';
-import clerk from '@clerk/astro';
 import { VitePWA } from 'vite-plugin-pwa';
 
 // https://astro.build/config
@@ -17,10 +16,6 @@ export default defineConfig({
     },
     integrations: [
         react(),
-        clerk({
-            afterSignInUrl: '/',
-            afterSignUpUrl: '/',
-        }),
     ],
     vite: {
         plugins: [

package/app/package.json

@@ -27,10 +27,9 @@
         "@astrojs/check": "^0.9.6",
         "@astrojs/react": "^4.4.2",
         "@astrojs/vercel": "^9.0.2",
-        "@clerk/astro": "^1.4.3",
-        "@clerk/clerk-react": "^5.17.3",
+        "@neondatabase/serverless": "^0.10.4",
         "@rocicorp/zero": "^0.2.0",
-        "@vercel/postgres": "^0.10.0",
+        "better-auth": "^1.2.7",
         "ai": "^5.0.0",
         "astro": "^5.16.6",
         "cheerio": "^1.0.0",

package/app/src/db/initialize.ts

@@ -1,14 +1,15 @@
-import { sql } from '@vercel/postgres';
-import { drizzle } from 'drizzle-orm/vercel-postgres';
+import { neon } from '@neondatabase/serverless';
+import { drizzle } from 'drizzle-orm/neon-http';
 import * as schema from './schema';
 import { posts, comments } from './schema';
 
 /**
  * Database client configuration
- * Uses Vercel Postgres for production-ready connection pooling
+ * Uses Neon serverless for production-ready connection pooling
  */
 
 // Create Drizzle instance with schema
+const sql = neon(process.env.DATABASE_URL!);
 export const db = drizzle(sql, { schema });
 
 // Export schema for convenience

package/app/src/db/schema.ts

@@ -17,7 +17,7 @@ export const posts = pgTable('posts', {
     content: text('content').notNull(),
     excerpt: text('excerpt'),
 
-    // Author information (Clerk user ID)
+    // Author information (BetterAuth user ID)
     authorId: varchar('author_id', { length: 255 }).notNull(),
     authorName: varchar('author_name', { length: 255 }),
 
@@ -52,7 +52,7 @@ export const comments = pgTable('comments', {
     // Comment content
     content: text('content').notNull(),
 
-    // Author information (Clerk user ID)
+    // Author information (BetterAuth user ID)
     authorId: varchar('author_id', { length: 255 }).notNull(),
     authorName: varchar('author_name', { length: 255 }),
 

package/app/src/lib/config.ts

@@ -23,7 +23,7 @@ export const siteConfig = {
      * Full description of the stack
      */
     stackDescription:
-        'Full-stack application built with Astro, TypeScript, Drizzle, Clerk, and SCSS',
+        'Full-stack application built with Astro, TypeScript, Drizzle, BetterAuth, and SCSS',
 
     /**
      * Docs URL

package/app/src/pages/index.astro

@@ -41,7 +41,7 @@ import '@/styles/pages/index.scss';
                 </div>
 
                 <div class="home__feature card">
-                    <h3>🔐 Clerk</h3>
+                    <h3>🔐 BetterAuth</h3>
                     <p>Complete authentication and user management</p>
                 </div>
 

package/bin/cli.js

@@ -167,7 +167,6 @@ function generateAstroConfig(adapter, integrations = []) {
         vercel: `import { defineConfig } from 'astro/config';
 ${integrationImports}
 import vercel from '@astrojs/vercel';
-import clerk from '@clerk/astro';
 import { VitePWA } from 'vite-plugin-pwa';
 
 export default defineConfig({
@@ -182,10 +181,6 @@ export default defineConfig({
     },
     integrations: [
 ${integrationCalls}
-        clerk({
-            afterSignInUrl: '/',
-            afterSignUpUrl: '/',
-        }),
     ],
     vite: {
         plugins: [
@@ -250,7 +245,6 @@ ${integrationCalls}
         netlify: `import { defineConfig } from 'astro/config';
 ${integrationImports}
 import netlify from '@astrojs/netlify';
-import clerk from '@clerk/astro';
 import { VitePWA } from 'vite-plugin-pwa';
 
 export default defineConfig({
@@ -258,10 +252,6 @@ export default defineConfig({
     adapter: netlify(),
     integrations: [
 ${integrationCalls}
-        clerk({
-            afterSignInUrl: '/',
-            afterSignUpUrl: '/',
-        }),
     ],
     vite: {
         plugins: [
@@ -326,7 +316,6 @@ ${integrationCalls}
         cloudflare: `import { defineConfig} from 'astro/config';
 ${integrationImports}
 import cloudflare from '@astrojs/cloudflare';
-import clerk from '@clerk/astro';
 import { VitePWA } from 'vite-plugin-pwa';
 
 export default defineConfig({
@@ -334,10 +323,6 @@ export default defineConfig({
     adapter: cloudflare(),
     integrations: [
 ${integrationCalls}
-        clerk({
-            afterSignInUrl: '/',
-            afterSignUpUrl: '/',
-        }),
     ],
     vite: {
         plugins: [
@@ -402,7 +387,6 @@ ${integrationCalls}
         node: `import { defineConfig } from 'astro/config';
 ${integrationImports}
 import node from '@astrojs/node';
-import clerk from '@clerk/astro';
 import { VitePWA } from 'vite-plugin-pwa';
 
 export default defineConfig({
@@ -412,10 +396,6 @@ export default defineConfig({
     }),
     integrations: [
 ${integrationCalls}
-        clerk({
-            afterSignInUrl: '/',
-            afterSignUpUrl: '/',
-        }),
     ],
     vite: {
         plugins: [
@@ -479,17 +459,12 @@ ${integrationCalls}
 `,
         static: `import { defineConfig } from 'astro/config';
 ${integrationImports}
-import clerk from '@clerk/astro';
 import { VitePWA } from 'vite-plugin-pwa';
 
 export default defineConfig({
     output: 'static',
     integrations: [
 ${integrationCalls}
-        clerk({
-            afterSignInUrl: '/',
-            afterSignUpUrl: '/',
-        }),
     ],
     vite: {
         plugins: [
@@ -777,7 +752,7 @@ async function createProject(projectName, options = {}) {
         console.log('\nDocumentation:');
         console.log(`  • Astro: ${colors.cyan}https://astro.build${colors.reset}`);
         console.log(`  • Drizzle ORM: ${colors.cyan}https://orm.drizzle.team${colors.reset}`);
-        console.log(`  • Clerk: ${colors.cyan}https://clerk.com/docs${colors.reset}`);
+        console.log(`  • BetterAuth: ${colors.cyan}https://betterauth.dev/docs${colors.reset}`);
         console.log(`  • Vercel AI SDK: ${colors.cyan}https://sdk.vercel.ai${colors.reset}`);
         console.log(`  • Exa Search: ${colors.cyan}https://docs.exa.ai${colors.reset}`);
 
@@ -973,7 +948,7 @@ ${colors.bright}${colors.green}TECHNOLOGY STACK${colors.reset}
     ${colors.cyan}• NanoID${colors.reset}            - Secure unique ID generation for records
 
     ${colors.bright}Authentication:${colors.reset}
-    ${colors.cyan}• Clerk${colors.reset}             - Complete user management and authentication
+    ${colors.cyan}• BetterAuth${colors.reset}        - Complete user management and authentication
                        Includes social logins, 2FA, user profiles
 
     ${colors.bright}Styling:${colors.reset}
@@ -995,8 +970,8 @@ ${colors.bright}${colors.green}NEXT STEPS AFTER CREATION${colors.reset}
 
     ${colors.yellow}2.${colors.reset} Configure environment variables in ${colors.cyan}.env${colors.reset}:
      • DATABASE_URL              - PostgreSQL connection string
-     • PUBLIC_CLERK_PUBLISHABLE_KEY - Get from clerk.com
-     • CLERK_SECRET_KEY          - Get from clerk.com
+     • BETTER_AUTH_SECRET        - Random secret (min 32 chars)
+     • BETTER_AUTH_URL           - Your app URL
      • OPENAI_API_KEY            - Get from platform.openai.com
      • EXA_API_KEY               - Get from exa.ai (optional)
 
@@ -1018,7 +993,7 @@ ${colors.bright}${colors.green}RESOURCES${colors.reset}
     ${colors.cyan}Documentation:${colors.reset}
     • Astro:        https://docs.astro.build
     • Drizzle ORM:  https://orm.drizzle.team
-    • Clerk:        https://clerk.com/docs
+    • BetterAuth:   https://betterauth.dev/docs
     • Zod:          https://zod.dev
     • Vercel AI:    https://sdk.vercel.ai/docs
     • Exa Search:   https://docs.exa.ai

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "create-atsdc-stack",
-    "version": "1.2.1",
-    "description": "ATSDC Stack - Astro, TypeScript, SCSS, Drizzle, Clerk CLI utility",
+    "version": "1.3.1",
+    "description": "ATSDC Stack - Astro, TypeScript, SCSS, Drizzle, BetterAuth CLI utility",
     "type": "module",
     "bin": {
         "create-atsdc-stack": "./bin/cli.js"
@@ -18,7 +18,7 @@
         "astro",
         "typescript",
         "drizzle",
-        "clerk",
+        "better-auth",
         "scss",
         "zod",
         "vercel-ai",