react-use-auth

2.1.0-14 verified Sat May 09 auth: no javascript

React hook for adding authentication to apps with minimal setup. Current stable version 2.0.0 (August 2021) with 2.1.0-14 as prerelease. Supports Auth0, Netlify Identity, and Firebase. Key differentiator: uses XState state machine under the hood, handles SSR, and provides a declarative AuthConfig component. Release cadence is irregular; v2 introduced provider-specific imports to reduce bundle size. Peer dependencies must be installed separately (auth0-js, netlify-identity-widget, or firebase). Ships TypeScript definitions.

Common errors

error useAuth is not a function or its return value is not iterable ↓

cause Incorrect import path for useAuth; likely imported as default export but library only exports named.

fix

Use import { useAuth } from 'react-use-auth' (named import).

error Cannot find module 'react-use-auth/auth0' ↓

cause v2+ requires provider-specific subpaths; v1 did not have them.

fix

Upgrade to v2 and change imports to 'react-use-auth/auth0' or downgrade to v1 (not recommended).

error authProvider is not a constructor ↓

cause Passing a string or default import instead of the class/constructor from provider subpath.

fix

Use import { Auth0 } from 'react-use-auth/auth0' and pass Auth0 (the imported class) to AuthConfig.

Warnings

breaking v2.0.0 changed import paths: Auth0 must be imported from 'react-use-auth/auth0' instead of 'react-use-auth'. This breaks all v1 imports. ↓

fix Update imports to provider-specific subpaths, e.g., import { Auth0 } from 'react-use-auth/auth0'.

deprecated AuthProvider component was renamed to AuthConfig in v1.0.0 and removed in v2. ↓

fix Replace AuthProvider with AuthConfig in all JSX.

deprecated Authentication provider peer dependencies (auth0-js, netlify-identity-widget, firebase, firebaseui) are not installed automatically. You must install one manually. ↓

fix Run 'yarn add auth0-js' (or netlify-identity-widget, firebase) as appropriate.

gotcha The authProvider param in AuthConfig expects a constructor function, not a module. Passing the wrong type may cause errors like 'authProvider is not a constructor'. ↓

fix Ensure the import provides a class/constructor: import { Auth0 } from 'react-use-auth/auth0' and pass Auth0 (not a string or object).

gotcha useAuth() must be called inside a component wrapped with AuthConfig (or at least rendered after AuthConfig). Otherwise, it throws because the XState machine hasn't started. ↓

fix Place AuthConfig at a high level (e.g., _app.js or gatsby-browser.js) to ensure it renders before any useAuth calls.

Install

npm install react-use-auth

yarn add react-use-auth

pnpm add react-use-auth

Imports

useAuth

wrong

const useAuth = require('react-use-auth')

correct

import { useAuth } from 'react-use-auth'

Default export is not available; ESM only.

AuthProvider
wrong
```
import { AuthProvider } from 'react-use-auth'
```
correct
```
import { AuthConfig } from 'react-use-auth'
```
AuthProvider was renamed to AuthConfig in v1.0.0. Deprecated and removed in v2.
Auth0
wrong
```
import { Auth0 } from 'react-use-auth'
```
correct
```
import { Auth0 } from 'react-use-auth/auth0'
```
Provider-specific imports were introduced in v2.0.0 to enable tree-shaking. Must import from subpath.

NetlifyIdentity

wrong

import { NetlifyIdentity } from 'react-use-auth'

correct

import { NetlifyIdentity } from 'react-use-auth/netlify-identity'

Same as Auth0; provider-specific import path required in v2.

Quickstart

Complete setup of Auth0 with useAuth: configures AuthProvider, provides login/logout, and displays user info.

// App.tsx
import * as React from 'react';
import { useAuth, AuthConfig } from 'react-use-auth';
import { Auth0 } from 'react-use-auth/auth0';

const navigate = (to: string) => window.location.assign(to);

function App() {
  const { isAuthenticated, login, logout, user } = useAuth();
  return (
    <div>
      <AuthConfig
        navigate={navigate}
        authProvider={Auth0}
        params={{ domain: process.env.AUTH0_DOMAIN ?? 'example.auth0.com', clientID: process.env.AUTH0_CLIENT_ID ?? '' }}
      />
      {isAuthenticated ? (
        <div>Hello {user?.name}! <button onClick={logout}>Log out</button></div>
      ) : (
        <button onClick={login}>Log in</button>
      )}
    </div>
  );
}

export default App;