Xadmin Auth

3.3.4 verified Mon Apr 27 auth: no javascript

Xadmin Auth is the authentication module for the Xadmin ecosystem (v3.3.4), providing user login, logout, permission checks, and session management for React applications. It integrates tightly with xadmin-model and xadmin-form v3, requires react-router-dom v6 for routing, and lodash for utilities. Designed for admin panels, it offers higher-level auth components and hooks compared to raw auth libraries. Release cadence is irregular but semver-compliant. Key differentiator: seamless with Xadmin UI framework; standalone use is not recommended without adjacent xadmin packages.

Common errors

error Module not found: Can't resolve 'xadmin-auth' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install xadmin-auth' or 'yarn add xadmin-auth'.

error TypeError: Cannot destructure property 'login' of '(0 , ...)' as it is undefined. ↓

cause useAuth hook called outside of AuthProvider.

fix

Ensure component is inside <AuthProvider>.

error Warning: React.createElement: type is invalid -- expected a string (for built-in components) or a class/function but got: object. ↓

cause Importing a default export when only named exports exist (e.g., import AuthProvider from 'xadmin-auth').

fix

Use named import: import { AuthProvider } from 'xadmin-auth'.

Warnings

breaking v3 drops CommonJS support; only ES modules are provided. ↓

fix Ensure your project uses ESM (type: module in package.json) and uses import statements.

breaking v3 restructured exports; 'authenticated' HOC replaced by 'withAuth' and 'AuthProvider' is now required. ↓

fix Wrap app in <AuthProvider> and replace 'authenticated' with 'withAuth(Component)'.

deprecated The 'signOut' method in useAuth is deprecated in favor of 'logout'. ↓

fix Replace signOut() calls with logout().

gotcha AuthProvider and useAuth must be used within an Xadmin component tree. ↓

fix Wrap your app with <Xadmin> before <AuthProvider>.

gotcha The 'login' method expects FormData-like structure; passing plain objects may fail. ↓

fix Use FormData or ensure object has 'username' and 'password' fields as per API expectations.

Install

npm install xadmin-auth

yarn add xadmin-auth

pnpm add xadmin-auth

Imports

AuthProvider

wrong

const AuthProvider = require('xadmin-auth')

correct

import { AuthProvider } from 'xadmin-auth'

ESM-only package since v3; CommonJS require will fail.

useAuth

wrong

import useAuth from 'xadmin-auth'

correct

import { useAuth } from 'xadmin-auth'

Named export, not default export.

withAuth
wrong
```
import { withAuth } from 'xadmin-auth/withAuth'
```
correct
```
import { withAuth } from 'xadmin-auth'
```
Import directly from package root; subpaths may break in future versions.

Quickstart

Shows setup of AuthProvider and useAuth hook with a basic login form.

import React from 'react';
import { AuthProvider, useAuth } from 'xadmin-auth';
import { Xadmin } from 'xadmin';

function LoginPage() {
  const { login } = useAuth();
  const handleSubmit = async (e) => {
    e.preventDefault();
    const form = new FormData(e.target);
    try {
      await login(form.get('username'), form.get('password'));
      alert('Logged in!');
    } catch (err) {
      alert('Login failed: ' + err.message);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="username" placeholder="Username" />
      <input name="password" type="password" placeholder="Password" />
      <button type="submit">Log In</button>
    </form>
  );
}

function App() {
  return (
    <Xadmin>
      <AuthProvider>
        <LoginPage />
      </AuthProvider>
    </Xadmin>
  );
}

export default App;