Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createAuthProvider
✓ import { createAuthProvider } from 'react-token-auth';
✗ const { createAuthProvider } = require('react-token-auth');
Primarily designed for ESM and TypeScript; CommonJS require() pattern is incorrect for modern usage.
useAuth
✓ import { useAuth } from 'react-token-auth';
Destructured from the return value of `createAuthProvider` but typically imported directly for convenience.
login
✓ import { login } from 'react-token-auth';
Similarly, `login`, `logout`, and `authFetch` are exposed directly for module-level usage after `createAuthProvider` is called.
This quickstart demonstrates the core functionality: initializing the auth provider, implementing login/logout, using the `useAuth` hook for conditional rendering, and making authenticated API calls with `authFetch`.
import { createAuthProvider } from 'react-token-auth';
import React, { FormEvent, useEffect } from 'react';
import { BrowserRouter, Switch, Route, Redirect } from 'react-router-dom'; // Assuming react-router-dom for routing context
// Define the shape of your session object
type Session = { accessToken: string; refreshToken: string };
// 1. Create the auth provider instance
export const { useAuth, authFetch, login, logout } = createAuthProvider<Session>({
getAccessToken: session => session.accessToken,
// Use localStorage for web applications. Ensure it's available (e.g., client-side).
storage: typeof window !== 'undefined' ? localStorage : undefined,
onUpdateToken: async (token: { refreshToken: string }) => {
// This function is called when the accessToken needs to be refreshed.
// It must return a new session object { accessToken: string; refreshToken: string }
try {
const response = await fetch('/update-token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ refreshToken: token.refreshToken }),
});
if (!response.ok) {
const errorData = await response.json();
console.error('Token refresh failed:', errorData);
throw new Error('Failed to refresh token');
}
return response.json();
} catch (error) {
console.error('Network or server error during token refresh:', error);
throw error;
}
},
// Optional: Callback when a session is loaded from storage (hydration)
onHydratation: session => {
console.log('Session hydrated:', session);
},
});
// A dummy component for registration
const Register = () => <div>Register Page</div>;
// 2. Example Login Component
const Login = () => {
const onSubmit = async (e: FormEvent) => {
e.preventDefault();
// Simulate a login API call
try {
const response = await fetch('/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username: 'testuser', password: 'password' }), // Replace with actual credentials
});
if (!response.ok) {
const errorData = await response.json();
console.error('Login failed:', errorData);
alert('Login failed!');
return;
}
const session = await response.json();
login(session); // Save the new session
alert('Logged in successfully!');
} catch (error) {
console.error('Network error during login:', error);
alert('Network error during login!');
}
};
return (
<form onSubmit={onSubmit}>
<h2>Login</h2>
<input type="text" placeholder="Username" />
<input type="password" placeholder="Password" />
<button type="submit">Login</button>
</form>
);
};
// A dummy dashboard component
const Dashboard = () => {
const handleLogout = () => {
logout();
alert('Logged out!');
};
// Example of using authFetch to make authenticated requests
const fetchData = async () => {
try {
const response = await authFetch('/api/protected-data');
const data = await response.json();
console.log('Protected data:', data);
alert('Fetched protected data: ' + JSON.stringify(data));
} catch (error) {
console.error('Failed to fetch protected data:', error);
alert('Failed to fetch protected data. Maybe token expired or invalid.');
}
};
return (
<div>
<h2>Dashboard</h2>
<button onClick={handleLogout}>Logout</button>
<button onClick={fetchData}>Fetch Protected Data</button>
</div>
);
};
// 3. Main Router component using useAuth hook to manage routing based on auth state
const AppRouter = () => {
const [logged, session] = useAuth(); // Get current auth state
useEffect(() => {
console.log('Auth state changed:', logged, session);
}, [logged, session]);
return (
<BrowserRouter>
<Switch>
{!logged ? (
<>
<Route path="/register" component={Register} />
<Route path="/login" component={Login} />
<Redirect to="/login" />
</>
) : (
<>
<Route path="/dashboard" component={Dashboard} exact />
<Redirect to="/dashboard" />
</>
)}
</Switch>
</BrowserRouter>
);
};
// To run this example in a real React app, you would render <AppRouter /> in your ReactDOM.render()
// For demonstration purposes, we omit the ReactDOM.render() call.
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'accessToken')
The `getAccessToken` property in `createAuthProvider` is misconfigured, or the session object passed to `login` is `null`/`undefined` or lacks the expected `accessToken` field.
fixVerify that your `Session` type correctly matches the structure of tokens returned by your backend and that `getAccessToken` accurately points to the access token. Ensure `login()` is called with a valid session object.
Uncaught (in promise) TypeError: Failed to fetch
A network request initiated by `onUpdateToken`, `login`, `logout`, or `authFetch` failed due to network connectivity issues, incorrect URL, CORS policies, or an unreachable server.
fixCheck your network connection and server status. Verify the URLs used in `fetch` calls. Ensure your server correctly handles CORS preflight requests and has the expected endpoints (`/login`, `/update-token`, etc.).
ReferenceError: localStorage is not defined
The library is configured to use `localStorage` but is being run in a server-side rendering (SSR) environment or React Native without a compatible storage shim.
fixWhen using `react-token-auth` in SSR or React Native, provide a custom `storage` implementation to `createAuthProvider` that defers to `localStorage` only on the client or uses an appropriate async storage solution.
RangeError: Maximum call stack size exceeded
Often indicative of an infinite loop within the token refresh logic. This can happen if `onUpdateToken` repeatedly fails in a way that triggers itself again without a circuit breaker or proper error exit.
fixReview the `onUpdateToken` implementation to ensure it has robust error handling and a clear exit strategy for persistent failures, preventing recursive calls without resolution. Implement safeguards like retry limits.
Audit
Dependencies
No dependency data recorded yet.