Authentication System Template Skill

Objective

Give this skill to your AI — it will guide you through the entire process of building a robust authentication system in Next.js. The workflow encompasses UI component integration (Tailwind CSS, Sonner), core configuration via Better Auth, database setup with Drizzle ORM and PostgreSQL, OAuth integration (Google), email service configuration (Resend), and route protection via proxy.

Step 1: UI Components & Frontend Pages

• Action: Check if the user's project already contains UI designs and pages (such as a homepage, login page, or reset-password page). If so, warn them that copying the files will overwrite their existing content, and ask them to proceed with caution. If their folder is completely empty, guide them to initialize a Next.js project first. You will copy the pre-built files from the templates/ directory. Then, tell them: "Here is the structure of what will be copied to your project."

Project Root
├── tailwind.config.ts            → templates/config/tailwind.config.ts
├── lib/
│   └── utils.ts                  → templates/lib/utils.ts
├── app/
│   ├── layout.tsx                → templates/pages/layout.tsx
│   ├── globals.css               → templates/config/globals.css
│   ├── page.tsx                  → templates/pages/home-page.tsx
│   ├── login/page.tsx            → templates/pages/login-page.tsx
│   └── reset-password/page.tsx   → templates/pages/reset-password-page.tsx
└── components/
    ├── forms/
    │   ├── login-form.tsx            → templates/forms/login-form.tsx
    │   ├── register-form.tsx         → templates/forms/register-form.tsx
    │   ├── forgot-password-form.tsx  → templates/forms/forgot-password-form.tsx
    │   └── reset-password-form.tsx   → templates/forms/reset-password-form.tsx
    └── ui/
        ├── button.tsx            → templates/ui/button.tsx
        ├── card.tsx              → templates/ui/card.tsx
        ├── input.tsx             → templates/ui/input.tsx
        └── field.tsx             → templates/ui/field.tsx

• Wait: Wait for confirmation.

Step 2: Toast Notifications (Sonner)

• Action: Guide them to set up global toast notifications using references/toast-system.md. Instruct them to add <Toaster /> to app/layout.tsx and replace alert() placeholders with toast.success() and toast.error() in the form components.
• Condition: If the user already has a toast notification system (like react-hot-toast or an existing Sonner setup), skip this step.

Step 3: Better Auth Core Configuration

• Action:
  1. Guide the user to set up .env for Auth (BETTER_AUTH_SECRET, BETTER_AUTH_URL).
  2. Provide the npm install command for auth dependencies.
  3. Provide core auth code (Auth instance config and /api/auth/[...all]/route.ts).
  4. Instruct the user to restore getCurrentUser logic in app/page.tsx and integrate real signIn/signUp functions into the form components, removing the mock logic.

Step 4: Route Protection

• Action: Write proxy.ts (using references/route-protection.md).
• Goal: Configure protected routes (e.g., /dashboard) to intercept unauthenticated users and redirect them to /login.

Step 5: Database Configuration (Drizzle / Postgres)

• Action:
  1. Guide the user to set up .env for database connections.
  2. Provide the npm install command for database dependencies (Drizzle, Postgres driver).
  3. Provide the Schema definition code (templates/db/schema.ts) and database connection setup.

Step 6: Google OAuth Integration

• Action: Provide Google OAuth .env variables guide and related logic code.

Step 7: Resend Email Service

• Action: Configure Resend .env variables (RESEND_API_KEY and RESEND_FROM_EMAIL) and code for sending emails. Warn the user that if they do not set a verified domain for RESEND_FROM_EMAIL, emails to new users will fail due to Resend's sandbox restrictions.

Step 8: Frontend Session & Logout

• Action: Provide code examples for retrieving the current session on the Client or Server side. Add a Sign Out button to complete the authentication loop.
• Conclusion: Celebrate the completed setup!

Implementation Rules

• Pacing: Never combine multiple steps in a single response.
• Toasts: Use Sonner for all toast notifications (position: "top-center").
• UI Components: Use the hand-written shadcn-style components provided. Do NOT tell the user to install Radix UI or shadcn/ui.
• Forms: All form components must support onSwitchTo* callbacks to handle form switching (e.g., switching from login to register).
• Validation: Minimum password length is 8 characters. Email validation must use regex: /^[^\s@]+@[^\s@]+\.[^\s@]+$/.

Quick Reference - File Mapping

Project Root
├── .env                          → templates/config/env.example
├── tailwind.config.ts            → templates/config/tailwind.config.ts
├── postcss.config.js             → templates/config/postcss.config.js
├── next.config.js                → templates/config/next.config.js
├── drizzle.config.ts             → templates/config/drizzle.config.ts
├── proxy.ts                      → templates/config/proxy.ts
├── db/
│   ├── drizzle.ts                → templates/db/drizzle.ts
│   └── schema.ts                 → templates/db/schema.ts
├── lib/
│   ├── auth.ts                   → templates/lib/auth.ts
│   ├── auth-client.ts            → templates/lib/auth-client.ts
│   └── utils.ts                  → templates/lib/utils.ts
├── server/
│   └── users.ts                  → templates/server/users.ts
├── app/
│   ├── layout.tsx                → templates/pages/layout.tsx
│   ├── globals.css               → templates/config/globals.css
│   ├── page.tsx                  → templates/pages/home-page.tsx
│   ├── login/page.tsx            → templates/pages/login-page.tsx
│   ├── reset-password/page.tsx   → templates/pages/reset-password-page.tsx
│   └── api/auth/[...all]/route.ts → templates/api/route.ts
└── components/
    ├── forms/
    │   ├── login-form.tsx            → templates/forms/login-form.tsx
    │   ├── register-form.tsx         → templates/forms/register-form.tsx
    │   ├── forgot-password-form.tsx  → templates/forms/forgot-password-form.tsx
    │   └── reset-password-form.tsx   → templates/forms/reset-password-form.tsx
    └── ui/
        ├── button.tsx            → templates/ui/button.tsx
        ├── card.tsx              → templates/ui/card.tsx
        ├── input.tsx             → templates/ui/input.tsx
        └── field.tsx             → templates/ui/field.tsx