Quickstart with Hosted UI

Who this is for: Developers who want the fastest path to a working login (15 minutes)

What you get: A complete Passcards authentication flow with hosted UI components

Prereqs:

• Node.js 18+ installed
• Supabase account (free tier works)
• Next.js project (or create one with npx create-next-app@latest)

Steps:

1. Install Passcards (2 minutes)

# In your Next.js project
npx passcards-auth init

This will:

• ✅ Install dependencies (@supabase/supabase-js, @supabase/ssr)
• ✅ Generate API routes (app/api/auth/passcards/route.ts)
• ✅ Generate UI components (components/Passcards.tsx)
• ✅ Generate auth utilities (lib/passcard-auth.ts)
• ✅ Create database migration SQL

2. Set Up Supabase (5 minutes)

1. Create Supabase project: https://supabase.com
2. Run migration: Copy SQL from supabase/migrations/passcard_oauth.sql to Supabase SQL Editor
3. Get credentials: Project Settings → API
   • Project URL
   • anon key (public)
   • service_role key (secret)

3. Configure Environment Variables (2 minutes)

Create .env.local:

NEXT_PUBLIC_SUPABASE_URL=your_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

4. Add Login Page (3 minutes)

Create app/auth/passcards/page.tsx:

'use client'

import { Passcards } from '@/components/Passcards'
import { useRouter } from 'next/navigation'

export default function PasscardsLoginPage() {
  const router = useRouter()

  const handleSuccess = () => {
    router.push('/dashboard')
  }

  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="max-w-md w-full">
        <h1 className="text-2xl font-bold mb-6">Sign in with Passcards</h1>
        <Passcards onComplete={handleSuccess} />
      </div>
    </div>
  )
}

5. Protect a Route (2 minutes)

Create app/dashboard/page.tsx:

import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'

export default async function DashboardPage() {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()
  
  if (!user) {
    redirect('/auth/passcards')
  }
  
  return (
    <main>
      <h1>Welcome back, {user.email}!</h1>
      <p>You're authenticated with Passcards.</p>
    </main>
  )
}

6. Test It (1 minute)

npm run dev

Visit http://localhost:3000/auth/passcards:

1. Pick 4 cards to create your pattern
2. Submit to register
3. Pick the same 4 cards to login
4. Redirected to dashboard

✅ You now have working Passcards authentication!

Common failures and fixes:

• "Cannot find module '@/components/Passcards'" → Run npx passcards-auth init to generate components
• "Supabase connection failed" → Check .env.local variables match Supabase dashboard exactly
• "Pattern validation failed" → Ensure pattern is exactly 4, 8, 12, or 16 cards
• "Rate limit exceeded" → Wait 15 minutes or reset in Supabase: DELETE FROM passcard_rate_limits WHERE identifier = 'your_ip'
• "Migration failed" → Check Supabase SQL Editor for error messages, ensure tables don't already exist

Security notes:

• Environment variables: Never commit .env.local to git
• Service role key: Only use server-side, never expose to client
• Rate limiting: Enabled by default (5 attempts per 15 minutes)
• HTTPS required: Use HTTPS in production (Vercel/Netlify provide automatically)

Copy paste examples:

# Complete setup script
npx create-next-app@latest my-app
cd my-app
npx passcards-auth init

# Add to .env.local
cat >> .env.local << EOF
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
EOF

# Run dev server
npm run dev

Next: API Only Quickstart → For custom UI implementations