@zewstid/react

Official ZewstID SDK for React - Authentication for single-page applications.

✨ Features

Authentication Methods (v0.1.0)

🔐 OAuth 2.0 + OIDC - Industry-standard authentication with PKCE
🌐 Social Login - Google, GitHub, Microsoft, Apple, Facebook
🔄 Auto Token Refresh - Seamless session management
🛡️ Secure by Default - HTTPS, PKCE, httpOnly cookies
📱 Modern UI - Popup and redirect-based flows

Developer Experience

⚡ React Hooks - Modern hooks-based API
📦 Lightweight - Small bundle size with tree-shaking
🎯 TypeScript - Full type safety
⚡ Fast - Optimized for performance
🎨 Flexible - Works with any React setup (Vite, CRA, Remix, etc.)
🔧 Developer-Friendly - Clear error messages and debugging

🚀 Installation

From ZewstID npm Registry:


npm install @zewstid/react --registry https://npm.zewstid.com/

Or configure registry in

.npmrc


# .npmrc
@zewstid:registry=https://npm.zewstid.com/

Then install normally:


npm install @zewstid/react

Quick Start

1. Wrap Your App with Provider


import { ZewstIDProvider } from '@zewstid/react';

function App() {
  return (
    <ZewstIDProvider
      config={{
        clientId: process.env.REACT_APP_ZEWSTID_CLIENT_ID!,
        redirectUri: window.location.origin + '/callback',
      }}
    >
      <YourApp />
    </ZewstIDProvider>
  );
}

2. Use Authentication in Components


import { useZewstID } from '@zewstid/react';

function Profile() {
  const { user, isAuthenticated, signIn, signOut } = useZewstID();

  if (!isAuthenticated) {
    return <button onClick={() => signIn()}>Sign in with ZewstID</button>;
  }

  return (
    <div>
      <p>Welcome {user?.name}</p>
      <button onClick={() => signOut()}>Sign out</button>
    </div>
  );
}

3. Create a Callback Page


// src/pages/Callback.tsx
import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';

export function Callback() {
  const navigate = useNavigate();

  useEffect(() => {
    // The provider automatically handles the callback
    // Just redirect to home after a short delay
    setTimeout(() => navigate('/'), 100);
  }, [navigate]);

  return <div>Completing sign in...</div>;
}

API Reference

`<ZewstIDProvider>`

Wrap your application with this provider.

Props:


interface ZewstIDProviderProps {
  config: {
    clientId: string;                 // Required
    redirectUri: string;              // Required
    issuerUrl?: string;               // Default: https://auth.zewstid.com/realms/zewstid
    postLogoutRedirectUri?: string;   // Default: redirectUri
    scopes?: string[];                // Default: ['openid', 'profile', 'email', 'roles']
    debug?: boolean;                  // Default: false
    automaticSilentRenew?: boolean;   // Default: true
    loadUserInfo?: boolean;           // Default: true
  };
  children: ReactNode;
  onAuthStateChange?: (user: ZewstIDUser | null) => void;
}

Example:


<ZewstIDProvider
  config={{
    clientId: 'your_client_id',
    redirectUri: 'http://localhost:3000/callback',
    issuerUrl: 'https://auth.zewstid.com/realms/zewstid',
    scopes: ['openid', 'profile', 'email', 'roles'],
    debug: true,
  }}
  onAuthStateChange={(user) => {
    console.log('Auth state changed:', user);
  }}
>
  <App />
</ZewstIDProvider>

`useZewstID()`

Main hook for authentication.

Returns:


{
  user: ZewstIDUser | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  error: Error | null;
  signIn: (options?: SignInOptions) => Promise<void>;
  signInWithPopup: (options?: SignInOptions) => Promise<void>;
  signOut: (options?: SignOutOptions) => Promise<void>;
  getAccessToken: () => Promise<string | null>;
  getIdToken: () => Promise<string | null>;
  refreshTokens: () => Promise<void>;
}

Example:


function MyComponent() {
  const { user, isAuthenticated, signIn, signOut } = useZewstID();

  return (
    <div>
      {isAuthenticated ? (
        <>
          <p>Welcome {user?.name}</p>
          <button onClick={() => signOut()}>Sign out</button>
        </>
      ) : (
        <button onClick={() => signIn()}>Sign in</button>
      )}
    </div>
  );
}

`useUser()`

Get current user (shorthand).


const user = useUser();

`useAuth()`

Get authentication status.


const { isAuthenticated, isLoading, error } = useAuth();

`useAccessToken()`

Get access token for API calls.


const getAccessToken = useAccessToken();

async function callAPI() {
  const token = await getAccessToken();
  const response = await fetch('/api/data', {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  });
}

`<RequireAuth>`

Component that requires authentication.

Props:


interface RequireAuthProps {
  children: ReactNode;
  loadingComponent?: ReactNode;
  fallbackComponent?: ReactNode;
  redirectToSignIn?: boolean;  // Default: true
  returnTo?: string;
}

Example:


import { RequireAuth } from '@zewstid/react';

function ProtectedPage() {
  return (
    <RequireAuth
      loadingComponent={<div>Loading...</div>}
      fallbackComponent={<div>Please sign in</div>}
    >
      <Dashboard />
    </RequireAuth>
  );
}

`<WithAuth>`

Render prop component for conditional rendering.

Example:


import { WithAuth } from '@zewstid/react';

function MyComponent() {
  return (
    <WithAuth>
      {({ isAuthenticated, user, signIn, signOut }) => (
        isAuthenticated ? (
          <div>
            <p>Welcome {user?.name}</p>
            <button onClick={signOut}>Sign out</button>
          </div>
        ) : (
          <button onClick={signIn}>Sign in</button>
        )
      )}
    </WithAuth>
  );
}

Advanced Usage

Instead of redirect-based authentication, use popup:


function SignInButton() {
  const { signInWithPopup } = useZewstID();

  return (
    <button onClick={() => signInWithPopup()}>
      Sign in with Popup
    </button>
  );
}

Pass additional parameters to the authorization endpoint:


signIn({
  extraParams: {
    prompt: 'login',
    ui_locales: 'en',
  }
});

Manual Token Refresh


const { refreshTokens } = useZewstID();

// Manually refresh tokens
await refreshTokens();

Access Token for API Calls


import { useAccessToken } from '@zewstid/react';

function DataFetcher() {
  const getAccessToken = useAccessToken();

  async function fetchData() {
    const token = await getAccessToken();

    const response = await fetch('https://api.example.com/data', {
      headers: {
        'Authorization': `Bearer ${token}`,
      },
    });

    return response.json();
  }

  // ... rest of component
}

Role-Based Access Control


function AdminPanel() {
  const { user } = useUser();

  if (!user?.roles?.includes('admin')) {
    return <div>Access denied. Admin role required.</div>;
  }

  return <div>Admin Dashboard</div>;
}

Auth State Changes


<ZewstIDProvider
  config={{ /* ... */ }}
  onAuthStateChange={(user) => {
    if (user) {
      console.log('User signed in:', user);
      // Track analytics, update app state, etc.
    } else {
      console.log('User signed out');
    }
  }}
>
  <App />
</ZewstIDProvider>

React Router Integration

With React Router v6


import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
import { RequireAuth } from '@zewstid/react';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/callback" element={<Callback />} />
        <Route
          path="/dashboard"
          element={
            <RequireAuth>
              <Dashboard />
            </RequireAuth>
          }
        />
      </Routes>
    </BrowserRouter>
  );
}

Protected Route Component


import { Navigate } from 'react-router-dom';
import { useAuth } from '@zewstid/react';

function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { isAuthenticated, isLoading } = useAuth();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (!isAuthenticated) {
    return <Navigate to="/login" replace />;
  }

  return <>{children}</>;
}

TypeScript

Full TypeScript support included.


import type {
  ZewstIDUser,
  ZewstIDConfig,
  ZewstIDContextValue,
  SignInOptions,
  SignOutOptions,
} from '@zewstid/react';

Environment Variables

Create a

.env

file:


REACT_APP_ZEWSTID_CLIENT_ID=your_client_id_here
REACT_APP_ZEWSTID_REDIRECT_URI=http://localhost:3000/callback

Examples

FAQ

Q: Does this work with Create React App? A: Yes! Works with CRA, Vite, and any React setup.

Q: Can I use this with React Native? A: No, use

@zewstid/react-native

for mobile apps.

Q: How do I handle token expiration? A: The SDK automatically refreshes tokens when

automaticSilentRenew

is enabled (default).

Q: Can I customize the redirect URI? A: Yes, set it in the config. Make sure it matches your ZewstID dashboard settings.

Support

License

Proprietary and Confidential

This software is proprietary and confidential. Unauthorized distribution or use is prohibited.

Was this page helpful?

Let us know how we can improve our documentation

@zewstid/react

✨ Features

Authentication Methods (v0.1.0)

Developer Experience

🚀 Installation

Quick Start

1. Wrap Your App with Provider

2. Use Authentication in Components

3. Create a Callback Page

API Reference

Copy<ZewstIDProvider>

CopyuseZewstID()

CopyuseUser()

CopyuseAuth()

CopyuseAccessToken()

Copy<RequireAuth>

Copy<WithAuth>

Advanced Usage

Popup-Based Sign In

Custom Sign In Parameters

Manual Token Refresh

Access Token for API Calls

Role-Based Access Control

Auth State Changes

React Router Integration

With React Router v6

Protected Route Component

TypeScript

Environment Variables

Examples

FAQ

Support

License

Was this page helpful?

`<ZewstIDProvider>`

`useZewstID()`

`useUser()`

`useAuth()`

`useAccessToken()`

`<RequireAuth>`

`<WithAuth>`