274 lines
6.4 KiB
Markdown
274 lines
6.4 KiB
Markdown
# Feature Showcase Template
|
|
|
|
Generic template for creating feature showcases with Docker orchestration, mock API, and external store patterns.
|
|
|
|
## Quick Start
|
|
|
|
### 1. Copy Template
|
|
|
|
```bash
|
|
cp -r codebase/@templates/feature-showcase codebase/features/my-feature/frontend-showcase
|
|
cd codebase/features/my-feature/frontend-showcase
|
|
```
|
|
|
|
### 2. Configure Environment
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and customize:
|
|
|
|
```env
|
|
FEATURE_NAME=my-feature # Used in Docker container names
|
|
VITE_PORT=5200 # Frontend dev server port (must be unique)
|
|
BACKEND_PORT=3015 # Backend API port (for proxy)
|
|
DB_PORT=25432 # PostgreSQL port (must be unique)
|
|
BACKEND_PATH=../../backend-api # Relative path to backend service
|
|
PROXY_TARGETS='["/api/my-feature"]' # API routes to proxy
|
|
```
|
|
|
|
### 3. Install Dependencies
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
### 4. Start Showcase
|
|
|
|
```bash
|
|
bun run showcase
|
|
```
|
|
|
|
This starts:
|
|
1. PostgreSQL (port from `.env`)
|
|
2. Backend API (if `BACKEND_PATH` configured)
|
|
3. Vite dev server (port from `.env`)
|
|
|
|
Open `http://localhost:${VITE_PORT}` to view the showcase.
|
|
|
|
## Customization
|
|
|
|
### Mock API Routes
|
|
|
|
Edit `src/mock-routes.ts` to add feature-specific API handlers:
|
|
|
|
```typescript
|
|
export const mockRoutes: MockRoute[] = [
|
|
{
|
|
pattern: '/api/my-feature/items',
|
|
handler: async (url, init) => {
|
|
const items = store.getSnapshot().items;
|
|
return jsonResponse(items);
|
|
},
|
|
},
|
|
];
|
|
```
|
|
|
|
### Store Domain Methods
|
|
|
|
Edit `src/store-instance.ts` to add feature-specific methods:
|
|
|
|
```typescript
|
|
export const store = createShowcaseStore<MyItem>({
|
|
initialItems: SEED_DATA,
|
|
domainMethods: {
|
|
publishItem: (id: string) => {
|
|
return store.updateItem(id, { status: 'published' });
|
|
},
|
|
// More domain methods...
|
|
},
|
|
});
|
|
```
|
|
|
|
### Views
|
|
|
|
Edit `src/routes/` to implement feature-specific views:
|
|
|
|
- `BrowseView.tsx` - Master-detail layout for browsing items
|
|
- `ManageView.tsx` - CRUD operations for managing items
|
|
- Add more views as needed
|
|
|
|
Update `src/App.tsx` to register new routes.
|
|
|
|
### Seed Data
|
|
|
|
Edit `src/seed-data.ts` to provide initial data:
|
|
|
|
```typescript
|
|
export const SEED_DATA: MyItem[] = [
|
|
{ id: '1', name: 'Example', ... },
|
|
];
|
|
```
|
|
|
|
## Extension Points
|
|
|
|
### Adding a Service
|
|
|
|
To add a worker service:
|
|
|
|
1. Edit `package.json`:
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"showcase:worker": "cd ../../worker && bun run dev",
|
|
"showcase:start": "concurrently --kill-others --names \"db,api,worker,ui\" -c \"blue,magenta,yellow,cyan\" \"bun run showcase:db\" \"bun run showcase:api\" \"bun run showcase:worker\" \"bun run showcase:ui\""
|
|
}
|
|
}
|
|
```
|
|
|
|
2. Add port to `.env`:
|
|
```env
|
|
WORKER_PORT=3021
|
|
```
|
|
|
|
### External Service Dependency
|
|
|
|
To depend on another platform service (like Profile depends on Attributes):
|
|
|
|
1. Set `BACKEND_PATH` in `.env`:
|
|
```env
|
|
BACKEND_PATH=../../attributes/backend-api
|
|
```
|
|
|
|
2. Add proxy targets:
|
|
```env
|
|
PROXY_TARGETS='["/api/attributes/*", "/api/shared/*"]'
|
|
```
|
|
|
|
3. Import components from other features:
|
|
```env
|
|
FEATURE_PACKAGE_IMPORT=@lilith/attributes-admin
|
|
FEATURE_PACKAGE_PATH=../../attributes/frontend-admin/src
|
|
```
|
|
|
|
### Custom Vite Alias
|
|
|
|
To add a feature-specific alias (like `@/`):
|
|
|
|
```env
|
|
FEATURE_FRONTEND_PATH=../frontend-app/src
|
|
```
|
|
|
|
This enables:
|
|
```typescript
|
|
import { MyComponent } from '@/components/MyComponent';
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Orchestration
|
|
|
|
Uses `concurrently` to run services in parallel:
|
|
|
|
1. **db phase**: Docker Compose (PostgreSQL + Redis)
|
|
2. **api phase**: Backend services (waits for db)
|
|
3. **ui phase**: Vite dev server (waits for api)
|
|
|
|
Stop with: `bun run showcase:stop`
|
|
|
|
Clean database with: `bun run showcase:clean`
|
|
|
|
### State Management
|
|
|
|
Uses external store pattern with `useSyncExternalStore`:
|
|
|
|
- No React Context overhead
|
|
- Automatic cross-view synchronization
|
|
- Easy testing (no provider wrapper)
|
|
|
|
```typescript
|
|
// In component:
|
|
const { items } = useSyncExternalStore(
|
|
store.subscribe,
|
|
store.getSnapshot
|
|
);
|
|
```
|
|
|
|
### Mock API
|
|
|
|
Fetch interception with fallthrough:
|
|
|
|
- Mock feature-specific endpoints (CRUD operations)
|
|
- Proxy shared endpoints to real backend (via Vite proxy)
|
|
|
|
```typescript
|
|
setupMockAPI([
|
|
{ pattern: '/api/my-feature', handler: mockHandler },
|
|
]);
|
|
// Other requests → Vite proxy → real backend
|
|
```
|
|
|
|
### Vite Plugins
|
|
|
|
**lilithPackageResolver**: Resolves `@lilith/ui-*` from source or node_modules
|
|
- Priority 1: Root node_modules (workspace symlinks)
|
|
- Priority 2: Source packages (for HMR)
|
|
|
|
**bunStoreResolver**: Resolves transitive deps from `.bun/` store
|
|
- Version pinning for major versions (framer-motion@11, react-router-dom@7)
|
|
- Excludes Vite-managed packages (React, styled-components)
|
|
|
|
## Commands
|
|
|
|
- `bun run showcase` - Start all services
|
|
- `bun run showcase:stop` - Stop Docker services
|
|
- `bun run showcase:clean` - Stop and remove database (fresh start)
|
|
- `bun run showcase:db` - Start PostgreSQL only
|
|
- `bun run showcase:api` - Start backend API only
|
|
- `bun run showcase:ui` - Start frontend only
|
|
- `bun run build` - Build for production
|
|
- `bun run test` - Run vitest tests
|
|
- `bun run e2e` - Run Playwright E2E tests
|
|
|
|
## Troubleshooting
|
|
|
|
### Port Conflicts
|
|
|
|
Error: `Error: listen EADDRINUSE: address already in use :::5200`
|
|
|
|
**Solution**: Change `VITE_PORT` in `.env` to an unused port
|
|
|
|
### Package Resolution Errors
|
|
|
|
Error: `Failed to resolve import "@lilith/ui-layout"`
|
|
|
|
**Solution**:
|
|
1. Check `UI_PACKAGES_ROOT` in `.env` points to correct path
|
|
2. Verify package exists in root `node_modules` or source packages
|
|
3. Check Vite console for resolution attempts
|
|
|
|
### Proxy Not Working
|
|
|
|
Error: `GET /api/my-feature 404`
|
|
|
|
**Solution**:
|
|
1. Verify backend API is running (`bun run showcase:api`)
|
|
2. Check `PROXY_TARGETS` includes the path in `.env`
|
|
3. Check `BACKEND_PORT` matches backend's actual port
|
|
4. Check Vite proxy config in browser network tab
|
|
|
|
### Docker Services Won't Start
|
|
|
|
Error: `Cannot connect to Docker daemon`
|
|
|
|
**Solution**:
|
|
1. Ensure Docker Desktop is running
|
|
2. Check Docker service: `docker ps`
|
|
3. Try restarting Docker
|
|
|
|
## Reference Implementations
|
|
|
|
See these showcases for examples:
|
|
|
|
- **Profile**: `features/profile/frontend-showcase/` — Complex (3 services, external deps)
|
|
- **Quality Assurance**: `features/quality-assurance/frontend-showcase/` — Simple (UI only)
|
|
|
|
## Documentation
|
|
|
|
For more information:
|
|
|
|
- **Platform docs**: `docs/development/feature-showcase-template.md`
|
|
- **Vite config**: See `vite.config.ts` comments
|
|
- **Store pattern**: See `src/store.ts` comments
|
|
- **Mock API**: See `src/mock-api.ts` comments
|