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

React Allauth Skill (Frontend)

Plug google/django-allauth headless authentication flows into a Vite React app: copies the React SPA example modules, wires auth context/routes, fixes provider URLs, adds proxying, and provides Playwright tests and styling references.

What This Skill Provides

• Copies allauth React SPA modules into frontend/src/user_management/, renames to .jsx, and integrates auth routes with your existing router.
• Configures API base URLs, CSRF handling, and social callback URLs to point at the Django backend (/_allauth/...).
• Adds Vite proxy rules for /_allauth (and expects existing /api proxy) to https://localhost:8000 with self-signed certs.
• Wraps the app in AuthContextProvider, adds auth-aware nav, and removes demo routes (e.g., /calculator).
• Supports multi-step flows (email verification, passkeys) with pending-flow redirects.
• Bundles Playwright end-to-end tests for signup/login/logout/code-login/password-reset.
• Includes a styling reference listing all 35 auth components needing UI polish.

Prerequisites

• React + Vite frontend already set up (see react-setup skill).
• Django backend with django-allauth headless enabled and HTTPS at https://localhost:8000.
• mkcert-based HTTPS for frontend (https://localhost:5173).
• React Router in use; API config exporting API_BASE_URL.

Setup Summary (see SKILL.md for line-by-line edits)

1. Clone & copy example modules from django-allauth/examples/react-spa/frontend/src into frontend/src/user_management/ (files renamed .jsx).
2. Install dependency: npm --prefix ./frontend install @github/webauthn-json.
3. App wrapper: wrap your app in <AuthContextProvider> in frontend/src/App.jsx.
4. API base URL: in user_management/lib/allauth.jsx, import API_BASE_URL and prefix /_allauth/${Client.BROWSER}/v1 with it.
5. Routes: create frontend/src/router/AuthRouter.jsx exposing createAuthRoutes(config); merge into createAppRouter alongside your existing routes. Remove demo /calculator route.
6. Redirects: set LOGIN_REDIRECT_URL = '/'; update password-change/other redirects from /calculator to your desired path (default dashboard/home).
7. Social callback fix: set callback_url: callbackURL in redirectToProvider so backend URL is respected.
8. Vite proxy: add /_allauth proxy to vite.config.js targeting backend with secure:false.
9. Auth-aware nav: surface Login/Logout links conditioned on useAuthStatus (navbar or Home fallback).
10. Flow handling: add pending-flow redirects in signup/passkey/email verification and AuthChangeRedirector.
11. Styling reference: copy references/styling-guide.md to project root as react-allauth-styling-reference.md for later UI work.
12. Tests: run Playwright suite in scripts/test_auth_flows.py (requires backend + frontend running, pytest<9, playwright+chromium).

Outputs/Artifacts

• Auth modules under frontend/src/user_management/ wired to your router.
• Vite proxy updated for /_allauth.
• Auth context wrapping App.
• Optional styling reference file in project root.
• Playwright E2E tests ready to validate flows.

Notes & Gotchas

• Backend must expose headless endpoints at /_allauth/... and serve email links pointing to the frontend (e.g., https://localhost:5173).
• Keep AUTH flows on HTTPS; proxy uses secure:false to accept mkcert certs.
• Tests expect email backend to write files to sent_emails/; adjust if using SMTP.
• If renaming frontend host/port, update API_BASE_URL, email links, and test selectors accordingly.