Remix Project

---
applyTo: "**/app/**/*.tsx, **/app/**/*.ts"
---

# Remix Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest Remix documentation: https://remix.run/docs
- Use Remix 2.x for full-stack web applications
- Leverage nested routing with file-based conventions
- Implement server-side data loading with loaders
- Use actions for data mutations and form handling
- Follow progressive enhancement principles

**Core Principles:**

- Embrace web fundamentals: forms, links, HTTP
- Use loaders for GET requests (data fetching)
- Use actions for POST/PUT/DELETE (mutations)
- Implement nested routes for nested layouts
- Leverage the platform (browser, HTTP)
- Progressive enhancement - works without JavaScript

**Routing:**

- Use file-based routing in app/routes/
- Implement nested routes with folder structure
- Use dynamic segments with $param.tsx
- Implement catch-all routes with $.tsx
- Use index routes (index.tsx) for default content

**Data Loading:**

- Implement loader functions for server-side data fetching
- Use useLoaderData() hook in components
- Return Response objects from loaders
- Implement proper error handling in loaders
- Use defer() for streaming data

**Mutations:**

- Implement action functions for form submissions
- Use useActionData() for accessing action results
- Return redirects after successful mutations
- Handle validation errors in actions
- Use Form component for progressive enhancement

**Forms:**

- Use Remix Form component for enhanced forms
- Implement proper validation with Zod or similar
- Handle optimistic UI updates
- Use fetcher for non-navigational forms
- Implement proper error display

**Error Handling:**

- Use ErrorBoundary for route-level errors
- Implement CatchBoundary for 404s and other responses
- Return proper HTTP status codes
- Display user-friendly error messages
- Log errors for monitoring

**Sessions and Cookies:**

- Use session storage for authentication
- Implement cookie-based sessions
- Store minimal data in sessions
- Use secure cookie settings
- Implement proper CSRF protection

**Performance:**

- Use defer() for non-critical data
- Implement proper caching headers
- Use CDN for static assets
- Leverage nested routing for code splitting
- Implement resource routes for API endpoints

**Meta and SEO:**

- Use meta() function for page metadata
- Implement dynamic meta tags based on data
- Use links() for stylesheets and prefetching
- Implement proper OpenGraph tags
- Use canonical URLs

**Testing:**

- Use Vitest for unit testing
- Implement integration tests with Testing Library
- Test loaders and actions separately
- Use MSW for mocking API calls
- Implement E2E tests with Playwright

**Summary:**

> For all Remix work, always use the fetch tool to look up the latest documentation from https://remix.run/docs. Build fast, resilient web applications with progressive enhancement.