react-allauth

What this skill does

## 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:

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

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

```bash
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:

```bash
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:

```bash
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:

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

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

```jsx
<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:
```jsx
import { API_BASE_URL } from '../../config/api'
```

Then update the API endpoint path from:
```jsx
`/_allauth/${Client.BROWSER}/v1`
```

To:
```jsx
`${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:
```jsx
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:

```bash
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:
```jsx
import { AuthChangeRedirector, AnonymousRoute, AuthenticatedRoute } from './auth'
```

To:
```jsx
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:
```jsx
import Login from './account/Login'
import Signup from './account/Signup'
// ... etc
```

To:
```jsx
import Login from '../user_management/account/Login'
import Signup from '../user_management/account/Signup'
// ... etc
```

Update the `Root` import:
```jsx
import Root from '../layouts/Root'
```

Update the `useConfig` import:
```jsx
import { useConfig } from '../user_management/auth/hooks'
```

**File:** `frontend/src/router/AppRoutes.jsx`

Import and integrate authentication routes into `createAppRouter`:

```jsx
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:
```jsx
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:
```jsx
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:
```jsx
callback_url: window.location.protocol + '//' + window.location.host + callbackURL,
```

To:
```jsx
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:
```js
'/_allauth': {
  target: 'https://localhost:8000',
  changeOrigin: true,
  secure: false,  // Allow self-signed certificates
},
```

**Expected result:**
```js
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:

```jsx
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=