@groo.dev/auth-react

React hooks and components for integrating Groo authentication into your React/Next.js applications using OAuth-style consent flow.

Installation

npm install @groo.dev/auth-react

Prerequisites

Before using this SDK, you need:

1. A registered application at accounts.groo.dev with a client_id
2. A backend API using @groo.dev/auth-server to proxy authentication

Quick Start

1. Set up your backend API

Your API needs to use @groo.dev/auth-server:

// api/src/index.ts
import { Hono } from 'hono'
import { grooAuth } from '@groo.dev/auth-server'
import { GrooHonoMiddleware } from '@groo.dev/auth-server/hono'

type Env = {
  CLIENT_ID: string
  CLIENT_SECRET: string
}

const hono = new GrooHonoMiddleware<Env>((env) => grooAuth({
  clientId: env.CLIENT_ID,
  clientSecret: env.CLIENT_SECRET,
}))

const app = new Hono<{ Bindings: Env }>()

app.use('*', hono.init)
app.route('/v1', hono.routes)

export default app

2. Proxy API calls from your frontend

Configure your frontend to proxy /v1/* requests to your API:

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: '/v1/:path*',
        destination: 'https://api.myapp.groo.dev/v1/:path*',
      },
    ]
  },
}

export default nextConfig

3. Wrap your app with AuthProvider

// app/providers.tsx
'use client'

import { AuthProvider } from '@groo.dev/auth-react'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AuthProvider
      baseUrl="https://accounts.groo.dev"
      clientId="your-client-id"
      redirectUri="https://myapp.groo.dev"
    >
      {children}
    </AuthProvider>
  )
}

4. Use the auth hooks

'use client'

import { useAuth, LoginButton, LogoutButton } from '@groo.dev/auth-react'

export default function Page() {
  const { user, isLoading, error } = useAuth()

  if (isLoading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return user ? (
    <div>
      <p>Welcome, {user.name || user.email}!</p>
      <LogoutButton>Sign Out</LogoutButton>
    </div>
  ) : (
    <div>
      <p>Not logged in</p>
      <LoginButton>Sign In</LoginButton>
    </div>
  )
}

API Reference

AuthProvider

Provides authentication context to your app.

<AuthProvider
  baseUrl="https://accounts.groo.dev"  // Required: Groo accounts service URL
  clientId="your-client-id"            // Required: Your application's client ID
  redirectUri="https://myapp.groo.dev" // Required: Where to redirect after login
>
  {children}
</AuthProvider>

useAuth()

Hook to access authentication state.

const { user, isLoading, error, loginUrl, logoutUrl, refetch } = useAuth()

Returns:

• user: User | null - Current user or null if not authenticated
• isLoading: boolean - True while fetching user data
• error: Error | null - Error if authentication check failed
• loginUrl: string - URL to redirect for login
• logoutUrl: string - URL to redirect for logout
• refetch: () => Promise<void> - Function to refetch user data

LoginButton

A link that redirects to the login page with OAuth parameters.

<LoginButton className="btn">
  Sign In
</LoginButton>

The login URL includes:

• client_id - Your application's client ID
• redirect_uri - Current page URL (for redirect after login)

LogoutButton

A link that redirects to the logout endpoint. Clears the session and redirects back to your app.

<LogoutButton className="btn">
  Sign Out
</LogoutButton>

The logout URL redirects to {baseUrl}/v1/auth/logout?redirect_uri={origin} which:

1. Clears the session cookie
2. Redirects the user back to your app's origin

RequireAuth

Wrapper component that only renders children when user is authenticated.

<RequireAuth
  fallback={<div>Loading...</div>}  // Optional: Show while loading
  redirectTo="/login"                // Optional: Redirect if not authenticated
>
  <ProtectedContent />
</RequireAuth>

User Object

interface User {
  id: string
  email: string | null
  phone: string | null
  name: string | null
  role: string
}

// When using auth-server middleware, you also get consent info:
interface ConsentedUser extends User {
  consent: {
    id: string
    consentedAt: string
    lastAccessedAt: string
    revokedAt: string | null
    appData: Record<string, unknown>  // App-specific data storage
  }
}

How It Works

Login Flow

1. AuthProvider checks authentication by calling /v1/__auth/me on your API
2. Your API validates the session via accounts.groo.dev/v1/client/auth/me
3. LoginButton redirects to accounts.groo.dev/login?client_id=...&redirect_uri=...
4. User authenticates and grants consent to your application
5. User is redirected back with a session cookie
6. SDK detects the session and fetches user data

Logout Flow

1. LogoutButton redirects to accounts.groo.dev/v1/auth/logout?redirect_uri=...
2. Session is deleted and cookie is cleared
3. User is redirected back to your app

Related Packages

• @groo.dev/auth-server - Server-side middleware for Hono/Cloudflare Workers
• @groo.dev/auth-core - Shared types and utilities

License

MIT