gh-otoshek-claude-code-toolkit/skills/react-allauth/SKILL.md

name, description

name	description
react-allauth	Configure React frontend with django-allauth headless API integration, including authentication UI, auth state management, protected routes, and social authentication flows

Purpose

Configure a React frontend application to integrate with django-allauth's headless API, enabling complete authentication workflows including signup, login, email verification, password reset, and social authentication. This skill handles the entire setup process from copying authentication modules to validating flows with automated testing.

Prerequisites

Before starting this configuration, ensure the following requirements are met:

• React project with Vite - A React frontend application initialized with Vite
• Django backend with django-allauth - Django backend configured with django-allauth headless API (in settings.py - Look for allauth in INSTALLED_APPS)
• HTTPS development environment - Both frontend and backend running over HTTPS (mkcert recommended for local SSL certificates)
• React Router - Project uses react-router-dom for routing
• API configuration - An API_BASE_URL constant exported from a config file (typically src/config/api.js or src/config/api.jsx)
• Project structure - Frontend source code located in frontend/src/ with standard Vite directory structure

Steps Overview

1. Clone Repository and Copy Authentication Modules
2. Install Required Dependencies
3. Update App.jsx to Include Authentication Context
4. Configure API Base URL in allauth.jsx
5. Update Redirect URLs
6. Copy Authentication Router and Integrate Routes
7. Fix Social Authentication Callback URL
8. Configure Vite Proxy for Authentication Endpoints
9. Add Auth-Aware Navigation Link
10. Enable Flow-Based Signup Navigation
11. Validate Authentication Flows with Automated Testing
12. Copy Styling Reference Guide
13. Stop Background Tasks

---

Step 1: Clone Repository and Copy Authentication Modules

Clone the django-allauth repository at the project root:

git clone https://github.com/pennersr/django-allauth

Refactor authentication components by renaming .js files to .jsx:

find django-allauth/examples/react-spa/frontend/src/ -name "*.js" -exec bash -c 'mv "$0" "${0%.js}.jsx"' {} \;

Copy the authentication modules into the React project:

mkdir -p frontend/src/user_management
find django-allauth/examples/react-spa/frontend/src/ -mindepth 1 -maxdepth 1 -type d -exec cp -r {} frontend/src/user_management/ \;

This creates a user_management directory in the React project and copies all authentication-related folders from the cloned repository. The django-allauth/ directory remains available for later steps in this skill.

---

Step 2: Install Required Dependencies

Install the WebAuthn dependency required by the authentication modules:

npm --prefix ./frontend install @github/webauthn-json

---

Step 3: Update App.jsx to Include Authentication Context

File: frontend/src/App.jsx

Import the AuthContextProvider and wrap the app's content with it:

import { AuthContextProvider } from './user_management/auth'

Wrap the existing app content (typically the router) with <AuthContextProvider>:

<AuthContextProvider>
  {/* Existing app content */}
</AuthContextProvider>

---

Step 4: Configure API Base URL in allauth.jsx

File: frontend/src/user_management/lib/allauth.jsx

After the getCSRFToken import, add:

import { API_BASE_URL } from '../../config/api'

Then update the API endpoint path from:

`/_allauth/${Client.BROWSER}/v1`

To:

`${API_BASE_URL}/_allauth/${Client.BROWSER}/v1`

---

Step 5: Update Redirect URLs

Update redirect paths from /calculator to /dashboard:

File: frontend/src/user_management/auth/routing.jsx

Change the LOGIN_REDIRECT_URL path to:

LOGIN_REDIRECT_URL: '/'

File: frontend/src/user_management/account/ChangePassword.jsx

Replace any occurrence of '/calculator' with '/dashboard'

---

Step 6: Copy Authentication Router and Integrate Routes

Copy the authentication router file and clean up the cloned repository:

cp django-allauth/examples/react-spa/frontend/src/Router.jsx frontend/src/router/AuthRouter.jsx && rm -rf django-allauth

File: frontend/src/router/AuthRouter.jsx

Update all import paths to use the user_management directory:

Change:

import { AuthChangeRedirector, AnonymousRoute, AuthenticatedRoute } from './auth'

To:

import { AuthChangeRedirector, AnonymousRoute, AuthenticatedRoute } from '../user_management/auth'

Update all component imports (like Login, Signup, ChangeEmail, etc.) from relative paths to use user_management:

Change:

import Login from './account/Login'
import Signup from './account/Signup'
// ... etc

To:

import Login from '../user_management/account/Login'
import Signup from '../user_management/account/Signup'
// ... etc

Update the Root import:

import Root from '../layouts/Root'

Update the useConfig import:

import { useConfig } from '../user_management/auth/hooks'

File: frontend/src/router/AppRoutes.jsx

Import and integrate authentication routes into createAppRouter:

import Root from "../layouts/Root";
import Home from "../pages/Home";
import { createAuthRoutes } from './AuthRouter';

export function createAppRouter(config) {
  const authRoutes = createAuthRoutes(config);

  return [
    {
      path: "/",
      element: <Root />,
      children: [
        {
          path: "/",
          element: <Home />,
        },
        ...authRoutes
      ],
    },
  ];
}

File: frontend/src/router/AuthRouter.jsx

Rename the exported function and export the routes array:

Change:

function createRouter (config) {
  return createBrowserRouter([
    {
      path: '/',
      element: <AuthChangeRedirector><Root /></AuthChangeRedirector>,
      children: [
        // ... routes
      ]
    }
  ])
}

export default function Router () {
  const [router, setRouter] = useState(null)
  const config = useConfig()
  useEffect(() => {
    setRouter(createRouter(config))
  }, [config])
  return router ? <RouterProvider router={router} /> : null
}

To:

export function createAuthRoutes (config) {
  return [
    // ... all the route objects from the children array
  ]
}

Remove the /calculator route as it's not needed.

---

Step 7: Fix Social Authentication Callback URL

File: frontend/src/user_management/lib/allauth.jsx

Find the redirectToProvider function and update the callback_url parameter.

Change:

callback_url: window.location.protocol + '//' + window.location.host + callbackURL,

To:

callback_url: callbackURL,

This configuration ensures social authentication callbacks use the correct backend URL instead of the frontend host.

---

Step 8: Configure Vite Proxy for Authentication Endpoints

File: frontend/vite.config.js

Add the /_allauth proxy configuration to forward authentication requests to the Django backend.

Add to the proxy object:

'/_allauth': {
  target: 'https://localhost:8000',
  changeOrigin: true,
  secure: false,  // Allow self-signed certificates
},

Expected result:

proxy: {
  '/api': {
    target: 'https://localhost:8000',
    changeOrigin: true,
    secure: false,
  },
  '/_allauth': {
    target: 'https://localhost:8000',
    changeOrigin: true,
    secure: false,
  },
}

---

Step 9: Add Auth-Aware Navigation Link

First, search the project to determine if a navbar or header component exists.

If a navbar component exists:

Import the auth status helper and toggle the navigation link based on whether the user is logged in:

import { useAuthStatus } from "@/user_management/auth";
import { Link } from "react-router-dom";

const [, authInfo] = useAuthStatus();

{authInfo.isAuthenticated ? (
  <Link to="/account/logout">
    <NavigationMenuLink className={navigationMenuTriggerStyle()}>
      Logout
    </NavigationMenuLink>
  </Link>
) : (
  <Link to="/account/login">
    <NavigationMenuLink className={navigationMenuTriggerStyle()}>
      Login
    </NavigationMenuLink>
  </Link>
)}

If NO navbar component exists:

Add auth-aware navigation links to the landing page.

File: frontend/src/pages/Home.jsx

Import the required dependencies at the top:

import { useAuthStatus } from "@/user_management/auth";
import { Link } from "react-router-dom";

Add the navigation links in the component JSX:

const [, authInfo] = useAuthStatus();

return (
  <div>
    <nav style={{ padding: '1rem', borderBottom: '1px solid #ccc' }}>
      {authInfo.isAuthenticated ? (
        <Link to="/account/logout" style={{ marginRight: '1rem' }}>
          Logout
        </Link>
      ) : (
        <Link to="/account/login" style={{ marginRight: '1rem' }}>
          Login
        </Link>
      )}
    </nav>
    {/* Rest of Home page content */}
  </div>
);

Note: Linking to /account/logout ensures authenticated users reach the confirmation screen before finalizing the logout. Anonymous visitors continue to see the Login link.

---

Step 10: Enable Flow-Based Signup Navigation

This step configures multi-step signup flows (like email verification + passkey creation) to navigate correctly between steps without intermediate redirects.

Step 10.1: Configure Signup Screens to Handle Pending Flows

Files:

• frontend/src/user_management/account/Signup.jsx
• frontend/src/user_management/mfa/SignupByPasskey.jsx

Add the following imports at the top of each signup component:

import { useEffect } from 'react'
import { useNavigate } from 'react-router-dom'
import { pathForFlow } from '../auth'

Inside each component, instantiate the navigate function:

const navigate = useNavigate()

Add a useEffect hook that watches for pending flows in the response:

useEffect(() => {
  if (response.content) {
    const pending = response.content?.data?.flows?.find(flow => flow.is_pending)
    if (pending) {
      navigate(pathForFlow(pending), { replace: true })
    }
  }
}, [response.content, navigate])

This configuration ensures users are redirected to the next step in the signup flow (e.g., email verification) without leaving the signup page in the history stack.

Step 10.2: Update Authentication Redirector for Pending Flows

File: frontend/src/user_management/auth/routing.jsx

Update the AuthChangeRedirector component to check for pending flows before redirecting to the default login redirect URL.

In the LOGGED_IN branch, add logic to call pathForPendingFlow(auth) before defaulting to LOGIN_REDIRECT_URL:

if (auth.status === AuthStatus.LOGGED_IN) {
  const pendingPath = pathForPendingFlow(auth)
  if (pendingPath) {
    navigate(pendingPath, { replace: true })
  } else {
    navigate(LOGIN_REDIRECT_URL, { replace: true })
  }
}

This logic prevents users from being redirected to the dashboard when pending authentication steps remain.

Step 10.3: Configure Email Verification to Handle Flows

File: frontend/src/user_management/account/VerifyEmailByCode.jsx

Replace the static <Navigate> component return with a useEffect hook that handles flow-based redirects.

Add the required imports:

import { useEffect } from 'react'
import { useNavigate } from 'react-router-dom'
import { pathForFlow } from '../auth'

Instantiate navigate:

const navigate = useNavigate()

Replace the <Navigate> return with a useEffect that redirects based on the response:

useEffect(() => {
  const content = response.content
  if (!content) {
    return
  }

  const flows = content.data?.flows
  if (flows?.length) {
    const pending = flows.find(flow => flow.is_pending)
    if (pending) {
      navigate(pathForFlow(pending), { replace: true })
      return
    }
  }

  if (content.status === 200) {
    navigate('/account/email', { replace: true })
  } else if (content.status === 401) {
    navigate('/account/login', { replace: true })
  }
}, [response.content, navigate])

This configuration ensures email verification redirects to the next pending flow step (e.g., passkey creation) or falls back to the appropriate default page.

---

Step 11: Validate Authentication Flows with Automated Testing

Run the comprehensive authentication flow test suite to validate the entire integration. This step confirms all authentication flows work correctly end-to-end.

Step 11.1: Install Testing Dependencies

Activate the Django virtual environment and install Playwright for browser automation testing:

source venv/bin/activate

# Install pytest only if missing
python -c "import pytest" 2>/dev/null || pip install 'pytest>=7.4,<9.0'

# Install playwright only if missing
python -c "import playwright" 2>/dev/null || pip install playwright

# Install chromium only if Playwright hasn't installed it yet
playwright show-browsers | grep -q "chromium" \
  || playwright install chromium

Step 11.2: Check and Start Servers, Then Run the Test Suite

Before running tests, verify both servers are running and start them if needed.

Check if backend is running on port 8000:

lsof -i :8000

If backend is not running, start it:

Activate the virtual environment, and run the startup script in the background:

source venv/bin/activate && \
uvicorn backend.asgi:application \
  --host 127.0.0.1 \
  --port 8000 \
  --ssl-keyfile ./certs/localhost+2-key.pem \
  --ssl-certfile ./certs/localhost+2.pem

Check if frontend is running on port 5173:

lsof -i :5173

If frontend is not running, start it:

Start the development server in the background:

npm --prefix ./frontend run dev

Wait for servers to be ready:

Allow a few seconds for both servers to fully initialize before proceeding with tests.

Execute the test suite:

From the Django project root with the virtual environment activated: Activate the virtual environment source venv/bin/activate and run the test script at: scripts/test_auth_flows.py

The test suite includes:

1. test_01_signup - User signup flow validation
2. test_02_email_verification - Email verification workflow
3. test_03_password_login - Password-based authentication
4. test_04_logout - Logout functionality
5. test_05_code_login - Passwordless code-based login
6. test_06_password_reset - Password reset workflow

Prerequisites for testing:

• Django backend running on https://localhost:8000
• React frontend running on https://localhost:5173
• Email backend configured to save emails to sent_emails/ directory
• Clean database state (tests create unique users with timestamps)

Test execution:

• Tests run with visible browser (headless=False) for debugging
• Each test is independent and creates its own test user
• Tests clean up email files between runs
• Verbose output (verbosity=2) shows detailed test progress

Note: Tests run sequentially and may take several minutes to complete due to browser automation and wait times for email delivery.

---

Step 12: Copy Styling Reference Guide

Read the styling reference guide from the skill's bundled resources and write it to the project root for later use.

The styling guide is located at references/styling-guide.md within this skill's directory. Read this file and write its contents to react-allauth-styling-reference.md in the project root.

This file lists all 35 authentication components that require styling and can be referenced by styling skills. Delete this file after styling is complete.

---

Step 13: Stop Background Tasks

Terminate any background commands or servers started during the configuration process.