@liedsonc/core-auth-kit 2.1.4 → 2.1.7

package/README.md

@@ -0,0 +1,802 @@
+# @liedsonc/core-auth-kit
+
+This is a core authentication UI package for Next.js for lazy people like me 😂. 
+
+I don't want to make Login, Register, and Forgot Password page for every project 🤢 (sooooo boring). 
+That's why I created this package that makes all UI using my fav tech's `shadcn/ui`, `Tailwind CSS`, `Resend` for mailing. 
+Make my auth UI with a single command, and it is also customizable for your project. Just install the package and connect it with the services keys.
+
+
+## Features
+
+- 🔐 **Complete Auth Flows** - Login, Register, Forgot Password, Reset Password, Email Verification
+- 🎨 **Beautiful UI** - Built with shadcn/ui components, fully themeable and accessible
+- 🔌 **Backend Agnostic** - Works with any authentication backend via `AuthClient` interface
+- 📱 **Mobile-First** - Responsive design that works on all devices
+- ♿ **Accessible** - WCAG compliant with proper ARIA attributes and keyboard navigation
+- 🎯 **Type-Safe** - Full TypeScript support with strict typing
+- 🚀 **Zero Config** - Works out-of-the-box with sensible defaults
+- 🎨 **Customizable** - Override components, styles, and behavior as needed
+- 🌙 **Dark Mode** - Built-in dark mode support via Tailwind CSS
+- ⚙️ **Environment Configurable** - OAuth providers and settings via environment variables
+- 📧 **Email Integration** - Built-in Resend email service support for verification and password reset emails
+
+## Installation
+
+For plug-and-play, run **one command** from your Next.js app root (see [Plug and Play](#plug-and-play-recommended)):
+
+```bash
+npx @liedsonc/core-auth-kit init
+```
+
+Or install the package yourself; all UI dependencies are installed automatically:
+
+```bash
+npm install @liedsonc/core-auth-kit
+```
+
+### Peer Dependencies
+
+The following peer dependencies are required but should already be installed in your Next.js project:
+
+- `next` (^15.0.0) - Next.js framework
+- `react` (^19.0.0) - React library
+- `react-dom` (^19.0.0) - React DOM library
+
+If you're not using Next.js or these aren't installed, install them:
+
+```bash
+npm install next react react-dom
+```
+
+**Note:** The following dependencies are automatically installed with the package:
+- `@radix-ui/react-label` - For accessible form labels
+- `@radix-ui/react-slot` - For component composition
+- `class-variance-authority` - For component variants
+- `clsx` - For conditional class names
+- `tailwind-merge` - For merging Tailwind classes
+
+### Email Service (Optional)
+
+For email verification and password reset functionality, install Resend:
+
+```bash
+npm install resend
+```
+
+### shadcn/ui Components
+
+The package includes shadcn/ui components by default. Ensure your project has the shadcn/ui setup:
+
+1. Install shadcn/ui components (if not already installed):
+```bash
+npx shadcn@latest add button input card label
+```
+
+2. Ensure your `tailwind.config.ts` includes the auth-ui styles:
+```ts
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  content: [
+    "./app/**/*.{js,ts,jsx,tsx,mdx}",
+    "./components/**/*.{js,ts,jsx,tsx,mdx}",
+    "./node_modules/@liedsonc/core-auth-kit/**/*.{js,ts,jsx,tsx}",
+  ],
+  // ... rest of config
+};
+```
+
+3. Import the styles in your root layout:
+```tsx
+import "@liedsonc/core-auth-kit/styles";
+```
+
+## Plug and Play (Recommended)
+
+From your Next.js app root, a single command installs the package (if needed) and creates all auth pages, layout, config, and optional API route stubs:
+
+```bash
+npx @liedsonc/core-auth-kit init
+```
+
+The CLI installs `@liedsonc/core-auth-kit` when it is not already in your project, then scaffolds the files. Use `--force` to overwrite existing files. The CLI detects `app` vs `src/app` and `lib` vs `src/lib` automatically.
+
+**Next steps:**
+
+1. Implement `lib/auth-client.ts` (or `src/lib/auth-client.ts`) with your backend (e.g. Supabase, custom API). The stub returns "NOT_IMPLEMENTED" until you replace it.
+2. Copy `.env.example` to `.env.local` and set your environment variables.
+3. If your `AuthClient` calls `/api/auth/*`, implement the scaffolded API routes in `app/api/auth/` (or `src/app/api/auth/`); each stub returns 501 until you wire it to your backend.
+4. Ensure Tailwind content includes the package and you import `@liedsonc/core-auth-kit/styles` in your root layout (see above).
+
+After that, auth routes are available at `/login`, `/register`, `/forgot-password`, `/reset-password`, and `/verify-email`. The only required integration point is your `AuthClient` implementation; the rest is wiring and optional API handlers.
+
+### Scaffolded files
+
+| Path | Purpose | What to do |
+|------|---------|------------|
+| `app/(auth)/layout.tsx` | Wraps auth routes with `AuthUIProvider` and config from `lib/auth-config.ts`. | Usually no change. |
+| `app/(auth)/login/page.tsx` | Login page (and similar for register, forgot-password, reset-password, verify-email). | Usually no change. |
+| `lib/auth-config.ts` | Builds `AuthUIConfig` (authClient, OAuth from env, redirects). | Edit only if you need custom redirects or OAuth config. |
+| `lib/auth-client.ts` | **AuthClient implementation.** | **Replace the stub** with your real backend (Supabase, custom API, etc.). |
+| `.env.example` | Example environment variables. | Copy to `.env.local` and fill in your values. |
+| `app/api/auth/*/route.ts` | API route stubs (login, register, logout, forgot-password, reset-password, verify-email, session). | Implement each handler to call your backend; stubs return 501 until then. |
+
+## Environment Variables
+
+Create a `.env.local` file (or `.env`) with the following variables:
+
+```bash
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+NEXT_PUBLIC_AUTH_REDIRECT_AFTER_LOGIN=/
+NEXT_PUBLIC_AUTH_REDIRECT_AFTER_REGISTER=/login
+NEXT_PUBLIC_AUTH_REDIRECT_AFTER_RESET=/login
+
+NEXT_PUBLIC_OAUTH_GOOGLE_ENABLED=false
+NEXT_PUBLIC_OAUTH_GOOGLE_CLIENT_ID=your_google_client_id
+NEXT_PUBLIC_OAUTH_GOOGLE_REDIRECT_URI=http://localhost:3000/api/auth/google
+OAUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
+
+NEXT_PUBLIC_OAUTH_APPLE_ENABLED=false
+NEXT_PUBLIC_OAUTH_APPLE_CLIENT_ID=your_apple_client_id
+NEXT_PUBLIC_OAUTH_APPLE_REDIRECT_URI=http://localhost:3000/api/auth/apple
+OAUTH_APPLE_CLIENT_SECRET=your_apple_client_secret
+
+RESEND_API_KEY=re_your_resend_api_key
+RESEND_FROM_EMAIL=noreply@yourdomain.com
+RESEND_FROM_NAME=Your App Name
+NEXT_PUBLIC_APP_NAME=Your App Name
+```
+
+### Environment Variable Reference
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `NEXT_PUBLIC_APP_URL` | Your application base URL | No | `http://localhost:3000` |
+| `NEXT_PUBLIC_AUTH_REDIRECT_AFTER_LOGIN` | Redirect URL after successful login | No | `/` |
+| `NEXT_PUBLIC_AUTH_REDIRECT_AFTER_REGISTER` | Redirect URL after registration | No | `/login` |
+| `NEXT_PUBLIC_AUTH_REDIRECT_AFTER_RESET` | Redirect URL after password reset | No | `/login` |
+| `NEXT_PUBLIC_OAUTH_GOOGLE_ENABLED` | Enable/disable Google OAuth | No | `false` |
+| `NEXT_PUBLIC_OAUTH_GOOGLE_CLIENT_ID` | Google OAuth Client ID | Yes (if Google enabled) | - |
+| `NEXT_PUBLIC_OAUTH_GOOGLE_REDIRECT_URI` | Google OAuth redirect URI | Yes (if Google enabled) | - |
+| `OAUTH_GOOGLE_CLIENT_SECRET` | Google OAuth Client Secret (server-only) | Yes (if Google enabled) | - |
+| `NEXT_PUBLIC_OAUTH_APPLE_ENABLED` | Enable/disable Apple OAuth | No | `false` |
+| `NEXT_PUBLIC_OAUTH_APPLE_CLIENT_ID` | Apple OAuth Client ID | Yes (if Apple enabled) | - |
+| `NEXT_PUBLIC_OAUTH_APPLE_REDIRECT_URI` | Apple OAuth redirect URI | Yes (if Apple enabled) | - |
+| `OAUTH_APPLE_CLIENT_SECRET` | Apple OAuth Client Secret (server-only) | Yes (if Apple enabled) | - |
+| `RESEND_API_KEY` | Resend API key for sending emails | Yes (if using email features) | - |
+| `RESEND_FROM_EMAIL` | Email address to send from (must be verified in Resend) | Yes (if using email features) | - |
+| `RESEND_FROM_NAME` | Display name for email sender | No | - |
+| `NEXT_PUBLIC_APP_NAME` | Your application name (used in emails) | No | `App` |
+
+**Note:** Variables prefixed with `NEXT_PUBLIC_` are exposed to the browser. Secrets should NOT use this prefix.
+
+## Quick Start
+
+If you ran `npx @liedsonc/core-auth-kit init`, the layout and pages already exist; go to **1. Implement AuthClient** and replace the stub in `lib/auth-client.ts` with your backend. Otherwise, follow steps 1–3 below.
+
+### 1. Implement AuthClient
+
+Create an `AuthClient` that connects to your backend (or replace the stub in `lib/auth-client.ts` if you used init):
+
+```typescript
+import type { AuthClient } from "@liedsonc/core-auth-kit";
+
+export const myAuthClient: AuthClient = {
+  async login(email, password) {
+    const response = await fetch("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, password }),
+    });
+    
+    if (!response.ok) {
+      return {
+        success: false,
+        error: { code: "INVALID_CREDENTIALS", message: "Invalid email or password" },
+      };
+    }
+    
+    return { success: true };
+  },
+  
+  async register(email, password) {
+    const response = await fetch("/api/auth/register", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, password }),
+    });
+    
+    if (!response.ok) {
+      const data = await response.json();
+      return {
+        success: false,
+        error: { code: data.code || "REGISTRATION_FAILED", message: data.message },
+      };
+    }
+    
+    return { success: true };
+  },
+  
+  async logout() {
+    await fetch("/api/auth/logout", { method: "POST" });
+  },
+  
+  async forgotPassword(email) {
+    const response = await fetch("/api/auth/forgot-password", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email }),
+    });
+    
+    return response.ok ? { success: true } : {
+      success: false,
+      error: { code: "FAILED", message: "Failed to send reset email" },
+    };
+  },
+  
+  async resetPassword(token, newPassword) {
+    const response = await fetch("/api/auth/reset-password", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token, newPassword }),
+    });
+    
+    if (!response.ok) {
+      return {
+        success: false,
+        error: { code: "INVALID_TOKEN", message: "Invalid or expired token" },
+      };
+    }
+    
+    return { success: true };
+  },
+  
+  async verifyEmail(token) {
+    const response = await fetch("/api/auth/verify-email", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token }),
+    });
+    
+    if (!response.ok) {
+      const data = await response.json();
+      return {
+        success: false,
+        error: { code: data.code || "INVALID", message: data.message },
+      };
+    }
+    
+    return { success: true };
+  },
+  
+  async getSession() {
+    const response = await fetch("/api/auth/session");
+    if (!response.ok) return null;
+    return response.json();
+  },
+};
+```
+
+### 2. Setup Provider with Environment Variables
+
+Create a utility to load OAuth config from environment variables:
+
+```typescript
+// lib/oauth-config.ts
+import type { OAuthProvider } from "@liedsonc/core-auth-kit";
+
+export interface OAuthProviderConfig {
+  provider: OAuthProvider;
+  enabled: boolean;
+  clientId?: string;
+  redirectUri?: string;
+}
+
+export function getOAuthProvidersFromEnv(): OAuthProviderConfig[] {
+  const providers: OAuthProviderConfig[] = [];
+
+  if (process.env.NEXT_PUBLIC_OAUTH_GOOGLE_ENABLED === "true") {
+    providers.push({
+      provider: "google",
+      enabled: true,
+      clientId: process.env.NEXT_PUBLIC_OAUTH_GOOGLE_CLIENT_ID,
+      redirectUri: process.env.NEXT_PUBLIC_OAUTH_GOOGLE_REDIRECT_URI,
+    });
+  }
+
+  if (process.env.NEXT_PUBLIC_OAUTH_APPLE_ENABLED === "true") {
+    providers.push({
+      provider: "apple",
+      enabled: true,
+      clientId: process.env.NEXT_PUBLIC_OAUTH_APPLE_CLIENT_ID,
+      redirectUri: process.env.NEXT_PUBLIC_OAUTH_APPLE_REDIRECT_URI,
+    });
+  }
+
+  return providers;
+}
+```
+
+Wrap your auth routes with `AuthUIProvider`:
+
+```tsx
+// app/(auth)/layout.tsx
+"use client";
+
+import { AuthUIProvider } from "@liedsonc/core-auth-kit";
+import { myAuthClient } from "@/lib/auth-client";
+import { getOAuthProvidersFromEnv } from "@/lib/oauth-config";
+
+export default function AuthLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <AuthUIProvider
+      config={{
+        authClient: myAuthClient,
+        oauthProviders: getOAuthProvidersFromEnv(),
+        redirectAfterLogin: process.env.NEXT_PUBLIC_AUTH_REDIRECT_AFTER_LOGIN || "/",
+        redirectAfterRegister: process.env.NEXT_PUBLIC_AUTH_REDIRECT_AFTER_REGISTER || "/login",
+        redirectAfterReset: process.env.NEXT_PUBLIC_AUTH_REDIRECT_AFTER_RESET || "/login",
+      }}
+    >
+      {children}
+    </AuthUIProvider>
+  );
+}
+```
+
+### 3. Create Auth Pages
+
+Use the pre-built page components:
+
+```tsx
+// app/(auth)/login/page.tsx
+import { LoginPage } from "@liedsonc/core-auth-kit";
+
+export default function Login() {
+  return <LoginPage />;
+}
+```
+
+```tsx
+// app/(auth)/register/page.tsx
+import { RegisterPage } from "@liedsonc/core-auth-kit";
+
+export default function Register() {
+  return <RegisterPage />;
+}
+```
+
+```tsx
+// app/(auth)/forgot-password/page.tsx
+import { ForgotPasswordPage } from "@liedsonc/core-auth-kit";
+
+export default function ForgotPassword() {
+  return <ForgotPasswordPage />;
+}
+```
+
+```tsx
+// app/(auth)/reset-password/page.tsx
+import { ResetPasswordPage } from "@liedsonc/core-auth-kit";
+
+export default function ResetPassword() {
+  return <ResetPasswordPage />;
+}
+```
+
+```tsx
+// app/(auth)/verify-email/page.tsx
+import { VerifyEmailPage } from "@liedsonc/core-auth-kit";
+
+export default function VerifyEmail() {
+  return <VerifyEmailPage />;
+}
+```
+
+## Email Integration with Resend
+
+The package includes utilities for sending verification and password reset emails via Resend. Here's how to integrate it:
+
+### 1. Setup Resend
+
+1. Sign up for a [Resend account](https://resend.com)
+2. Get your API key from the dashboard
+3. Verify your domain (or use Resend's test domain for development)
+4. Add your credentials to `.env.local`:
+
+```bash
+RESEND_API_KEY=re_your_api_key_here
+RESEND_FROM_EMAIL=noreply@yourdomain.com
+RESEND_FROM_NAME=Your App Name
+NEXT_PUBLIC_APP_NAME=Your App Name
+```
+
+### 2. Use Resend Email Service
+
+Import and use the Resend email service in your AuthClient implementation:
+
+```typescript
+// lib/auth-client.ts
+import type { AuthClient } from "@liedsonc/core-auth-kit";
+import { createResendEmailService } from "@/lib/resend-email";
+import { randomBytes } from "crypto";
+
+const emailService = createResendEmailService({
+  apiKey: process.env.RESEND_API_KEY!,
+  from: process.env.RESEND_FROM_EMAIL!,
+  fromName: process.env.RESEND_FROM_NAME,
+  appName: process.env.NEXT_PUBLIC_APP_NAME || "App",
+});
+
+const appUrl = process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";
+
+export const myAuthClient: AuthClient = {
+  async register(email, password) {
+    // Your registration logic here
+    // ... save user to database
+    
+    // Generate verification token
+    const token = randomBytes(32).toString("hex");
+    // Store token in database with expiration
+    // await db.verificationTokens.create({ email, token, expiresAt: ... });
+    
+    // Send verification email
+    const verificationUrl = `${appUrl}/verify-email?token=${token}`;
+    const emailResult = await emailService.sendVerificationEmail({
+      email,
+      token,
+      verificationUrl,
+    });
+    
+    if (!emailResult.success) {
+      return {
+        success: false,
+        error: { code: "EMAIL_SEND_FAILED", message: "Failed to send verification email" },
+      };
+    }
+    
+    return { success: true };
+  },
+  
+  async forgotPassword(email) {
+    // Generate reset token
+    const token = randomBytes(32).toString("hex");
+    // Store token in database with expiration (e.g., 1 hour)
+    // await db.resetTokens.create({ email, token, expiresAt: ... });
+    
+    // Send password reset email
+    const resetUrl = `${appUrl}/reset-password?token=${token}`;
+    const emailResult = await emailService.sendPasswordResetEmail({
+      email,
+      token,
+      resetUrl,
+      expiresIn: "1 hour",
+    });
+    
+    if (!emailResult.success) {
+      return {
+        success: false,
+        error: { code: "EMAIL_SEND_FAILED", message: "Failed to send reset email" },
+      };
+    }
+    
+    return { success: true };
+  },
+  
+  // ... other AuthClient methods
+};
+```
+
+### 3. Example Implementation
+
+See `lib/auth-client-with-resend.ts` for a complete example implementation that includes:
+- Token generation and validation
+- Email sending with Resend
+- Token expiration handling
+- Error handling
+
+### 4. Customizing Email Templates
+
+The email templates are built into the `ResendEmailService` class. To customize them:
+
+1. Extend the `ResendEmailService` class
+2. Override the template methods (`getVerificationEmailTemplate`, `getPasswordResetEmailTemplate`)
+3. Use your custom service instance
+
+```typescript
+class CustomEmailService extends ResendEmailService {
+  private getVerificationEmailTemplate({ verificationUrl, appName }: { verificationUrl: string; appName: string }): string {
+    // Your custom HTML template
+    return `...`;
+  }
+}
+```
+
+### 5. Email Service API
+
+```typescript
+import { createResendEmailService, ResendEmailService } from "@/lib/resend-email";
+
+// Create service instance
+const emailService = createResendEmailService({
+  apiKey: process.env.RESEND_API_KEY!,
+  from: process.env.RESEND_FROM_EMAIL!,
+  fromName: "Your App",
+  appName: "Your App Name",
+});
+
+// Send verification email
+await emailService.sendVerificationEmail({
+  email: "user@example.com",
+  token: "verification_token",
+  verificationUrl: "https://yourapp.com/verify-email?token=...",
+  appName: "Your App", // Optional, uses service default if not provided
+});
+
+// Send password reset email
+await emailService.sendPasswordResetEmail({
+  email: "user@example.com",
+  token: "reset_token",
+  resetUrl: "https://yourapp.com/reset-password?token=...",
+  appName: "Your App", // Optional
+  expiresIn: "1 hour", // Optional, default is "1 hour"
+});
+```
+
+## API Reference
+
+### Components
+
+#### Pages
+
+- **`LoginPage`** - Complete login page with email/password and OAuth
+- **`RegisterPage`** - Registration page with password strength indicator
+- **`ForgotPasswordPage`** - Password reset request page
+- **`ResetPasswordPage`** - Password reset form (requires token query param)
+- **`VerifyEmailPage`** - Email verification page (requires token query param)
+
+#### UI Components
+
+- **`AuthCard`** - Reusable card layout for auth pages
+- **`AuthForm`** - Form wrapper with loading/error states
+- **`FormField`** - Form field with label and error display
+- **`PasswordInput`** - Password input with show/hide toggle and strength indicator
+- **`OAuthButtons`** - OAuth provider buttons (Google, Apple)
+- **`ErrorMessage`** - Error message display component
+- **`SuccessMessage`** - Success message display component
+- **`LoadingSpinner`** - Loading spinner component
+
+### Hooks
+
+#### `useAuth()`
+
+Main authentication hook that provides all auth methods:
+
+```typescript
+const {
+  login,           // (email: string, password: string) => Promise<AuthResult>
+  register,        // (email: string, password: string) => Promise<AuthResult>
+  logout,          // () => Promise<void>
+  forgotPassword,  // (email: string) => Promise<AuthResult>
+  resetPassword,   // (token: string, newPassword: string) => Promise<AuthResult>
+  verifyEmail,     // (token: string) => Promise<AuthResult>
+  session,         // AuthSession | null
+  loadSession,     // () => Promise<AuthSession | null>
+  loading,         // boolean
+  error,           // AuthError | null
+  clearError,      // () => void
+} = useAuth();
+```
+
+#### `useOAuth(onRedirect)`
+
+OAuth authentication hook:
+
+```typescript
+const { signIn, loadingProvider } = useOAuth(
+  (provider) => `/api/auth/${provider}`
+);
+```
+
+### Types
+
+```typescript
+interface AuthClient {
+  login: (email: string, password: string) => Promise<AuthResult>;
+  register: (email: string, password: string) => Promise<AuthResult>;
+  logout: () => Promise<void>;
+  forgotPassword: (email: string) => Promise<AuthResult>;
+  resetPassword: (token: string, newPassword: string) => Promise<AuthResult>;
+  verifyEmail: (token: string) => Promise<AuthResult>;
+  getSession?: () => Promise<AuthSession | null>;
+}
+
+interface AuthUIConfig {
+  authClient: AuthClient;
+  oauthProviders?: { provider: OAuthProvider; enabled: boolean }[];
+  logo?: ReactNode;
+  redirectAfterLogin?: string;
+  redirectAfterRegister?: string;
+  redirectAfterReset?: string;
+}
+
+type AuthResult = 
+  | { success: true }
+  | { success: false; error: AuthError };
+
+interface AuthError {
+  code: string;
+  message: string;
+}
+
+type OAuthProvider = "google" | "apple";
+```
+
+## Customization
+
+### Custom Logo
+
+```tsx
+<AuthUIProvider
+  config={{
+    authClient: myAuthClient,
+    logo: <img src="/logo.svg" alt="Logo" />,
+  }}
+>
+  {children}
+</AuthUIProvider>
+```
+
+### OAuth Configuration via Environment Variables
+
+Enable/disable OAuth providers and configure credentials via environment variables:
+
+```bash
+NEXT_PUBLIC_OAUTH_GOOGLE_ENABLED=true
+NEXT_PUBLIC_OAUTH_GOOGLE_CLIENT_ID=your_client_id
+NEXT_PUBLIC_OAUTH_GOOGLE_REDIRECT_URI=https://yourapp.com/api/auth/google
+OAUTH_GOOGLE_CLIENT_SECRET=your_client_secret
+```
+
+The `getOAuthProvidersFromEnv()` utility automatically reads these and configures providers.
+
+### Custom Redirects
+
+Set redirects via environment variables or config:
+
+```tsx
+<AuthUIProvider
+  config={{
+    authClient: myAuthClient,
+    redirectAfterLogin: process.env.NEXT_PUBLIC_AUTH_REDIRECT_AFTER_LOGIN || "/dashboard",
+    redirectAfterRegister: process.env.NEXT_PUBLIC_AUTH_REDIRECT_AFTER_REGISTER || "/onboarding",
+    redirectAfterReset: process.env.NEXT_PUBLIC_AUTH_REDIRECT_AFTER_RESET || "/login?reset=success",
+  }}
+>
+  {children}
+</AuthUIProvider>
+```
+
+### Using Individual Components
+
+You can also use components individually to build custom pages:
+
+```tsx
+import { AuthCard, AuthForm, FormField, PasswordInput, Button } from "@liedsonc/core-auth-kit";
+
+export function CustomLoginPage() {
+  return (
+    <AuthCard title="Sign In">
+      <AuthForm onSubmit={handleSubmit}>
+        <FormField label="Email" htmlFor="email">
+          <Input id="email" type="email" />
+        </FormField>
+        <FormField label="Password" htmlFor="password">
+          <PasswordInput id="password" />
+        </FormField>
+        <Button type="submit">Sign In</Button>
+      </AuthForm>
+    </AuthCard>
+  );
+}
+```
+
+## Production Setup
+
+### 1. Environment Variables
+
+Copy `.env.example` to `.env.local` and fill in your production values:
+
+```bash
+cp .env.example .env.local
+```
+
+**Important:** Never commit `.env.local` to version control. Add it to `.gitignore`.
+
+### 2. OAuth Provider Setup
+
+#### Google OAuth
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing
+3. Enable Google+ API
+4. Create OAuth 2.0 credentials
+5. Add authorized redirect URIs
+6. Copy Client ID and Client Secret to `.env.local`
+
+#### Apple OAuth
+
+1. Go to [Apple Developer Portal](https://developer.apple.com/)
+2. Create an App ID
+3. Create a Services ID
+4. Configure Sign in with Apple
+5. Add redirect URIs
+6. Copy Client ID and Client Secret to `.env.local`
+
+### 3. Build and Deploy
+
+```bash
+npm run build
+npm start
+```
+
+## Styling
+
+The package uses Tailwind CSS and follows shadcn/ui conventions. Customize colors via CSS variables:
+
+```css
+:root {
+  --primary: 222.2 47.4% 11.2%;
+  --primary-foreground: 210 40% 98%;
+  /* ... other variables */
+}
+```
+
+See [shadcn/ui theming](https://ui.shadcn.com/docs/theming) for details.
+
+## Security Considerations
+
+- **No User Enumeration**: Error messages don't reveal if an email exists
+- **Secure Defaults**: Password inputs prevent autofill leaks
+- **CSRF Protection**: Implement CSRF tokens in your `AuthClient`
+- **Rate Limiting**: Implement rate limiting in your backend
+- **Token Security**: Handle tokens securely in your `AuthClient`
+- **Environment Variables**: Never expose secrets in client-side code (use `NEXT_PUBLIC_` prefix only for public values)
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Project Structure
+
+```
+core-auth-kit/
+├── auth-ui/              # Package source code
+│   ├── components/       # UI components
+│   ├── hooks/           # React hooks
+│   ├── pages/           # Page components
+│   ├── types/           # TypeScript types
+│   ├── styles/          # CSS styles
+│   └── index.ts         # Main export
+├── app/                 # Example Next.js app
+├── lib/                 # Utilities (oauth-config, auth-client)
+├── .env.example         # Environment variables template
+└── README.md            # This file
+```
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+## License
+
+MIT
+
+## Support
+
+For issues, questions, or contributions, please open an issue on GitHub.