stackpatch 1.1.2 → 1.1.4

package/README.md

@@ -10,7 +10,7 @@ StackPatch is a CLI tool that helps you quickly add production-ready features to
 ## ✨ Features
 
 - 🚀 **Zero Configuration** - Add features with a single command
-- 🔐 **Authentication** - Full NextAuth.js setup with customizable OAuth providers
+- 🔐 **Authentication** - Full Better Auth setup with customizable OAuth providers
 - 🛡️ **Protected Routes** - Easy route protection with components or middleware
 - 🎨 **UI Components** - Pre-built, production-ready components
 - 📦 **Composable** - Add only what you need, when you need it
@@ -89,31 +89,40 @@ This will:
 
 ## 📖 What Gets Added
 
-### Authentication Setup
+### Setup Flow
 
-When you run `npx stackpatch add auth`, StackPatch:
+When you run `npx stackpatch add auth`, StackPatch will guide you through an interactive setup:
 
-1. **Asks which OAuth providers** you want to configure:
-   - Google OAuth
-   - GitHub OAuth
-   - Email/Password (Credentials)
+1. **Session Mode**: Choose between Database (persistent sessions) or Stateless (JWT only)
+2. **Database** (if database mode): Select PostgreSQL, MySQL, SQLite, or MongoDB
+3. **ORM** (if database mode): Choose Drizzle, Prisma, or Raw SQL driver
+4. **Auth Providers**: Enable Email/Password and select OAuth providers (Google, GitHub)
+5. **UI Components**: Choose whether to add prebuilt login/signup pages
+6. **Protected Routes**: Select which routes to protect (supports wildcards like `/dashboard/*`)
 
-2. **Adds the following files**:
-   - ✅ NextAuth.js configuration with your selected providers
-   - ✅ Login and signup pages (`/auth/login`, `/auth/signup`)
-   - ✅ OAuth buttons for selected providers with email/password forms
-   - ✅ Protected route component (`components/protected-route.tsx` or `src/components/protected-route.tsx`)
-   - ✅ Middleware for route protection (`middleware.ts`)
-   - ✅ Session provider and toaster components
-   - ✅ Environment file template (`.env.example`)
+### Files Generated
 
-3. **Smart file placement**:
-   - Detects if your app is in `app/` or `src/app/`
-   - Places components in matching location (`components/` or `src/components/`)
-   - Uses your `tsconfig.json` path aliases for imports
-   - Generates correct import paths automatically
+After the interactive setup, StackPatch automatically generates:
 
-4. **Tracks all changes** in `.stackpatch/manifest.json` for safe reversion
+- ✅ **Better Auth configuration** (`lib/auth.ts` or `src/lib/auth.ts`)
+- ✅ **Auth client utilities** (`lib/auth-client.ts` or `src/lib/auth-client.ts`)
+- ✅ **Protected routes config** (`lib/protected-routes.ts` - only if protected routes are configured)
+- ✅ **API route handler** (`app/api/auth/[...all]/route.ts`)
+- ✅ **Middleware** (`middleware.ts` - only if protected routes are configured)
+- ✅ **Login/Signup pages** (`app/auth/login/page.tsx`, `app/auth/signup/page.tsx` - if UI enabled)
+- ✅ **Landing page** (`app/stackpatch/page.tsx` - if UI enabled)
+- ✅ **Auth wrapper** (`components/auth-wrapper.tsx` - if UI enabled, added to layout.tsx)
+- ✅ **Toaster component** (`components/toaster.tsx` - if UI enabled, added to layout.tsx)
+- ✅ **Environment template** (`.env.example`)
+
+### Smart File Placement
+
+StackPatch automatically:
+- ✅ Detects if your app is in `app/` or `src/app/`
+- ✅ Places components in matching location (`components/` or `src/components/`)
+- ✅ Uses your `tsconfig.json` path aliases for imports
+- ✅ Generates correct import paths automatically
+- ✅ Tracks all changes in `.stackpatch/manifest.json` for safe reversion
 
 ## 🔐 OAuth Setup
 
@@ -126,7 +135,7 @@ If you selected Google OAuth:
 1. Go to [Google Cloud Console](https://console.cloud.google.com/)
 2. Create a project → APIs & Services → Credentials
 3. Create OAuth client ID (Web application)
-4. Add redirect URI: `http://localhost:3000/api/auth/callback/google`
+4. Add redirect URI: `http://localhost:3000/api/auth/callback/google` (or your production URL)
 5. Copy Client ID and Secret to `.env.local`:
    ```env
    GOOGLE_CLIENT_ID=your_client_id
@@ -139,7 +148,7 @@ If you selected GitHub OAuth:
 
 1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
 2. New OAuth App
-3. Set callback URL: `http://localhost:3000/api/auth/callback/github`
+3. Set callback URL: `http://localhost:3000/api/auth/callback/github` (or your production URL)
 4. Copy Client ID and generate Secret
 5. Add to `.env.local`:
    ```env
@@ -152,8 +161,8 @@ If you selected GitHub OAuth:
 Your `.env.local` will include only the variables for providers you selected:
 
 ```env
-NEXTAUTH_URL=http://localhost:3000
-NEXTAUTH_SECRET=your_generated_secret
+BETTER_AUTH_SECRET=your_generated_secret
+BETTER_AUTH_URL=http://localhost:3000
 
 # Only included if you selected Google
 GOOGLE_CLIENT_ID=your_google_client_id
@@ -164,85 +173,76 @@ GITHUB_CLIENT_ID=your_github_client_id
 GITHUB_CLIENT_SECRET=your_github_client_secret
 ```
 
-## 🧭 Auth Navbar (Demo)
+## 🛡️ Protecting Routes
 
-An example navbar component (`components/auth-navbar.tsx`) is included that shows:
-- **When logged out**: Sign In button
-- **When logged in**: User name/email, avatar, and Sign Out button
+StackPatch automatically protects routes based on your configuration. Routes are protected via:
+- **Middleware** - Server-side protection with automatic redirects
+- **AuthWrapper** - Client-side protection in your root layout
 
-> **Note**: This is a demo component named `auth-navbar.tsx` to avoid conflicts with existing navbars. You can rename it or use it as reference.
+### How It Works
 
-### Usage
+1. **During Setup**: You'll be prompted to select which routes to protect
+2. **Automatic Protection**: StackPatch configures middleware and AuthWrapper automatically
+3. **Redirects**: Unauthenticated users are redirected to `/auth/login?redirect=<original-path>`
+4. **After Login**: Users are automatically redirected back to the original protected route
 
-```tsx
-// app/layout.tsx or any page
-import { AuthNavbar } from "@/components/auth-navbar";
-
-export default function Layout({ children }) {
-  return (
-    <>
-      <AuthNavbar />
-      {children}
-    </>
-  );
-}
-```
+### Wildcard Routes
 
-The auth navbar is included in example pages (`app/page.tsx` and `app/dashboard/page.tsx`) as a reference.
+Use `/*` to protect a route and all its sub-routes:
 
-## 🛡️ Protecting Routes
+- `/dashboard` → Protects only `/dashboard`
+- `/dashboard/*` → Protects `/dashboard` and ALL sub-routes (`/dashboard/settings`, `/dashboard/users`, etc.)
 
-### Method 1: Component-Based (Recommended)
+**Examples:**
+```
+/dashboard/*    → Protects /dashboard and all sub-routes
+/admin/*        → Protects /admin and all sub-routes
+/profile        → Protects only /profile (not sub-routes)
+```
 
-Wrap any page or component:
+**To Modify Protected Routes:**
+Edit `lib/protected-routes.ts` (or `src/lib/protected-routes.ts`):
 
-```tsx
-// app/dashboard/page.tsx
-import { ProtectedRoute } from "@/components/protected-route";
-import { AuthNavbar } from "@/components/auth-navbar";
-
-export default function Dashboard() {
-  return (
-    <ProtectedRoute>
-      <AuthNavbar />
-      <h1>Protected Dashboard</h1>
-    </ProtectedRoute>
-  );
-}
+```ts
+export const PROTECTED_ROUTES = [
+  "/dashboard/*",  // Protects /dashboard and all sub-routes
+  "/admin/*",      // Protects /admin and all sub-routes
+  "/profile",      // Protects only /profile
+] as const;
 ```
 
-### Method 2: Middleware-Based
+## ⚙️ Configuration Options
 
-Edit `middleware.ts` and add routes to protect:
+### Session Modes
 
-```ts
-// middleware.ts
-export const config = {
-  matcher: [
-    "/dashboard/:path*",  // Protect all dashboard routes
-    "/profile/:path*",    // Protect all profile routes
-  ],
-};
-```
+**Database Mode** (Recommended for production):
+- Persistent sessions stored in your database
+- Supports session management and revocation
+- Requires database setup (PostgreSQL, MySQL, SQLite, or MongoDB)
+- Choose an ORM: Drizzle, Prisma, or Raw SQL
 
-## ⚠️ Email/Password Auth (Demo Mode)
+**Stateless Mode** (JWT/JWE):
+- No database required
+- Sessions stored in encrypted cookies
+- Perfect for serverless deployments
+- Limited session management features
 
-The email/password authentication is in **demo mode** with placeholder credentials:
+### Email/Password Authentication
 
-- **Demo credentials**: `demo@example.com` / `demo123`
+Email/password authentication works out of the box with Better Auth. If you selected database mode:
 
-### To Implement Real Auth:
+1. **Generate database schema**:
+   ```bash
+   npx @better-auth/cli generate
+   # or
+   npx @better-auth/cli migrate
+   ```
 
-1. **Set up a database** (PostgreSQL, MongoDB, Prisma, etc.)
-2. **Install bcrypt**: `npm install bcryptjs @types/bcryptjs`
-3. **Update `app/api/auth/[...nextauth]/route.ts`**:
-   - Replace the `authorize` function with database lookup
-   - Hash and compare passwords using bcrypt
-4. **Create signup API** (`app/api/auth/signup/route.ts`):
-   - Hash passwords before storing
-   - Validate and create users in database
+2. **Configure in `lib/auth.ts`** (already set up by StackPatch):
+   - Database adapter is configured based on your selection
+   - Email/password is enabled if you selected it
 
-See code comments in the files for detailed implementation examples.
+See Better Auth documentation for advanced configuration: https://better-auth.dev/docs
 
 ## 📁 File Locations
 
@@ -250,16 +250,20 @@ After running `npx stackpatch add auth`, you'll find files in locations that mat
 
 ### If your app is in `app/`:
 - **Auth pages**: `app/auth/login/page.tsx`, `app/auth/signup/page.tsx`
-- **NextAuth config**: `app/api/auth/[...nextauth]/route.ts`
-- **Components**: `components/auth-navbar.tsx`, `components/protected-route.tsx`, etc.
+- **Auth config**: `lib/auth.ts`, `lib/auth-client.ts`
+- **Protected routes config**: `lib/protected-routes.ts`
+- **API routes**: `app/api/auth/[...all]/route.ts`
+- **Components**: `components/auth-wrapper.tsx`, `components/toaster.tsx`
 - **Middleware**: `middleware.ts` (root)
 - **Environment**: `.env.example`, `.env.local`
 - **Tracking**: `.stackpatch/manifest.json` (for revert)
 
 ### If your app is in `src/app/`:
 - **Auth pages**: `src/app/auth/login/page.tsx`, `src/app/auth/signup/page.tsx`
-- **NextAuth config**: `src/app/api/auth/[...nextauth]/route.ts`
-- **Components**: `src/components/auth-navbar.tsx`, `src/components/protected-route.tsx`, etc.
+- **Auth config**: `src/lib/auth.ts`, `src/lib/auth-client.ts`
+- **Protected routes config**: `src/lib/protected-routes.ts`
+- **API routes**: `src/app/api/auth/[...all]/route.ts`
+- **Components**: `src/components/auth-wrapper.tsx`, `src/components/toaster.tsx`
 - **Middleware**: `middleware.ts` (root)
 - **Environment**: `.env.example`, `.env.local`
 - **Tracking**: `.stackpatch/manifest.json` (for revert)
@@ -271,36 +275,35 @@ StackPatch automatically detects your project structure and places files accordi
 
 ## 🔧 Customization
 
-### Change Login Redirect
+### Change Default Redirect After Login
 
-Edit `app/api/auth/[...nextauth]/route.ts`:
+The login/signup pages automatically redirect users based on:
+1. The `redirect` query parameter (set by middleware when protecting routes)
+2. Fallback to `/stackpatch` if no redirect parameter
 
-```ts
-pages: {
-  signIn: "/your-custom-login", // Change this
-}
-```
-
-### Custom Protected Route Redirect
+To change the fallback route, edit `app/auth/login/page.tsx` and `app/auth/signup/page.tsx`:
 
 ```tsx
-<ProtectedRoute redirectTo="/custom-login">
-  <YourComponent />
-</ProtectedRoute>
+// Change the fallback route (default: "/stackpatch")
+const redirectTo = searchParams.get("redirect") || "/your-custom-route";
 ```
 
 ### Protect API Routes
 
 ```ts
 // app/api/protected/route.ts
-import { getServerSession } from "next-auth";
-import { authOptions } from "@/app/api/auth/[...nextauth]/route";
+import { auth } from "@/lib/auth";
+import { headers } from "next/headers";
 
 export async function GET() {
-  const session = await getServerSession(authOptions);
-  if (!session) {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  });
+
+  if (!session || !session.user) {
     return Response.json({ error: "Unauthorized" }, { status: 401 });
   }
+
   return Response.json({ data: "Protected data" });
 }
 ```
@@ -310,7 +313,7 @@ export async function GET() {
 ### OAuth redirect_uri_mismatch
 
 - Ensure redirect URIs match exactly in OAuth provider settings
-- Check `NEXTAUTH_URL` matches your app URL
+- Check `BETTER_AUTH_URL` matches your app URL (defaults to `http://localhost:3000` in development)
 
 ### OAuth buttons not working
 
@@ -346,11 +349,14 @@ your-project/
 │   │   └── signup/page.tsx      # Signup page
 │   └── api/
 │       └── auth/
-│           └── [...nextauth]/route.ts  # NextAuth config
+│           └── [...all]/route.ts  # Better Auth API route
+├── lib/
+│   ├── auth.ts                  # Better Auth configuration
+│   ├── auth-client.ts           # Client-side auth utilities
+│   └── protected-routes.ts     # Protected routes configuration
 ├── components/
-│   ├── protected-route.tsx      # Route protection component
-│   ├── auth-button.tsx          # Auth button component
-│   └── session-provider.tsx    # Session provider
+│   ├── auth-wrapper.tsx         # Automatic route protection wrapper
+│   └── toaster.tsx             # Toast notifications
 ├── middleware.ts                # Route protection middleware
 ├── .env.local                   # Your environment variables
 └── .stackpatch/                 # Tracking for revert (git-ignored)
@@ -369,11 +375,14 @@ your-project/
 │   │   │   └── signup/page.tsx
 │   │   └── api/
 │   │       └── auth/
-│   │           └── [...nextauth]/route.ts
+│   │           └── [...all]/route.ts
+│   ├── lib/
+│   │   ├── auth.ts
+│   │   ├── auth-client.ts
+│   │   └── protected-routes.ts
 │   └── components/
-│       ├── protected-route.tsx
-│       ├── auth-button.tsx
-│       └── session-provider.tsx
+│       ├── auth-wrapper.tsx
+│       └── toaster.tsx
 ├── middleware.ts
 ├── .env.local
 └── .stackpatch/