docs: add design spec for auth + React frontend
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
thibaud-leclere
201
docs/superpowers/specs/2026-03-28-auth-react-frontend-design.md
Normal file
201
docs/superpowers/specs/2026-03-28-auth-react-frontend-design.md
Normal file
@@ -0,0 +1,201 @@
|
|||||||
|
# Auth + React Frontend — Design Spec
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Actorle is a Symfony 8.0 word game (Wordle-like for actors) running on FrankenPHP with PostgreSQL. The app currently has no authentication and uses Asset Mapper with Stimulus for a minimal frontend. This spec covers adding user authentication and migrating to a React-based interactive frontend via SymfonyUX.
|
||||||
|
|
||||||
|
## Approach
|
||||||
|
|
||||||
|
**Hybrid Twig + React** (SymfonyUX React option 2):
|
||||||
|
- Symfony stays in control of routing, sessions, and page rendering via Twig
|
||||||
|
- Interactive parts (the game grid) are React components mounted in Twig via `{{ react_component() }}`
|
||||||
|
- Auth pages (login, register) remain pure Twig — no benefit from React here
|
||||||
|
|
||||||
|
## 1. Frontend Migration: Asset Mapper to Vite
|
||||||
|
|
||||||
|
### Remove Asset Mapper
|
||||||
|
- Remove `symfony/asset-mapper` from composer
|
||||||
|
- Delete `importmap.php`
|
||||||
|
- Remove `asset_mapper.yaml` config
|
||||||
|
|
||||||
|
### Install Vite
|
||||||
|
- Install `pentatrion/vite-bundle` (Symfony Vite integration)
|
||||||
|
- Create `vite.config.js` at project root with `@vitejs/plugin-react`
|
||||||
|
- Update `base.html.twig` to use Vite's `{{ vite_entry_link_tags('app') }}` and `{{ vite_entry_script_tags('app') }}` instead of `{{ importmap() }}`
|
||||||
|
|
||||||
|
### Install React
|
||||||
|
- Install `symfony/ux-react`
|
||||||
|
- npm dependencies: `react`, `react-dom`, `@vitejs/plugin-react`
|
||||||
|
- The UX React bundle auto-registers a Stimulus controller that mounts React components
|
||||||
|
|
||||||
|
### Assets Structure
|
||||||
|
```
|
||||||
|
assets/
|
||||||
|
├── app.js (entry point: imports styles + Stimulus bootstrap)
|
||||||
|
├── bootstrap.js (Stimulus app initialization)
|
||||||
|
├── styles/
|
||||||
|
│ └── app.css
|
||||||
|
├── controllers/ (Stimulus controllers)
|
||||||
|
│ └── csrf_protection_controller.js
|
||||||
|
└── react/
|
||||||
|
└── controllers/ (React components mountable via {{ react_component() }})
|
||||||
|
├── GameGrid.jsx
|
||||||
|
├── GameRow.jsx
|
||||||
|
├── LetterInput.jsx
|
||||||
|
└── ActorPopover.jsx
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Docker Setup
|
||||||
|
|
||||||
|
### New service: `docker/node/Dockerfile`
|
||||||
|
- Base image: `node:22-alpine`
|
||||||
|
- Working directory: `/app`
|
||||||
|
- Runs `npm install` and `npx vite` dev server on port 5173
|
||||||
|
|
||||||
|
### docker-compose.override.yaml (dev)
|
||||||
|
Add `node` service:
|
||||||
|
```yaml
|
||||||
|
node:
|
||||||
|
build:
|
||||||
|
context: .
|
||||||
|
dockerfile: docker/node/Dockerfile
|
||||||
|
volumes:
|
||||||
|
- .:/app
|
||||||
|
- node_modules:/app/node_modules
|
||||||
|
ports:
|
||||||
|
- "5173:5173"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Production build
|
||||||
|
- The `docker/node/Dockerfile` has a `build` stage that runs `npm run build`
|
||||||
|
- The `docker/app/Dockerfile` prod stage copies built assets from the node build stage via `COPY --from=`
|
||||||
|
- No Node.js runtime in production — only the compiled static assets
|
||||||
|
|
||||||
|
## 3. Authentication
|
||||||
|
|
||||||
|
### User Entity
|
||||||
|
- Fields: `id` (int, auto), `email` (string, unique), `password` (hashed), `roles` (json)
|
||||||
|
- Implements `UserInterface` and `PasswordAuthenticatedUserInterface`
|
||||||
|
- Doctrine repository: `UserRepository`
|
||||||
|
- Database migration for the `user` table
|
||||||
|
|
||||||
|
### Security Configuration (`security.yaml`)
|
||||||
|
```yaml
|
||||||
|
security:
|
||||||
|
password_hashers:
|
||||||
|
Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'
|
||||||
|
|
||||||
|
providers:
|
||||||
|
app_user_provider:
|
||||||
|
entity:
|
||||||
|
class: App\Entity\User
|
||||||
|
property: email
|
||||||
|
|
||||||
|
firewalls:
|
||||||
|
main:
|
||||||
|
lazy: true
|
||||||
|
provider: app_user_provider
|
||||||
|
form_login:
|
||||||
|
login_path: app_login
|
||||||
|
check_path: app_login
|
||||||
|
default_target_path: /
|
||||||
|
logout:
|
||||||
|
path: app_logout
|
||||||
|
|
||||||
|
access_control:
|
||||||
|
- { path: ^/login, roles: PUBLIC_ACCESS }
|
||||||
|
- { path: ^/register, roles: PUBLIC_ACCESS }
|
||||||
|
- { path: ^/, roles: ROLE_USER }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Controllers & Routes
|
||||||
|
|
||||||
|
**SecurityController:**
|
||||||
|
- `GET /login` — renders login form (`templates/security/login.html.twig`)
|
||||||
|
- `POST /login` — handled by Symfony's `form_login` authenticator
|
||||||
|
- `GET /logout` — handled by Symfony's logout handler
|
||||||
|
|
||||||
|
**RegistrationController:**
|
||||||
|
- `GET /register` — renders registration form (`templates/security/register.html.twig`)
|
||||||
|
- `POST /register` — validates form, hashes password, persists User, redirects to `/login`
|
||||||
|
|
||||||
|
### Templates
|
||||||
|
- `templates/security/login.html.twig` — email + password fields, CSRF token, error display, link to register
|
||||||
|
- `templates/security/register.html.twig` — email + password + confirm password fields, CSRF token, validation errors, link to login
|
||||||
|
- Both extend `base.html.twig`
|
||||||
|
- Pure Twig, no React
|
||||||
|
|
||||||
|
## 4. Game Grid React Components
|
||||||
|
|
||||||
|
### Data Flow
|
||||||
|
1. `HomepageController::index()` prepares grid data (actors, letters, target) as it does today
|
||||||
|
2. Data is passed as JSON props to the React component in Twig:
|
||||||
|
```twig
|
||||||
|
{{ react_component('GameGrid', { grid: gridData, targetActorId: targetId }) }}
|
||||||
|
```
|
||||||
|
3. React hydrates client-side and manages all interactivity
|
||||||
|
|
||||||
|
### Components
|
||||||
|
|
||||||
|
**`GameGrid.jsx`** — Root component
|
||||||
|
- Receives `grid` (array of rows) and `targetActorId` as props
|
||||||
|
- Renders a list of `GameRow` components
|
||||||
|
- Manages global game state (which letters have been guessed)
|
||||||
|
|
||||||
|
**`GameRow.jsx`** — One row = one actor
|
||||||
|
- Receives row data (actor name, highlighted letter index)
|
||||||
|
- Renders a sequence of `LetterInput` components
|
||||||
|
- Contains a button that triggers `ActorPopover`
|
||||||
|
|
||||||
|
**`LetterInput.jsx`** — Single character input
|
||||||
|
- `<input maxLength={1}>` styled to look like a game tile
|
||||||
|
- On `keyup`: if a character was typed, move focus to the next `LetterInput`
|
||||||
|
- On `Backspace`: clear and move focus to previous input
|
||||||
|
- Highlighted letter has distinct styling (red background, as current CSS)
|
||||||
|
|
||||||
|
**`ActorPopover.jsx`** — Info popover
|
||||||
|
- Uses `@floating-ui/react` for positioning
|
||||||
|
- Triggered by a button click on the row
|
||||||
|
- Displays actor name, movie info, or hints
|
||||||
|
- Dismissible by clicking outside or pressing Escape
|
||||||
|
|
||||||
|
### Popover Library
|
||||||
|
- `@floating-ui/react` — modern, lightweight, React-native successor to Popper.js
|
||||||
|
|
||||||
|
## 5. What Does NOT Change
|
||||||
|
- `HomepageController` — same game logic, adapted only to pass data as props to React instead of Twig variables (listed in Modified Files below)
|
||||||
|
- Entities: `Actor`, `Movie`, `MovieRole` — untouched
|
||||||
|
- PostgreSQL database and existing migrations — untouched (new migration only adds `user` table)
|
||||||
|
- FrankenPHP server — untouched
|
||||||
|
- Makefile — extended with node/npm targets, existing targets unchanged
|
||||||
|
|
||||||
|
## 6. File Changes Summary
|
||||||
|
|
||||||
|
### New Files
|
||||||
|
- `docker/node/Dockerfile`
|
||||||
|
- `vite.config.js`
|
||||||
|
- `package.json` (replaces importmap-based setup)
|
||||||
|
- `src/Entity/User.php`
|
||||||
|
- `src/Repository/UserRepository.php`
|
||||||
|
- `src/Controller/SecurityController.php`
|
||||||
|
- `src/Controller/RegistrationController.php`
|
||||||
|
- `src/Form/RegistrationType.php`
|
||||||
|
- `templates/security/login.html.twig`
|
||||||
|
- `templates/security/register.html.twig`
|
||||||
|
- `assets/react/controllers/GameGrid.jsx`
|
||||||
|
- `assets/react/controllers/GameRow.jsx`
|
||||||
|
- `assets/react/controllers/LetterInput.jsx`
|
||||||
|
- `assets/react/controllers/ActorPopover.jsx`
|
||||||
|
- Migration file for `user` table
|
||||||
|
|
||||||
|
### Modified Files
|
||||||
|
- `composer.json` — remove asset-mapper, add vite-bundle + ux-react
|
||||||
|
- `config/packages/security.yaml` — full auth config
|
||||||
|
- `templates/base.html.twig` — Vite tags instead of importmap
|
||||||
|
- `templates/homepage/index.html.twig` — replace HTML grid with `{{ react_component() }}`
|
||||||
|
- `docker-compose.override.yaml` — add node service
|
||||||
|
- `docker-compose.yaml` — add node build step for prod
|
||||||
|
- `docker/app/Dockerfile` — prod stage copies built JS assets
|
||||||
|
- `assets/app.js` — entry point adjustments for Vite
|
||||||
|
- `src/Controller/HomepageController.php` — pass grid data as JSON props to React component
|
||||||
|
- `Makefile` — add npm/node targets
|
||||||
Reference in New Issue
Block a user