{user.name}
\n\t\t\t{user.bio}
\n\t\t\t\n\t\t\n\t\t\t{canDelete && (\n\t\t\t\t\n\t\t\t)}\n\t\t
\n\t)\n}\n```\n\n**Check if user has role:**\n\n```typescript\nimport { userHasRole } from '#app/utils/user.ts'\n\nexport default function AdminRoute() {\n\tconst user = useOptionalUser()\n\tconst isAdmin = userHasRole(user, 'admin')\n\n\tif (!isAdmin) {\n\t\treturn Access Denied
\n\t}\n\n\treturn Admin Panel
\n}\n```\n\n### Create New Permissions\n\n**En Prisma Studio o seed:**\n\n```typescript\n// prisma/seed.ts\nawait prisma.permission.create({\n\tdata: {\n\t\taction: 'create',\n\t\tentity: 'post',\n\t\taccess: 'own',\n\t\tdescription: 'Can create their own posts',\n\t\troles: {\n\t\t\tconnect: { name: 'user' },\n\t\t},\n\t},\n})\n```\n\n**Permiso con múltiples niveles de acceso:**\n\n```typescript\nawait prisma.permission.createMany({\n\tdata: [\n\t\t{\n\t\t\taction: 'read',\n\t\t\tentity: 'post',\n\t\t\taccess: 'own',\n\t\t\tdescription: 'Can read own posts',\n\t\t},\n\t\t{\n\t\t\taction: 'read',\n\t\t\tentity: 'post',\n\t\t\taccess: 'any',\n\t\t\tdescription: 'Can read any post',\n\t\t},\n\t],\n})\n```\n\n### Assign Roles to Users\n\n**When creating user:**\n\n```typescript\nconst user = await prisma.user.create({\n\tdata: {\n\t\temail,\n\t\tusername,\n\t\troles: {\n\t\t\tconnect: { name: 'user' }, // Assign 'user' role\n\t\t},\n\t},\n})\n```\n\n**Assign multiple roles:**\n\n```typescript\nawait prisma.user.update({\n\twhere: { id: userId },\n\tdata: {\n\t\troles: {\n\t\t\tconnect: [{ name: 'user' }, { name: 'moderator' }],\n\t\t},\n\t},\n})\n```\n\n### Permissions and Roles Seed\n\n**Seed example:**\n\n```typescript\n// prisma/seed.ts\n\n// Create permissions\nconst permissions = await Promise.all([\n\t// User permissions\n\tprisma.permission.create({\n\t\tdata: {\n\t\t\taction: 'create',\n\t\t\tentity: 'note',\n\t\t\taccess: 'own',\n\t\t\tdescription: 'Can create own notes',\n\t\t},\n\t}),\n\tprisma.permission.create({\n\t\tdata: {\n\t\t\taction: 'read',\n\t\t\tentity: 'note',\n\t\t\taccess: 'own',\n\t\t\tdescription: 'Can read own notes',\n\t\t},\n\t}),\n\tprisma.permission.create({\n\t\tdata: {\n\t\t\taction: 'update',\n\t\t\tentity: 'note',\n\t\t\taccess: 'own',\n\t\t\tdescription: 'Can update own notes',\n\t\t},\n\t}),\n\tprisma.permission.create({\n\t\tdata: {\n\t\t\taction: 'delete',\n\t\t\tentity: 'note',\n\t\t\taccess: 'own',\n\t\t\tdescription: 'Can delete own notes',\n\t\t},\n\t}),\n\t// Admin permissions\n\tprisma.permission.create({\n\t\tdata: {\n\t\t\taction: 'delete',\n\t\t\tentity: 'user',\n\t\t\taccess: 'any',\n\t\t\tdescription: 'Can delete any user',\n\t\t},\n\t}),\n])\n\n// Create roles\nconst userRole = await prisma.role.create({\n\tdata: {\n\t\tname: 'user',\n\t\tdescription: 'Standard user',\n\t\tpermissions: {\n\t\t\tconnect: permissions.slice(0, 4).map((p) => ({ id: p.id })),\n\t\t},\n\t},\n})\n\nconst adminRole = await prisma.role.create({\n\tdata: {\n\t\tname: 'admin',\n\t\tdescription: 'Administrator',\n\t\tpermissions: {\n\t\t\tconnect: permissions.map((p) => ({ id: p.id })),\n\t\t},\n\t},\n})\n```\n\n### Permission Type\n\n**Type-safe permission strings:**\n\n```typescript\nimport { type PermissionString } from '#app/utils/user.ts'\n\n// Tipo: 'create:note:own' | 'read:note:own' | etc.\nconst permission: PermissionString = 'delete:note:own'\n```\n\n**Parsear permission string:**\n\n```typescript\nimport { parsePermissionString } from '#app/utils/user.ts'\n\nconst { action, entity, access } = parsePermissionString('delete:note:own')\n// action: 'delete'\n// entity: 'note'\n// access: ['own']\n```\n\n## Common examples\n\n### Example 1: Proteger action con permiso\n\n```typescript\n// app/routes/users/$username/notes/$noteId.tsx\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\tconst formData = await request.formData()\n\tconst { noteId } = Object.fromEntries(formData)\n\n\tconst note = await prisma.note.findFirst({\n\t\tselect: { id: true, ownerId: true, owner: { select: { username: true } } },\n\t\twhere: { id: noteId },\n\t})\n\n\tif (!note) {\n\t\tthrow new Response('Not found', { status: 404 })\n\t}\n\n\tconst isOwner = note.ownerId === userId\n\n\t// Validate permiso según si es propietario o no\n\tawait requireUserWithPermission(\n\t\trequest,\n\t\tisOwner ? 'delete:note:own' : 'delete:note:any',\n\t)\n\n\tawait prisma.note.delete({ where: { id: note.id } })\n\n\treturn redirect(`/users/${note.owner.username}/notes`)\n}\n```\n\n### Example 2: Mostrar UI condicional basada en permisos\n\n```typescript\nexport default function NoteRoute({ loaderData }: Route.ComponentProps) {\n\tconst user = useOptionalUser()\n\tconst isOwner = user?.id === loaderData.note.ownerId\n\n\tconst canDelete = userHasPermission(\n\t\tuser,\n\t\tisOwner ? 'delete:note:own' : 'delete:note:any',\n\t)\n\tconst canEdit = userHasPermission(\n\t\tuser,\n\t\tisOwner ? 'update:note:own' : 'update:note:any',\n\t)\n\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n```\n\n### Example 3: Ruta solo para admin\n\n```typescript\n// app/routes/admin/users.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tawait requireUserWithRole(request, 'admin')\n\n\tconst users = await prisma.user.findMany({\n\t\tselect: {\n\t\t\tid: true,\n\t\t\temail: true,\n\t\t\tusername: true,\n\t\t},\n\t})\n\n\treturn { users }\n}\n\nexport default function AdminUsersRoute({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t{loaderData.note.title}
\n\t\t\t{loaderData.note.content}
\n\n\t\t\t{(canEdit || canDelete) && (\n\t\t\t\t\n\t\t\t\t\t{canEdit && (\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t)}\n\t\t\t\t\t{canDelete && (\n\t\t\t\t\t\t
\n\t\t\t)}\n\t\t\n\t\t\t
\n\t)\n}\n```\n\n### Example 4: Create new permission and assign it\n\n```typescript\n// Migración o seed\nasync function setupPostPermissions() {\n\t// Create post permissions\n\tconst createOwn = await prisma.permission.create({\n\t\tdata: {\n\t\t\taction: 'create',\n\t\t\tentity: 'post',\n\t\t\taccess: 'own',\n\t\t\tdescription: 'Can create own posts',\n\t\t},\n\t})\n\n\tconst readAny = await prisma.permission.create({\n\t\tdata: {\n\t\t\taction: 'read',\n\t\t\tentity: 'post',\n\t\t\taccess: 'any',\n\t\t\tdescription: 'Can read any post',\n\t\t},\n\t})\n\n\t// Assign to user role\n\tawait prisma.role.update({\n\t\twhere: { name: 'user' },\n\t\tdata: {\n\t\t\tpermissions: {\n\t\t\t\tconnect: [{ id: createOwn.id }, { id: readAny.id }],\n\t\t\t},\n\t\t},\n\t})\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Implicit permission checks**: Always explicitly check permissions - make\n permission requirements visible in code\n- ❌ **Not validating permissions on server-side**: Always validate permissions\n in action/loader, never trust client-side only\n- ❌ **Forgetting to verify `own` vs `any`**: Explicitly determine if user is\n owner before validating permission\n- ❌ **Not using correct helpers**: Use `requireUserWithPermission` for\n server-side and `userHasPermission` for client-side - explicit helpers\n- ❌ **Not creating unique permissions**: Use\n `@@unique([action, entity, access])` in schema - explicit permission structure\n- ❌ **Assuming permissions instead of verifying**: Always verify explicitly,\n even if you think user has the permission\n- ❌ **Not handling 403 errors**: Helpers throw errors that must be handled by\n ErrorBoundary\n- ❌ **Not using types**: Use `PermissionString` type for type-safety - explicit\n types\n- ❌ **Hidden permission logic**: Don't hide permission checks in utility\n functions - make them explicit at the call site\n\n## References\n\n- [Epic Stack Permissions Docs](../epic-stack/docs/permissions.md)\n- [Epic Web Principles](https://www.epicweb.dev/principles)\n- [RBAC Explained](https://auth0.com/intro-to-iam/what-is-role-based-access-control-rbac)\n- `app/utils/permissions.server.ts` - Server-side permission utilities\n- `app/utils/user.ts` - Client-side permission utilities\n- `prisma/schema.prisma` - Permission and Role models\n- `prisma/seed.ts` - Permission seed examples\n","docs/skills/epic-react-patterns/SKILL.md":"---\nname: epic-react-patterns\ndescription:\n Guide on React patterns, performance optimization, and code quality for Epic\n Stack\ncategories:\n - react\n - performance\n - patterns\n - optimization\n---\n\n# Epic Stack: React Patterns and Guidelines\n\n## When to use this skill\n\nUse this skill when you need to:\n\n- Write efficient React components in Epic Stack applications\n- Optimize performance and bundle size\n- Follow React Router patterns and conventions\n- Avoid common React anti-patterns\n- Implement proper code splitting\n- Optimize re-renders and data fetching\n- Use React hooks correctly\n\n## Philosophy\n\nFollowing Epic Web principles:\n\n- **Make it work, make it right, make it fast** - In that order. First make it\n functional, then refactor for clarity, then optimize for performance.\n- **Pragmatism over purity** - Choose practical solutions that work well in your\n context rather than theoretically perfect ones.\n- **Optimize for sustainable velocity** - Write code that's easy to maintain and\n extend, not just fast to write initially.\n- **Do as little as possible** - Only add complexity when it provides real\n value.\n\n## Patterns and conventions\n\n### Data Fetching in React Router\n\nEpic Stack uses React Router loaders for data fetching, not `useEffect`.\n\n**✅ Good - Use loaders:**\n\n```typescript\n// app/routes/users/$username.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\treturn { user }\n}\n\nexport default function UserRoute({ loaderData }: Route.ComponentProps) {\n\treturn All Users
\n\t\t\t{loaderData.users.map(user => (\n\t\t\t\t{user.username}
\n\t\t\t))}\n\t\t{loaderData.user.name}
\n}\n```\n\n**❌ Avoid - Don't fetch in useEffect:**\n\n```typescript\n// ❌ Don't do this\nexport default function UserRoute({ params }: Route.ComponentProps) {\n\tconst [user, setUser] = useState(null)\n\n\tuseEffect(() => {\n\t\tfetch(`/api/users/${params.username}`)\n\t\t\t.then(res => res.json())\n\t\t\t.then(setUser)\n\t}, [params.username])\n\n\treturn user ? {user.name}
: Loading...
\n}\n```\n\n### Avoid useEffect for Side Effects\n\n[You Might Not Need `useEffect`](https://react.dev/learn/you-might-not-need-an-effect)\n\nInstead of using `useEffect`, use event handlers, CSS, ref callbacks, or\n`useSyncExternalStore`.\n\n**✅ Good - Use event handlers:**\n\n```typescript\nfunction ProductPage({ product, addToCart }: Route.ComponentProps) {\n\tfunction buyProduct() {\n\t\taddToCart(product)\n\t\tshowNotification(`Added ${product.name} to cart!`)\n\t}\n\n\tfunction handleBuyClick() {\n\t\tbuyProduct()\n\t}\n\n\tfunction handleCheckoutClick() {\n\t\tbuyProduct()\n\t\tnavigate('/checkout')\n\t}\n\n\treturn (\n\t\t\n\t\t\t\n\t\t\t\n\t\t
\n\t)\n}\n```\n\n**❌ Avoid - Side effects in useEffect:**\n\n```typescript\n// ❌ Don't do this\nfunction ProductPage({ product, addToCart }: Route.ComponentProps) {\n\tuseEffect(() => {\n\t\tif (product.isInCart) {\n\t\t\tshowNotification(`Added ${product.name} to cart!`)\n\t\t}\n\t}, [product])\n\n\tfunction handleBuyClick() {\n\t\taddToCart(product)\n\t}\n\n\t// ...\n}\n```\n\n**✅ Appropriate use of useEffect:**\n\n```typescript\n// ✅ Good - Event listeners are appropriate\nuseEffect(() => {\n\tconst controller = new AbortController()\n\n\twindow.addEventListener(\n\t\t'keydown',\n\t\t(event: KeyboardEvent) => {\n\t\t\tif (event.key !== 'Escape') return\n\t\t\t// handle escape key\n\t\t},\n\t\t{ signal: controller.signal },\n\t)\n\n\treturn () => {\n\t\tcontroller.abort()\n\t}\n}, [])\n```\n\n### Code Splitting with React Router\n\nReact Router automatically code-splits by route. Use dynamic imports for heavy\ncomponents.\n\n**✅ Good - Dynamic imports:**\n\n```typescript\n// app/routes/admin/dashboard.tsx\nimport { lazy } from 'react'\n\nconst AdminChart = lazy(() => import('#app/components/admin/chart.tsx'))\n\nexport default function AdminDashboard() {\n\treturn (\n\t\t- \n\t\t\t{sortedUsers.map(user => (\n\t\t\t\t
- {user.name} \n\t\t\t))}\n\t\t
\n\t\t\t
\n\t)\n}\n```\n\n### Error Boundaries\n\n**✅ Good - Use error boundaries:**\n\n```typescript\n// app/routes/users/$username.tsx\nexport function ErrorBoundary() {\n\treturn (\n\t\t\n\t\t\t\t
\n\t\t\t\t
\n\t\t\t{user.name}
\n\t\t\t\n\t\t\t\t
\n\t\t\t{user.email}
\n\t\t\t\t{user.bio}
\n\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t
\n\t\tUser \"{params.username}\" not found
\n\t\t\t\t),\n\t\t\t}}\n\t\t/>\n\t)\n}\n```\n\n### TypeScript Guidelines\n\n**✅ Good - Type props explicitly:**\n\n```typescript\ninterface UserCardProps {\n\tuser: {\n\t\tid: string\n\t\tname: string\n\t\temail: string\n\t}\n\tonEdit?: (userId: string) => void\n}\n\nfunction UserCard({ user, onEdit }: UserCardProps) {\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n```\n\n**✅ Good - Use Route types:**\n\n```typescript\nimport type { Route } from './+types/users.$username'\n\nexport async function loader({ params }: Route.LoaderArgs) {\n\t// params is type-safe!\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\treturn { user }\n}\n\nexport default function UserRoute({ loaderData }: Route.ComponentProps) {\n\t// loaderData is type-safe!\n\treturn {user.name}
\n\t\t\t{user.email}
\n\t\t\t{onEdit && }\n\t\t{loaderData.user.name}
\n}\n```\n\n### Loading States\n\n**✅ Good - Use React Router's pending states:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction NoteForm() {\n\tconst navigation = useNavigation()\n\tconst isSubmitting = navigation.state === 'submitting'\n\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Preventing Data Fetching Waterfalls\n\nReact Router loaders can prevent waterfalls by fetching data in parallel.\n\n**❌ Avoid - Sequential data fetching (waterfall):**\n\n```typescript\n// ❌ Don't do this - creates a waterfall\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\t// Second fetch waits for first to complete\n\tconst notes = await prisma.note.findMany({\n\t\twhere: { ownerId: user.id },\n\t})\n\treturn { user, notes }\n}\n```\n\n**✅ Good - Parallel data fetching:**\n\n```typescript\n// ✅ Fetch data in parallel\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true, username: true, name: true },\n\t})\n\n\t// Fetch notes in parallel with user data\n\tconst [notes, stats] = await Promise.all([\n\t\tuser\n\t\t\t? prisma.note.findMany({\n\t\t\t\t\twhere: { ownerId: user.id },\n\t\t\t\t\tselect: { id: true, title: true, updatedAt: true },\n\t\t\t\t})\n\t\t\t: Promise.resolve([]),\n\t\tuser\n\t\t\t? prisma.note.count({ where: { ownerId: user.id } })\n\t\t\t: Promise.resolve(0),\n\t])\n\n\treturn { user, notes, stats }\n}\n```\n\n**✅ Good - Nested route parallel loading:**\n\n```typescript\n// Parent route loader\n// app/routes/users/$username.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true, username: true, name: true },\n\t})\n\treturn { user }\n}\n\n// Child route loader runs in parallel\n// app/routes/users/$username/notes.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true },\n\t})\n\n\tif (!user) {\n\t\tthrow new Response('Not Found', { status: 404 })\n\t}\n\n\tconst notes = await prisma.note.findMany({\n\t\twhere: { ownerId: user.id },\n\t\tselect: { id: true, title: true, updatedAt: true },\n\t})\n\n\treturn { notes }\n}\n```\n\n### Server-Side Rendering (SSR) Performance\n\nReact Router provides SSR by default. Optimize by:\n\n**✅ Good - Selective data fetching:**\n\n```typescript\nexport async function loader({ request }: Route.LoaderArgs) {\n\t// Only fetch what's needed for initial render\n\tconst searchParams = new URL(request.url).searchParams\n\tconst page = Number(searchParams.get('page') || '1')\n\n\tconst [items, total] = await Promise.all([\n\t\tprisma.item.findMany({\n\t\t\ttake: 20,\n\t\t\tskip: (page - 1) * 20,\n\t\t\tselect: { id: true, title: true }, // Only needed fields\n\t\t}),\n\t\tprisma.item.count(),\n\t])\n\n\treturn { items, total, page }\n}\n```\n\n**✅ Good - Use caching for expensive operations:**\n\n```typescript\nimport { cachified, cache } from '#app/utils/cache.server.ts'\n\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst timings: Timings = {}\n\n\t// Cache expensive database queries\n\tconst stats = await cachified({\n\t\tkey: 'user-stats',\n\t\tcache,\n\t\ttimings,\n\t\tgetFreshValue: async () => {\n\t\t\treturn await prisma.user.aggregate({\n\t\t\t\t_count: { id: true },\n\t\t\t})\n\t\t},\n\t\tttl: 1000 * 60 * 5, // 5 minutes\n\t})\n\n\treturn { stats }\n}\n```\n\n### Rendering Performance\n\n**✅ Good - Use React.memo for expensive components:**\n\n```typescript\nimport { memo } from 'react'\n\nconst ExpensiveChart = memo(function ExpensiveChart({ data }: { data: Data[] }) {\n\t// Expensive rendering logic\n\treturn {user.name}
\n\t\t\t{user.email}
\n\t\t- \n\t\t\t{users.map(user => (\n\t\t\t\t
{loaderData.user.name}
\n}\n\n// ❌ Avoid - Over-engineered route structure\n// app/routes/users/$username/_layout.tsx\n// app/routes/users/$username/index.tsx\n// app/routes/users/$username/_components/UserHeader.tsx\n// app/routes/users/$username/_components/UserDetails.tsx\n// Unnecessary complexity for a simple user page\n```\n\n**Example - Add complexity only when needed:**\n\n```typescript\n// ✅ Good - Add nested routes only when you actually need them\n// If you have user notes, then nested routes make sense:\n// app/routes/users/$username/notes/_layout.tsx\n// app/routes/users/$username/notes/index.tsx\n// app/routes/users/$username/notes/$noteId.tsx\n\n// ❌ Avoid - Creating nested routes \"just in case\"\n// Don't create complex structures before you need them\n```\n\n### File-based routing with react-router-auto-routes\n\nEpic Stack uses `react-router-auto-routes` instead of React Router's standard\nconvention. This enables better organization and code co-location.\n\n**Basic structure:**\n\n```\napp/routes/\n├── _layout.tsx # Layout for child routes\n├── index.tsx # Root route (/)\n├── about.tsx # Route /about\n└── users/\n ├── _layout.tsx # Layout for user routes\n ├── index.tsx # Route /users\n └── $username/\n └── index.tsx # Route /users/:username\n```\n\n**Configuration in `app/routes.ts`:**\n\n```typescript\nimport { type RouteConfig } from '@react-router/dev/routes'\nimport { autoRoutes } from 'react-router-auto-routes'\n\nexport default autoRoutes({\n\tignoredRouteFiles: [\n\t\t'.*',\n\t\t'**/*.css',\n\t\t'**/*.test.{js,jsx,ts,tsx}',\n\t\t'**/__*.*',\n\t\t'**/*.server.*', // Co-located server utilities\n\t\t'**/*.client.*', // Co-located client utilities\n\t],\n}) satisfies RouteConfig\n```\n\n### Route Groups\n\nRoute groups are folders that start with `_` and don't affect the URL but help\norganize related code.\n\n**Common examples:**\n\n- `_auth/` - Authentication routes (login, signup, etc.)\n- `_marketing/` - Marketing pages (home, about, etc.)\n- `_seo/` - SEO routes (sitemap, robots.txt)\n\n**Example:**\n\n```\napp/routes/\n├── _auth/\n│ ├── login.tsx # URL: /login\n│ ├── signup.tsx # URL: /signup\n│ └── forgot-password.tsx # URL: /forgot-password\n└── _marketing/\n ├── index.tsx # URL: /\n └── about.tsx # URL: /about\n```\n\n### Route Parameters\n\nUse `$` to indicate route parameters:\n\n**Syntax:**\n\n- `$param.tsx` → `:param` in URL\n- `$username.tsx` → `:username` in URL\n\n**Example route with parameter:**\n\n```typescript\n// app/routes/users/$username/index.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst username = params.username // Type-safe!\n\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username },\n\t})\n\n\treturn { user }\n}\n```\n\n### Nested Layouts with `_layout.tsx`\n\nUse `_layout.tsx` to create shared layouts for child routes.\n\n**Example:**\n\n```typescript\n// app/routes/users/$username/notes/_layout.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst owner = await prisma.user.findFirst({\n\t\twhere: { username: params.username },\n\t})\n\treturn { owner }\n}\n\nexport default function NotesLayout({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t{/* Use loaderData.data */}
\n}\n```\n\n**Action pattern:**\n\n```typescript\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\tconst formData = await request.formData()\n\n\t// Validate and process data\n\tawait prisma.something.create({\n\t\tdata: { /* ... */ },\n\t})\n\n\treturn redirect('/success')\n}\n\nexport default function RouteComponent() {\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Search Params\n\nAccess query parameters using `useSearchParams`:\n\n```typescript\nimport { useSearchParams } from 'react-router'\n\nexport default function SearchPage() {\n\tconst [searchParams, setSearchParams] = useSearchParams()\n\tconst query = searchParams.get('q') || ''\n\tconst page = Number(searchParams.get('page') || '1')\n\n\treturn (\n\t\t\n\t\t\t setSearchParams({ q: e.target.value })}\n\t\t\t/>\n\t\t\t{/* Results */}\n\t\t
\n\t)\n}\n```\n\n### Code Co-location\n\nEpic Stack encourages placing related code close to where it's used.\n\n**Typical structure:**\n\n```\napp/routes/users/$username/notes/\n├── _layout.tsx # Layout with loader\n├── index.tsx # Notes list\n├── $noteId.tsx # Note view\n├── $noteId_.edit.tsx # Edit note\n├── +shared/ # Code shared between routes\n│ └── note-editor.tsx # Shared editor\n└── $noteId.server.ts # Server-side utilities\n```\n\nThe `+` prefix indicates co-located modules that are not routes.\n\n### Naming Conventions\n\n- `_layout.tsx` - Layout for child routes\n- `index.tsx` - Root route of the segment\n- `$param.tsx` - Route parameter\n- `$param_.action.tsx` - Route with parameter + action (using `_`)\n- `[.]ext.tsx` - Resource route (e.g., `robots[.]txt.ts`)\n\n## Common examples\n\n### Example 1: Create a basic route with layout\n\n```typescript\n// app/routes/products/_layout.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst categories = await prisma.category.findMany()\n\treturn { categories }\n}\n\nexport default function ProductsLayout({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t\t\t\n\t\t\t
\n\t)\n}\n\n// app/routes/products/index.tsx\nexport default function ProductsIndex() {\n\treturn Products list
\n}\n```\n\n### Example 2: Route with dynamic parameter\n\n```typescript\n// app/routes/products/$slug.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst product = await prisma.product.findUnique({\n\t\twhere: { slug: params.slug },\n\t})\n\n\tif (!product) {\n\t\tthrow new Response('Not Found', { status: 404 })\n\t}\n\n\treturn { product }\n}\n\nexport default function ProductPage({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n\nexport function ErrorBoundary() {\n\treturn (\n\t\t{loaderData.product.name}
\n\t\t\t{loaderData.product.description}
\n\t\tProduct \"{params.slug}\" not found
\n\t\t\t\t),\n\t\t\t}}\n\t\t/>\n\t)\n}\n```\n\n### Example 3: Resource route for download\n\n```typescript\n// app/routes/resources/download-report.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst userId = await requireUserId(request)\n\n\tconst report = await generateReport(userId)\n\n\treturn new Response(report, {\n\t\theaders: {\n\t\t\t'Content-Type': 'application/pdf',\n\t\t\t'Content-Disposition': 'attachment; filename=\"report.pdf\"',\n\t\t},\n\t})\n}\n```\n\n### Example 4: Route with multiple nested parameters\n\n```typescript\n// app/routes/users/$username/posts/$postId/comments/$commentId.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\t// params contains: { username, postId, commentId }\n\tconst comment = await prisma.comment.findUnique({\n\t\twhere: { id: params.commentId },\n\t\tinclude: {\n\t\t\tpost: {\n\t\t\t\tinclude: { author: true },\n\t\t\t},\n\t\t},\n\t})\n\n\treturn { comment }\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Over-engineering route structure**: Keep routes simple - don't create\n complex nested structures unless you actually need them\n- ❌ **Creating abstractions prematurely**: Start with simple routes, add\n complexity only when there's a clear benefit\n- ❌ **Using React Router's standard convention**: Epic Stack uses\n `react-router-auto-routes`, not the standard convention\n- ❌ **Exporting default component in resource routes**: Resource routes should\n not export components\n- ❌ **Not using nested layouts when needed**: Use `_layout.tsx` when you have\n shared UI, but don't create layouts unnecessarily\n- ❌ **Forgetting `{userContent}
\n```\n\n### Secure Headers\n\nEpic Stack uses Helmet for secure headers.\n\n**Configuration:**\n\n```typescript\nimport { helmet } from '@nichtsam/helmet/node-http'\n\napp.use((_, res, next) => {\n\thelmet(res, { general: { referrerPolicy: false } })\n\tnext()\n})\n```\n\n**Included headers:**\n\n- X-Content-Type-Options: nosniff\n- X-Frame-Options: DENY\n- X-XSS-Protection: 1; mode=block\n- Referrer-Policy (configurable)\n\n### HTTPS Only\n\n**Redirect HTTP to HTTPS:**\n\n```typescript\napp.use((req, res, next) => {\n\tif (req.method !== 'GET') return next()\n\tconst proto = req.get('X-Forwarded-Proto')\n\tconst host = getHost(req)\n\tif (proto === 'http') {\n\t\tres.set('X-Forwarded-Proto', 'https')\n\t\tres.redirect(`https://${host}${req.originalUrl}`)\n\t\treturn\n\t}\n\tnext()\n})\n```\n\n### Secrets Management\n\n**Variables de entorno:**\n\n```bash\n# .env\nSESSION_SECRET=secret1,secret2,secret3 # Secret rotation\nHONEYPOT_SECRET=your-honeypot-secret\nDATABASE_URL=file:./data/db.sqlite\n```\n\n**En Fly.io:**\n\n```bash\nfly secrets set SESSION_SECRET=\"secret1,secret2,secret3\"\nfly secrets set HONEYPOT_SECRET=\"your-secret\"\n```\n\n**Never commit secrets:**\n\n- Use `.env.example` to document required variables\n- `.env` is in `.gitignore`\n- Use `fly secrets` for production\n\n### Validación de Session Expiration (Fail Fast)\n\n**Always verify expiration early:**\n\n```typescript\nexport async function getUserId(request: Request) {\n\tconst authSession = await authSessionStorage.getSession(\n\t\trequest.headers.get('cookie'),\n\t)\n\tconst sessionId = authSession.get(sessionKey)\n\n\t// Fail fast - return null immediately if no session\n\tif (!sessionId) return null\n\n\t// Verify expiration early - fail fast if expired\n\tconst session = await prisma.session.findUnique({\n\t\tselect: { userId: true },\n\t\twhere: {\n\t\t\tid: sessionId,\n\t\t\texpirationDate: { gt: new Date() }, // Verify expiration\n\t\t},\n\t})\n\n\t// Fail fast - destroy invalid session immediately\n\tif (!session?.userId) {\n\t\tthrow redirect('/', {\n\t\t\theaders: {\n\t\t\t\t'set-cookie': await authSessionStorage.destroySession(authSession),\n\t\t\t},\n\t\t})\n\t}\n\treturn session.userId\n}\n```\n\n## Common examples\n\n### Example 1: Public form with honeypot\n\n```typescript\n// app/routes/_auth/signup.tsx\nimport { HoneypotInputs } from 'remix-utils/honeypot/react'\nimport { checkHoneypot } from '#app/utils/honeypot.server.ts'\n\nexport async function action({ request }: Route.ActionArgs) {\n\tconst formData = await request.formData()\n\n\tawait checkHoneypot(formData) // Spam protection\n\n\tconst submission = await parseWithZod(formData, {\n\t\tschema: SignupSchema,\n\t})\n\n\t// ... rest of code\n}\n\nexport default function SignupRoute({ actionData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Example 2: Custom rate limiting\n\n```typescript\n// server/index.ts\nconst apiRateLimit = rateLimit({\n\t...rateLimitDefault,\n\twindowMs: 60 * 1000,\n\tlimit: 100, // 100 requests per minute for API\n\tkeyGenerator: (req) => {\n\t\tconst apiKey = req.get('X-API-Key')\n\t\treturn apiKey ?? req.get('fly-client-ip') ?? req.ip\n\t},\n})\n\napp.use('/api', apiRateLimit)\n```\n\n### Example 3: Strict input validation\n\n```typescript\n// app/utils/user-validation.ts\nimport { z } from 'zod'\n\nexport const EmailSchema = z\n\t.string({ required_error: 'Email is required' })\n\t.email({ message: 'Email is invalid' })\n\t.min(3, { message: 'Email is too short' })\n\t.max(100, { message: 'Email is too long' })\n\t.transform((value) => value.toLowerCase().trim()) // Sanitization\n\nexport const UsernameSchema = z\n\t.string({ required_error: 'Username is required' })\n\t.min(3, { message: 'Username is too short' })\n\t.max(20, { message: 'Username is too long' })\n\t.regex(/^[a-zA-Z0-9_]+$/, {\n\t\tmessage: 'Username can only include letters, numbers, and underscores',\n\t})\n\t.transform((value) => value.toLowerCase().trim()) // Sanitization\n\nexport const PasswordSchema = z\n\t.string({ required_error: 'Password is required' })\n\t.min(6, { message: 'Password is too short' })\n\t.refine((val) => new TextEncoder().encode(val).length <= 72, {\n\t\tmessage: 'Password is too long', // bcrypt limit\n\t})\n```\n\n### Example 4: Permission verification before actions\n\n```typescript\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\n\t// Validate that user has permission\n\tawait requireUserWithPermission(request, 'delete:note:own')\n\n\t// Only after validating permissions\n\tawait prisma.note.delete({ where: { id: noteId } })\n\n\treturn redirect('/notes')\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Delayed security checks**: Validate authentication, authorization, and\n input as early as possible - fail fast\n- ❌ **Generic error messages**: Provide clear, actionable error messages that\n help with debugging (without exposing sensitive data)\n- ❌ **Forgetting honeypot in public forms**: Always include `HoneypotInputs` in\n forms accessible without authentication\n- ❌ **Not validating session expiration**: Always verify `expirationDate` when\n getting sessions - check early\n- ❌ **Using `dangerouslySetInnerHTML` with user data**: Never render user HTML\n without sanitizing\n- ❌ **Not using rate limiting**: Protect sensitive routes with rate limiting\n- ❌ **Secrets in code**: Never hardcode secrets, use environment variables\n- ❌ **Not sanitizing inputs**: Always sanitize inputs with `.transform()` from\n Zod\n- ❌ **Not validating common passwords**: Check passwords against Have I Been\n Pwned\n- ❌ **Sessions without httpOnly**: Always use `httpOnly: true` in session\n cookies\n- ❌ **Not using HTTPS in production**: Make sure to redirect HTTP to HTTPS\n- ❌ **CSP too permissive**: Review and adjust CSP according to your needs\n- ❌ **Not logging security events**: Log security failures with context for\n debugging (without sensitive data)\n\n## References\n\n- [Epic Stack Security Docs](../epic-stack/docs/security.md)\n- [Epic Web Principles](https://www.epicweb.dev/principles)\n- [OWASP Top 10](https://owasp.org/www-project-top-ten/)\n- [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)\n- `app/utils/honeypot.server.ts` - Honeypot implementation\n- `server/index.ts` - Server security configuration\n- `docs/decisions/033-honeypot.md` - Honeypot documentation\n- `docs/decisions/025-rate-limiting.md` - Rate limiting documentation\n- `docs/decisions/008-content-security-policy.md` - CSP documentation\n","docs/skills/epic-testing/SKILL.md":"---\nname: epic-testing\ndescription: Guide on testing with Vitest and Playwright for Epic Stack\ncategories:\n - testing\n - vitest\n - playwright\n - e2e\n---\n\n# Epic Stack: Testing\n\n## When to use this skill\n\nUse this skill when you need to:\n\n- Write unit tests for utilities and components\n- Create E2E tests with Playwright\n- Test forms and validation\n- Test routes and loaders\n- Mock external services with MSW\n- Test authentication and permissions\n- Configure test database\n\n## Patterns and conventions\n\n### Testing Philosophy\n\nFollowing Epic Web principles:\n\n**Tests should resemble users** - Write tests that mirror how real users\ninteract with your application. Test user workflows, not implementation details.\nIf a user would click a button, your test should click that button. If a user\nwould see an error message, your test should check for that specific message.\n\n**Make assertions specific** - Be explicit about what you're testing. Instead of\nvague assertions, use specific, meaningful checks that clearly communicate the\nexpected behavior. This makes tests easier to understand and debug when they\nfail.\n\n**Example - Tests that resemble users:**\n\n```typescript\n// ✅ Good - Tests user workflow\ntest('User can sign up and create their first note', async ({ page, navigate }) => {\n\t// User visits signup page\n\tawait navigate('/signup')\n\n\t// User fills out form like a real person would\n\tawait page.getByRole('textbox', { name: /email/i }).fill('newuser@example.com')\n\tawait page.getByRole('textbox', { name: /username/i }).fill('newuser')\n\tawait page.getByRole('textbox', { name: /^password$/i }).fill('securepassword123')\n\tawait page.getByRole('textbox', { name: /confirm/i }).fill('securepassword123')\n\n\t// User submits form\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// User is redirected to onboarding\n\tawait expect(page).toHaveURL(/\\/onboarding/)\n\n\t// User creates their first note\n\tawait navigate('/notes/new')\n\tawait page.getByRole('textbox', { name: /title/i }).fill('My First Note')\n\tawait page.getByRole('textbox', { name: /content/i }).fill('This is my first note!')\n\tawait page.getByRole('button', { name: /create/i }).click()\n\n\t// User sees their note\n\tawait expect(page.getByRole('heading', { name: 'My First Note' })).toBeVisible()\n\tawait expect(page.getByText('This is my first note!')).toBeVisible()\n})\n\n// ❌ Avoid - Testing implementation details\ntest('Signup form calls API endpoint', async ({ page }) => {\n\t// This tests implementation, not user experience\n\tconst response = await page.request.post('/signup', { data: {...} })\n\texpect(response.status()).toBe(200)\n})\n```\n\n**Example - Specific assertions:**\n\n```typescript\n// ✅ Good - Specific assertions\ntest('Form shows specific validation errors', async ({ page, navigate }) => {\n\tawait navigate('/signup')\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// Specific error messages that users would see\n\tawait expect(page.getByText(/email is required/i)).toBeVisible()\n\tawait expect(\n\t\tpage.getByText(/username must be at least 3 characters/i),\n\t).toBeVisible()\n\tawait expect(\n\t\tpage.getByText(/password must be at least 6 characters/i),\n\t).toBeVisible()\n})\n\n// ❌ Avoid - Vague assertions\ntest('Form shows errors', async ({ page, navigate }) => {\n\tawait navigate('/signup')\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// Too vague - what errors? where?\n\texpect(page.locator('.error')).toBeVisible()\n})\n```\n\n### Two Types of Tests\n\nEpic Stack uses two types of tests:\n\n1. **Unit Tests with Vitest** - Tests for individual components and utilities\n2. **E2E Tests with Playwright** - End-to-end tests of the complete flow\n\n### Unit Tests with Vitest\n\n**Basic setup:**\n\n```typescript\n// app/utils/my-util.test.ts\nimport { describe, expect, it } from 'vitest'\nimport { myUtil } from './my-util.ts'\n\ndescribe('myUtil', () => {\n\tit('should do something', () => {\n\t\texpect(myUtil('input')).toBe('expected')\n\t})\n})\n```\n\n**Testing con DOM:**\n\n```typescript\nimport { describe, expect, it } from 'vitest'\nimport { render, screen } from '@testing-library/react'\nimport { MyComponent } from './my-component.tsx'\n\ndescribe('MyComponent', () => {\n\tit('should render correctly', () => {\n\t\trender(\n\t
\n```\n\n### Form Accessibility\n\n**✅ Good - Always use labels:**\n\n```typescript\nimport { Field } from '#app/components/forms.tsx'\n\n{user.name}
\n\t{user.bio}
\n\t{formatDate(user.createdAt)}
\n\n\t\t\t{children}\n\t\t
\n\t)\n}\n```\n\n**✅ Good - Use Tailwind responsive utilities:**\n\n```typescript\n\n\t{items.map(item => (\n\t\t{item.name} \n\t))}\n
\n```\n\n**✅ Good - Use Tailwind dark mode:**\n\n```typescript\n\n\t{content}\n
\n```\n\n### Error Handling in Forms\n\n**✅ Good - Display errors accessibly:**\n\n```typescript\nimport { Field, ErrorList } from '#app/components/forms.tsx'\n\n // High contrast\n\n\t\t\t \n\t)\n}\n```\n\n**❌ Avoid - Large monolithic components:**\n\n```typescript\n// ❌ Don't put everything in one component\nfunction UserProfile({ user }: { user: User }) {\n\treturn (\n\t\t (\n\t\t\t\t\t\n\t\t\t \n\t)\n}, (prev, next) => prev.user.id === next.user.id)\n\nfunction UserList({ users }: { users: User[] }) {\n\treturn (\n\t\tLoading...
}>\n\t\t\t // Accessible links\n```\n\n**❌ Avoid - Low contrast text:**\n\n```typescript\n// ❌ Don't use low contrast\n\n\t\n\t\t{/* Focus is trapped inside dialog */}\n\t\tClose \n\t \n \n```\n\n### Focus Management for React Router\n\n**✅ Good - Focus on route changes:**\n\n```typescript\nimport { useEffect } from 'react'\nimport { useNavigation } from 'react-router'\n\nfunction RouteComponent() {\n\tconst navigation = useNavigation()\n\tconst mainRef = useRef(null)\n\n\tuseEffect(() => {\n\t\tif (navigation.state === 'idle' && mainRef.current) {\n\t\t\tmainRef.current.focus()\n\t\t}\n\t}, [navigation.state])\n\n\treturn (\n\t\t\n\t\t\t{/* Content */}\n\t\t \n\t)\n}\n```\n\n**✅ Good - Focus on errors:**\n\n```typescript\nimport { useEffect, useRef } from 'react'\n\nfunction FormWithErrorFocus({ actionData }: Route.ComponentProps) {\n\tconst firstErrorRef = useRef(null)\n\n\tuseEffect(() => {\n\t\tif (actionData?.errors && firstErrorRef.current) {\n\t\t\t// Focus first error field\n\t\t\tfirstErrorRef.current.focus()\n\t\t\t// Announce error\n\t\t\tfirstErrorRef.current.setAttribute('aria-invalid', 'true')\n\t\t}\n\t}, [actionData?.errors])\n\n\treturn `, ``, `
}>\n\t\t\t // Very low contrast\n```\n\n### Responsive Design\n\n**✅ Good - Mobile-first approach:**\n\n```typescript\n\n\t\t\t{isSubmitting ? 'Saving...' : 'Save'}\n\t\t\n\t)\n}\n```\n\n### Icon Usage\n\n**✅ Good - Decorative icons:**\n\n```typescript\nimport { Icon } from '#app/components/ui/icon.tsx'\n\n\n```\n\n**✅ Good - Semantic icons:**\n\n```typescript\n\n```\n\n### Skip Links\n\n**✅ Good - Add skip to main content:**\n\n```typescript\n// In your root layout\n\n\tSkip to main content\n\n\n\n\t{/* Main content */}\n \n```\n\n### Progressive Enhancement\n\n**✅ Good - Forms work without JavaScript:**\n\n```typescript\n// Conform forms work without JavaScript\n\n```\n\nForms automatically:\n\n- Submit via native HTML forms if JavaScript is disabled\n- Validate server-side\n- Show errors appropriately\n\n### Screen Reader Best Practices\n\n**✅ Good - Use semantic HTML first:**\n\n```typescript\n// ✅ Semantic HTML provides context automatically\n\n```\n\n**✅ Good - Announce dynamic content:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction SearchResults({ results }: { results: Result[] }) {\n\tconst navigation = useNavigation()\n\tconst isSearching = navigation.state === 'loading'\n\n\treturn (\n\t\t\n\t\t\t{isSearching ? 'Searching...' : `${results.length} results found`}\n\t\t
\n\t)\n}\n```\n\n**✅ Good - Live regions for important updates:**\n\n```typescript\nfunction ToastContainer({ toasts }: { toasts: Toast[] }) {\n\treturn (\n\t\t\n\t{/* Content */}\n
\n```\n\n**✅ Good - Responsive typography:**\n\n```typescript\n\n\tResponsive Heading\n
\n```\n\n### Loading States\n\n**✅ Good - Accessible loading indicators:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction SubmitButton() {\n\tconst navigation = useNavigation()\n\tconst isSubmitting = navigation.state === 'submitting'\n\n\treturn (\n\t\t\n\t\t\t{toasts.map(toast => (\n\t\t\t\t
\n\t)\n}\n```\n\n**ARIA live region options:**\n\n- `aria-live=\"polite\"` - For non-critical updates (search results, status\n messages)\n- `aria-live=\"assertive\"` - For critical updates (errors, confirmations)\n- `aria-atomic=\"true\"` - Screen reader reads entire region on update\n- `aria-atomic=\"false\"` - Screen reader reads only changed parts\n\n### Keyboard Navigation Patterns\n\n**✅ Good - Tab order follows visual order:**\n\n```typescript\n// Elements appear in logical tab order\n\n```\n\n**✅ Good - Keyboard shortcuts:**\n\n```typescript\nimport { useEffect } from 'react'\n\nfunction SearchDialog({ onClose }: { onClose: () => void }) {\n\tuseEffect(() => {\n\t\tfunction handleKeyDown(e: KeyboardEvent) {\n\t\t\tif (e.key === 'Escape') {\n\t\t\t\tonClose()\n\t\t\t}\n\t\t}\n\n\t\twindow.addEventListener('keydown', handleKeyDown)\n\t\treturn () => window.removeEventListener('keydown', handleKeyDown)\n\t}, [onClose])\n\n\treturn \n}\n```\n\n**✅ Good - Focus trap in modals:**\n\n```typescript\n// Radix Dialog automatically handles focus trap\n\n\t\t\t\t\t{toast.message}\n\t\t\t\t
\n\t\t\t))}\n\t\tReadable body text
\nClear headings
\n```\n\n**✅ Good - Sufficient line height:**\n\n```typescript\n// Tailwind defaults provide good line height\nComfortable reading
\n```\n\n**❌ Avoid - Small or hard-to-read text:**\n\n```typescript\n// ❌ Don't use very small text\nHard to read
\n```\n\n### Touch Target Sizes\n\n**✅ Good - Sufficient touch targets:**\n\n```typescript\n// Buttons should be at least 44x44px (touch target size)\n\n```\n\n**✅ Good - Spacing between interactive elements:**\n\n```typescript\n\n\t\n\t\n
\n```\n\n### Internationalization (i18n) Considerations\n\n**✅ Good - Use semantic HTML for dates/times:**\n\n```typescript\n\n```\n\n**✅ Good - Use semantic HTML for numbers:**\n\n```typescript\n// Screen readers can pronounce numbers correctly\nTotal: {count}
\n```\n\n**✅ Good - Language attributes:**\n\n```typescript\n// In root.tsx\n\n\t\n\t\t{/* Content */}\n\t\n\n```\n\n### Dark Mode Accessibility\n\n**✅ Good - Maintain contrast in dark mode:**\n\n```typescript\n// Ensure sufficient contrast in both modes\n\n\t{content}\n
\n```\n\n**✅ Good - Respect user preference:**\n\n```typescript\n// Epic Stack automatically handles theme preference\n// Use semantic colors that work in both modes\n\n```\n\n### Animation and Motion\n\n**✅ Good - Respect reduced motion:**\n\n```typescript\n// Tailwind automatically respects prefers-reduced-motion\n\n\t{/* Animations disabled for users who prefer reduced motion */}\n
\n```\n\n**✅ Good - Use CSS for animations:**\n\n```typescript\n// ✅ CSS animations can be disabled via prefers-reduced-motion\n\n\t{/* Content */}\n
\n\n// ❌ JavaScript animations may not respect user preferences\n```\n\n## Common mistakes to avoid\n\n- ❌ **Treating accessibility as a checklist**: Accessibility is about serving\n real people, not just meeting standards\n- ❌ **Missing form labels**: Always use `Field` component which includes\n labels - helps all users, not just screen reader users\n- ❌ **Using divs for semantic elements**: Use `- \n\t\t\t{sortedUsers.map(user => (\n\t\t\t\t
- {user.name} \n\t\t\t))}\n\t\t
\n\t\t\t
\n\t)\n}\n```\n\n### Error Boundaries\n\n**✅ Good - Use error boundaries:**\n\n```typescript\n// app/routes/users/$username.tsx\nexport function ErrorBoundary() {\n\treturn (\n\t\t\n\t\t\t\t\n\t\t\t\t
\n\t\t\t{user.name}
\n\t\t\t\n\t\t\t\t
\n\t\t\t{user.email}
\n\t\t\t\t{user.bio}
\n\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t
\n\t\tUser \"{params.username}\" not found
\n\t\t\t\t),\n\t\t\t}}\n\t\t/>\n\t)\n}\n```\n\n### TypeScript Guidelines\n\n**✅ Good - Type props explicitly:**\n\n```typescript\ninterface UserCardProps {\n\tuser: {\n\t\tid: string\n\t\tname: string\n\t\temail: string\n\t}\n\tonEdit?: (userId: string) => void\n}\n\nfunction UserCard({ user, onEdit }: UserCardProps) {\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n```\n\n**✅ Good - Use Route types:**\n\n```typescript\nimport type { Route } from './+types/users.$username'\n\nexport async function loader({ params }: Route.LoaderArgs) {\n\t// params is type-safe!\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\treturn { user }\n}\n\nexport default function UserRoute({ loaderData }: Route.ComponentProps) {\n\t// loaderData is type-safe!\n\treturn {user.name}
\n\t\t\t{user.email}
\n\t\t\t{onEdit && }\n\t\t{loaderData.user.name}
\n}\n```\n\n### Loading States\n\n**✅ Good - Use React Router's pending states:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction NoteForm() {\n\tconst navigation = useNavigation()\n\tconst isSubmitting = navigation.state === 'submitting'\n\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Preventing Data Fetching Waterfalls\n\nReact Router loaders can prevent waterfalls by fetching data in parallel.\n\n**❌ Avoid - Sequential data fetching (waterfall):**\n\n```typescript\n// ❌ Don't do this - creates a waterfall\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\t// Second fetch waits for first to complete\n\tconst notes = await prisma.note.findMany({\n\t\twhere: { ownerId: user.id },\n\t})\n\treturn { user, notes }\n}\n```\n\n**✅ Good - Parallel data fetching:**\n\n```typescript\n// ✅ Fetch data in parallel\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true, username: true, name: true },\n\t})\n\n\t// Fetch notes in parallel with user data\n\tconst [notes, stats] = await Promise.all([\n\t\tuser\n\t\t\t? prisma.note.findMany({\n\t\t\t\t\twhere: { ownerId: user.id },\n\t\t\t\t\tselect: { id: true, title: true, updatedAt: true },\n\t\t\t\t})\n\t\t\t: Promise.resolve([]),\n\t\tuser\n\t\t\t? prisma.note.count({ where: { ownerId: user.id } })\n\t\t\t: Promise.resolve(0),\n\t])\n\n\treturn { user, notes, stats }\n}\n```\n\n**✅ Good - Nested route parallel loading:**\n\n```typescript\n// Parent route loader\n// app/routes/users/$username.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true, username: true, name: true },\n\t})\n\treturn { user }\n}\n\n// Child route loader runs in parallel\n// app/routes/users/$username/notes.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true },\n\t})\n\n\tif (!user) {\n\t\tthrow new Response('Not Found', { status: 404 })\n\t}\n\n\tconst notes = await prisma.note.findMany({\n\t\twhere: { ownerId: user.id },\n\t\tselect: { id: true, title: true, updatedAt: true },\n\t})\n\n\treturn { notes }\n}\n```\n\n### Server-Side Rendering (SSR) Performance\n\nReact Router provides SSR by default. Optimize by:\n\n**✅ Good - Selective data fetching:**\n\n```typescript\nexport async function loader({ request }: Route.LoaderArgs) {\n\t// Only fetch what's needed for initial render\n\tconst searchParams = new URL(request.url).searchParams\n\tconst page = Number(searchParams.get('page') || '1')\n\n\tconst [items, total] = await Promise.all([\n\t\tprisma.item.findMany({\n\t\t\ttake: 20,\n\t\t\tskip: (page - 1) * 20,\n\t\t\tselect: { id: true, title: true }, // Only needed fields\n\t\t}),\n\t\tprisma.item.count(),\n\t])\n\n\treturn { items, total, page }\n}\n```\n\n**✅ Good - Use caching for expensive operations:**\n\n```typescript\nimport { cachified, cache } from '#app/utils/cache.server.ts'\n\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst timings: Timings = {}\n\n\t// Cache expensive database queries\n\tconst stats = await cachified({\n\t\tkey: 'user-stats',\n\t\tcache,\n\t\ttimings,\n\t\tgetFreshValue: async () => {\n\t\t\treturn await prisma.user.aggregate({\n\t\t\t\t_count: { id: true },\n\t\t\t})\n\t\t},\n\t\tttl: 1000 * 60 * 5, // 5 minutes\n\t})\n\n\treturn { stats }\n}\n```\n\n### Rendering Performance\n\n**✅ Good - Use React.memo for expensive components:**\n\n```typescript\nimport { memo } from 'react'\n\nconst ExpensiveChart = memo(function ExpensiveChart({ data }: { data: Data[] }) {\n\t// Expensive rendering logic\n\treturn {user.name}
\n\t\t\t{user.email}
\n\t\t- \n\t\t\t{users.map(user => (\n\t\t\t\t
{loaderData.user.name}
\n}\n\n// ❌ Avoid - Over-engineered route structure\n// app/routes/users/$username/_layout.tsx\n// app/routes/users/$username/index.tsx\n// app/routes/users/$username/_components/UserHeader.tsx\n// app/routes/users/$username/_components/UserDetails.tsx\n// Unnecessary complexity for a simple user page\n```\n\n**Example - Add complexity only when needed:**\n\n```typescript\n// ✅ Good - Add nested routes only when you actually need them\n// If you have user notes, then nested routes make sense:\n// app/routes/users/$username/notes/_layout.tsx\n// app/routes/users/$username/notes/index.tsx\n// app/routes/users/$username/notes/$noteId.tsx\n\n// ❌ Avoid - Creating nested routes \"just in case\"\n// Don't create complex structures before you need them\n```\n\n### File-based routing with react-router-auto-routes\n\nEpic Stack uses `react-router-auto-routes` instead of React Router's standard\nconvention. This enables better organization and code co-location.\n\n**Basic structure:**\n\n```\napp/routes/\n├── _layout.tsx # Layout for child routes\n├── index.tsx # Root route (/)\n├── about.tsx # Route /about\n└── users/\n ├── _layout.tsx # Layout for user routes\n ├── index.tsx # Route /users\n └── $username/\n └── index.tsx # Route /users/:username\n```\n\n**Configuration in `app/routes.ts`:**\n\n```typescript\nimport { type RouteConfig } from '@react-router/dev/routes'\nimport { autoRoutes } from 'react-router-auto-routes'\n\nexport default autoRoutes({\n\tignoredRouteFiles: [\n\t\t'.*',\n\t\t'**/*.css',\n\t\t'**/*.test.{js,jsx,ts,tsx}',\n\t\t'**/__*.*',\n\t\t'**/*.server.*', // Co-located server utilities\n\t\t'**/*.client.*', // Co-located client utilities\n\t],\n}) satisfies RouteConfig\n```\n\n### Route Groups\n\nRoute groups are folders that start with `_` and don't affect the URL but help\norganize related code.\n\n**Common examples:**\n\n- `_auth/` - Authentication routes (login, signup, etc.)\n- `_marketing/` - Marketing pages (home, about, etc.)\n- `_seo/` - SEO routes (sitemap, robots.txt)\n\n**Example:**\n\n```\napp/routes/\n├── _auth/\n│ ├── login.tsx # URL: /login\n│ ├── signup.tsx # URL: /signup\n│ └── forgot-password.tsx # URL: /forgot-password\n└── _marketing/\n ├── index.tsx # URL: /\n └── about.tsx # URL: /about\n```\n\n### Route Parameters\n\nUse `$` to indicate route parameters:\n\n**Syntax:**\n\n- `$param.tsx` → `:param` in URL\n- `$username.tsx` → `:username` in URL\n\n**Example route with parameter:**\n\n```typescript\n// app/routes/users/$username/index.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst username = params.username // Type-safe!\n\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username },\n\t})\n\n\treturn { user }\n}\n```\n\n### Nested Layouts with `_layout.tsx`\n\nUse `_layout.tsx` to create shared layouts for child routes.\n\n**Example:**\n\n```typescript\n// app/routes/users/$username/notes/_layout.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst owner = await prisma.user.findFirst({\n\t\twhere: { username: params.username },\n\t})\n\treturn { owner }\n}\n\nexport default function NotesLayout({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t{loaderData.owner.name}'s Notes
\n\t\t\t{/* Use loaderData.data */}
\n}\n```\n\n**Action pattern:**\n\n```typescript\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\tconst formData = await request.formData()\n\n\t// Validate and process data\n\tawait prisma.something.create({\n\t\tdata: { /* ... */ },\n\t})\n\n\treturn redirect('/success')\n}\n\nexport default function RouteComponent() {\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Search Params\n\nAccess query parameters using `useSearchParams`:\n\n```typescript\nimport { useSearchParams } from 'react-router'\n\nexport default function SearchPage() {\n\tconst [searchParams, setSearchParams] = useSearchParams()\n\tconst query = searchParams.get('q') || ''\n\tconst page = Number(searchParams.get('page') || '1')\n\n\treturn (\n\t\t\n\t\t\t setSearchParams({ q: e.target.value })}\n\t\t\t/>\n\t\t\t{/* Results */}\n\t\t
\n\t)\n}\n```\n\n### Code Co-location\n\nEpic Stack encourages placing related code close to where it's used.\n\n**Typical structure:**\n\n```\napp/routes/users/$username/notes/\n├── _layout.tsx # Layout with loader\n├── index.tsx # Notes list\n├── $noteId.tsx # Note view\n├── $noteId_.edit.tsx # Edit note\n├── +shared/ # Code shared between routes\n│ └── note-editor.tsx # Shared editor\n└── $noteId.server.ts # Server-side utilities\n```\n\nThe `+` prefix indicates co-located modules that are not routes.\n\n### Naming Conventions\n\n- `_layout.tsx` - Layout for child routes\n- `index.tsx` - Root route of the segment\n- `$param.tsx` - Route parameter\n- `$param_.action.tsx` - Route with parameter + action (using `_`)\n- `[.]ext.tsx` - Resource route (e.g., `robots[.]txt.ts`)\n\n## Common examples\n\n### Example 1: Create a basic route with layout\n\n```typescript\n// app/routes/products/_layout.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst categories = await prisma.category.findMany()\n\treturn { categories }\n}\n\nexport default function ProductsLayout({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t\t\t\n\t\t\t
\n\t)\n}\n\n// app/routes/products/index.tsx\nexport default function ProductsIndex() {\n\treturn Products list
\n}\n```\n\n### Example 2: Route with dynamic parameter\n\n```typescript\n// app/routes/products/$slug.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst product = await prisma.product.findUnique({\n\t\twhere: { slug: params.slug },\n\t})\n\n\tif (!product) {\n\t\tthrow new Response('Not Found', { status: 404 })\n\t}\n\n\treturn { product }\n}\n\nexport default function ProductPage({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n\nexport function ErrorBoundary() {\n\treturn (\n\t\t{loaderData.product.name}
\n\t\t\t{loaderData.product.description}
\n\t\tProduct \"{params.slug}\" not found
\n\t\t\t\t),\n\t\t\t}}\n\t\t/>\n\t)\n}\n```\n\n### Example 3: Resource route for download\n\n```typescript\n// app/routes/resources/download-report.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst userId = await requireUserId(request)\n\n\tconst report = await generateReport(userId)\n\n\treturn new Response(report, {\n\t\theaders: {\n\t\t\t'Content-Type': 'application/pdf',\n\t\t\t'Content-Disposition': 'attachment; filename=\"report.pdf\"',\n\t\t},\n\t})\n}\n```\n\n### Example 4: Route with multiple nested parameters\n\n```typescript\n// app/routes/users/$username/posts/$postId/comments/$commentId.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\t// params contains: { username, postId, commentId }\n\tconst comment = await prisma.comment.findUnique({\n\t\twhere: { id: params.commentId },\n\t\tinclude: {\n\t\t\tpost: {\n\t\t\t\tinclude: { author: true },\n\t\t\t},\n\t\t},\n\t})\n\n\treturn { comment }\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Over-engineering route structure**: Keep routes simple - don't create\n complex nested structures unless you actually need them\n- ❌ **Creating abstractions prematurely**: Start with simple routes, add\n complexity only when there's a clear benefit\n- ❌ **Using React Router's standard convention**: Epic Stack uses\n `react-router-auto-routes`, not the standard convention\n- ❌ **Exporting default component in resource routes**: Resource routes should\n not export components\n- ❌ **Not using nested layouts when needed**: Use `_layout.tsx` when you have\n shared UI, but don't create layouts unnecessarily\n- ❌ **Forgetting `{userContent}
\n```\n\n### Secure Headers\n\nEpic Stack uses Helmet for secure headers.\n\n**Configuration:**\n\n```typescript\nimport { helmet } from '@nichtsam/helmet/node-http'\n\napp.use((_, res, next) => {\n\thelmet(res, { general: { referrerPolicy: false } })\n\tnext()\n})\n```\n\n**Included headers:**\n\n- X-Content-Type-Options: nosniff\n- X-Frame-Options: DENY\n- X-XSS-Protection: 1; mode=block\n- Referrer-Policy (configurable)\n\n### HTTPS Only\n\n**Redirect HTTP to HTTPS:**\n\n```typescript\napp.use((req, res, next) => {\n\tif (req.method !== 'GET') return next()\n\tconst proto = req.get('X-Forwarded-Proto')\n\tconst host = getHost(req)\n\tif (proto === 'http') {\n\t\tres.set('X-Forwarded-Proto', 'https')\n\t\tres.redirect(`https://${host}${req.originalUrl}`)\n\t\treturn\n\t}\n\tnext()\n})\n```\n\n### Secrets Management\n\n**Variables de entorno:**\n\n```bash\n# .env\nSESSION_SECRET=secret1,secret2,secret3 # Secret rotation\nHONEYPOT_SECRET=your-honeypot-secret\nDATABASE_URL=file:./data/db.sqlite\n```\n\n**En Fly.io:**\n\n```bash\nfly secrets set SESSION_SECRET=\"secret1,secret2,secret3\"\nfly secrets set HONEYPOT_SECRET=\"your-secret\"\n```\n\n**Never commit secrets:**\n\n- Use `.env.example` to document required variables\n- `.env` is in `.gitignore`\n- Use `fly secrets` for production\n\n### Validación de Session Expiration (Fail Fast)\n\n**Always verify expiration early:**\n\n```typescript\nexport async function getUserId(request: Request) {\n\tconst authSession = await authSessionStorage.getSession(\n\t\trequest.headers.get('cookie'),\n\t)\n\tconst sessionId = authSession.get(sessionKey)\n\n\t// Fail fast - return null immediately if no session\n\tif (!sessionId) return null\n\n\t// Verify expiration early - fail fast if expired\n\tconst session = await prisma.session.findUnique({\n\t\tselect: { userId: true },\n\t\twhere: {\n\t\t\tid: sessionId,\n\t\t\texpirationDate: { gt: new Date() }, // Verify expiration\n\t\t},\n\t})\n\n\t// Fail fast - destroy invalid session immediately\n\tif (!session?.userId) {\n\t\tthrow redirect('/', {\n\t\t\theaders: {\n\t\t\t\t'set-cookie': await authSessionStorage.destroySession(authSession),\n\t\t\t},\n\t\t})\n\t}\n\treturn session.userId\n}\n```\n\n## Common examples\n\n### Example 1: Public form with honeypot\n\n```typescript\n// app/routes/_auth/signup.tsx\nimport { HoneypotInputs } from 'remix-utils/honeypot/react'\nimport { checkHoneypot } from '#app/utils/honeypot.server.ts'\n\nexport async function action({ request }: Route.ActionArgs) {\n\tconst formData = await request.formData()\n\n\tawait checkHoneypot(formData) // Spam protection\n\n\tconst submission = await parseWithZod(formData, {\n\t\tschema: SignupSchema,\n\t})\n\n\t// ... rest of code\n}\n\nexport default function SignupRoute({ actionData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Example 2: Custom rate limiting\n\n```typescript\n// server/index.ts\nconst apiRateLimit = rateLimit({\n\t...rateLimitDefault,\n\twindowMs: 60 * 1000,\n\tlimit: 100, // 100 requests per minute for API\n\tkeyGenerator: (req) => {\n\t\tconst apiKey = req.get('X-API-Key')\n\t\treturn apiKey ?? req.get('fly-client-ip') ?? req.ip\n\t},\n})\n\napp.use('/api', apiRateLimit)\n```\n\n### Example 3: Strict input validation\n\n```typescript\n// app/utils/user-validation.ts\nimport { z } from 'zod'\n\nexport const EmailSchema = z\n\t.string({ required_error: 'Email is required' })\n\t.email({ message: 'Email is invalid' })\n\t.min(3, { message: 'Email is too short' })\n\t.max(100, { message: 'Email is too long' })\n\t.transform((value) => value.toLowerCase().trim()) // Sanitization\n\nexport const UsernameSchema = z\n\t.string({ required_error: 'Username is required' })\n\t.min(3, { message: 'Username is too short' })\n\t.max(20, { message: 'Username is too long' })\n\t.regex(/^[a-zA-Z0-9_]+$/, {\n\t\tmessage: 'Username can only include letters, numbers, and underscores',\n\t})\n\t.transform((value) => value.toLowerCase().trim()) // Sanitization\n\nexport const PasswordSchema = z\n\t.string({ required_error: 'Password is required' })\n\t.min(6, { message: 'Password is too short' })\n\t.refine((val) => new TextEncoder().encode(val).length <= 72, {\n\t\tmessage: 'Password is too long', // bcrypt limit\n\t})\n```\n\n### Example 4: Permission verification before actions\n\n```typescript\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\n\t// Validate that user has permission\n\tawait requireUserWithPermission(request, 'delete:note:own')\n\n\t// Only after validating permissions\n\tawait prisma.note.delete({ where: { id: noteId } })\n\n\treturn redirect('/notes')\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Delayed security checks**: Validate authentication, authorization, and\n input as early as possible - fail fast\n- ❌ **Generic error messages**: Provide clear, actionable error messages that\n help with debugging (without exposing sensitive data)\n- ❌ **Forgetting honeypot in public forms**: Always include `HoneypotInputs` in\n forms accessible without authentication\n- ❌ **Not validating session expiration**: Always verify `expirationDate` when\n getting sessions - check early\n- ❌ **Using `dangerouslySetInnerHTML` with user data**: Never render user HTML\n without sanitizing\n- ❌ **Not using rate limiting**: Protect sensitive routes with rate limiting\n- ❌ **Secrets in code**: Never hardcode secrets, use environment variables\n- ❌ **Not sanitizing inputs**: Always sanitize inputs with `.transform()` from\n Zod\n- ❌ **Not validating common passwords**: Check passwords against Have I Been\n Pwned\n- ❌ **Sessions without httpOnly**: Always use `httpOnly: true` in session\n cookies\n- ❌ **Not using HTTPS in production**: Make sure to redirect HTTP to HTTPS\n- ❌ **CSP too permissive**: Review and adjust CSP according to your needs\n- ❌ **Not logging security events**: Log security failures with context for\n debugging (without sensitive data)\n\n## References\n\n- [Epic Stack Security Docs](../epic-stack/docs/security.md)\n- [Epic Web Principles](https://www.epicweb.dev/principles)\n- [OWASP Top 10](https://owasp.org/www-project-top-ten/)\n- [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)\n- `app/utils/honeypot.server.ts` - Honeypot implementation\n- `server/index.ts` - Server security configuration\n- `docs/decisions/033-honeypot.md` - Honeypot documentation\n- `docs/decisions/025-rate-limiting.md` - Rate limiting documentation\n- `docs/decisions/008-content-security-policy.md` - CSP documentation\n","docs/skills/epic-testing/SKILL.md":"---\nname: epic-testing\ndescription: Guide on testing with Vitest and Playwright for Epic Stack\ncategories:\n - testing\n - vitest\n - playwright\n - e2e\n---\n\n# Epic Stack: Testing\n\n## When to use this skill\n\nUse this skill when you need to:\n\n- Write unit tests for utilities and components\n- Create E2E tests with Playwright\n- Test forms and validation\n- Test routes and loaders\n- Mock external services with MSW\n- Test authentication and permissions\n- Configure test database\n\n## Patterns and conventions\n\n### Testing Philosophy\n\nFollowing Epic Web principles:\n\n**Tests should resemble users** - Write tests that mirror how real users\ninteract with your application. Test user workflows, not implementation details.\nIf a user would click a button, your test should click that button. If a user\nwould see an error message, your test should check for that specific message.\n\n**Make assertions specific** - Be explicit about what you're testing. Instead of\nvague assertions, use specific, meaningful checks that clearly communicate the\nexpected behavior. This makes tests easier to understand and debug when they\nfail.\n\n**Example - Tests that resemble users:**\n\n```typescript\n// ✅ Good - Tests user workflow\ntest('User can sign up and create their first note', async ({ page, navigate }) => {\n\t// User visits signup page\n\tawait navigate('/signup')\n\n\t// User fills out form like a real person would\n\tawait page.getByRole('textbox', { name: /email/i }).fill('newuser@example.com')\n\tawait page.getByRole('textbox', { name: /username/i }).fill('newuser')\n\tawait page.getByRole('textbox', { name: /^password$/i }).fill('securepassword123')\n\tawait page.getByRole('textbox', { name: /confirm/i }).fill('securepassword123')\n\n\t// User submits form\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// User is redirected to onboarding\n\tawait expect(page).toHaveURL(/\\/onboarding/)\n\n\t// User creates their first note\n\tawait navigate('/notes/new')\n\tawait page.getByRole('textbox', { name: /title/i }).fill('My First Note')\n\tawait page.getByRole('textbox', { name: /content/i }).fill('This is my first note!')\n\tawait page.getByRole('button', { name: /create/i }).click()\n\n\t// User sees their note\n\tawait expect(page.getByRole('heading', { name: 'My First Note' })).toBeVisible()\n\tawait expect(page.getByText('This is my first note!')).toBeVisible()\n})\n\n// ❌ Avoid - Testing implementation details\ntest('Signup form calls API endpoint', async ({ page }) => {\n\t// This tests implementation, not user experience\n\tconst response = await page.request.post('/signup', { data: {...} })\n\texpect(response.status()).toBe(200)\n})\n```\n\n**Example - Specific assertions:**\n\n```typescript\n// ✅ Good - Specific assertions\ntest('Form shows specific validation errors', async ({ page, navigate }) => {\n\tawait navigate('/signup')\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// Specific error messages that users would see\n\tawait expect(page.getByText(/email is required/i)).toBeVisible()\n\tawait expect(\n\t\tpage.getByText(/username must be at least 3 characters/i),\n\t).toBeVisible()\n\tawait expect(\n\t\tpage.getByText(/password must be at least 6 characters/i),\n\t).toBeVisible()\n})\n\n// ❌ Avoid - Vague assertions\ntest('Form shows errors', async ({ page, navigate }) => {\n\tawait navigate('/signup')\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// Too vague - what errors? where?\n\texpect(page.locator('.error')).toBeVisible()\n})\n```\n\n### Two Types of Tests\n\nEpic Stack uses two types of tests:\n\n1. **Unit Tests with Vitest** - Tests for individual components and utilities\n2. **E2E Tests with Playwright** - End-to-end tests of the complete flow\n\n### Unit Tests with Vitest\n\n**Basic setup:**\n\n```typescript\n// app/utils/my-util.test.ts\nimport { describe, expect, it } from 'vitest'\nimport { myUtil } from './my-util.ts'\n\ndescribe('myUtil', () => {\n\tit('should do something', () => {\n\t\texpect(myUtil('input')).toBe('expected')\n\t})\n})\n```\n\n**Testing con DOM:**\n\n```typescript\nimport { describe, expect, it } from 'vitest'\nimport { render, screen } from '@testing-library/react'\nimport { MyComponent } from './my-component.tsx'\n\ndescribe('MyComponent', () => {\n\tit('should render correctly', () => {\n\t\trender({user.name}
\n\t\t\t{user.bio}
\n\t\t\t\n\t\t\n\t
\n```\n\n### Form Accessibility\n\n**✅ Good - Always use labels:**\n\n```typescript\nimport { Field } from '#app/components/forms.tsx'\n\n{user.name}
\n\t{user.bio}
\n\t{formatDate(user.createdAt)}
\n\n\t\t\t{children}\n\t\t
\n\t)\n}\n```\n\n**✅ Good - Use Tailwind responsive utilities:**\n\n```typescript\n\n\t{items.map(item => (\n\t\t{item.name} \n\t))}\n
\n```\n\n**✅ Good - Use Tailwind dark mode:**\n\n```typescript\n\n\t{content}\n
\n```\n\n### Error Handling in Forms\n\n**✅ Good - Display errors accessibly:**\n\n```typescript\nimport { Field, ErrorList } from '#app/components/forms.tsx'\n\n // High contrast\n\n\t\t\t \n\t)\n}\n```\n\n**❌ Avoid - Large monolithic components:**\n\n```typescript\n// ❌ Don't put everything in one component\nfunction UserProfile({ user }: { user: User }) {\n\treturn (\n\t\t (\n\t\t\t\t\t\n\t\t\t \n\t)\n}, (prev, next) => prev.user.id === next.user.id)\n\nfunction UserList({ users }: { users: User[] }) {\n\treturn (\n\t\tLoading...
}>\n\t\t\t // Accessible links\n```\n\n**❌ Avoid - Low contrast text:**\n\n```typescript\n// ❌ Don't use low contrast\n\n\t\n\t\t{/* Focus is trapped inside dialog */}\n\t\tClose \n\t \n \n```\n\n### Focus Management for React Router\n\n**✅ Good - Focus on route changes:**\n\n```typescript\nimport { useEffect } from 'react'\nimport { useNavigation } from 'react-router'\n\nfunction RouteComponent() {\n\tconst navigation = useNavigation()\n\tconst mainRef = useRef(null)\n\n\tuseEffect(() => {\n\t\tif (navigation.state === 'idle' && mainRef.current) {\n\t\t\tmainRef.current.focus()\n\t\t}\n\t}, [navigation.state])\n\n\treturn (\n\t\t\n\t\t\t{/* Content */}\n\t\t \n\t)\n}\n```\n\n**✅ Good - Focus on errors:**\n\n```typescript\nimport { useEffect, useRef } from 'react'\n\nfunction FormWithErrorFocus({ actionData }: Route.ComponentProps) {\n\tconst firstErrorRef = useRef(null)\n\n\tuseEffect(() => {\n\t\tif (actionData?.errors && firstErrorRef.current) {\n\t\t\t// Focus first error field\n\t\t\tfirstErrorRef.current.focus()\n\t\t\t// Announce error\n\t\t\tfirstErrorRef.current.setAttribute('aria-invalid', 'true')\n\t\t}\n\t}, [actionData?.errors])\n\n\treturn `, ``, `
}>\n\t\t\t // Very low contrast\n```\n\n### Responsive Design\n\n**✅ Good - Mobile-first approach:**\n\n```typescript\n\n\t\t\t{isSubmitting ? 'Saving...' : 'Save'}\n\t\t\n\t)\n}\n```\n\n### Icon Usage\n\n**✅ Good - Decorative icons:**\n\n```typescript\nimport { Icon } from '#app/components/ui/icon.tsx'\n\n\n```\n\n**✅ Good - Semantic icons:**\n\n```typescript\n\n```\n\n### Skip Links\n\n**✅ Good - Add skip to main content:**\n\n```typescript\n// In your root layout\n\n\tSkip to main content\n\n\n\n\t{/* Main content */}\n \n```\n\n### Progressive Enhancement\n\n**✅ Good - Forms work without JavaScript:**\n\n```typescript\n// Conform forms work without JavaScript\n\n```\n\nForms automatically:\n\n- Submit via native HTML forms if JavaScript is disabled\n- Validate server-side\n- Show errors appropriately\n\n### Screen Reader Best Practices\n\n**✅ Good - Use semantic HTML first:**\n\n```typescript\n// ✅ Semantic HTML provides context automatically\n\n```\n\n**✅ Good - Announce dynamic content:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction SearchResults({ results }: { results: Result[] }) {\n\tconst navigation = useNavigation()\n\tconst isSearching = navigation.state === 'loading'\n\n\treturn (\n\t\t\n\t\t\t{isSearching ? 'Searching...' : `${results.length} results found`}\n\t\t
\n\t)\n}\n```\n\n**✅ Good - Live regions for important updates:**\n\n```typescript\nfunction ToastContainer({ toasts }: { toasts: Toast[] }) {\n\treturn (\n\t\t\n\t{/* Content */}\n
\n```\n\n**✅ Good - Responsive typography:**\n\n```typescript\n\n\tResponsive Heading\n
\n```\n\n### Loading States\n\n**✅ Good - Accessible loading indicators:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction SubmitButton() {\n\tconst navigation = useNavigation()\n\tconst isSubmitting = navigation.state === 'submitting'\n\n\treturn (\n\t\t\n\t\t\t{toasts.map(toast => (\n\t\t\t\t
\n\t)\n}\n```\n\n**ARIA live region options:**\n\n- `aria-live=\"polite\"` - For non-critical updates (search results, status\n messages)\n- `aria-live=\"assertive\"` - For critical updates (errors, confirmations)\n- `aria-atomic=\"true\"` - Screen reader reads entire region on update\n- `aria-atomic=\"false\"` - Screen reader reads only changed parts\n\n### Keyboard Navigation Patterns\n\n**✅ Good - Tab order follows visual order:**\n\n```typescript\n// Elements appear in logical tab order\n\n```\n\n**✅ Good - Keyboard shortcuts:**\n\n```typescript\nimport { useEffect } from 'react'\n\nfunction SearchDialog({ onClose }: { onClose: () => void }) {\n\tuseEffect(() => {\n\t\tfunction handleKeyDown(e: KeyboardEvent) {\n\t\t\tif (e.key === 'Escape') {\n\t\t\t\tonClose()\n\t\t\t}\n\t\t}\n\n\t\twindow.addEventListener('keydown', handleKeyDown)\n\t\treturn () => window.removeEventListener('keydown', handleKeyDown)\n\t}, [onClose])\n\n\treturn \n}\n```\n\n**✅ Good - Focus trap in modals:**\n\n```typescript\n// Radix Dialog automatically handles focus trap\n\n\t\t\t\t\t{toast.message}\n\t\t\t\t
\n\t\t\t))}\n\t\tReadable body text
\nClear headings
\n```\n\n**✅ Good - Sufficient line height:**\n\n```typescript\n// Tailwind defaults provide good line height\nComfortable reading
\n```\n\n**❌ Avoid - Small or hard-to-read text:**\n\n```typescript\n// ❌ Don't use very small text\nHard to read
\n```\n\n### Touch Target Sizes\n\n**✅ Good - Sufficient touch targets:**\n\n```typescript\n// Buttons should be at least 44x44px (touch target size)\n\n```\n\n**✅ Good - Spacing between interactive elements:**\n\n```typescript\n\n\t\n\t\n
\n```\n\n### Internationalization (i18n) Considerations\n\n**✅ Good - Use semantic HTML for dates/times:**\n\n```typescript\n\n```\n\n**✅ Good - Use semantic HTML for numbers:**\n\n```typescript\n// Screen readers can pronounce numbers correctly\nTotal: {count}
\n```\n\n**✅ Good - Language attributes:**\n\n```typescript\n// In root.tsx\n\n\t\n\t\t{/* Content */}\n\t\n\n```\n\n### Dark Mode Accessibility\n\n**✅ Good - Maintain contrast in dark mode:**\n\n```typescript\n// Ensure sufficient contrast in both modes\n\n\t{content}\n
\n```\n\n**✅ Good - Respect user preference:**\n\n```typescript\n// Epic Stack automatically handles theme preference\n// Use semantic colors that work in both modes\n\n```\n\n### Animation and Motion\n\n**✅ Good - Respect reduced motion:**\n\n```typescript\n// Tailwind automatically respects prefers-reduced-motion\n\n\t{/* Animations disabled for users who prefer reduced motion */}\n
\n```\n\n**✅ Good - Use CSS for animations:**\n\n```typescript\n// ✅ CSS animations can be disabled via prefers-reduced-motion\n\n\t{/* Content */}\n
\n\n// ❌ JavaScript animations may not respect user preferences\n```\n\n## Common mistakes to avoid\n\n- ❌ **Treating accessibility as a checklist**: Accessibility is about serving\n real people, not just meeting standards\n- ❌ **Missing form labels**: Always use `Field` component which includes\n labels - helps all users, not just screen reader users\n- ❌ **Using divs for semantic elements**: Use `- \n\t\t\t{sortedUsers.map(user => (\n\t\t\t\t
- {user.name} \n\t\t\t))}\n\t\t
\n\t\t\t
\n\t)\n}\n```\n\n### Error Boundaries\n\n**✅ Good - Use error boundaries:**\n\n```typescript\n// app/routes/users/$username.tsx\nexport function ErrorBoundary() {\n\treturn (\n\t\t\n\t\t\t\t\n\t\t\t\t
\n\t\t\t{user.name}
\n\t\t\t\n\t\t\t\t
\n\t\t\t{user.email}
\n\t\t\t\t{user.bio}
\n\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t
\n\t\tUser \"{params.username}\" not found
\n\t\t\t\t),\n\t\t\t}}\n\t\t/>\n\t)\n}\n```\n\n### TypeScript Guidelines\n\n**✅ Good - Type props explicitly:**\n\n```typescript\ninterface UserCardProps {\n\tuser: {\n\t\tid: string\n\t\tname: string\n\t\temail: string\n\t}\n\tonEdit?: (userId: string) => void\n}\n\nfunction UserCard({ user, onEdit }: UserCardProps) {\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n```\n\n**✅ Good - Use Route types:**\n\n```typescript\nimport type { Route } from './+types/users.$username'\n\nexport async function loader({ params }: Route.LoaderArgs) {\n\t// params is type-safe!\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\treturn { user }\n}\n\nexport default function UserRoute({ loaderData }: Route.ComponentProps) {\n\t// loaderData is type-safe!\n\treturn {user.name}
\n\t\t\t{user.email}
\n\t\t\t{onEdit && }\n\t\t{loaderData.user.name}
\n}\n```\n\n### Loading States\n\n**✅ Good - Use React Router's pending states:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction NoteForm() {\n\tconst navigation = useNavigation()\n\tconst isSubmitting = navigation.state === 'submitting'\n\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Preventing Data Fetching Waterfalls\n\nReact Router loaders can prevent waterfalls by fetching data in parallel.\n\n**❌ Avoid - Sequential data fetching (waterfall):**\n\n```typescript\n// ❌ Don't do this - creates a waterfall\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\t// Second fetch waits for first to complete\n\tconst notes = await prisma.note.findMany({\n\t\twhere: { ownerId: user.id },\n\t})\n\treturn { user, notes }\n}\n```\n\n**✅ Good - Parallel data fetching:**\n\n```typescript\n// ✅ Fetch data in parallel\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true, username: true, name: true },\n\t})\n\n\t// Fetch notes in parallel with user data\n\tconst [notes, stats] = await Promise.all([\n\t\tuser\n\t\t\t? prisma.note.findMany({\n\t\t\t\t\twhere: { ownerId: user.id },\n\t\t\t\t\tselect: { id: true, title: true, updatedAt: true },\n\t\t\t\t})\n\t\t\t: Promise.resolve([]),\n\t\tuser\n\t\t\t? prisma.note.count({ where: { ownerId: user.id } })\n\t\t\t: Promise.resolve(0),\n\t])\n\n\treturn { user, notes, stats }\n}\n```\n\n**✅ Good - Nested route parallel loading:**\n\n```typescript\n// Parent route loader\n// app/routes/users/$username.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true, username: true, name: true },\n\t})\n\treturn { user }\n}\n\n// Child route loader runs in parallel\n// app/routes/users/$username/notes.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true },\n\t})\n\n\tif (!user) {\n\t\tthrow new Response('Not Found', { status: 404 })\n\t}\n\n\tconst notes = await prisma.note.findMany({\n\t\twhere: { ownerId: user.id },\n\t\tselect: { id: true, title: true, updatedAt: true },\n\t})\n\n\treturn { notes }\n}\n```\n\n### Server-Side Rendering (SSR) Performance\n\nReact Router provides SSR by default. Optimize by:\n\n**✅ Good - Selective data fetching:**\n\n```typescript\nexport async function loader({ request }: Route.LoaderArgs) {\n\t// Only fetch what's needed for initial render\n\tconst searchParams = new URL(request.url).searchParams\n\tconst page = Number(searchParams.get('page') || '1')\n\n\tconst [items, total] = await Promise.all([\n\t\tprisma.item.findMany({\n\t\t\ttake: 20,\n\t\t\tskip: (page - 1) * 20,\n\t\t\tselect: { id: true, title: true }, // Only needed fields\n\t\t}),\n\t\tprisma.item.count(),\n\t])\n\n\treturn { items, total, page }\n}\n```\n\n**✅ Good - Use caching for expensive operations:**\n\n```typescript\nimport { cachified, cache } from '#app/utils/cache.server.ts'\n\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst timings: Timings = {}\n\n\t// Cache expensive database queries\n\tconst stats = await cachified({\n\t\tkey: 'user-stats',\n\t\tcache,\n\t\ttimings,\n\t\tgetFreshValue: async () => {\n\t\t\treturn await prisma.user.aggregate({\n\t\t\t\t_count: { id: true },\n\t\t\t})\n\t\t},\n\t\tttl: 1000 * 60 * 5, // 5 minutes\n\t})\n\n\treturn { stats }\n}\n```\n\n### Rendering Performance\n\n**✅ Good - Use React.memo for expensive components:**\n\n```typescript\nimport { memo } from 'react'\n\nconst ExpensiveChart = memo(function ExpensiveChart({ data }: { data: Data[] }) {\n\t// Expensive rendering logic\n\treturn {user.name}
\n\t\t\t{user.email}
\n\t\t- \n\t\t\t{users.map(user => (\n\t\t\t\t
{loaderData.user.name}
\n}\n\n// ❌ Avoid - Over-engineered route structure\n// app/routes/users/$username/_layout.tsx\n// app/routes/users/$username/index.tsx\n// app/routes/users/$username/_components/UserHeader.tsx\n// app/routes/users/$username/_components/UserDetails.tsx\n// Unnecessary complexity for a simple user page\n```\n\n**Example - Add complexity only when needed:**\n\n```typescript\n// ✅ Good - Add nested routes only when you actually need them\n// If you have user notes, then nested routes make sense:\n// app/routes/users/$username/notes/_layout.tsx\n// app/routes/users/$username/notes/index.tsx\n// app/routes/users/$username/notes/$noteId.tsx\n\n// ❌ Avoid - Creating nested routes \"just in case\"\n// Don't create complex structures before you need them\n```\n\n### File-based routing with react-router-auto-routes\n\nEpic Stack uses `react-router-auto-routes` instead of React Router's standard\nconvention. This enables better organization and code co-location.\n\n**Basic structure:**\n\n```\napp/routes/\n├── _layout.tsx # Layout for child routes\n├── index.tsx # Root route (/)\n├── about.tsx # Route /about\n└── users/\n ├── _layout.tsx # Layout for user routes\n ├── index.tsx # Route /users\n └── $username/\n └── index.tsx # Route /users/:username\n```\n\n**Configuration in `app/routes.ts`:**\n\n```typescript\nimport { type RouteConfig } from '@react-router/dev/routes'\nimport { autoRoutes } from 'react-router-auto-routes'\n\nexport default autoRoutes({\n\tignoredRouteFiles: [\n\t\t'.*',\n\t\t'**/*.css',\n\t\t'**/*.test.{js,jsx,ts,tsx}',\n\t\t'**/__*.*',\n\t\t'**/*.server.*', // Co-located server utilities\n\t\t'**/*.client.*', // Co-located client utilities\n\t],\n}) satisfies RouteConfig\n```\n\n### Route Groups\n\nRoute groups are folders that start with `_` and don't affect the URL but help\norganize related code.\n\n**Common examples:**\n\n- `_auth/` - Authentication routes (login, signup, etc.)\n- `_marketing/` - Marketing pages (home, about, etc.)\n- `_seo/` - SEO routes (sitemap, robots.txt)\n\n**Example:**\n\n```\napp/routes/\n├── _auth/\n│ ├── login.tsx # URL: /login\n│ ├── signup.tsx # URL: /signup\n│ └── forgot-password.tsx # URL: /forgot-password\n└── _marketing/\n ├── index.tsx # URL: /\n └── about.tsx # URL: /about\n```\n\n### Route Parameters\n\nUse `$` to indicate route parameters:\n\n**Syntax:**\n\n- `$param.tsx` → `:param` in URL\n- `$username.tsx` → `:username` in URL\n\n**Example route with parameter:**\n\n```typescript\n// app/routes/users/$username/index.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst username = params.username // Type-safe!\n\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username },\n\t})\n\n\treturn { user }\n}\n```\n\n### Nested Layouts with `_layout.tsx`\n\nUse `_layout.tsx` to create shared layouts for child routes.\n\n**Example:**\n\n```typescript\n// app/routes/users/$username/notes/_layout.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst owner = await prisma.user.findFirst({\n\t\twhere: { username: params.username },\n\t})\n\treturn { owner }\n}\n\nexport default function NotesLayout({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t{loaderData.owner.name}'s Notes
\n\t\t\t{/* Use loaderData.data */}
\n}\n```\n\n**Action pattern:**\n\n```typescript\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\tconst formData = await request.formData()\n\n\t// Validate and process data\n\tawait prisma.something.create({\n\t\tdata: { /* ... */ },\n\t})\n\n\treturn redirect('/success')\n}\n\nexport default function RouteComponent() {\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Search Params\n\nAccess query parameters using `useSearchParams`:\n\n```typescript\nimport { useSearchParams } from 'react-router'\n\nexport default function SearchPage() {\n\tconst [searchParams, setSearchParams] = useSearchParams()\n\tconst query = searchParams.get('q') || ''\n\tconst page = Number(searchParams.get('page') || '1')\n\n\treturn (\n\t\t\n\t\t\t setSearchParams({ q: e.target.value })}\n\t\t\t/>\n\t\t\t{/* Results */}\n\t\t
\n\t)\n}\n```\n\n### Code Co-location\n\nEpic Stack encourages placing related code close to where it's used.\n\n**Typical structure:**\n\n```\napp/routes/users/$username/notes/\n├── _layout.tsx # Layout with loader\n├── index.tsx # Notes list\n├── $noteId.tsx # Note view\n├── $noteId_.edit.tsx # Edit note\n├── +shared/ # Code shared between routes\n│ └── note-editor.tsx # Shared editor\n└── $noteId.server.ts # Server-side utilities\n```\n\nThe `+` prefix indicates co-located modules that are not routes.\n\n### Naming Conventions\n\n- `_layout.tsx` - Layout for child routes\n- `index.tsx` - Root route of the segment\n- `$param.tsx` - Route parameter\n- `$param_.action.tsx` - Route with parameter + action (using `_`)\n- `[.]ext.tsx` - Resource route (e.g., `robots[.]txt.ts`)\n\n## Common examples\n\n### Example 1: Create a basic route with layout\n\n```typescript\n// app/routes/products/_layout.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst categories = await prisma.category.findMany()\n\treturn { categories }\n}\n\nexport default function ProductsLayout({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t\t\t\n\t\t\t
\n\t)\n}\n\n// app/routes/products/index.tsx\nexport default function ProductsIndex() {\n\treturn Products list
\n}\n```\n\n### Example 2: Route with dynamic parameter\n\n```typescript\n// app/routes/products/$slug.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst product = await prisma.product.findUnique({\n\t\twhere: { slug: params.slug },\n\t})\n\n\tif (!product) {\n\t\tthrow new Response('Not Found', { status: 404 })\n\t}\n\n\treturn { product }\n}\n\nexport default function ProductPage({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n\nexport function ErrorBoundary() {\n\treturn (\n\t\t{loaderData.product.name}
\n\t\t\t{loaderData.product.description}
\n\t\tProduct \"{params.slug}\" not found
\n\t\t\t\t),\n\t\t\t}}\n\t\t/>\n\t)\n}\n```\n\n### Example 3: Resource route for download\n\n```typescript\n// app/routes/resources/download-report.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst userId = await requireUserId(request)\n\n\tconst report = await generateReport(userId)\n\n\treturn new Response(report, {\n\t\theaders: {\n\t\t\t'Content-Type': 'application/pdf',\n\t\t\t'Content-Disposition': 'attachment; filename=\"report.pdf\"',\n\t\t},\n\t})\n}\n```\n\n### Example 4: Route with multiple nested parameters\n\n```typescript\n// app/routes/users/$username/posts/$postId/comments/$commentId.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\t// params contains: { username, postId, commentId }\n\tconst comment = await prisma.comment.findUnique({\n\t\twhere: { id: params.commentId },\n\t\tinclude: {\n\t\t\tpost: {\n\t\t\t\tinclude: { author: true },\n\t\t\t},\n\t\t},\n\t})\n\n\treturn { comment }\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Over-engineering route structure**: Keep routes simple - don't create\n complex nested structures unless you actually need them\n- ❌ **Creating abstractions prematurely**: Start with simple routes, add\n complexity only when there's a clear benefit\n- ❌ **Using React Router's standard convention**: Epic Stack uses\n `react-router-auto-routes`, not the standard convention\n- ❌ **Exporting default component in resource routes**: Resource routes should\n not export components\n- ❌ **Not using nested layouts when needed**: Use `_layout.tsx` when you have\n shared UI, but don't create layouts unnecessarily\n- ❌ **Forgetting `{userContent}
\n```\n\n### Secure Headers\n\nEpic Stack uses Helmet for secure headers.\n\n**Configuration:**\n\n```typescript\nimport { helmet } from '@nichtsam/helmet/node-http'\n\napp.use((_, res, next) => {\n\thelmet(res, { general: { referrerPolicy: false } })\n\tnext()\n})\n```\n\n**Included headers:**\n\n- X-Content-Type-Options: nosniff\n- X-Frame-Options: DENY\n- X-XSS-Protection: 1; mode=block\n- Referrer-Policy (configurable)\n\n### HTTPS Only\n\n**Redirect HTTP to HTTPS:**\n\n```typescript\napp.use((req, res, next) => {\n\tif (req.method !== 'GET') return next()\n\tconst proto = req.get('X-Forwarded-Proto')\n\tconst host = getHost(req)\n\tif (proto === 'http') {\n\t\tres.set('X-Forwarded-Proto', 'https')\n\t\tres.redirect(`https://${host}${req.originalUrl}`)\n\t\treturn\n\t}\n\tnext()\n})\n```\n\n### Secrets Management\n\n**Variables de entorno:**\n\n```bash\n# .env\nSESSION_SECRET=secret1,secret2,secret3 # Secret rotation\nHONEYPOT_SECRET=your-honeypot-secret\nDATABASE_URL=file:./data/db.sqlite\n```\n\n**En Fly.io:**\n\n```bash\nfly secrets set SESSION_SECRET=\"secret1,secret2,secret3\"\nfly secrets set HONEYPOT_SECRET=\"your-secret\"\n```\n\n**Never commit secrets:**\n\n- Use `.env.example` to document required variables\n- `.env` is in `.gitignore`\n- Use `fly secrets` for production\n\n### Validación de Session Expiration (Fail Fast)\n\n**Always verify expiration early:**\n\n```typescript\nexport async function getUserId(request: Request) {\n\tconst authSession = await authSessionStorage.getSession(\n\t\trequest.headers.get('cookie'),\n\t)\n\tconst sessionId = authSession.get(sessionKey)\n\n\t// Fail fast - return null immediately if no session\n\tif (!sessionId) return null\n\n\t// Verify expiration early - fail fast if expired\n\tconst session = await prisma.session.findUnique({\n\t\tselect: { userId: true },\n\t\twhere: {\n\t\t\tid: sessionId,\n\t\t\texpirationDate: { gt: new Date() }, // Verify expiration\n\t\t},\n\t})\n\n\t// Fail fast - destroy invalid session immediately\n\tif (!session?.userId) {\n\t\tthrow redirect('/', {\n\t\t\theaders: {\n\t\t\t\t'set-cookie': await authSessionStorage.destroySession(authSession),\n\t\t\t},\n\t\t})\n\t}\n\treturn session.userId\n}\n```\n\n## Common examples\n\n### Example 1: Public form with honeypot\n\n```typescript\n// app/routes/_auth/signup.tsx\nimport { HoneypotInputs } from 'remix-utils/honeypot/react'\nimport { checkHoneypot } from '#app/utils/honeypot.server.ts'\n\nexport async function action({ request }: Route.ActionArgs) {\n\tconst formData = await request.formData()\n\n\tawait checkHoneypot(formData) // Spam protection\n\n\tconst submission = await parseWithZod(formData, {\n\t\tschema: SignupSchema,\n\t})\n\n\t// ... rest of code\n}\n\nexport default function SignupRoute({ actionData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Example 2: Custom rate limiting\n\n```typescript\n// server/index.ts\nconst apiRateLimit = rateLimit({\n\t...rateLimitDefault,\n\twindowMs: 60 * 1000,\n\tlimit: 100, // 100 requests per minute for API\n\tkeyGenerator: (req) => {\n\t\tconst apiKey = req.get('X-API-Key')\n\t\treturn apiKey ?? req.get('fly-client-ip') ?? req.ip\n\t},\n})\n\napp.use('/api', apiRateLimit)\n```\n\n### Example 3: Strict input validation\n\n```typescript\n// app/utils/user-validation.ts\nimport { z } from 'zod'\n\nexport const EmailSchema = z\n\t.string({ required_error: 'Email is required' })\n\t.email({ message: 'Email is invalid' })\n\t.min(3, { message: 'Email is too short' })\n\t.max(100, { message: 'Email is too long' })\n\t.transform((value) => value.toLowerCase().trim()) // Sanitization\n\nexport const UsernameSchema = z\n\t.string({ required_error: 'Username is required' })\n\t.min(3, { message: 'Username is too short' })\n\t.max(20, { message: 'Username is too long' })\n\t.regex(/^[a-zA-Z0-9_]+$/, {\n\t\tmessage: 'Username can only include letters, numbers, and underscores',\n\t})\n\t.transform((value) => value.toLowerCase().trim()) // Sanitization\n\nexport const PasswordSchema = z\n\t.string({ required_error: 'Password is required' })\n\t.min(6, { message: 'Password is too short' })\n\t.refine((val) => new TextEncoder().encode(val).length <= 72, {\n\t\tmessage: 'Password is too long', // bcrypt limit\n\t})\n```\n\n### Example 4: Permission verification before actions\n\n```typescript\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\n\t// Validate that user has permission\n\tawait requireUserWithPermission(request, 'delete:note:own')\n\n\t// Only after validating permissions\n\tawait prisma.note.delete({ where: { id: noteId } })\n\n\treturn redirect('/notes')\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Delayed security checks**: Validate authentication, authorization, and\n input as early as possible - fail fast\n- ❌ **Generic error messages**: Provide clear, actionable error messages that\n help with debugging (without exposing sensitive data)\n- ❌ **Forgetting honeypot in public forms**: Always include `HoneypotInputs` in\n forms accessible without authentication\n- ❌ **Not validating session expiration**: Always verify `expirationDate` when\n getting sessions - check early\n- ❌ **Using `dangerouslySetInnerHTML` with user data**: Never render user HTML\n without sanitizing\n- ❌ **Not using rate limiting**: Protect sensitive routes with rate limiting\n- ❌ **Secrets in code**: Never hardcode secrets, use environment variables\n- ❌ **Not sanitizing inputs**: Always sanitize inputs with `.transform()` from\n Zod\n- ❌ **Not validating common passwords**: Check passwords against Have I Been\n Pwned\n- ❌ **Sessions without httpOnly**: Always use `httpOnly: true` in session\n cookies\n- ❌ **Not using HTTPS in production**: Make sure to redirect HTTP to HTTPS\n- ❌ **CSP too permissive**: Review and adjust CSP according to your needs\n- ❌ **Not logging security events**: Log security failures with context for\n debugging (without sensitive data)\n\n## References\n\n- [Epic Stack Security Docs](../epic-stack/docs/security.md)\n- [Epic Web Principles](https://www.epicweb.dev/principles)\n- [OWASP Top 10](https://owasp.org/www-project-top-ten/)\n- [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)\n- `app/utils/honeypot.server.ts` - Honeypot implementation\n- `server/index.ts` - Server security configuration\n- `docs/decisions/033-honeypot.md` - Honeypot documentation\n- `docs/decisions/025-rate-limiting.md` - Rate limiting documentation\n- `docs/decisions/008-content-security-policy.md` - CSP documentation\n","frontmatter":{"name":"epic-security","description":"Guide on security practices including CSP, rate limiting, and session security for Epic Stack","categories":["security","csp","rate-limiting","headers"]},"isInternal":false,"tokens":3882,"sizeBytes":15557},{"name":"SKILL.md","path":"docs/skills/epic-testing/SKILL.md","rawUrl":"https://raw.githubusercontent.com/epicweb-dev/epic-stack/HEAD/docs/skills/epic-testing/SKILL.md","title":"epic-testing","category":"anthropic-skill","format":"markdown","content":"---\nname: epic-testing\ndescription: Guide on testing with Vitest and Playwright for Epic Stack\ncategories:\n - testing\n - vitest\n - playwright\n - e2e\n---\n\n# Epic Stack: Testing\n\n## When to use this skill\n\nUse this skill when you need to:\n\n- Write unit tests for utilities and components\n- Create E2E tests with Playwright\n- Test forms and validation\n- Test routes and loaders\n- Mock external services with MSW\n- Test authentication and permissions\n- Configure test database\n\n## Patterns and conventions\n\n### Testing Philosophy\n\nFollowing Epic Web principles:\n\n**Tests should resemble users** - Write tests that mirror how real users\ninteract with your application. Test user workflows, not implementation details.\nIf a user would click a button, your test should click that button. If a user\nwould see an error message, your test should check for that specific message.\n\n**Make assertions specific** - Be explicit about what you're testing. Instead of\nvague assertions, use specific, meaningful checks that clearly communicate the\nexpected behavior. This makes tests easier to understand and debug when they\nfail.\n\n**Example - Tests that resemble users:**\n\n```typescript\n// ✅ Good - Tests user workflow\ntest('User can sign up and create their first note', async ({ page, navigate }) => {\n\t// User visits signup page\n\tawait navigate('/signup')\n\n\t// User fills out form like a real person would\n\tawait page.getByRole('textbox', { name: /email/i }).fill('newuser@example.com')\n\tawait page.getByRole('textbox', { name: /username/i }).fill('newuser')\n\tawait page.getByRole('textbox', { name: /^password$/i }).fill('securepassword123')\n\tawait page.getByRole('textbox', { name: /confirm/i }).fill('securepassword123')\n\n\t// User submits form\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// User is redirected to onboarding\n\tawait expect(page).toHaveURL(/\\/onboarding/)\n\n\t// User creates their first note\n\tawait navigate('/notes/new')\n\tawait page.getByRole('textbox', { name: /title/i }).fill('My First Note')\n\tawait page.getByRole('textbox', { name: /content/i }).fill('This is my first note!')\n\tawait page.getByRole('button', { name: /create/i }).click()\n\n\t// User sees their note\n\tawait expect(page.getByRole('heading', { name: 'My First Note' })).toBeVisible()\n\tawait expect(page.getByText('This is my first note!')).toBeVisible()\n})\n\n// ❌ Avoid - Testing implementation details\ntest('Signup form calls API endpoint', async ({ page }) => {\n\t// This tests implementation, not user experience\n\tconst response = await page.request.post('/signup', { data: {...} })\n\texpect(response.status()).toBe(200)\n})\n```\n\n**Example - Specific assertions:**\n\n```typescript\n// ✅ Good - Specific assertions\ntest('Form shows specific validation errors', async ({ page, navigate }) => {\n\tawait navigate('/signup')\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// Specific error messages that users would see\n\tawait expect(page.getByText(/email is required/i)).toBeVisible()\n\tawait expect(\n\t\tpage.getByText(/username must be at least 3 characters/i),\n\t).toBeVisible()\n\tawait expect(\n\t\tpage.getByText(/password must be at least 6 characters/i),\n\t).toBeVisible()\n})\n\n// ❌ Avoid - Vague assertions\ntest('Form shows errors', async ({ page, navigate }) => {\n\tawait navigate('/signup')\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// Too vague - what errors? where?\n\texpect(page.locator('.error')).toBeVisible()\n})\n```\n\n### Two Types of Tests\n\nEpic Stack uses two types of tests:\n\n1. **Unit Tests with Vitest** - Tests for individual components and utilities\n2. **E2E Tests with Playwright** - End-to-end tests of the complete flow\n\n### Unit Tests with Vitest\n\n**Basic setup:**\n\n```typescript\n// app/utils/my-util.test.ts\nimport { describe, expect, it } from 'vitest'\nimport { myUtil } from './my-util.ts'\n\ndescribe('myUtil', () => {\n\tit('should do something', () => {\n\t\texpect(myUtil('input')).toBe('expected')\n\t})\n})\n```\n\n**Testing con DOM:**\n\n```typescript\nimport { describe, expect, it } from 'vitest'\nimport { render, screen } from '@testing-library/react'\nimport { MyComponent } from './my-component.tsx'\n\ndescribe('MyComponent', () => {\n\tit('should render correctly', () => {\n\t\trender({user.name}
\n\t\t\t{user.bio}
\n\t\t\t\n\t\t\n\t
\n```\n\n### Form Accessibility\n\n**✅ Good - Always use labels:**\n\n```typescript\nimport { Field } from '#app/components/forms.tsx'\n\n{user.name}
\n\t{user.bio}
\n\t{formatDate(user.createdAt)}
\n\n\t\t\t{children}\n\t\t
\n\t)\n}\n```\n\n**✅ Good - Use Tailwind responsive utilities:**\n\n```typescript\n\n\t{items.map(item => (\n\t\t{item.name} \n\t))}\n
\n```\n\n**✅ Good - Use Tailwind dark mode:**\n\n```typescript\n\n\t{content}\n
\n```\n\n### Error Handling in Forms\n\n**✅ Good - Display errors accessibly:**\n\n```typescript\nimport { Field, ErrorList } from '#app/components/forms.tsx'\n\n // High contrast\n\n\t\t\t \n\t)\n}\n```\n\n**❌ Avoid - Large monolithic components:**\n\n```typescript\n// ❌ Don't put everything in one component\nfunction UserProfile({ user }: { user: User }) {\n\treturn (\n\t\t (\n\t\t\t\t\t\n\t\t\t \n\t)\n}, (prev, next) => prev.user.id === next.user.id)\n\nfunction UserList({ users }: { users: User[] }) {\n\treturn (\n\t\tLoading...
}>\n\t\t\t // Accessible links\n```\n\n**❌ Avoid - Low contrast text:**\n\n```typescript\n// ❌ Don't use low contrast\n\n\t\n\t\t{/* Focus is trapped inside dialog */}\n\t\tClose \n\t \n \n```\n\n### Focus Management for React Router\n\n**✅ Good - Focus on route changes:**\n\n```typescript\nimport { useEffect } from 'react'\nimport { useNavigation } from 'react-router'\n\nfunction RouteComponent() {\n\tconst navigation = useNavigation()\n\tconst mainRef = useRef(null)\n\n\tuseEffect(() => {\n\t\tif (navigation.state === 'idle' && mainRef.current) {\n\t\t\tmainRef.current.focus()\n\t\t}\n\t}, [navigation.state])\n\n\treturn (\n\t\t\n\t\t\t{/* Content */}\n\t\t \n\t)\n}\n```\n\n**✅ Good - Focus on errors:**\n\n```typescript\nimport { useEffect, useRef } from 'react'\n\nfunction FormWithErrorFocus({ actionData }: Route.ComponentProps) {\n\tconst firstErrorRef = useRef(null)\n\n\tuseEffect(() => {\n\t\tif (actionData?.errors && firstErrorRef.current) {\n\t\t\t// Focus first error field\n\t\t\tfirstErrorRef.current.focus()\n\t\t\t// Announce error\n\t\t\tfirstErrorRef.current.setAttribute('aria-invalid', 'true')\n\t\t}\n\t}, [actionData?.errors])\n\n\treturn `, ``, `
}>\n\t\t\t // Very low contrast\n```\n\n### Responsive Design\n\n**✅ Good - Mobile-first approach:**\n\n```typescript\n\n\t\t\t{isSubmitting ? 'Saving...' : 'Save'}\n\t\t\n\t)\n}\n```\n\n### Icon Usage\n\n**✅ Good - Decorative icons:**\n\n```typescript\nimport { Icon } from '#app/components/ui/icon.tsx'\n\n\n```\n\n**✅ Good - Semantic icons:**\n\n```typescript\n\n```\n\n### Skip Links\n\n**✅ Good - Add skip to main content:**\n\n```typescript\n// In your root layout\n\n\tSkip to main content\n\n\n\n\t{/* Main content */}\n \n```\n\n### Progressive Enhancement\n\n**✅ Good - Forms work without JavaScript:**\n\n```typescript\n// Conform forms work without JavaScript\n\n```\n\nForms automatically:\n\n- Submit via native HTML forms if JavaScript is disabled\n- Validate server-side\n- Show errors appropriately\n\n### Screen Reader Best Practices\n\n**✅ Good - Use semantic HTML first:**\n\n```typescript\n// ✅ Semantic HTML provides context automatically\n\n```\n\n**✅ Good - Announce dynamic content:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction SearchResults({ results }: { results: Result[] }) {\n\tconst navigation = useNavigation()\n\tconst isSearching = navigation.state === 'loading'\n\n\treturn (\n\t\t\n\t\t\t{isSearching ? 'Searching...' : `${results.length} results found`}\n\t\t
\n\t)\n}\n```\n\n**✅ Good - Live regions for important updates:**\n\n```typescript\nfunction ToastContainer({ toasts }: { toasts: Toast[] }) {\n\treturn (\n\t\t\n\t{/* Content */}\n
\n```\n\n**✅ Good - Responsive typography:**\n\n```typescript\n\n\tResponsive Heading\n
\n```\n\n### Loading States\n\n**✅ Good - Accessible loading indicators:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction SubmitButton() {\n\tconst navigation = useNavigation()\n\tconst isSubmitting = navigation.state === 'submitting'\n\n\treturn (\n\t\t\n\t\t\t{toasts.map(toast => (\n\t\t\t\t
\n\t)\n}\n```\n\n**ARIA live region options:**\n\n- `aria-live=\"polite\"` - For non-critical updates (search results, status\n messages)\n- `aria-live=\"assertive\"` - For critical updates (errors, confirmations)\n- `aria-atomic=\"true\"` - Screen reader reads entire region on update\n- `aria-atomic=\"false\"` - Screen reader reads only changed parts\n\n### Keyboard Navigation Patterns\n\n**✅ Good - Tab order follows visual order:**\n\n```typescript\n// Elements appear in logical tab order\n\n```\n\n**✅ Good - Keyboard shortcuts:**\n\n```typescript\nimport { useEffect } from 'react'\n\nfunction SearchDialog({ onClose }: { onClose: () => void }) {\n\tuseEffect(() => {\n\t\tfunction handleKeyDown(e: KeyboardEvent) {\n\t\t\tif (e.key === 'Escape') {\n\t\t\t\tonClose()\n\t\t\t}\n\t\t}\n\n\t\twindow.addEventListener('keydown', handleKeyDown)\n\t\treturn () => window.removeEventListener('keydown', handleKeyDown)\n\t}, [onClose])\n\n\treturn \n}\n```\n\n**✅ Good - Focus trap in modals:**\n\n```typescript\n// Radix Dialog automatically handles focus trap\n\n\t\t\t\t\t{toast.message}\n\t\t\t\t
\n\t\t\t))}\n\t\tReadable body text
\nClear headings
\n```\n\n**✅ Good - Sufficient line height:**\n\n```typescript\n// Tailwind defaults provide good line height\nComfortable reading
\n```\n\n**❌ Avoid - Small or hard-to-read text:**\n\n```typescript\n// ❌ Don't use very small text\nHard to read
\n```\n\n### Touch Target Sizes\n\n**✅ Good - Sufficient touch targets:**\n\n```typescript\n// Buttons should be at least 44x44px (touch target size)\n\n```\n\n**✅ Good - Spacing between interactive elements:**\n\n```typescript\n\n\t\n\t\n
\n```\n\n### Internationalization (i18n) Considerations\n\n**✅ Good - Use semantic HTML for dates/times:**\n\n```typescript\n\n```\n\n**✅ Good - Use semantic HTML for numbers:**\n\n```typescript\n// Screen readers can pronounce numbers correctly\nTotal: {count}
\n```\n\n**✅ Good - Language attributes:**\n\n```typescript\n// In root.tsx\n\n\t\n\t\t{/* Content */}\n\t\n\n```\n\n### Dark Mode Accessibility\n\n**✅ Good - Maintain contrast in dark mode:**\n\n```typescript\n// Ensure sufficient contrast in both modes\n\n\t{content}\n
\n```\n\n**✅ Good - Respect user preference:**\n\n```typescript\n// Epic Stack automatically handles theme preference\n// Use semantic colors that work in both modes\n\n```\n\n### Animation and Motion\n\n**✅ Good - Respect reduced motion:**\n\n```typescript\n// Tailwind automatically respects prefers-reduced-motion\n\n\t{/* Animations disabled for users who prefer reduced motion */}\n
\n```\n\n**✅ Good - Use CSS for animations:**\n\n```typescript\n// ✅ CSS animations can be disabled via prefers-reduced-motion\n\n\t{/* Content */}\n
\n\n// ❌ JavaScript animations may not respect user preferences\n```\n\n## Common mistakes to avoid\n\n- ❌ **Treating accessibility as a checklist**: Accessibility is about serving\n real people, not just meeting standards\n- ❌ **Missing form labels**: Always use `Field` component which includes\n labels - helps all users, not just screen reader users\n- ❌ **Using divs for semantic elements**: Use `- \n\t\t\t{sortedUsers.map(user => (\n\t\t\t\t
- {user.name} \n\t\t\t))}\n\t\t
\n\t\t\t
\n\t)\n}\n```\n\n### Error Boundaries\n\n**✅ Good - Use error boundaries:**\n\n```typescript\n// app/routes/users/$username.tsx\nexport function ErrorBoundary() {\n\treturn (\n\t\t\n\t\t\t\t\n\t\t\t\t
\n\t\t\t{user.name}
\n\t\t\t\n\t\t\t\t
\n\t\t\t{user.email}
\n\t\t\t\t{user.bio}
\n\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t
\n\t\tUser \"{params.username}\" not found
\n\t\t\t\t),\n\t\t\t}}\n\t\t/>\n\t)\n}\n```\n\n### TypeScript Guidelines\n\n**✅ Good - Type props explicitly:**\n\n```typescript\ninterface UserCardProps {\n\tuser: {\n\t\tid: string\n\t\tname: string\n\t\temail: string\n\t}\n\tonEdit?: (userId: string) => void\n}\n\nfunction UserCard({ user, onEdit }: UserCardProps) {\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n```\n\n**✅ Good - Use Route types:**\n\n```typescript\nimport type { Route } from './+types/users.$username'\n\nexport async function loader({ params }: Route.LoaderArgs) {\n\t// params is type-safe!\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\treturn { user }\n}\n\nexport default function UserRoute({ loaderData }: Route.ComponentProps) {\n\t// loaderData is type-safe!\n\treturn {user.name}
\n\t\t\t{user.email}
\n\t\t\t{onEdit && }\n\t\t{loaderData.user.name}
\n}\n```\n\n### Loading States\n\n**✅ Good - Use React Router's pending states:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction NoteForm() {\n\tconst navigation = useNavigation()\n\tconst isSubmitting = navigation.state === 'submitting'\n\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Preventing Data Fetching Waterfalls\n\nReact Router loaders can prevent waterfalls by fetching data in parallel.\n\n**❌ Avoid - Sequential data fetching (waterfall):**\n\n```typescript\n// ❌ Don't do this - creates a waterfall\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t})\n\t// Second fetch waits for first to complete\n\tconst notes = await prisma.note.findMany({\n\t\twhere: { ownerId: user.id },\n\t})\n\treturn { user, notes }\n}\n```\n\n**✅ Good - Parallel data fetching:**\n\n```typescript\n// ✅ Fetch data in parallel\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true, username: true, name: true },\n\t})\n\n\t// Fetch notes in parallel with user data\n\tconst [notes, stats] = await Promise.all([\n\t\tuser\n\t\t\t? prisma.note.findMany({\n\t\t\t\t\twhere: { ownerId: user.id },\n\t\t\t\t\tselect: { id: true, title: true, updatedAt: true },\n\t\t\t\t})\n\t\t\t: Promise.resolve([]),\n\t\tuser\n\t\t\t? prisma.note.count({ where: { ownerId: user.id } })\n\t\t\t: Promise.resolve(0),\n\t])\n\n\treturn { user, notes, stats }\n}\n```\n\n**✅ Good - Nested route parallel loading:**\n\n```typescript\n// Parent route loader\n// app/routes/users/$username.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true, username: true, name: true },\n\t})\n\treturn { user }\n}\n\n// Child route loader runs in parallel\n// app/routes/users/$username/notes.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username: params.username },\n\t\tselect: { id: true },\n\t})\n\n\tif (!user) {\n\t\tthrow new Response('Not Found', { status: 404 })\n\t}\n\n\tconst notes = await prisma.note.findMany({\n\t\twhere: { ownerId: user.id },\n\t\tselect: { id: true, title: true, updatedAt: true },\n\t})\n\n\treturn { notes }\n}\n```\n\n### Server-Side Rendering (SSR) Performance\n\nReact Router provides SSR by default. Optimize by:\n\n**✅ Good - Selective data fetching:**\n\n```typescript\nexport async function loader({ request }: Route.LoaderArgs) {\n\t// Only fetch what's needed for initial render\n\tconst searchParams = new URL(request.url).searchParams\n\tconst page = Number(searchParams.get('page') || '1')\n\n\tconst [items, total] = await Promise.all([\n\t\tprisma.item.findMany({\n\t\t\ttake: 20,\n\t\t\tskip: (page - 1) * 20,\n\t\t\tselect: { id: true, title: true }, // Only needed fields\n\t\t}),\n\t\tprisma.item.count(),\n\t])\n\n\treturn { items, total, page }\n}\n```\n\n**✅ Good - Use caching for expensive operations:**\n\n```typescript\nimport { cachified, cache } from '#app/utils/cache.server.ts'\n\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst timings: Timings = {}\n\n\t// Cache expensive database queries\n\tconst stats = await cachified({\n\t\tkey: 'user-stats',\n\t\tcache,\n\t\ttimings,\n\t\tgetFreshValue: async () => {\n\t\t\treturn await prisma.user.aggregate({\n\t\t\t\t_count: { id: true },\n\t\t\t})\n\t\t},\n\t\tttl: 1000 * 60 * 5, // 5 minutes\n\t})\n\n\treturn { stats }\n}\n```\n\n### Rendering Performance\n\n**✅ Good - Use React.memo for expensive components:**\n\n```typescript\nimport { memo } from 'react'\n\nconst ExpensiveChart = memo(function ExpensiveChart({ data }: { data: Data[] }) {\n\t// Expensive rendering logic\n\treturn {user.name}
\n\t\t\t{user.email}
\n\t\t- \n\t\t\t{users.map(user => (\n\t\t\t\t
{loaderData.user.name}
\n}\n\n// ❌ Avoid - Over-engineered route structure\n// app/routes/users/$username/_layout.tsx\n// app/routes/users/$username/index.tsx\n// app/routes/users/$username/_components/UserHeader.tsx\n// app/routes/users/$username/_components/UserDetails.tsx\n// Unnecessary complexity for a simple user page\n```\n\n**Example - Add complexity only when needed:**\n\n```typescript\n// ✅ Good - Add nested routes only when you actually need them\n// If you have user notes, then nested routes make sense:\n// app/routes/users/$username/notes/_layout.tsx\n// app/routes/users/$username/notes/index.tsx\n// app/routes/users/$username/notes/$noteId.tsx\n\n// ❌ Avoid - Creating nested routes \"just in case\"\n// Don't create complex structures before you need them\n```\n\n### File-based routing with react-router-auto-routes\n\nEpic Stack uses `react-router-auto-routes` instead of React Router's standard\nconvention. This enables better organization and code co-location.\n\n**Basic structure:**\n\n```\napp/routes/\n├── _layout.tsx # Layout for child routes\n├── index.tsx # Root route (/)\n├── about.tsx # Route /about\n└── users/\n ├── _layout.tsx # Layout for user routes\n ├── index.tsx # Route /users\n └── $username/\n └── index.tsx # Route /users/:username\n```\n\n**Configuration in `app/routes.ts`:**\n\n```typescript\nimport { type RouteConfig } from '@react-router/dev/routes'\nimport { autoRoutes } from 'react-router-auto-routes'\n\nexport default autoRoutes({\n\tignoredRouteFiles: [\n\t\t'.*',\n\t\t'**/*.css',\n\t\t'**/*.test.{js,jsx,ts,tsx}',\n\t\t'**/__*.*',\n\t\t'**/*.server.*', // Co-located server utilities\n\t\t'**/*.client.*', // Co-located client utilities\n\t],\n}) satisfies RouteConfig\n```\n\n### Route Groups\n\nRoute groups are folders that start with `_` and don't affect the URL but help\norganize related code.\n\n**Common examples:**\n\n- `_auth/` - Authentication routes (login, signup, etc.)\n- `_marketing/` - Marketing pages (home, about, etc.)\n- `_seo/` - SEO routes (sitemap, robots.txt)\n\n**Example:**\n\n```\napp/routes/\n├── _auth/\n│ ├── login.tsx # URL: /login\n│ ├── signup.tsx # URL: /signup\n│ └── forgot-password.tsx # URL: /forgot-password\n└── _marketing/\n ├── index.tsx # URL: /\n └── about.tsx # URL: /about\n```\n\n### Route Parameters\n\nUse `$` to indicate route parameters:\n\n**Syntax:**\n\n- `$param.tsx` → `:param` in URL\n- `$username.tsx` → `:username` in URL\n\n**Example route with parameter:**\n\n```typescript\n// app/routes/users/$username/index.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst username = params.username // Type-safe!\n\n\tconst user = await prisma.user.findUnique({\n\t\twhere: { username },\n\t})\n\n\treturn { user }\n}\n```\n\n### Nested Layouts with `_layout.tsx`\n\nUse `_layout.tsx` to create shared layouts for child routes.\n\n**Example:**\n\n```typescript\n// app/routes/users/$username/notes/_layout.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst owner = await prisma.user.findFirst({\n\t\twhere: { username: params.username },\n\t})\n\treturn { owner }\n}\n\nexport default function NotesLayout({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t{loaderData.owner.name}'s Notes
\n\t\t\t{/* Use loaderData.data */}
\n}\n```\n\n**Action pattern:**\n\n```typescript\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\tconst formData = await request.formData()\n\n\t// Validate and process data\n\tawait prisma.something.create({\n\t\tdata: { /* ... */ },\n\t})\n\n\treturn redirect('/success')\n}\n\nexport default function RouteComponent() {\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Search Params\n\nAccess query parameters using `useSearchParams`:\n\n```typescript\nimport { useSearchParams } from 'react-router'\n\nexport default function SearchPage() {\n\tconst [searchParams, setSearchParams] = useSearchParams()\n\tconst query = searchParams.get('q') || ''\n\tconst page = Number(searchParams.get('page') || '1')\n\n\treturn (\n\t\t\n\t\t\t setSearchParams({ q: e.target.value })}\n\t\t\t/>\n\t\t\t{/* Results */}\n\t\t
\n\t)\n}\n```\n\n### Code Co-location\n\nEpic Stack encourages placing related code close to where it's used.\n\n**Typical structure:**\n\n```\napp/routes/users/$username/notes/\n├── _layout.tsx # Layout with loader\n├── index.tsx # Notes list\n├── $noteId.tsx # Note view\n├── $noteId_.edit.tsx # Edit note\n├── +shared/ # Code shared between routes\n│ └── note-editor.tsx # Shared editor\n└── $noteId.server.ts # Server-side utilities\n```\n\nThe `+` prefix indicates co-located modules that are not routes.\n\n### Naming Conventions\n\n- `_layout.tsx` - Layout for child routes\n- `index.tsx` - Root route of the segment\n- `$param.tsx` - Route parameter\n- `$param_.action.tsx` - Route with parameter + action (using `_`)\n- `[.]ext.tsx` - Resource route (e.g., `robots[.]txt.ts`)\n\n## Common examples\n\n### Example 1: Create a basic route with layout\n\n```typescript\n// app/routes/products/_layout.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst categories = await prisma.category.findMany()\n\treturn { categories }\n}\n\nexport default function ProductsLayout({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t\t\t\n\t\t\t
\n\t)\n}\n\n// app/routes/products/index.tsx\nexport default function ProductsIndex() {\n\treturn Products list
\n}\n```\n\n### Example 2: Route with dynamic parameter\n\n```typescript\n// app/routes/products/$slug.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\tconst product = await prisma.product.findUnique({\n\t\twhere: { slug: params.slug },\n\t})\n\n\tif (!product) {\n\t\tthrow new Response('Not Found', { status: 404 })\n\t}\n\n\treturn { product }\n}\n\nexport default function ProductPage({ loaderData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t\t\t
\n\t)\n}\n\nexport function ErrorBoundary() {\n\treturn (\n\t\t{loaderData.product.name}
\n\t\t\t{loaderData.product.description}
\n\t\tProduct \"{params.slug}\" not found
\n\t\t\t\t),\n\t\t\t}}\n\t\t/>\n\t)\n}\n```\n\n### Example 3: Resource route for download\n\n```typescript\n// app/routes/resources/download-report.tsx\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst userId = await requireUserId(request)\n\n\tconst report = await generateReport(userId)\n\n\treturn new Response(report, {\n\t\theaders: {\n\t\t\t'Content-Type': 'application/pdf',\n\t\t\t'Content-Disposition': 'attachment; filename=\"report.pdf\"',\n\t\t},\n\t})\n}\n```\n\n### Example 4: Route with multiple nested parameters\n\n```typescript\n// app/routes/users/$username/posts/$postId/comments/$commentId.tsx\nexport async function loader({ params }: Route.LoaderArgs) {\n\t// params contains: { username, postId, commentId }\n\tconst comment = await prisma.comment.findUnique({\n\t\twhere: { id: params.commentId },\n\t\tinclude: {\n\t\t\tpost: {\n\t\t\t\tinclude: { author: true },\n\t\t\t},\n\t\t},\n\t})\n\n\treturn { comment }\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Over-engineering route structure**: Keep routes simple - don't create\n complex nested structures unless you actually need them\n- ❌ **Creating abstractions prematurely**: Start with simple routes, add\n complexity only when there's a clear benefit\n- ❌ **Using React Router's standard convention**: Epic Stack uses\n `react-router-auto-routes`, not the standard convention\n- ❌ **Exporting default component in resource routes**: Resource routes should\n not export components\n- ❌ **Not using nested layouts when needed**: Use `_layout.tsx` when you have\n shared UI, but don't create layouts unnecessarily\n- ❌ **Forgetting `{userContent}
\n```\n\n### Secure Headers\n\nEpic Stack uses Helmet for secure headers.\n\n**Configuration:**\n\n```typescript\nimport { helmet } from '@nichtsam/helmet/node-http'\n\napp.use((_, res, next) => {\n\thelmet(res, { general: { referrerPolicy: false } })\n\tnext()\n})\n```\n\n**Included headers:**\n\n- X-Content-Type-Options: nosniff\n- X-Frame-Options: DENY\n- X-XSS-Protection: 1; mode=block\n- Referrer-Policy (configurable)\n\n### HTTPS Only\n\n**Redirect HTTP to HTTPS:**\n\n```typescript\napp.use((req, res, next) => {\n\tif (req.method !== 'GET') return next()\n\tconst proto = req.get('X-Forwarded-Proto')\n\tconst host = getHost(req)\n\tif (proto === 'http') {\n\t\tres.set('X-Forwarded-Proto', 'https')\n\t\tres.redirect(`https://${host}${req.originalUrl}`)\n\t\treturn\n\t}\n\tnext()\n})\n```\n\n### Secrets Management\n\n**Variables de entorno:**\n\n```bash\n# .env\nSESSION_SECRET=secret1,secret2,secret3 # Secret rotation\nHONEYPOT_SECRET=your-honeypot-secret\nDATABASE_URL=file:./data/db.sqlite\n```\n\n**En Fly.io:**\n\n```bash\nfly secrets set SESSION_SECRET=\"secret1,secret2,secret3\"\nfly secrets set HONEYPOT_SECRET=\"your-secret\"\n```\n\n**Never commit secrets:**\n\n- Use `.env.example` to document required variables\n- `.env` is in `.gitignore`\n- Use `fly secrets` for production\n\n### Validación de Session Expiration (Fail Fast)\n\n**Always verify expiration early:**\n\n```typescript\nexport async function getUserId(request: Request) {\n\tconst authSession = await authSessionStorage.getSession(\n\t\trequest.headers.get('cookie'),\n\t)\n\tconst sessionId = authSession.get(sessionKey)\n\n\t// Fail fast - return null immediately if no session\n\tif (!sessionId) return null\n\n\t// Verify expiration early - fail fast if expired\n\tconst session = await prisma.session.findUnique({\n\t\tselect: { userId: true },\n\t\twhere: {\n\t\t\tid: sessionId,\n\t\t\texpirationDate: { gt: new Date() }, // Verify expiration\n\t\t},\n\t})\n\n\t// Fail fast - destroy invalid session immediately\n\tif (!session?.userId) {\n\t\tthrow redirect('/', {\n\t\t\theaders: {\n\t\t\t\t'set-cookie': await authSessionStorage.destroySession(authSession),\n\t\t\t},\n\t\t})\n\t}\n\treturn session.userId\n}\n```\n\n## Common examples\n\n### Example 1: Public form with honeypot\n\n```typescript\n// app/routes/_auth/signup.tsx\nimport { HoneypotInputs } from 'remix-utils/honeypot/react'\nimport { checkHoneypot } from '#app/utils/honeypot.server.ts'\n\nexport async function action({ request }: Route.ActionArgs) {\n\tconst formData = await request.formData()\n\n\tawait checkHoneypot(formData) // Spam protection\n\n\tconst submission = await parseWithZod(formData, {\n\t\tschema: SignupSchema,\n\t})\n\n\t// ... rest of code\n}\n\nexport default function SignupRoute({ actionData }: Route.ComponentProps) {\n\treturn (\n\t\t\n\t)\n}\n```\n\n### Example 2: Custom rate limiting\n\n```typescript\n// server/index.ts\nconst apiRateLimit = rateLimit({\n\t...rateLimitDefault,\n\twindowMs: 60 * 1000,\n\tlimit: 100, // 100 requests per minute for API\n\tkeyGenerator: (req) => {\n\t\tconst apiKey = req.get('X-API-Key')\n\t\treturn apiKey ?? req.get('fly-client-ip') ?? req.ip\n\t},\n})\n\napp.use('/api', apiRateLimit)\n```\n\n### Example 3: Strict input validation\n\n```typescript\n// app/utils/user-validation.ts\nimport { z } from 'zod'\n\nexport const EmailSchema = z\n\t.string({ required_error: 'Email is required' })\n\t.email({ message: 'Email is invalid' })\n\t.min(3, { message: 'Email is too short' })\n\t.max(100, { message: 'Email is too long' })\n\t.transform((value) => value.toLowerCase().trim()) // Sanitization\n\nexport const UsernameSchema = z\n\t.string({ required_error: 'Username is required' })\n\t.min(3, { message: 'Username is too short' })\n\t.max(20, { message: 'Username is too long' })\n\t.regex(/^[a-zA-Z0-9_]+$/, {\n\t\tmessage: 'Username can only include letters, numbers, and underscores',\n\t})\n\t.transform((value) => value.toLowerCase().trim()) // Sanitization\n\nexport const PasswordSchema = z\n\t.string({ required_error: 'Password is required' })\n\t.min(6, { message: 'Password is too short' })\n\t.refine((val) => new TextEncoder().encode(val).length <= 72, {\n\t\tmessage: 'Password is too long', // bcrypt limit\n\t})\n```\n\n### Example 4: Permission verification before actions\n\n```typescript\nexport async function action({ request }: Route.ActionArgs) {\n\tconst userId = await requireUserId(request)\n\n\t// Validate that user has permission\n\tawait requireUserWithPermission(request, 'delete:note:own')\n\n\t// Only after validating permissions\n\tawait prisma.note.delete({ where: { id: noteId } })\n\n\treturn redirect('/notes')\n}\n```\n\n## Common mistakes to avoid\n\n- ❌ **Delayed security checks**: Validate authentication, authorization, and\n input as early as possible - fail fast\n- ❌ **Generic error messages**: Provide clear, actionable error messages that\n help with debugging (without exposing sensitive data)\n- ❌ **Forgetting honeypot in public forms**: Always include `HoneypotInputs` in\n forms accessible without authentication\n- ❌ **Not validating session expiration**: Always verify `expirationDate` when\n getting sessions - check early\n- ❌ **Using `dangerouslySetInnerHTML` with user data**: Never render user HTML\n without sanitizing\n- ❌ **Not using rate limiting**: Protect sensitive routes with rate limiting\n- ❌ **Secrets in code**: Never hardcode secrets, use environment variables\n- ❌ **Not sanitizing inputs**: Always sanitize inputs with `.transform()` from\n Zod\n- ❌ **Not validating common passwords**: Check passwords against Have I Been\n Pwned\n- ❌ **Sessions without httpOnly**: Always use `httpOnly: true` in session\n cookies\n- ❌ **Not using HTTPS in production**: Make sure to redirect HTTP to HTTPS\n- ❌ **CSP too permissive**: Review and adjust CSP according to your needs\n- ❌ **Not logging security events**: Log security failures with context for\n debugging (without sensitive data)\n\n## References\n\n- [Epic Stack Security Docs](../epic-stack/docs/security.md)\n- [Epic Web Principles](https://www.epicweb.dev/principles)\n- [OWASP Top 10](https://owasp.org/www-project-top-ten/)\n- [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)\n- `app/utils/honeypot.server.ts` - Honeypot implementation\n- `server/index.ts` - Server security configuration\n- `docs/decisions/033-honeypot.md` - Honeypot documentation\n- `docs/decisions/025-rate-limiting.md` - Rate limiting documentation\n- `docs/decisions/008-content-security-policy.md` - CSP documentation\n\n\n---\nname: epic-testing\ndescription: Guide on testing with Vitest and Playwright for Epic Stack\ncategories:\n - testing\n - vitest\n - playwright\n - e2e\n---\n\n# Epic Stack: Testing\n\n## When to use this skill\n\nUse this skill when you need to:\n\n- Write unit tests for utilities and components\n- Create E2E tests with Playwright\n- Test forms and validation\n- Test routes and loaders\n- Mock external services with MSW\n- Test authentication and permissions\n- Configure test database\n\n## Patterns and conventions\n\n### Testing Philosophy\n\nFollowing Epic Web principles:\n\n**Tests should resemble users** - Write tests that mirror how real users\ninteract with your application. Test user workflows, not implementation details.\nIf a user would click a button, your test should click that button. If a user\nwould see an error message, your test should check for that specific message.\n\n**Make assertions specific** - Be explicit about what you're testing. Instead of\nvague assertions, use specific, meaningful checks that clearly communicate the\nexpected behavior. This makes tests easier to understand and debug when they\nfail.\n\n**Example - Tests that resemble users:**\n\n```typescript\n// ✅ Good - Tests user workflow\ntest('User can sign up and create their first note', async ({ page, navigate }) => {\n\t// User visits signup page\n\tawait navigate('/signup')\n\n\t// User fills out form like a real person would\n\tawait page.getByRole('textbox', { name: /email/i }).fill('newuser@example.com')\n\tawait page.getByRole('textbox', { name: /username/i }).fill('newuser')\n\tawait page.getByRole('textbox', { name: /^password$/i }).fill('securepassword123')\n\tawait page.getByRole('textbox', { name: /confirm/i }).fill('securepassword123')\n\n\t// User submits form\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// User is redirected to onboarding\n\tawait expect(page).toHaveURL(/\\/onboarding/)\n\n\t// User creates their first note\n\tawait navigate('/notes/new')\n\tawait page.getByRole('textbox', { name: /title/i }).fill('My First Note')\n\tawait page.getByRole('textbox', { name: /content/i }).fill('This is my first note!')\n\tawait page.getByRole('button', { name: /create/i }).click()\n\n\t// User sees their note\n\tawait expect(page.getByRole('heading', { name: 'My First Note' })).toBeVisible()\n\tawait expect(page.getByText('This is my first note!')).toBeVisible()\n})\n\n// ❌ Avoid - Testing implementation details\ntest('Signup form calls API endpoint', async ({ page }) => {\n\t// This tests implementation, not user experience\n\tconst response = await page.request.post('/signup', { data: {...} })\n\texpect(response.status()).toBe(200)\n})\n```\n\n**Example - Specific assertions:**\n\n```typescript\n// ✅ Good - Specific assertions\ntest('Form shows specific validation errors', async ({ page, navigate }) => {\n\tawait navigate('/signup')\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// Specific error messages that users would see\n\tawait expect(page.getByText(/email is required/i)).toBeVisible()\n\tawait expect(\n\t\tpage.getByText(/username must be at least 3 characters/i),\n\t).toBeVisible()\n\tawait expect(\n\t\tpage.getByText(/password must be at least 6 characters/i),\n\t).toBeVisible()\n})\n\n// ❌ Avoid - Vague assertions\ntest('Form shows errors', async ({ page, navigate }) => {\n\tawait navigate('/signup')\n\tawait page.getByRole('button', { name: /sign up/i }).click()\n\n\t// Too vague - what errors? where?\n\texpect(page.locator('.error')).toBeVisible()\n})\n```\n\n### Two Types of Tests\n\nEpic Stack uses two types of tests:\n\n1. **Unit Tests with Vitest** - Tests for individual components and utilities\n2. **E2E Tests with Playwright** - End-to-end tests of the complete flow\n\n### Unit Tests with Vitest\n\n**Basic setup:**\n\n```typescript\n// app/utils/my-util.test.ts\nimport { describe, expect, it } from 'vitest'\nimport { myUtil } from './my-util.ts'\n\ndescribe('myUtil', () => {\n\tit('should do something', () => {\n\t\texpect(myUtil('input')).toBe('expected')\n\t})\n})\n```\n\n**Testing con DOM:**\n\n```typescript\nimport { describe, expect, it } from 'vitest'\nimport { render, screen } from '@testing-library/react'\nimport { MyComponent } from './my-component.tsx'\n\ndescribe('MyComponent', () => {\n\tit('should render correctly', () => {\n\t\trender({user.name}
\n\t\t\t{user.bio}
\n\t\t\t\n\t\t\n\t
\n```\n\n### Form Accessibility\n\n**✅ Good - Always use labels:**\n\n```typescript\nimport { Field } from '#app/components/forms.tsx'\n\n{user.name}
\n\t{user.bio}
\n\t{formatDate(user.createdAt)}
\n\n\t\t\t{children}\n\t\t
\n\t)\n}\n```\n\n**✅ Good - Use Tailwind responsive utilities:**\n\n```typescript\n\n\t{items.map(item => (\n\t\t{item.name} \n\t))}\n
\n```\n\n**✅ Good - Use Tailwind dark mode:**\n\n```typescript\n\n\t{content}\n
\n```\n\n### Error Handling in Forms\n\n**✅ Good - Display errors accessibly:**\n\n```typescript\nimport { Field, ErrorList } from '#app/components/forms.tsx'\n\n // High contrast\n
// Accessible links\n```\n\n**❌ Avoid - Low contrast text:**\n\n```typescript\n// ❌ Don't use low contrast\n\n\t\n\t\t{/* Focus is trapped inside dialog */}\n\t\tClose \n\t \n \n```\n\n### Focus Management for React Router\n\n**✅ Good - Focus on route changes:**\n\n```typescript\nimport { useEffect } from 'react'\nimport { useNavigation } from 'react-router'\n\nfunction RouteComponent() {\n\tconst navigation = useNavigation()\n\tconst mainRef = useRef(null)\n\n\tuseEffect(() => {\n\t\tif (navigation.state === 'idle' && mainRef.current) {\n\t\t\tmainRef.current.focus()\n\t\t}\n\t}, [navigation.state])\n\n\treturn (\n\t\t\n\t\t\t{/* Content */}\n\t\t \n\t)\n}\n```\n\n**✅ Good - Focus on errors:**\n\n```typescript\nimport { useEffect, useRef } from 'react'\n\nfunction FormWithErrorFocus({ actionData }: Route.ComponentProps) {\n\tconst firstErrorRef = useRef(null)\n\n\tuseEffect(() => {\n\t\tif (actionData?.errors && firstErrorRef.current) {\n\t\t\t// Focus first error field\n\t\t\tfirstErrorRef.current.focus()\n\t\t\t// Announce error\n\t\t\tfirstErrorRef.current.setAttribute('aria-invalid', 'true')\n\t\t}\n\t}, [actionData?.errors])\n\n\treturn `, ``, `
// Very low contrast\n```\n\n### Responsive Design\n\n**✅ Good - Mobile-first approach:**\n\n```typescript\n\n\t\t\t{isSubmitting ? 'Saving...' : 'Save'}\n\t\t\n\t)\n}\n```\n\n### Icon Usage\n\n**✅ Good - Decorative icons:**\n\n```typescript\nimport { Icon } from '#app/components/ui/icon.tsx'\n\n\n```\n\n**✅ Good - Semantic icons:**\n\n```typescript\n\n```\n\n### Skip Links\n\n**✅ Good - Add skip to main content:**\n\n```typescript\n// In your root layout\n\n\tSkip to main content\n\n\n\n\t{/* Main content */}\n \n```\n\n### Progressive Enhancement\n\n**✅ Good - Forms work without JavaScript:**\n\n```typescript\n// Conform forms work without JavaScript\n\n```\n\nForms automatically:\n\n- Submit via native HTML forms if JavaScript is disabled\n- Validate server-side\n- Show errors appropriately\n\n### Screen Reader Best Practices\n\n**✅ Good - Use semantic HTML first:**\n\n```typescript\n// ✅ Semantic HTML provides context automatically\n\n```\n\n**✅ Good - Announce dynamic content:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction SearchResults({ results }: { results: Result[] }) {\n\tconst navigation = useNavigation()\n\tconst isSearching = navigation.state === 'loading'\n\n\treturn (\n\t\t\n\t\t\t{isSearching ? 'Searching...' : `${results.length} results found`}\n\t\t
\n\t)\n}\n```\n\n**✅ Good - Live regions for important updates:**\n\n```typescript\nfunction ToastContainer({ toasts }: { toasts: Toast[] }) {\n\treturn (\n\t\t\n\t{/* Content */}\n
\n```\n\n**✅ Good - Responsive typography:**\n\n```typescript\n\n\tResponsive Heading\n
\n```\n\n### Loading States\n\n**✅ Good - Accessible loading indicators:**\n\n```typescript\nimport { useNavigation } from 'react-router'\n\nfunction SubmitButton() {\n\tconst navigation = useNavigation()\n\tconst isSubmitting = navigation.state === 'submitting'\n\n\treturn (\n\t\t\n\t\t\t{toasts.map(toast => (\n\t\t\t\t
\n\t)\n}\n```\n\n**ARIA live region options:**\n\n- `aria-live=\"polite\"` - For non-critical updates (search results, status\n messages)\n- `aria-live=\"assertive\"` - For critical updates (errors, confirmations)\n- `aria-atomic=\"true\"` - Screen reader reads entire region on update\n- `aria-atomic=\"false\"` - Screen reader reads only changed parts\n\n### Keyboard Navigation Patterns\n\n**✅ Good - Tab order follows visual order:**\n\n```typescript\n// Elements appear in logical tab order\n\n```\n\n**✅ Good - Keyboard shortcuts:**\n\n```typescript\nimport { useEffect } from 'react'\n\nfunction SearchDialog({ onClose }: { onClose: () => void }) {\n\tuseEffect(() => {\n\t\tfunction handleKeyDown(e: KeyboardEvent) {\n\t\t\tif (e.key === 'Escape') {\n\t\t\t\tonClose()\n\t\t\t}\n\t\t}\n\n\t\twindow.addEventListener('keydown', handleKeyDown)\n\t\treturn () => window.removeEventListener('keydown', handleKeyDown)\n\t}, [onClose])\n\n\treturn \n}\n```\n\n**✅ Good - Focus trap in modals:**\n\n```typescript\n// Radix Dialog automatically handles focus trap\n\n\t\t\t\t\t{toast.message}\n\t\t\t\t
\n\t\t\t))}\n\t\tReadable body text
\nClear headings
\n```\n\n**✅ Good - Sufficient line height:**\n\n```typescript\n// Tailwind defaults provide good line height\nComfortable reading
\n```\n\n**❌ Avoid - Small or hard-to-read text:**\n\n```typescript\n// ❌ Don't use very small text\nHard to read
\n```\n\n### Touch Target Sizes\n\n**✅ Good - Sufficient touch targets:**\n\n```typescript\n// Buttons should be at least 44x44px (touch target size)\n\n```\n\n**✅ Good - Spacing between interactive elements:**\n\n```typescript\n\n\t\n\t\n
\n```\n\n### Internationalization (i18n) Considerations\n\n**✅ Good - Use semantic HTML for dates/times:**\n\n```typescript\n\n```\n\n**✅ Good - Use semantic HTML for numbers:**\n\n```typescript\n// Screen readers can pronounce numbers correctly\nTotal: {count}
\n```\n\n**✅ Good - Language attributes:**\n\n```typescript\n// In root.tsx\n\n\t\n\t\t{/* Content */}\n\t\n\n```\n\n### Dark Mode Accessibility\n\n**✅ Good - Maintain contrast in dark mode:**\n\n```typescript\n// Ensure sufficient contrast in both modes\n\n\t{content}\n
\n```\n\n**✅ Good - Respect user preference:**\n\n```typescript\n// Epic Stack automatically handles theme preference\n// Use semantic colors that work in both modes\n\n```\n\n### Animation and Motion\n\n**✅ Good - Respect reduced motion:**\n\n```typescript\n// Tailwind automatically respects prefers-reduced-motion\n\n\t{/* Animations disabled for users who prefer reduced motion */}\n
\n```\n\n**✅ Good - Use CSS for animations:**\n\n```typescript\n// ✅ CSS animations can be disabled via prefers-reduced-motion\n\n\t{/* Content */}\n
\n\n// ❌ JavaScript animations may not respect user preferences\n```\n\n## Common mistakes to avoid\n\n- ❌ **Treating accessibility as a checklist**: Accessibility is about serving\n real people, not just meeting standards\n- ❌ **Missing form labels**: Always use `Field` component which includes\n labels - helps all users, not just screen reader users\n- ❌ **Using divs for semantic elements**: Use `