Epic Workshop Development Guide
Documents a React Router v7 monorepo for running EpicWeb.dev workshops locally, with build, test, and dev commands.
What this file does
Documents a React Router v7 monorepo for running EpicWeb.dev workshops locally, with build, test, and dev commands.
When to use it
- Setting up a local copy of the Epic Workshop learning environment
- Contributing to the epicshop repository and need command reference
- Understanding the monorepo package structure and testing approach
Assumes this stack
Epic Workshop Development Guide
Overview
Epic Workshop (epicshop) is a React Router v7 monorepo providing a local learning environment for EpicWeb.dev workshops.
Services
| Service | Port | Command | Notes |
|---|---|---|---|
| Workshop App | 5639+ (auto-assigned) | npm run dev | Main web UI, runs from example/ directory |
| Sidecar processes | Various | Auto-started | Workshop-specific, defined in epicshop.sidecarProcesses |
Key Commands
| Task | Command |
|---|---|
| Build all | npm run build |
| Lint | npm run lint |
| Format | npm run format |
| Unit tests | npm run test |
| E2E tests | npm run test:e2e |
| Dev server | npm run dev |
| Full validation | npm run validate |
Architecture Notes
- Nx orchestration: All build/test/lint commands use nx for automatic dependency ordering and caching
- Server-only modules: Files with
.serversuffix in@epic-web/workshop-utilsare server-only and cannot be imported in client components - Always build before testing: Run
npm run buildbeforenpm run devwhen testing client-side changes - Port auto-assignment: The app starts on port 5639 by default but will auto-find an available port if occupied
Package Structure
epicshop(packages/workshop-cli): CLI tool@epic-web/workshop-app(packages/workshop-app): Main React Router app@epic-web/workshop-utils(packages/workshop-utils): Shared server utilities@epic-web/workshop-presence(packages/workshop-presence): Optional real-time presence@epic-web/workshop-mcp(packages/workshop-mcp): MCP server for AI assistants
Testing Approach
- Unit tests use vitest and cover CLI, utils, presence, and MCP packages
- E2E tests use Playwright and test against the
example/workshop - For UI changes, test manually via
npm run devand browser
Agent Workflow
- If you discover improvements that are unrelated to your current change, first search closed issues to see if the idea was already decided against, then open a new GitHub issue with a concise problem, proposal, and acceptance criteria.
Common Issues
- If changes aren't reflected, ensure you've run
npm run buildfirst - The TESTS tab in the UI requires authentication to use
What's inside
6 sections: overview, services table, key commands, architecture notes, package structure, testing approach, agent workflow, common issues.
Change this for your project
- Replace
epicweb-dev/epicshopwith your own repository name - Replace
@epic-web/workshop-utilswith your own package scope - Replace
example/directory references with your own workshop path
Where it goes
Save in docs/ or the repository root. Gives agents and new contributors a map of the codebase.
Worth borrowing
- Auto-assigning ports to avoid conflicts during development
- Using Nx for automatic dependency ordering and caching across monorepo packages
- Separating server-only modules with a
.serversuffix to prevent client imports
Related Documents
PCB Design Sources for Industry-Scale Testing
Lists GitHub repos and communities where you can download real PCB designs for testing optimization at scale.
Design Document: BharatSeva AI
Describes a 10-agent AWS system that helps India's informal workers access government schemes via voice-first, serverless architecture.
Qwen Image and Edit: Open-sourcing and Local GGUF Generations with Lightning
Documents the Qwen-Image and Qwen-Image-Edit models, covering architecture, training, benchmarks, ComfyUI setup, and prompting techniques for local GGUF deployment.
OpenClaw Enterprise Transformation Plan
Transforms a single-user AI agent into a dual-mode platform supporting both viral open-source and Fortune 500 enterprise deployments through phased security, IAM, audit, multi-tenancy, and Kubernetes features.