@govector/auth

React authentication components and hooks for Vector-generated apps. Handles login/signup via Vector's hosted auth proxy with JWT-based session management.

Install

npm install @govector/auth

Setup

Wrap your app with VectorAuthProvider:

import { VectorAuthProvider } from "@govector/auth";

function App() {
  return (
    <VectorAuthProvider
      config={{
        authProxyUrl: import.meta.env.VITE_AUTH_PROXY_URL,
        appId: import.meta.env.VITE_APP_ID,
        appVersionId: import.meta.env.VITE_APP_VERSION_ID,
      }}
    >
      <YourApp />
    </VectorAuthProvider>
  );
}

Usage

useAuth hook

import { useAuth } from "@govector/auth";

function Profile() {
  const { isAuthenticated, user, loading, logout, loginUrl, signupUrl } = useAuth();

  if (loading) return <p>Loading...</p>;

  if (!isAuthenticated) {
    return <a href={loginUrl}>Sign in</a>;
  }

  return (
    <div>
      <p>Welcome, {user.full_name}</p>
      <button onClick={logout}>Sign out</button>
    </div>
  );
}

LoginButton / SignupButton

import { LoginButton, SignupButton } from "@govector/auth";

function Landing() {
  return (
    <div>
      <LoginButton label="Sign in" className="btn btn-primary" />
      <SignupButton label="Get started" className="btn btn-secondary" />
    </div>
  );
}

AuthCallback

Add to your router at /auth/callback:

import { AuthCallback } from "@govector/auth";
import { useNavigate } from "react-router-dom";

function AuthCallbackPage() {
  const navigate = useNavigate();

  return (
    <AuthCallback
      onSuccess={() => navigate("/", { replace: true })}
      onError={(error) => console.error(error)}
    />
  );
}

onSuccess fires once the user is fully signed in — i.e. after the token has been exchanged and the session has hydrated via useAuth — so navigating to a protected route from onSuccess is safe.

onError fires for token-exchange failures, a missing token, or a hydration timeout. If the token exchange succeeds but the session does not hydrate within 10 seconds (typically caused by third-party cookies being blocked), onError is called with a hydration-timeout message.

Auth Flow

1. User clicks LoginButton -> redirects to Vector's hosted login page
2. User authenticates (Google, magic link, etc.)
3. Auth proxy redirects to /auth/callback?token=<jwt>
4. AuthCallback exchanges the JWT for a local session cookie
5. useAuth detects the session and updates state

API

VectorAuthProvider

| Prop | Type | Description | |---|---|---| | config.authProxyUrl | string | Vector auth proxy URL | | config.appId | string | Your app's ID | | config.appVersionId | string | Your app version ID | | config.apiBaseUrl | string? | Base URL for API calls (default: current origin) |

useAuth() -> AuthState

| Field | Type | Description | |---|---|---| | isAuthenticated | boolean | Whether the user is logged in | | user | AuthUser \| null | Current user object | | loading | boolean | True during initial auth check | | loginUrl | string | URL to redirect for login | | signupUrl | string | URL to redirect for signup | | logout | () => void | Clears session and redirects to / |

AuthUser

| Field | Type | |---|---| | id | string | | email | string | | first_name | string | | last_name | string | | full_name | string | | picture | string |