@spacetimedb/auth

Zero-configuration SpacetimeAuth integration for React applications. Handles OIDC flow, token management, and SpacetimeDB connection authentication.

Installation

npm install @spacetimedb/auth react-oidc-context spacetimedb

Usage

Basic Setup

// main.tsx
import { SpacetimeAuthProvider } from '@spacetimedb/auth';
import { DbConnection } from './generated';

const conn = DbConnection.builder()
  .withUri(import.meta.env.VITE_STDB_URI)
  .withModuleName(import.meta.env.VITE_MODULE);

ReactDOM.createRoot(document.getElementById('root')!).render(
  <SpacetimeAuthProvider
    clientId={import.meta.env.VITE_AUTH_CLIENT_ID}
    connectionBuilder={conn}
  >
    <App />
  </SpacetimeAuthProvider>
);

Using the Unified Hook

// App.tsx
import { useSpacetimeDBWithAuth } from '@spacetimedb/auth';

function App() {
  const { isReady, user, logout } = useSpacetimeDBWithAuth();

  if (!isReady) return <div>Loading...</div>;

  return (
    <div>
      <h1>Welcome, {user.name}!</h1>
      <button onClick={logout}>Logout</button>
      <Game />
    </div>
  );
}

Custom Authority

<SpacetimeAuthProvider
  clientId="your-client-id"
  authority="https://custom-auth.example.com/oidc"
  connectionBuilder={conn}
>
  <App />
</SpacetimeAuthProvider>

API Reference

SpacetimeAuthProvider

Provider component that wraps your application with OIDC authentication and SpacetimeDB connection.

Props:

• clientId (string, required): OIDC client ID
• authority (string, optional): OIDC authority URL. Defaults to SpacetimeAuth
• connectionBuilder (required): SpacetimeDB connection builder
• children (ReactNode, required): Your application components

useSpacetimeDBWithAuth

Unified hook that combines authentication and SpacetimeDB connection state.

Returns:

• isAuthenticated (boolean): User authentication status
• user (object | undefined): User profile data
• login (function): Trigger OIDC login redirect
• logout (function): Trigger OIDC logout redirect
• stdb (object): SpacetimeDB connection instance
• isConnected (boolean): SpacetimeDB connection status
• isReady (boolean): Combined readiness (authenticated AND connected)

Features

• Zero-configuration OIDC integration
• Automatic token injection into SpacetimeDB connections
• Silent token renewal
• Unified authentication + connection state
• TypeScript support
• Loading states out of the box

License

MIT