Create shared auth-ui and email template packages

[mjunaidca]

🎯 Objective

Extract reusable React components and email templates into shared packages that can be used across multiple applications.

📋 Implementation Checklist

1. Create Auth-UI Package

Package Structure

• Create packages/auth-ui/ directory

  packages/auth-ui/
  ├── src/
  │   ├── components/
  │   │   ├── AuthLogin.tsx
  │   │   ├── AuthSignup.tsx
  │   │   ├── AuthResetPassword.tsx
  │   │   └── index.ts
  │   ├── hooks/
  │   │   ├── useAuth.ts
  │   │   └── index.ts
  │   ├── types.ts
  │   └── index.ts
  ├── package.json
  ├── tsconfig.json
  └── README.md
  

Package.json Configuration

• Create packages/auth-ui/package.json

  {
    "name": "@robolearn/auth-ui",
    "version": "0.1.0",
    "main": "./dist/index.js",
    "types": "./dist/index.d.ts",
    "exports": {
      "./": "./dist/",
      "./components": "./dist/components/index.js",
      "./hooks": "./dist/hooks/index.js"
    },
    "peerDependencies": {
      "react": "^18.0.0",
      "react-dom": "^18.0.0"
    },
    "dependencies": {
      "@robolearn/auth-client": "workspace:*"
    },
    "devDependencies": {
      "@types/react": "^18.0.0",
      "typescript": "^5.0.0"
    }
  }

React Components

AuthLogin Component

• Create src/components/AuthLogin.tsx
  • Email/password login form
  • Error handling
  • Loading states
  • Redirect after login
  • Props: onSuccess?, redirectTo?, className?

AuthSignup Component

• Create src/components/AuthSignup.tsx
  • Email/password signup form
  • Email verification notice
  • Error handling
  • Loading states
  • Props: onSuccess?, redirectTo?, className?

AuthResetPassword Component

• Create src/components/AuthResetPassword.tsx
  • Password reset request form
  • Password reset form (with token)
  • Error handling
  • Loading states
  • Props: resetToken?, onSuccess?, className?

useAuth Hook

• Create src/hooks/useAuth.ts
  • Wrapper around Better Auth's useSession
  • Additional helpers:
    • isAuthenticated
    • user
    • login
    • logout
    • signup
  • Type-safe return values

Export Structure

• Create src/index.ts

  export { AuthLogin } from './components/AuthLogin';
  export { AuthSignup } from './components/AuthSignup';
  export { AuthResetPassword } from './components/AuthResetPassword';
  export { useAuth } from './hooks/useAuth';
  export * from './types';

Build Configuration

• Set up TypeScript compilation
  • Output to dist/
  • Generate declaration files (.d.ts)
  • Configure tsconfig.json

Workspace Integration

• Update root package.json (if using workspace)

  {
    "workspaces": [
      "packages/*",
      "auth-server",
      "robolearn-interface"
    ]
  }

Usage in Downstream Apps

• Document installation

  # In robolearn-interface or other apps
  pnpm add @robolearn/auth-ui@workspace:*

• Document usage

  import { AuthLogin, useAuth } from '@robolearn/auth-ui';
  
  function LoginPage() {
    return <AuthLogin onSuccess={() => router.push('/dashboard')} />;
  }

---

2. Email Templates Package

Move Email Templates

• Create auth-server/src/lib/email/templates/ directory

  auth-server/src/lib/email/templates/
  ├── welcome.ts
  ├── reset-password.ts
  ├── verification.ts
  └── index.ts
  

Extract Templates

• Extract welcome email from auth.ts

  • Move HTML template to templates/welcome.ts
  • Export function: generateWelcomeEmail(user, url)

• Extract reset password email from auth.ts

  • Move HTML template to templates/reset-password.ts
  • Export function: generateResetPasswordEmail(user, url)

• Extract verification email from auth.ts

  • Move HTML template to templates/verification.ts
  • Export function: generateVerificationEmail(user, url)

Template Structure

• Create template functions

  // templates/welcome.ts
  export interface WelcomeEmailParams {
    user: { name: string; email: string };
    url: string;
  }
  
  export function generateWelcomeEmail({ user, url }: WelcomeEmailParams): string {
    return `
      <h2>Welcome to RoboLearn!</h2>
      <p>Hi ${user.name},</p>
      <p>Please verify your email address by clicking the link below:</p>
      <p><a href="${url}">Verify Email</a></p>
    `;
  }

Update Auth Server Imports

• Update auth-server/src/lib/auth.ts
  • Import templates from new location
  • Keep existing import paths working (backward compatibility)

  import {
    generateWelcomeEmail,
    generateResetPasswordEmail,
    generateVerificationEmail
  } from './email/templates';
  
  // Use in Better Auth config
  sendVerificationEmail: async ({ user, url }) => {
    await sendEmail({
      to: user.email,
      subject: 'Verify your RoboLearn account',
      html: generateVerificationEmail({ user, url })
    });
  }

Export for Future Workers

• Create auth-server/src/lib/email/index.ts
  • Export all templates
  • Export email sending function (if reusable)
  • Document usage for background workers

Future: Background Worker Support

• Document for future background workers
  • Templates can be imported by background workers
  • Workers can send emails independently
  • Shared template ensures consistency

---

3. Documentation

Auth-UI Package README

• Create packages/auth-ui/README.md
  • Installation instructions
  • Component API documentation
  • Usage examples
  • Props documentation

Email Templates Documentation

• Add section to auth-server/README.md
  • Location of templates
  • How to customize
  • How to use in background workers

---

🧪 Testing Checklist

Auth-UI Package

• Components render correctly
• useAuth hook works
• TypeScript types are correct
• Package builds successfully
• Can be imported in downstream apps

Email Templates

• Templates generate correct HTML
• All variables are interpolated correctly
• Existing imports still work (backward compatibility)
• Templates can be imported by external code

---

📋 Deliverables

• packages/auth-ui/ package with:
  • AuthLogin component
  • AuthSignup component
  • AuthResetPassword component
  • useAuth hook
  • TypeScript types
  • Package.json and build config
• auth-server/src/lib/email/templates/ directory with:
  • Welcome email template
  • Reset password email template
  • Verification email template
• Updated auth-server imports (backward compatible)
• Documentation (README files)
• Workspace configuration (if applicable)

---

🔗 Related Issues

• Add comprehensive JWT/JWKS/OIDC documentation guide #12: Add comprehensive JWT/JWKS/OIDC documentation guide
• Create shared auth-ui and email template packages #19: Create server-app integration guide

---

📝 Notes

Package Publishing

• Currently: Workspace-only (no external registry)
• Future: Consider publishing to npm if needed

Styling

• Consider if components should be unstyled (headless) or styled
• If styled: Use Tailwind CSS or CSS modules
• Document styling approach

Versioning

• Use workspace protocol for now: @robolearn/auth-ui@workspace:*
• Consider semantic versioning if publishing externally