| name | remix |
| description | Build and review Remix 3 applications using the `remix` npm package and subpath imports. Use when working on Remix app structure, routes, controllers, middleware, validation, data access, auth, sessions, file uploads, server setup, UI components, hydration, navigation, or tests. |
Build a Remix App
Use this skill for end-to-end Remix app work. This skill helps you choose the right layer
first, reach for the right package, and avoid the most common Remix-specific mistakes.
Full Package Documentation
This skill is the quick guide. When you need fuller API documentation, examples, or package-specific
details for a remix/* subpath, first look for a README next to the relevant generated source file
in the published remix package:
node_modules/remix/src/<subpath>/README.md. If that README does not exist, look for the nearest
parent README because some subpaths share their parent package documentation.
Examples:
remix/router -> node_modules/remix/src/fetch-router/README.mdremix/ui/button -> node_modules/remix/src/ui/button/README.md
What Remix Is
Remix 3 is a server-first web framework built on Web APIs such as Request, Response, URL,
and FormData. All packages ship from a single npm package, remix, and are imported via
subpath. There is no top-level remix import.
A Remix app has four main pieces:
- Routes in
app/routes.ts define the typed URL contract and power href() generation.
- Controllers in
app/actions implement that contract and return Response objects.
- Middleware composes request lifecycle behavior and populates typed context via
context.set(Key, value).
- Components render UI with
remix/ui. This is not React. A component receives a
handle, reads current props from handle.props, and returns a zero-argument render function.
When To Use This Skill
Use this skill for:
- new features or refactors that touch routing, controllers, middleware, data, auth, sessions, UI,
or tests
- reviewing Remix app code for correctness, architecture, or framework usage
- answering "how should this be structured in Remix?" questions
- finding the right package, reference doc, or default pattern for a task
Load Only The References You Need
Classify the task first, then load the smallest useful reference set. Each reference file starts
with a "What This Covers" section that lists the topics inside it — read that first to confirm
the file is relevant before reading the rest.
Use the table below to find candidates. Loading more than two or three files at once is usually a
sign that the task hasn't been narrowed enough yet.
| Task involves... | Start with |
|---|
| Defining URLs, writing controllers and actions, returning responses | references/routing-and-controllers.md |
| Composing the request lifecycle, ordering middleware, bridging to a server | references/middleware-and-server.md |
| Compiling and serving browser modules, asset URL namespaces, preloads | references/assets-and-browser-modules.md |
| Parsing input, validating with schemas, defining tables, querying, migrations | references/data-and-validation.md |
| Per-browser state, login flows, route protection, identity | references/auth-and-sessions.md |
Component setup, state, lifecycle, updates, queueTask, context | references/component-model.md |
| Event handlers, styles, refs, click/key behavior, simple animations | references/mixins-styling-events.md |
clientEntry, run, <Frame>, navigation, <head> | references/hydration-frames-navigation.md |
| Router tests, component tests, test isolation | references/testing-patterns.md |
| Spring physics, tweens, layout transitions | references/animate-elements.md |
| Authoring custom reusable mixins | references/create-mixins.md |
Common bundles:
- Form or CRUD feature -> routing, data and validation, testing; add auth if user-specific
- Protected area -> auth and sessions, routing, testing
- Interactive widget -> component model, mixins and styling; add hydration only if it runs in
the browser
- Browser asset pipeline -> assets and browser modules, hydration, middleware and server
- File upload -> middleware and server, data and validation, testing
- Navigation or frames -> hydration, frames, navigation
Default Workflow
- Classify the change. Decide whether it changes the route contract, request lifecycle, data
model, auth or session behavior, or only UI.
- Start from the server contract. Add or update
app/routes.ts before wiring handlers or UI.
- Put code in the narrowest owner. Favor route-local code first, then promote only when reuse
is real.
- Make the server path correct before adding browser behavior. A route should return the right
Response via router.fetch(...) before you add clientEntry(...), animations, or DOM
effects.
- Add middleware deliberately. Keep fast-exit middleware early and request-enriching
middleware later. Export a typed
AppContext from the root middleware stack and use it in
controllers.
- Validate input at the boundary. Parse and validate
Request, FormData, params, cookies,
and external payloads before they reach rendering or persistence logic.
- Hydrate only when necessary. Prefer server-rendered UI. Use
clientEntry(...) and run(...)
only for real browser interactivity or browser-only APIs.
- Test the narrowest meaningful layer. Prefer router tests for route behavior. Use component
tests when the behavior is truly interactive or DOM-specific.
- Finish with verification. Re-read the route flow, confirm auth and authorization boundaries,
and run the smallest relevant test and typecheck loop.
Project Layout
Use these root directories consistently:
app/ for runtime application codedb/ for migrations and local database filespublic/ for static assets served as-istest/ for shared helpers, fixtures, and integration coveragetmp/ for uploads, caches, local session files, and other scratch data
Inside app/, organize by responsibility:
assets/ for client entrypoints and client-owned browser behavioractions/ for controller-owned route handlers, route-local response rendering, and route-local
UI/helpers that are not shared across route areasdata/ for schema, queries, persistence setup, migrations, and runtime data initializationmiddleware/ for request lifecycle concerns such as auth, sessions, uploads, and database
injectionui/ for shared cross-route UI primitivesutils/ only for genuinely cross-layer helpers that do not clearly belong elsewhereroutes.ts for the route contractrouter.ts for router setup and wiring
Placement Precedence
When code could live in multiple places:
- Put it in the narrowest owner first.
- If it belongs to one route, keep it with that route.
- If it is shared UI across route areas, move it to
app/ui/.
- If it is request lifecycle setup, keep it in
app/middleware/.
- If it is schema, query, persistence, or startup data logic, keep it in
app/data/.
- Use
app/utils/ only as a last resort for truly cross-layer helpers.
Route Ownership
- Put top-level leaf actions in
app/actions/controller.tsx
- A controller's
actions object contains only direct leaf route keys from the route map passed to
router.map(...)
- Add
app/actions/<route-key>/controller.tsx for each nested route map that needs actions or
middleware, and map it explicitly with router.map(routes.<routeKey>, controller)
- Name directories under
app/actions/ after route-map keys, not URL path segments
- Keep route-local UI and helpers next to the controller that owns them
- Move shared cross-route UI to
app/ui/
- If a top-level leaf grows into a route map, move its handler into the nested route-key
controller and update
app/router.ts to map that route map explicitly
Response Rendering And Utilities
- Treat response rendering as action-layer code: modules that return
Response, choose HTTP status
or headers, call redirect(...), or call the local render(...) helper belong in app/actions
- Keep
app/actions/render.tsx small; it should adapt remix/ui/server output to
createHtmlResponse(...). Route-specific response assembly can live in flat action modules, but
directories under app/actions/ must still match route-map keys
- Put pure support code in focused
app/utils/<topic>.ts modules. Formatting, MIME
classification, path parsing, sorting, and normalization should be testable without a router,
request context, or Response, and should not import from app/actions, remix/ui/server, or
remix/response/*
- Do not introduce page-data intermediary shapes only to keep route-specific renderers away from
render(...); keep response assembly in actions and extract only the pure helpers
Layout Anti-Patterns
- Do not create
app/lib/ as a generic dumping ground
- Do not create
app/components/ as a second shared UI bucket when app/ui/ already owns that
role
- Do not create
app/controllers/; Remix app route handlers live under app/actions/
- Do not put shared cross-route UI in
app/actions/
- Do not create standalone root action files; put root route actions in
app/actions/controller.tsx
- Do not put nested route-map keys in a controller's
actions
- Do not register normal app leaf routes directly in
app/router.ts when they belong in a
controller
- Do not rely on middleware from one controller to protect another controller; map middleware
explicitly in each controller that needs it
- Do not put middleware or persistence helpers in
app/utils/ when they have a clearer home
Core Remix Rules
- Import from
remix/<subpath>, never import { ... } from 'remix'
- Treat
app/routes.ts as the source of truth for URLs. Use routes.<name>.href(...) for
redirects, links, tests, and internal URL construction
- Controllers should return explicit
Response objects, including redirects, 404s, and
validation failures. At the route boundary, prefer returning a Response for expected outcomes
(validation errors, conflicts, not found) over throwing for control flow
router.map(routes, controller) maps only the direct leaf routes in routes; nested route maps
must be mapped with their own explicit controllers- Model HTTP behavior explicitly. Status codes, headers, redirects, cache rules, and content types
are part of the route contract
- Make the server route correct first. A POST should already return the right HTML, redirect, or
error response on its own before
clientEntry(...) layers interactivity on top
- Validate input at the boundary using
remix/data-schema (and remix/data-schema/form-data for
forms). parseSafe makes the failure path a return value instead of an exception
- Derive
AppContext from the root middleware stack so get(Database), get(Session),
get(Auth), and similar keys stay typed. If the controller never reads from context, it doesn't
need the harness
- Outside actions and controllers, only use
getContext() when asyncContext() is in the
middleware stack
- Remix Component is not React: write
function Name(handle: Handle<Props>) { return () => ... },
read props from handle.props, keep state in setup-scope variables, call handle.update()
explicitly, and do DOM-sensitive work in event handlers or queueTask(...), not in render
- Prefer host-element mixins via
mix={mixin(...)} for behavior and styling instead of inventing
custom host prop conventions. Use mix={[...]} only when composing multiple mixins
- Hydrated
clientEntry(...) props must be serializable. Do not pass functions, class instances, or
opaque runtime objects
Security And Session Defaults
- Never ship demo secrets. In non-test environments, require session and provider secrets from the
environment and fail fast if they are missing
- Use hardened cookies:
httpOnly always, sameSite by default, and secure when serving over
HTTPS
- Regenerate session IDs on login, logout, and privilege changes
- Use
requireAuth() to protect authenticated route areas, but still authorize resource ownership
inside handlers and data writes
- Add CSRF protection when browser forms mutate state using cookie-backed sessions
- Add CORS only for endpoints that must be called cross-origin. Prefer same-origin by default
- Prefer JSX or
remix/html-template for HTML generation so escaping stays correct
- Validate uploads for size, type, and destination. Treat filenames and content as untrusted input
Testing Defaults
- Prefer server and router tests first. Drive the app with
router.fetch(new Request(...)) and
assert on the returned Response
- Keep controller tests shaped like controllers: root route behavior belongs in
app/actions/controller.test.ts(x), and nested route-map behavior belongs beside that route-key
controller
- Build a fresh router per test or per suite so sessions, in-memory storage, and database state
stay isolated
- Use
routes.<name>.href(...) in tests so URLs stay coupled to the route contract
- For auth or session scenarios, use a test cookie and
createMemorySessionStorage() instead of
production storage
- Co-locate tests for pure
app/utils helpers beside their modules. Test response behavior through
router or controller tests
- Use component tests only for interactive or DOM-specific behavior. Render with
createRoot(...),
interact with the real DOM, and call root.flush() between steps
- Prefer one representative behavior test over many repetitive assertion variants
Common Mistakes To Avoid
- Treating Remix Component like React and reaching for hooks or implicit rerendering
- Importing from a top-level
remix entry instead of a subpath
- Adding
clientEntry(...) before the server-rendered route behavior is correct
- Passing non-serializable props into
clientEntry(...)
- Calling
getContext() without asyncContext() in the middleware stack
- Getting middleware order wrong; fast exits like static files belong early, request enrichment later
- Skipping boundary validation and trusting raw
FormData, params, cookies, or external payloads
- Letting route-local domain errors leak out of the controller. Translate expected outcomes
(validation, conflicts, not-found) into the HTTP
Response the route means to return rather than
throwing a custom Error subclass and catching it elsewhere
- Reaching for
createCookie when a tamper-sensitive or server-managed per-browser fact really
wants remix/session. If editing the value would be a bug, use a session
- Building a JSON-only RPC layer when a normal form POST, redirect, or resource route would be
simpler. Fetch-from-the-client is a layer on top of sound route behavior, not a replacement for
it
- Treating JSON state endpoints and
<Frame> reloads as mutually exclusive patterns. Pick the
lightest sync mechanism that fits the UX; small widgets may reasonably poll a JSON endpoint
- Assuming authentication is enough without per-resource authorization checks
- Dropping shared code into vague buckets like
utils.ts, helpers.ts, or common.ts when
ownership is known
- Recreating the old
app/controllers or standalone root action file layout instead of using
controllers under app/actions
- Putting nested route-map keys inside a controller
actions object. Map nested route maps
explicitly in app/router.ts
- Treating direct
router.get(...)/router.post(...) registrations as the default app structure
instead of using controllers
- Assuming controller middleware applies to controllers registered for nested route maps
- Writing only component tests for a feature whose main behavior is really an HTTP route concern
Package Map
Use this map to find the right package quickly. Each entry says what the package is for, not just
what it exports. Open the linked reference file when you need full examples.
Routing, Server, and Responses
remix/router — the router itself. Use for createRouter, controller and middleware
types, and registering routesremix/routes — declarative route builders. Use for route, get, post, put, del,
form, resources when defining app/routes.tsremix/node-fetch-server — default Node adapter for new apps. Use createRequestListener with
node:http, node:https, or node:http2 in server.ts when booting the template-style appremix/assets — browser asset server. Use for createAssetServer when serving compiled
scripts and styles, getting public hrefs, and emitting preloads. Configure a basePath, and
keep fileMap URL patterns relative to it. Shared compiler options such as target,
sourceMaps, sourceMapSourcePaths, and minify live at the top levelremix/headers — SuperHeaders plus typed header parsers and builders. Use the default export
when you want a Headers subclass with typed accessors like headers.contentType,
headers.cacheControl, and headers.setCookie; use named classes such as CacheControl,
ContentDisposition, and Vary when working with individual header valuesremix/response/redirect — redirect(href, status?). Use for the canonical "POST then redirect"
pattern and other location changesremix/response/html — createHtmlResponse. Use when you need an HTML Response from a string
or stream without rendering through remix/uiremix/response/compress — compressResponse. Use when compressing one-off responses outside
the global compression() middlewareremix/response/file — file-download responses. Use for Content-Disposition: attachment
responsesremix/route-pattern — low-level URL matching and generation. Use RoutePattern or
createMatcher when working with raw patterns outside the router. href(...) encodes pathname
and search params for you, and match(...) returns decoded paramsremix/route-pattern/specificity — pattern ranking helpers. Use only when building custom
matcher or reporting logic outside the normal router/matcher APIsremix/fetch-proxy — Fetch-based HTTP proxying. Use to forward a request to another origin; pass
xForwardedHeaders when the upstream needs forwarded proto, host, and port. It also rewrites
proxied Set-Cookie domain/path attributes by default
Data, Validation, and Persistence
remix/data-schema — schema builders for runtime validation. Use for parse and parseSafe
to validate any input that crosses a trust boundary, and .transform(...) when validated output
should map to a different value or typeremix/data-schema/checks — common check helpers (email, minLength, maxLength, etc.).
Use to compose into a schemaremix/data-schema/coerce — coercion helpers for strings, numbers, booleans, dates, and ids.
Use when input arrives as a string but should be a typed valueremix/data-schema/form-data — f.object and f.field for parsing FormData directly. Use
in actions that read browser formsremix/data-schema/lazy — recursive or mutually-referential schemas. Use when a schema needs to
refer to itself or another schema that is declared laterremix/data-table — typed tables and a Database interface. Use for table, column,
createDatabase when modeling persisted dataremix/data-table/sqlite, remix/data-table/postgres, remix/data-table/mysql — adapters.
Use to back createDatabase with a real engine. SQLite accepts Node, Bun, and compatible
synchronous clients with the shared prepare/exec surfaceremix/data-table/migrations — migration authoring and runners. Use for createMigration,
createMigrationRunnerremix/data-table/migrations/node — loadMigrations from disk. Use in startup scripts that
apply migrationsremix/data-table/operators — query operators such as inList(...). Use when where clauses
need set or comparison logicremix/data-table/sql-helpers — SQL helper utilities for adapter or advanced query work. Avoid
this in normal app code unless you are intentionally working below the table/query API
Auth, Sessions, and Cookies
remix/session — the Session object: get, set, flash, unset, regenerateId. Use for
any per-browser state where tampering would be a bug (login, "I submitted this form already",
cart, flash messages)remix/middleware/session — session(cookie, storage). Use to wire a session cookie and
storage backend into the root middleware stackremix/session-storage/fs, remix/session-storage/memory, remix/session-storage/cookie —
storage backends. Use fs-storage for single-process apps, memory-storage for tests,
cookie-storage for stateless deployments where data fits in a cookieremix/session-storage/redis — Redis-backed storage. Use for multi-process or multi-host
deploymentsremix/session-storage/memcache — Memcache-backed storage. Same multi-host use case as Redisremix/cookie — createCookie for plain signed/unsigned cookies. Use for non-sensitive
preferences where the client is allowed to control the value (theme, locale, dismissed banner).
For state where tampering matters, prefer remix/sessionremix/auth — credentials, OAuth, OIDC, and Atmosphere providers. Use to define how identity is
verified, start/finish external login, and refresh stored OAuth/OIDC token bundles with
refreshExternalAuth(...)remix/middleware/auth — auth({ schemes }), requireAuth, the Auth context key. Use to
resolve identity into the request context and to gate routes
UI, Hydration, and Browser Behavior
remix/ui — the component runtime: components, core mixins, clientEntry, run, <Frame>,
navigation helpers, and createRoot. Use for app UI behaviorremix/ui/server — server rendering: renderToStream, renderToString. Use in the
app/actions/render.tsx helper that returns HTML responsesremix/ui/animation — animation APIs: animateEntrance, animateExit, animateLayout,
spring, tween, and easingsremix/ui/<primitive> — UI primitives, mixins, glyphs, and theme helpers. Current subpaths
include remix/ui/accordion, remix/ui/anchor, remix/ui/breadcrumbs, remix/ui/button,
remix/ui/combobox, remix/ui/glyph, remix/ui/listbox, remix/ui/menu,
remix/ui/popover, remix/ui/scroll-lock, remix/ui/select, remix/ui/separator, and
remix/ui/themeremix/ui/test — component test rendering helpers such as renderremix/ui/jsx-runtime and remix/ui/jsx-dev-runtime — JSX transform targets. Configured in
tsconfig.json, rarely imported directlyremix/html-template — escaped HTML template literals. Use when generating HTML outside the
component system (RSS feeds, email bodies, error pages)remix/file-storage — backend-agnostic File storage interface. Use as the type bound for
upload destinationsremix/file-storage/fs, remix/file-storage/memory, remix/file-storage/s3 — storage
backends. Use to implement an upload destination
Middleware
remix/middleware/static — staticFiles(dir). Use to serve files from public/ exactly as
they exist on diskremix/middleware/form-data — formData(). Use to parse FormData once and expose it via
get(FormData) instead of calling await request.formData() in each actionremix/form-data-parser — lower-level parseFormData, FileUpload. Use when implementing
custom upload handlers. Upload handler errors propagate directlyremix/multipart-parser and remix/multipart-parser/node — low-level multipart stream parsing.
MultipartPart.headers is a plain object keyed by lower-case header name; read values with
bracket notation such as part.headers['content-type']remix/middleware/compression — compression(). Use globally for text-like responsesremix/middleware/logger — logger(). Use in development for request logs; pass colors to
force terminal color output on or offremix/middleware/method-override — methodOverride(). Use when HTML forms need PUT,
PATCH, or DELETEremix/middleware/async-context — asyncContext(), getContext(). Use when helpers outside
actions need request context without threading it through every callremix/middleware/cors — cors(opts?). Use for endpoints called cross-originremix/middleware/csrf — csrf(opts?). Use when session-backed forms mutate state and need
synchronizer-token CSRF protectionremix/middleware/cop — cross-origin protection. Use to reject unsafe cross-origin browser
requests
Test
remix/test — describe, it, and lifecycle hooks. Use as the test frameworkremix/test/cli — programmatic test runner APIs such as runRemixTestremix/node-fetch-server/test — createTestServer for end-to-end tests that need a real local
HTTP server around a Fetch handlerremix/cli — programmatic Remix CLI API. Use the remix executable for project commands such
as remix test, remix routes, remix doctor, and remix versionremix/assert — assertion helpers. Use in place of node:assert so messages render cleanly
in the runnerremix/terminal — ANSI styles, color detection, style factories, and testable terminal streams.
Use for CLIs and terminal output instead of hand-rolled escape sequencesremix/fs — small filesystem helpers such as openLazyFile and writeFile. Use in Node-only
app or tooling code when you need lazy file responses or safe file writesremix/lazy-file — LazyFile primitives and byte-range helpers. Use when implementing file or
range responses below the higher-level response/file helpersremix/mime — content-type and MIME detection helpers. Use instead of maintaining app-local
extension mapsremix/tar-parser — streaming tar parsing. Use for import/export tooling that consumes tar
archives
Canonical Patterns
Define routes first
import { form, get, post, resources, route } from "remix/routes";
export const routes = route({
home: "/",
contact: form("contact"),
books: {
index: "/books",
show: "/books/:slug",
},
auth: route("auth", {
login: form("login"),
logout: post("logout"),
}),
admin: route("admin", {
index: get("/"),
books: resources("books", { param: "bookId" }),
}),
});
Type controllers against the route contract
import { createController } from 'remix/router'
import { routes } from '../routes.ts'
export default createController(routes.books, {
actions: {
async index({ get }) {
let db = get(Database)
let allBooks = await db.findMany(books, { orderBy: ['id', 'asc'] })
return render(<BooksIndexPage allBooks={allBooks} />)
},
async show({ get, params }) {
let db = get(Database)
let book = await db.findOne(books, { where: { slug: params.slug } })
if (!book) return new Response('Not Found', { status: 404 })
return render(<BookShowPage book={book} />)
},
},
})
Register Controllers Explicitly
import { createRouter } from "remix/router";
import rootController from "./actions/controller.tsx";
import adminController from "./actions/admin/controller.tsx";
import adminBooksController from "./actions/admin/books/controller.tsx";
import authController from "./actions/auth/controller.tsx";
import authLoginController from "./actions/auth/login/controller.tsx";
import booksController from "./actions/books/controller.tsx";
import contactController from "./actions/contact/controller.tsx";
import { routes } from "./routes.ts";
export const router = createRouter({ middleware });
router.map(routes, rootController);
router.map(routes.contact, contactController);
router.map(routes.books, booksController);
router.map(routes.auth, authController);
router.map(routes.auth.login, authLoginController);
router.map(routes.admin, adminController);
router.map(routes.admin.books, adminBooksController);
Compose middleware deliberately
import { createRouter } from "remix/router";
let middleware = [];
if (process.env.NODE_ENV === "development") {
middleware.push(logger());
}
middleware.push(compression());
middleware.push(staticFiles("./public"));
middleware.push(formData());
middleware.push(methodOverride());
middleware.push(session(cookie, storage));
middleware.push(asyncContext());
middleware.push(loadDatabase());
middleware.push(loadAuth());
let router = createRouter({ middleware });
Validate, mutate, and respond
import { createController } from 'remix/router'
import { redirect } from 'remix/response/redirect'
import * as s from 'remix/data-schema'
import * as f from 'remix/data-schema/form-data'
import { Session } from 'remix/session'
import { Database } from 'remix/data-table'
import { routes } from '../routes.ts'
let bookSchema = f.object({
slug: f.field(s.string()),
title: f.field(s.string()),
})
export default createController(routes.books, {
actions: {
async create({ get }) {
let parsed = s.parseSafe(bookSchema, get(FormData))
if (!parsed.success) {
return render(<NewBookPage errors={parsed.issues} />, { status: 400 })
}
let db = get(Database)
let book = await db.create(books, parsed.value)
let session = get(Session)
session.flash('message', `Added ${book.title}.`)
return redirect(routes.books.show.href({ slug: book.slug }))
},
},
})
This shape works without JavaScript, returns a Response for every outcome, and is ready for
clientEntry(...) interactivity when the UI needs it.
Build UI from handle props plus render
import { on, type Handle } from "remix/ui";
function Counter(handle: Handle<{ initialCount?: number; label: string }>) {
let count = handle.props.initialCount ?? 0;
return () => (
<button
mix={on("click", () => {
count++;
handle.update();
})}
>
{handle.props.label}: {count}
</button>
);
}
Only add clientEntry(...) and run(...) when the component needs browser interactivity or
browser-only APIs.
