React Scaffold (SDK)

A React application using @auth-gate/react to handle authentication with minimal server code. The SDK replaces the ~340 lines of custom auth routes from the custom React scaffold with a single function call.

Overview

This scaffold demonstrates the SDK approach to AuthGate integration. Instead of implementing OAuth state management, token verification, and session handling yourself, the @auth-gate/react package provides:

• createAuthRoutes() — server-side Hono routes for OAuth + email auth
• <AuthProvider> — React context for auth state
• <AuthGuard> — protected route wrapper
• useAuth() / useSession() — hooks for accessing user data

Compare the server setup between custom and SDK:

// Custom: ~340 lines in src/server/routes/auth.ts
// SDK: ~6 lines
const authRoutes = createAuthRoutes({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: process.env.AUTHGATE_URL!,
  appUrl,
});

Prerequisites

• Node.js 18+
• An AuthGate project with at least one provider enabled
• An API key from the AuthGate dashboard

Setup

cd apps/scaffolds/react/sdk
cp .env.example .env
# Fill in your AuthGate credentials
pnpm install
pnpm dev

The dev server runs at http://localhost:3005 by default.

Directory structure

src/
├── server/
│   └── index.ts              # Hono server with SDK auth routes (~54 lines)
├── components/
│   └── OAuthButtons.tsx      # Provider login buttons
├── pages/
│   ├── Home.tsx
│   ├── Login.tsx
│   ├── Signup.tsx
│   ├── ForgotPassword.tsx
│   ├── ResetPassword.tsx
│   └── Dashboard.tsx
├── App.tsx                   # Routes with AuthProvider + AuthGuard
└── main.tsx

Notice there's no lib/auth.tsx, no AuthGuard.tsx component, and no routes/auth.ts — the SDK provides all of these.

Key files

src/server/index.ts

The entire server-side auth setup:

import { createAuthRoutes } from "@auth-gate/react/server";

const authRoutes = createAuthRoutes({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: process.env.AUTHGATE_URL!,
  appUrl,
});

app.route("/api/auth", authRoutes);

The createAuthRoutes() function generates Hono routes for:

• GET /:provider/login — OAuth redirect with state
• GET /callback — OAuth callback verification
• POST /email/signup, /email/signin, /email/forgot-password, /email/reset-password
• GET /me — current session user
• POST /logout — clear session

Under the hood, the SDK uses @auth-gate/core for AES-256-GCM session encryption, HMAC state management, and token verification — the same security primitives as the custom scaffold, but abstracted away.

src/App.tsx

Wraps the app in <AuthProvider> and uses <AuthGuard> from the SDK:

import { AuthProvider, AuthGuard } from "@auth-gate/react";

function App() {
  return (
    <AuthProvider>
      <Routes>
        <Route path="/dashboard" element={
          <AuthGuard>
            <Dashboard />
          </AuthGuard>
        } />
        {/* ... */}
      </Routes>
    </AuthProvider>
  );
}

<AuthProvider> calls /api/auth/me on mount and provides auth context. <AuthGuard> redirects unauthenticated users to /login.

Pages

The login, signup, and password reset pages are identical to the custom scaffold — they submit forms to /api/auth/email/* endpoints. The SDK handles the server-side processing.

Environment variables