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