allauth-js

Common JS functions, React hooks and components for django-allauth headless mode.

Build authentication flows in JS/React/Next.js applications backed by django-allauth's battle-tested authentication system.

Features:

• Common JS functions for interacting with allauth's headless API
• Fully typed library
• React hooks for auth state, user data, emails, and sessions
• Route guards for protected and anonymous pages
• Full support for email/password, passwordless, and social auth
• Pre-built UI components with Tailwind CSS styling
• Fully customisable - start with pre-built then copy the components out to customise or build your own.

Installation

npm install @octue/allauth-js
# or
pnpm add @octue/allauth-js

Peer dependencies: React 18+ (for react hooks and components), Next.js 15+ (for route guards)

TypeScript Configuration

This library supports all modern TypeScript moduleResolution settings:

| Setting | Support | |---------|---------| | bundler | Recommended for Vite, Next.js, and modern bundlers | | node16 / nodenext | Full support | | node (legacy) | Supported via typesVersions fallback |

If you're starting a new project, we recommend using moduleResolution: "bundler" in your tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

Quick Start

1. Wrap your app with AuthContextProviderand AuthChangeRedirector

// pages/_app.tsx or app/layout.tsx
import { AuthContextProvider } from '@octue/allauth-js/react'
// If not using nextjs, you'll need to supply an equivalent to
// AuthChangeRedirector that works with your routing solution...
// Check the code, it's not too hard.
import { AuthChangeRedirector } from '@octue/allauth-js/nextjs'

export default function App({ Component, pageProps }) {
  return (
    <AuthContextProvider
      urls={{
        login: '/login',
        loginRedirect: '/dashboard',
        logoutRedirect: '/',
      }}
    >
      <AuthChangeRedirector>
        <Component {...pageProps} />
      </AuthChangeRedirector>
    </AuthContextProvider>
  )
}

2. Set up styling

Option A: Tailwind CSS (recommended)

Add the library to your Tailwind content paths and set the allauth color scale to match your branding:

/* Tailwind v4 - globals.css */
@import "tailwindcss";
@source "../node_modules/@octue/allauth-js/dist/**/*.{js,mjs}";

@theme inline {
  --color-allauth-50: #F1CFDA;
  --color-allauth-100: #ECBFCE;
  --color-allauth-200: #E2A0B6;
  --color-allauth-300: #D9819E;
  --color-allauth-400: #CF6186;
  --color-allauth-500: #C6426E;
  --color-allauth-600: #A03055;
  --color-allauth-700: #75233E;
  --color-allauth-800: #4A1627;
  --color-allauth-900: #1E0910;
  --color-allauth-950: #090305;
}

For Tailwind v3, use the preset:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,tsx}',
    './node_modules/@octue/allauth-js/dist/**/*.{js,mjs}',
  ],
  presets: [require('@octue/allauth-js/tailwind-preset')],
}

Option B: Pre-compiled CSS

If you're not using Tailwind, import (or redefine yourself) the pre-compiled styles:

import '@octue/allauth-js/styles.css'

3. Use hooks and components

import { useUser, useAuthStatus } from '@octue/allauth-js/react'
import { login, logout } from '@octue/allauth-js/core'

function Profile() {
  const { isAuthenticated } = useAuthStatus()
  const { user, loading } = useUser()

  if (!isAuthenticated) {
    return <button onClick={() => login({ email, password })}>Log in</button>
  }

  if (loading) return <div>Loading user details...</div>

  return (
    <div>
      <p>Welcome, {user?.email}</p>
      <button onClick={logout}>Log out</button>
    </div>
  )
}

Usage Examples

Login Form

import { useForm } from 'react-hook-form'
import { login } from '@octue/allauth-js/core'
import { Button, useSetErrors } from '@octue/allauth-js/react'
import { AnonymousRoute } from '@octue/allauth-js/nextjs'

function LoginForm() {
  const { register, handleSubmit, setError, formState: { errors, isSubmitting } } = useForm()
  const setErrors = useSetErrors(setError)

  const onSubmit = (data) => {
    login(data).then(setErrors)
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email')} type="email" placeholder="Email" />
      <input {...register('password')} type="password" placeholder="Password" />
      <Button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Logging in...' : 'Log in'}
      </Button>
    </form>
  )
}

// Wrap with AnonymousRoute to redirect authenticated users
export default function LoginPage() {
  return (
    <AnonymousRoute>
      <LoginForm />
    </AnonymousRoute>
  )
}

Protected Route

import { AuthenticatedRoute } from '@octue/allauth-js/nextjs'
import { useUser } from '@octue/allauth-js/react'

function DashboardContent() {
  const { user } = useUser()
  return <h1>Welcome back, {user?.email}</h1>
}

export default function Dashboard() {
  return (
    <AuthenticatedRoute>
      <DashboardContent />
    </AuthenticatedRoute>
  )
}

Email & Session Management

import { useEmails, useSessions, EmailsTable, SessionsTable } from '@octue/allauth-js/react'
import { AuthenticatedRoute } from '@octue/allauth-js/nextjs'

function SettingsPage() {
  const { emails, add, remove, makePrimary, verify, loading: emailsLoading } = useEmails()
  const { currentSession, otherSessions, endSessions, trackActivity, loading: sessionsLoading } = useSessions()

  return (
    <div>
      <h2>Email Addresses</h2>
      <EmailsTable
        emails={emails}
        add={add}
        remove={remove}
        makePrimary={makePrimary}
        verify={verify}
        disabled={emailsLoading}
      />

      <h2>Active Sessions</h2>
      <SessionsTable
        currentSession={currentSession}
        otherSessions={otherSessions}
        endSessions={endSessions}
        trackActivity={trackActivity}
        disabled={sessionsLoading}
      />
    </div>
  )
}

export default function Settings() {
  return (
    <AuthenticatedRoute>
      <SettingsPage />
    </AuthenticatedRoute>
  )
}

API Reference

Hooks (@octue/allauth-js/react)

| Hook | Purpose | |------|---------| | useUser() | Get current user and loading state | | useAuthStatus() | Get auth status (isAuthenticated, isLoading, pendingFlow) | | useEmails() | Manage user email addresses | | useSessions() | Manage active sessions | | useConfig() | Get backend configuration | | useAuthChange() | Detect auth state changes | | useSetErrors() | Map API errors to react-hook-form |

Components (@octue/allauth-js/react)

| Component | Purpose | |-----------|---------| | AuthContextProvider | Wrap app to provide auth context | | Button | Styled button with color palettes | | EmailsTable | Email management table | | SessionsTable | Session management table | | EmailsTableSkeleton | Loading skeleton for emails | | SessionsTableSkeleton | Loading skeleton for sessions |

Core Functions (@octue/allauth-js/core)

| Function | Purpose | |----------|---------| | login(data) | Authenticate with email/password | | logout() | End current session | | signUp(data) | Create new account | | changePassword(data) | Change password | | requestPasswordReset(email) | Start password reset flow | | resetPassword(password, key) | Complete password reset | | requestLoginCode(email) | Request passwordless login code | | confirmLoginCode(code) | Confirm passwordless login | | getAuth() | Get current auth state |

Route Guards (@octue/allauth-js/nextjs)

| Component | Purpose | |-----------|---------| | AuthenticatedRoute | Redirect to login if not authenticated | | AnonymousRoute | Redirect to dashboard if already authenticated |

Development

Receiving emails in development

Note that the development backend is not set up to send you emails via a third party provider. Instead, it'll simply print the plain text emails to the console. **For testing the email verification

Running the Example App

The repository includes a full Next.js example with Django backend.

Prerequisites: Node.js 18+, pnpm, Python 3.11+, uv

# 1. Start the Django backend
cd examples/backend
./setup.sh
uv run python manage.py runserver

# 2. Start the Next.js frontend (new terminal)
cd examples/nextjs
pnpm install
pnpm dev

Open http://localhost:3000. Test credentials: username admin / password admin123

See examples/nextjs/README.md for detailed example documentation.

Storybook

Preview components in isolation:

pnpm install
pnpm storybook

Open http://localhost:6006 to view the component library.

License

allauth-js is GPLv3 licensed and completely free for open-source use on codebases with compliant licenses.

For commercial closed source use, we have a simple, low-cost, one-off payment perpetual license to help support the high cost of maintaining open-source software. Go through the payment process and we'll send a filled out license.

For other license options (eg you want to redistribute or use in open-source but non GPL-compatible projects) please contact us.