菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| 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. |
Use this skill for end-to-end Remix app work. It should help the agent choose the right layer first, reach for the right package, and avoid the most common Remix-specific mistakes.
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:
app/routes.ts define the typed URL contract and power href()
generation.Response
objects.context.set(Key, value).remix/ui. This is not React. A component
receives a handle, reads current props from handle.props, and returns a
render function.Use this skill for:
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:
app/routes.ts before
wiring handlers or UI.Response via router.fetch(...) before you add
clientEntry(...), animations, or DOM effects.AppContext from the root
middleware stack and use it in controllers.Request, FormData,
params, cookies, and external payloads before they reach rendering or
persistence logic.clientEntry(...) and run(...) only for real browser interactivity or
browser-only APIs.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 dataInside app/, organize by responsibility:
assets/ for client entrypoints and client-owned browser behaviorcontrollers/ for route-owned handlers and route-local UIdata/ 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 wiringWhen code could live in multiple places:
app/ui/.app/middleware/.app/data/.app/utils/ only as a last resort for truly cross-layer helpers.app/controllers/ for a simple leaf action, such as
app/controllers/home.tsxcontroller.tsx when a route owns nested routes or multiple
actions, such as app/controllers/account/controller.tsxapp/controllers/auth/login/controller.tsxapp/controllers/contact/page.tsxapp/ui/app/lib/ as a generic dumping groundapp/components/ as a second shared UI bucket when app/ui/
already owns that roleapp/controllers/app/utils/ when they have a
clearer homeremix/<subpath>, never import { ... } from 'remix'app/routes.ts as the source of truth for URLs. Use
routes.<name>.href(...) for redirects, links, tests, and internal URL
constructionResponse 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 flowclientEntry(...) layers
interactivity on topremix/data-schema (and
remix/data-schema/form-data for forms). parseSafe makes the failure path a
return value instead of an exceptionAppContext 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 harnessgetContext() when asyncContext()
is in the middleware stackhandle.props, keep state in
setup-scope variables, call handle.update() explicitly, and do DOM-sensitive
work in event handlers or queueTask(...), not in rendermix={mixin(...)} for behavior and styling
instead of inventing custom host prop conventions. Use mix={[...]} only when
composing multiple mixinsclientEntry(...) props must be serializable. Do not pass functions,
class instances, or opaque runtime objectshttpOnly always, sameSite by default, and secure
when serving over HTTPSrequireAuth() to protect authenticated route areas, but still authorize
resource ownership inside handlers and data writesremix/html-template for HTML generation so escaping stays
correctrouter.fetch(new Request(...)) and assert on the returned Responseroutes.<name>.href(...) in tests so URLs stay coupled to the route
contractcreateMemorySessionStorage() instead of production storagecreateRoot(...), interact with the real DOM, and call root.flush() between
stepsremix entry instead of a subpathclientEntry(...) before the server-rendered route behavior is correctclientEntry(...)getContext() without asyncContext() in the middleware stackFormData, params, cookies, or
external payloadsResponse
the route means to return rather than throwing a custom Error subclass and
catching it elsewherecreateCookie 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<Frame> reloads as mutually exclusive
patterns. Pick the lightest sync mechanism that fits the UX; small widgets may
reasonably poll a JSON endpointutils.ts, helpers.ts, or
common.ts when ownership is knownUse 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.
remix/fetch-router — the router itself. Use for createRouter, controller
and middleware types, and registering routesremix/fetch-router/routes — declarative route builders. Use for route,
get, post, put, del, form, resources when defining app/routes.tsremix/node-fetch-server — adapter from Node's http module to a Fetch-style
router. Use for createRequestListener in server.tsremix/assets — browser asset server. Use for createAssetServer when
serving compiled scripts and styles, getting public hrefs, and emitting
preloads. Shared compiler options such as target, sourceMaps,
sourceMapSourcePaths, and minify live at the top levelremix/headers — typed header parsers and builders. Use when reading
Accept, Cookie, or setting CacheControl, Vary, etc., instead of
hand-formatting stringsremix/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 when
working with raw patterns outside the router (custom matchers, scripts)remix/fetch-proxy — Fetch-based HTTP proxying. Use to forward a request to
another origin; pass xForwardedHeaders when the upstream needs forwarded
proto, host, and portremix/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-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/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/session-middleware — session(cookie, storage). Use to wire a session
cookie and storage backend into the root middleware stackremix/session/fs-storage, remix/session/memory-storage,
remix/session/cookie-storage — 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/auth-middleware — auth({ schemes }), requireAuth, the Auth
context key. Use to resolve identity into the request context and to gate
routesremix/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 render(...) 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.
Import from remix/ui/accordion, remix/ui/button, remix/ui/select, etc.remix/ui/test — component test rendering helpers such as renderremix/ui/jsx-runtime — JSX transform target. 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 destinationremix/static-middleware — staticFiles(dir). Use to serve files from
public/ exactly as they exist on diskremix/form-data-middleware — 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/compression-middleware — compression(). Use globally for text-like
responsesremix/logger-middleware — logger(). Use in development for request logs;
pass colors to force terminal color output on or offremix/method-override-middleware — methodOverride(). Use when HTML forms
need PUT, PATCH, or DELETEremix/async-context-middleware — asyncContext(), getContext(). Use when
helpers outside actions need request context without threading it through
every callremix/cors-middleware — cors(opts?). Use for endpoints called cross-originremix/csrf-middleware — csrf(opts?). Use when session-backed forms mutate
state and need synchronizer-token CSRF protectionremix/cop-middleware — cross-origin protection. Use to reject unsafe
cross-origin browser requestsremix/test — describe, it, and lifecycle hooks. Use as the test
frameworkremix/test/cli — programmatic test runner APIs such as runRemixTestremix/cli — programmatic Remix CLI API. Use the remix executable for
project commands such as remix test, remix routes, and remix doctorremix/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 sequencesimport { form, get, post, resources, route } from 'remix/fetch-router/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' }),
}),
})
import type { Controller } from 'remix/fetch-router'
import type { AppContext } from '../router.ts'
import { routes } from '../routes.ts'
export default {
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} />)
},
},
} satisfies Controller<typeof routes.books, AppContext>
import {
createRouter,
type AnyParams,
type MiddlewareContext,
type WithParams,
} from 'remix/fetch-router'
export type RootMiddleware = [
ReturnType<typeof formData>,
ReturnType<typeof session>,
ReturnType<typeof loadDatabase>,
ReturnType<typeof loadAuth>,
]
export type AppContext<params extends AnyParams = AnyParams> = WithParams<
MiddlewareContext<RootMiddleware>,
params
>
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 })
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'
let bookSchema = f.object({
slug: f.field(s.string()),
title: f.field(s.string()),
})
export default {
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 }))
},
},
} satisfies Controller<typeof routes.books, AppContext>
This shape works without JavaScript, returns a Response for every outcome, and
is ready for clientEntry(...) interactivity when the UI needs it.
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.
Orchestrate sub-agents for large tasks: plan, delegate coding to cheap/fast models, parallelize the critical path, layer reviews, and close every loop without a human relay. Use when acting as an orchestrator or writing a kickoff prompt for one.
Babysit a PR. Iterate with AI reviewers and CI. Get it ready and maybe merge. Send summary message.
Generate and maintain the system recap block in a PR description - a GitHub-rendered visual summary of which system primitives a change touches, how risky it is, and what changed. Use when planning a non-trivial change (plan mode), when creating or updating a pull request (recap mode), or when the user asks for a visual recap, visual plan, system review, or PR recap.