forked from cardosofelipe/fast-next-template
Remove MSW handlers and update demo credentials for improved standardization
- Deleted `admin.ts`, `auth.ts`, and `users.ts` MSW handler files to streamline demo mode setup. - Updated demo credentials logic in `DemoCredentialsModal` and `DemoModeBanner` for stronger password requirements (≥12 characters). - Refined documentation in `CLAUDE.md` to align with new credential standards and auto-generated MSW workflows.
This commit is contained in:
110
frontend/scripts/sync-msw-with-openapi.md
Normal file
110
frontend/scripts/sync-msw-with-openapi.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Keeping MSW Handlers Synced with OpenAPI Spec
|
||||
|
||||
## Problem
|
||||
MSW handlers can drift out of sync with the backend API as it evolves.
|
||||
|
||||
## Solution Options
|
||||
|
||||
### Option 1: Use openapi-msw (Recommended)
|
||||
|
||||
Install the package that auto-generates MSW handlers from OpenAPI:
|
||||
|
||||
```bash
|
||||
npm install --save-dev openapi-msw
|
||||
```
|
||||
|
||||
Then create a generation script:
|
||||
|
||||
```typescript
|
||||
// scripts/generate-msw-handlers.ts
|
||||
import { generateMockHandlers } from 'openapi-msw';
|
||||
import fs from 'fs';
|
||||
|
||||
async function generate() {
|
||||
const spec = JSON.parse(fs.readFileSync('/tmp/openapi.json', 'utf-8'));
|
||||
|
||||
const handlers = generateMockHandlers(spec, {
|
||||
baseUrl: 'http://localhost:8000',
|
||||
});
|
||||
|
||||
fs.writeFileSync('src/mocks/handlers/generated.ts', handlers);
|
||||
}
|
||||
|
||||
generate();
|
||||
```
|
||||
|
||||
### Option 2: Manual Sync Checklist
|
||||
|
||||
When you add/change backend endpoints:
|
||||
|
||||
1. **Update Backend** → Make API changes
|
||||
2. **Generate Frontend Client** → `npm run generate:api`
|
||||
3. **Update MSW Handlers** → Edit `src/mocks/handlers/*.ts`
|
||||
4. **Test Demo Mode** → `NEXT_PUBLIC_DEMO_MODE=true npm run dev`
|
||||
|
||||
### Option 3: Automated with Script Hook
|
||||
|
||||
Add to `package.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"generate:api": "./scripts/generate-api-client.sh && npm run sync:msw",
|
||||
"sync:msw": "echo '⚠️ Don't forget to update MSW handlers in src/mocks/handlers/'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Current Coverage
|
||||
|
||||
Our MSW handlers currently cover:
|
||||
|
||||
**Auth Endpoints:**
|
||||
- POST `/api/v1/auth/register`
|
||||
- POST `/api/v1/auth/login`
|
||||
- POST `/api/v1/auth/refresh`
|
||||
- POST `/api/v1/auth/logout`
|
||||
- POST `/api/v1/auth/logout-all`
|
||||
- POST `/api/v1/auth/password-reset`
|
||||
- POST `/api/v1/auth/password-reset/confirm`
|
||||
- POST `/api/v1/auth/change-password`
|
||||
|
||||
**User Endpoints:**
|
||||
- GET `/api/v1/users/me`
|
||||
- PATCH `/api/v1/users/me`
|
||||
- DELETE `/api/v1/users/me`
|
||||
- GET `/api/v1/users/:id`
|
||||
- GET `/api/v1/users`
|
||||
- GET `/api/v1/organizations/me`
|
||||
- GET `/api/v1/sessions`
|
||||
- DELETE `/api/v1/sessions/:id`
|
||||
|
||||
**Admin Endpoints:**
|
||||
- GET `/api/v1/admin/stats`
|
||||
- GET `/api/v1/admin/users`
|
||||
- GET `/api/v1/admin/users/:id`
|
||||
- POST `/api/v1/admin/users`
|
||||
- PATCH `/api/v1/admin/users/:id`
|
||||
- DELETE `/api/v1/admin/users/:id`
|
||||
- POST `/api/v1/admin/users/bulk`
|
||||
- GET `/api/v1/admin/organizations`
|
||||
- GET `/api/v1/admin/organizations/:id`
|
||||
- GET `/api/v1/admin/organizations/:id/members`
|
||||
- GET `/api/v1/admin/sessions`
|
||||
|
||||
## Quick Validation
|
||||
|
||||
To check if MSW is missing handlers:
|
||||
|
||||
1. Start demo mode: `NEXT_PUBLIC_DEMO_MODE=true npm run dev`
|
||||
2. Open browser console
|
||||
3. Look for `[MSW] Warning: intercepted a request without a matching request handler`
|
||||
4. Add missing handlers to appropriate file in `src/mocks/handlers/`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep handlers simple** - Return happy path responses by default
|
||||
2. **Match backend schemas** - Use generated TypeScript types
|
||||
3. **Realistic delays** - Use `await delay(300)` for UX testing
|
||||
4. **Document passwords** - Make demo credentials obvious
|
||||
5. **Test regularly** - Run demo mode after API changes
|
||||
Reference in New Issue
Block a user