{"id":11821,"library":"react-oidc-context","title":"React OIDC Context","description":"react-oidc-context is a lightweight authentication library for React Single Page Applications (SPAs) that leverages the React Context API for state management, built on top of the `oidc-client-ts` library. The current stable version is 3.3.1. The package maintains a fairly active release cadence, with frequent bugfix and minor releases, and significant major versions introducing breaking changes as the underlying `oidc-client-ts` library evolves. It differentiates itself by providing convenient React hooks (`useAuth`) and Higher-Order Components (`withAuthenticationRequired`) to integrate OpenID Connect and OAuth2 authentication flows seamlessly into React components, handling aspects like token renewal and redirect callbacks without requiring manual route setup. It ships with full TypeScript support, making it suitable for modern React development.","status":"active","version":"3.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/authts/react-oidc-context","tags":["javascript","authentication","context-api","oauth2","oidc","openid","OpenID Connect","react-component","typescript"],"install":[{"cmd":"npm install react-oidc-context","lang":"bash","label":"npm"},{"cmd":"yarn add react-oidc-context","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-oidc-context","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core OpenID Connect client library that handles the OIDC protocol details.","package":"oidc-client-ts","optional":false},{"reason":"The core React library for building user interfaces.","package":"react","optional":false}],"imports":[{"note":"The library is ESM-only since v3.0.0. Use named imports for `AuthProvider` to wrap your React application.","wrong":"const { AuthProvider } = require('react-oidc-context');","symbol":"AuthProvider","correct":"import { AuthProvider } from 'react-oidc-context';"},{"note":"This hook provides access to the authentication state and methods within function components. The library ships with TypeScript types.","wrong":"const { useAuth } = require('react-oidc-context');","symbol":"useAuth","correct":"import { useAuth } from 'react-oidc-context';"},{"note":"A higher-order component (HOC) to secure routes or components by redirecting unauthenticated users to the login page. Introduced in v3.0.0-rc.0.","wrong":"const { withAuthenticationRequired } = require('react-oidc-context');","symbol":"withAuthenticationRequired","correct":"import { withAuthenticationRequired } from 'react-oidc-context';"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport { AuthProvider, useAuth } from 'react-oidc-context';\n\n// Your OIDC configuration\nconst oidcConfig = {\n  authority: 'https://your-identity-provider.com',\n  client_id: 'your-client-id',\n  redirect_uri: window.location.origin + '/authentication/callback',\n  onSigninCallback: () => {\n    // IMPORTANT: Clear URL payload upon successful login to prevent issues with silent renew\n    window.history.replaceState({}, document.title, window.location.pathname);\n  },\n  // automaticSilentRenew: true, // Enable automatic token renewal\n  // scope: 'openid profile email',\n  // ... other oidc-client-ts UserManagerSettings\n};\n\nfunction App() {\n    const auth = useAuth();\n\n    switch (auth.activeNavigator) {\n        case 'signinSilent':\n            return <div>Signing you in silently...</div>;\n        case 'signoutRedirect':\n            return <div>Signing you out...</div>;\n    }\n\n    if (auth.isLoading) {\n        return <div>Loading authentication status...</div>;\n    }\n\n    if (auth.error) {\n        return <div>Authentication error: {auth.error.message}</div>;\n    }\n\n    if (auth.isAuthenticated) {\n        return (\n        <div>\n            Hello, {auth.user?.profile.name || auth.user?.profile.sub}{' '}\n            <button onClick={() => void auth.removeUser()}>Log out locally</button>\n            <button onClick={() => void auth.signoutRedirect()}>Log out from IdP</button>\n        </div>\n        );\n    }\n\n    return (\n      <div>\n        <p>You are not authenticated.</p>\n        <button onClick={() => void auth.signinRedirect()}>Log in</button>\n      </div>\n    );\n}\n\nconst root = ReactDOM.createRoot(document.getElementById('root'));\nroot.render(\n  <React.StrictMode>\n    <AuthProvider {...oidcConfig}>\n      <App />\n    </AuthProvider>\n  </React.StrictMode>\n);\n","lang":"typescript","description":"This quickstart demonstrates how to set up `AuthProvider` to configure OpenID Connect and use the `useAuth` hook within a functional component to manage authentication state (loading, authenticated, user info) and trigger authentication actions like login and logout. It highlights the critical `onSigninCallback` for proper token renewal."},"warnings":[{"fix":"Ensure your Node.js environment is version 18 or higher. Update `oidc-client-ts` to a compatible v3.x version (`^3.1.0` or later).","message":"Version 3.0.0 introduced a breaking change by upgrading its peer dependency `oidc-client-ts` to v3.x. This change requires Node.js version >=18 and uses `crypto.subtle` instead of `crypto-js` for cryptographic operations.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always run your application under HTTPS, even during local development (e.g., via `mkcert` or a reverse proxy like `nginx`).","message":"Since v3.0.0, the library relies on the Web Cryptography API (`crypto.subtle`), which is only available in secure contexts (HTTPS). Running your application over plain HTTP will cause runtime errors related to undefined `crypto.subtle`.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Add an `onSigninCallback` to your `oidcConfig` that uses `window.history.replaceState({}, document.title, window.location.pathname);` to clean the URL.","message":"It is crucial to implement the `onSigninCallback` function within your `oidcConfig` to clear the OIDC payload from the URL upon successful login. Failure to do so will prevent `signinSilent` (automatic token renewal) from working correctly after a page refresh.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"Ensure your project is configured for ESM and use `import` statements for all `react-oidc-context` imports.","message":"The library transitioned to being an ESM-only module since v3.0.0. Direct `require()` statements for `react-oidc-context` will fail.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Serve your application over HTTPS. For local development, configure your server to use SSL/TLS or use a tool like `mkcert`.","cause":"The application is running in an insecure context (HTTP) where the Web Cryptography API (`crypto.subtle`) is not available.","error":"TypeError: crypto.subtle is undefined"},{"fix":"Implement the `onSigninCallback` function in your `oidcConfig` to clear the URL parameters, e.g., `onSigninCallback: () => { window.history.replaceState({}, document.title, window.location.pathname); }`.","cause":"The OIDC response payload remains in the URL after a successful login, preventing `oidc-client-ts` from correctly initiating silent renewals.","error":"Token renewal (signinSilent) is not working after a successful login and subsequent page refresh."},{"fix":"Update your import statements to use ESM `import` syntax (e.g., `import { AuthProvider } from 'react-oidc-context';`) and ensure your build configuration supports ESM.","cause":"Attempting to use CommonJS `require()` syntax to import `react-oidc-context`, which is an ESM-only module since version 3.0.0.","error":"Error: require() not supported for ESM module 'react-oidc-context'"}],"ecosystem":"npm"}