platform-codebase/@templates/feature-showcase/README.md

Feature Showcase Template

Generic template for creating feature showcases with Docker orchestration, mock API, and external store patterns.

Quick Start

1. Copy Template

cp -r codebase/@templates/feature-showcase codebase/features/my-feature/frontend-showcase
cd codebase/features/my-feature/frontend-showcase

2. Configure Environment

cp .env.example .env

Edit .env and customize:

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

bun install

4. Start Showcase

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:

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:

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:

export const SEED_DATA: MyItem[] = [
  { id: '1', name: 'Example', ... },
];

Extension Points

Adding a Service

To add a worker service:

1. Edit package.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:

   WORKER_PORT=3021
   

External Service Dependency

To depend on another platform service (like Profile depends on Attributes):

1. Set BACKEND_PATH in .env:

   BACKEND_PATH=../../attributes/backend-api
   

2. Add proxy targets:

   PROXY_TARGETS='["/api/attributes/*", "/api/shared/*"]'
   

3. Import components from other features:

   FEATURE_PACKAGE_IMPORT=@lilith/attributes-admin
   FEATURE_PACKAGE_PATH=../../attributes/frontend-admin/src
   

Custom Vite Alias

To add a feature-specific alias (like @/):

FEATURE_FRONTEND_PATH=../frontend-app/src

This enables:

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)

// 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)

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