# remix-run/remix — codebase unpack

> Canonical page: https://codevetter.com/unpack/remix

This is a deterministic Repo Unpack scan of remix-run/remix — a structural map, not a review, security audit, or maintainer-endorsed description.

- Scanned commit: 27bd7a4401594ec1acbe30ee3937518832270a30 (2026-10-01)
- Last upstream commit: Use atomic writes in HMR tests (#11960)
- Generated by codevetter 1.15.0 on 2026-10-02
- 2509 files scanned · 12.7 MB

Source inspection; upstream code and tests were not executed.

## Languages

- TypeScript: 1706 files
- JSON: 279 files
- Markdown: 276 files
- JavaScript: 85 files
- YAML: 31 files
- CSS: 14 files
- HTML: 13 files
- SQL: 9 files

## Repository structure

- packages/ — 1700 files
- demos/ — 418 files
- docs/ — 242 files
- scripts/ — 50 files
- .agents/ — 33 files
- .github/ — 26 files
- template/ — 17 files
- decisions/ — 6 files

Probable source entrypoint: `packages/` (inferred from the tree, not upstream docs)

## Package

- package.json: remix-the-web — 7 declared dependencies

## Structural health signals

Average score 7.1/10 across 96 files; 28 hotspots. These are deterministic review leads, not proof of a bug.

## Recent history

- 27bd7a440159 (2026-10-01) Use atomic writes in HMR tests (#11960)
- 6f8acb3c6b58 (2026-10-01) Fix release readiness and report the published Remix tag (#11959)
- 70cdc64df8fa (2026-10-01) Release v3.0.0 (#11954)
- 114d151388d4 (2026-10-01) Update install instructions for the stable Remix release (#11957)
- 697c7e98c213 (2026-10-01) Preserve encoded API documentation links

## Overview

Remix 3 is a full-stack TypeScript framework assembled from focused packages and distributed through the generated `remix` umbrella package. It connects typed Fetch routing, middleware, streaming server rendering, browser hydration, asset compilation, authentication, persistence, and testing through Web APIs. This brief investigates commit 27bd7a4401594ec1acbe30ee3937518832270a30 through public tracked source; its inventory is bounded, and tests and CI were inspected, not executed.

## System map

The repository separates portable framework packages from Node tooling, browser runtime code, example applications, and documentation generators. The `remix` distribution is generated from a canonical alias manifest rather than maintained as an independent implementation. The inspected application template starts a Node HTTP server, but routing and rendering boundaries use Web requests, responses, and streams. Storage is selected through interfaces and adapters rather than one repository-wide database.
- The root is a private ESM workspace pinned to pnpm@10.34.2 with Node >=24.3.0; its recursive scripts build, test, and typecheck workspace packages. — [package.json#L1-20](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/package.json#L1-L20) [package.json#L35-40](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/package.json#L35-L40)
- The pnpm workspace includes packages, demos, documentation apps, benchmarks, CLI fixtures, the application template, and maintenance scripts. — [pnpm-workspace.yaml#L18-41](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/pnpm-workspace.yaml#L18-L41)
- scripts/generate-remix.ts generates source re-exports, package exports, dependencies, copied READMEs, guides, and the documentation index from the umbrella manifest. — [scripts/generate-remix.ts#L1-22](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/scripts/generate-remix.ts#L1-L22) [packages/remix/manifest.json#L1-18](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/remix/manifest.json#L1-L18)
- The published-facing `remix` manifest exposes focused subpaths for components, auth, schema validation, databases, file storage, and middleware; its root export is types-only in the inspected source exports. — [packages/remix/package.json#L26-68](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/remix/package.json#L26-L68) [packages/remix/package.json#L88-95](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/remix/package.json#L88-L95)
- The generated CLI executable calls runRemix(process.argv.slice(2)) and exits with its numeric result, while the reusable CLI API lives in @remix-run/cli. — [packages/remix/src/cli-entry.ts#L1-13](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/remix/src/cli-entry.ts#L1-L13) [packages/cli/src/index.ts#L1-11](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/index.ts#L1-L11)
- The application template runs TypeScript/JSX directly through remix/node-tsx in development and production; development uses Node watch mode, and HMR has a separate command. — [template/package.json#L5-16](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/package.json#L5-L16)
- template/server.ts adapts router.fetch to Node HTTP, defaults PORT to 44100, recognizes REMIX_NODE_HMR and HMR_PROXY_PORT, and closes connections on SIGINT or SIGTERM. — [template/server.ts#L1-20](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/server.ts#L1-L20) [template/server.ts#L22-35](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/server.ts#L22-L35)
- The server component renderer produces ReadableStream<Uint8Array>; the browser runtime owns document frames, scheduling, styles, module caches, and navigation listeners. — [packages/component/src/server/stream.ts#L269-300](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/server/stream.ts#L269-L300) [packages/component/src/runtime/run.ts#L140-184](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L140-L184)
- SessionStorage defines asynchronous read(cookie) and save(session) operations; cookie storage embeds session data, whereas memory storage uses a process-local Map. — [packages/session/src/lib/session-storage.ts#L10-27](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session/src/lib/session-storage.ts#L10-L27) [packages/session/src/lib/session-storage/cookie.ts#L12-41](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session/src/lib/session-storage/cookie.ts#L12-L41) [packages/session/src/lib/session-storage/memory.ts#L21-52](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session/src/lib/session-storage/memory.ts#L21-L52)
- The bookstore demo selects SQLite with foreign keys, uses an in-memory database for NODE_ENV=test, and otherwise stores its database beside SQL migrations and seed data. — [demos/bookstore/app/db.ts#L1-19](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/bookstore/app/db.ts#L1-L19)
- Maintenance scripts are a separate ESM workspace with Octokit, semver, YAML, and shared documentation dependencies, plus remix test and tsc validation commands. — [scripts/package.json#L1-21](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/scripts/package.json#L1-L21)
- Repository automation includes generated comment routing, iteration, proposal review, and pull-request review workflows in addition to normal build/test workflows. — [.github/workflows/aw-comment-router.lock.yml#L57-78](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/aw-comment-router.lock.yml#L57-L78) [.github/workflows/aw-command-iterate.lock.yml#L63-94](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/aw-command-iterate.lock.yml#L63-L94) [.github/workflows/aw-command-review-proposal.lock.yml#L77-90](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/aw-command-review-proposal.lock.yml#L77-L90) [.github/workflows/aw-command-review-pull-request.lock.yml#L62-93](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/aw-command-review-pull-request.lock.yml#L62-L93)

## Feature catalog

The primary users are application developers consuming framework APIs and CLI commands. Features include routing, server and browser UI, assets, authentication, database management, storage, and testing. The bookstore and social-auth applications expose concrete examples of these capabilities. This catalog covers inspected public surfaces and documented package families; it is not an exhaustive enumeration of every export or demo screen.
- runRemix dispatches new, completion, assets, doctor, db, routes, test, version, and help commands, including --help and --version aliases. — [packages/cli/src/lib/cli.ts#L86-139](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/cli.ts#L86-L139)
- `remix new <target-dir>` scaffolds an application and accepts --app-name and --force. — [packages/cli/src/lib/commands/new.ts#L65-99](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/commands/new.ts#L65-L99) [packages/cli/src/lib/bootstrap-project.ts#L49-83](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L49-L83)
- `remix assets` lists browser-reachable assets; `remix assets inspect <url-or-file>` reports status, URL, file path, and matching denial information. — [packages/cli/src/lib/commands/assets.ts#L17-40](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/commands/assets.ts#L17-L40) [packages/cli/src/lib/commands/assets.ts#L52-79](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/commands/assets.ts#L52-L79) [packages/cli/src/lib/commands/assets.ts#L89-98](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/commands/assets.ts#L89-L98)
- Database CLI help exposes wipe, migrate, rollback, status, seed, and reset, with migration targeting, rollback dry-run, connection environment selection, and force flags for destructive operations. — [packages/cli/src/lib/commands/db.ts#L57-105](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/commands/db.ts#L57-L105)
- Routing supports method-specific registration, controller mapping, mounted route installers, automatic HEAD fallback from GET, and 405 responses with Allow headers. — [packages/fetch-router/src/lib/router.ts#L124-160](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L124-L160) [packages/fetch-router/src/lib/router.ts#L382-428](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L382-L428) [packages/fetch-router/src/lib/router.ts#L567-583](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L567-L583)
- The template exposes a home page and /assets/*path; its home controller returns component-rendered HTML and its asset controller falls back to a 404 response. — [template/app/routes.ts#L1-6](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/routes.ts#L1-L6) [template/app/actions/controller.tsx#L7-15](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/actions/controller.tsx#L7-L15)
- render middleware provides streaming component HTML, nested frame resolution, and asset-backed client-entry metadata; the browser runtime exposes ready(), flush(), dispose(), and frame handles. — [packages/render-middleware/src/lib/render-ui.ts#L70-93](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L70-L93) [packages/render-middleware/src/lib/render-ui.ts#L200-225](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L200-L225) [packages/component/src/runtime/run.ts#L49-57](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L49-L57)
- Template assets support development source maps, watching, optional component HMR, production minification, file allowlists, package allowlists, and test-file denial. — [template/app/assets.ts#L4-31](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/assets.ts#L4-L31)
- The auth public entrypoint exports credentials authentication, OAuth/OIDC lifecycle helpers, and provider factories for Auth0, Facebook, GitHub, Google, Microsoft, OIDC, Okta, and X. — [packages/auth/src/index.ts#L1-15](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/index.ts#L1-L15)
- The bookstore route map includes catalog browsing by genre and slug, search, contact forms, login and registration, password recovery, account settings, order views, cart APIs, checkout, and administrative resources. — [demos/bookstore/app/routes.ts#L16-52](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/bookstore/app/routes.ts#L16-L52) [demos/bookstore/app/routes.ts#L55-92](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/bookstore/app/routes.ts#L55-L92)
- The social-auth GitHub controller redirects into external login, resolves callback identities into persistent users/accounts, stores authentication state, and reports configuration or login failures through session flash messages. — [demos/social-auth/app/actions/auth/github/controller.ts#L16-65](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/social-auth/app/actions/auth/github/controller.ts#L16-L65)
- Documented package families also provide schema validation, MySQL/Postgres/SQLite queries, S3 file storage, multipart uploads, HTTP headers, compression, CORS/CSRF protection, and headless UI primitives. — [README.md#L60-83](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/README.md#L60-L83) [packages/remix/manifest.json#L19-39](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/remix/manifest.json#L19-L39) [README.md#L84-101](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/README.md#L84-L101)

## Data flow

HTTP input becomes a Web Request and request context before middleware and route dispatch. Component output becomes a byte stream carrying HTML and client-entry metadata, which the browser uses to activate components and frames. OAuth data crosses a session-backed redirect boundary before application-owned identity persistence. CLI inputs and configuration follow separate Node filesystem and process boundaries.
- For one-argument handlers, createRequestListener constructs a Web Request, invokes the handler, and sends synchronous or asynchronous responses through sendResponseForRequest; request-construction and handler failures use separate error paths. — [packages/node-fetch-server/src/lib/request-listener.ts#L128-164](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/node-fetch-server/src/lib/request-listener.ts#L128-L164)
- Router.fetch creates RequestContext, assigns its router, and dispatches through global middleware before matching routes against context.url. — [packages/fetch-router/src/lib/router.ts#L321-328](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L321-L328) [packages/fetch-router/src/lib/router.ts#L372-388](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L372-L388) [packages/fetch-router/src/lib/router.ts#L589-597](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L589-L597)
- dispatchMatch merges matched parameters into context.params and executes route middleware or the handler while racing against request abort. — [packages/fetch-router/src/lib/router.ts#L431-443](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L431-L443)
- renderWith stores a per-request renderer as both a context key and context.render; render connects request URL, abort signal, frame resolution, and client entries to renderToStream and createHtmlResponse. — [packages/render-middleware/src/lib/render.ts#L23-41](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render.ts#L23-L41) [packages/render-middleware/src/lib/render-ui.ts#L73-90](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L73-L90)
- A file:-based clientEntry ID is split into source ID and export name, resolved with assets.getScriptEntry, and returned with href, import map, and preload metadata. — [packages/render-middleware/src/lib/render-ui.ts#L200-225](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L200-L225)
- The template browser entry imports each requested module through importModule, selects its named export, rejects non-functions, and supplies that loader to run(). — [template/app/actions/public/entry.ts#L1-23](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/actions/public/entry.ts#L1-L23)
- Asset requests accept GET/HEAD, normalize transform query data, parse mapped paths, and route CSS through styleCompiler; compiled script responses enforce fingerprints and distinguish missing/disallowed files from invalid transforms. — [packages/assets/src/lib/asset-server.ts#L666-705](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/src/lib/asset-server.ts#L666-L705) [packages/assets/src/lib/asset-server.ts#L780-812](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/src/lib/asset-server.ts#L780-L812)
- Session middleware parses the signed cookie, optionally validates embedded expiration, loads SessionStorage, installs context.session, then saves after downstream handling and appends Set-Cookie when storage returns a value. — [packages/session-middleware/src/lib/session.ts#L33-74](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session-middleware/src/lib/session.ts#L33-L74) [packages/session-middleware/src/lib/session.ts#L78-99](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session-middleware/src/lib/session.ts#L78-L99)
- External login generates state and a PKCE verifier, stores the transaction under __auth by default, and returns the provider authorization redirect; callback processing validates provider/state before invoking the provider runtime. — [packages/auth/src/lib/utils.ts#L10-26](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/utils.ts#L10-L26) [packages/auth/src/lib/start-external-auth.ts#L40-49](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/start-external-auth.ts#L40-L49) [packages/auth/src/lib/finish-external-auth.ts#L48-76](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/finish-external-auth.ts#L48-L76)
- resolveExternalAuth looks up the provider account, extracts profile details, updates or creates a user, optionally links by profile-derived email, then creates or updates the auth-account row. — [demos/social-auth/app/actions/auth/resolve-external-auth.ts#L21-74](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/social-auth/app/actions/auth/resolve-external-auth.ts#L21-L74) [demos/social-auth/app/actions/auth/resolve-external-auth.ts#L76-109](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/social-auth/app/actions/auth/resolve-external-auth.ts#L76-L109)
- Scaffolding resolves the target directory and application name, copies token-substituted template files, and rewrites package name, Remix dependency version, development dependencies, and Node engine constraints. — [packages/cli/src/lib/bootstrap-project.ts#L49-78](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L49-L78) [packages/cli/src/lib/bootstrap-project.ts#L138-162](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L138-L162) [packages/cli/src/lib/bootstrap-project.ts#L186-221](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L186-L221)
- Route inspection launches a Node subprocess that dynamically imports app/routes.ts, normalizes the exported routes object, writes JSON to stdout, and returns that output to the parent loader. — [packages/cli/src/lib/route-map.ts#L79-119](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/route-map.ts#L79-L119) [packages/cli/src/lib/load-route-map-worker.ts#L16-33](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/load-route-map-worker.ts#L16-L33)

## Behavior traces

The investigation followed three concrete flows across implementation boundaries: scaffolding, template startup/rendering/hydration, and external login with persistence. Additional traces explain frame reloads and asset inspection. These are ordered source walkthroughs, not observed executions. Failure branches are included where they materially change the result.
- Scaffold entry: cli-entry.ts → runRemix → extractGlobalOptions → resolveCliContext → runCommand('new') → dynamically imported runNewCommand → parseNewCommandArgs → bootstrapProject. — [packages/remix/src/cli-entry.ts#L5-9](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/remix/src/cli-entry.ts#L5-L9) [packages/cli/src/lib/cli.ts#L43-67](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/cli.ts#L43-L67) [packages/cli/src/lib/cli.ts#L96-99](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/cli.ts#L96-L99) [packages/cli/src/lib/commands/new.ts#L35-48](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/commands/new.ts#L35-L48)
- Scaffold writes: bootstrapProject → ensureTargetDirectory → resolveTemplateDirectory → copyTemplateDirectory → replaceTemplateValues → writeScaffoldPackageJson; a nonempty target fails unless force is enabled. — [packages/cli/src/lib/bootstrap-project.ts#L66-78](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L66-L78) [packages/cli/src/lib/bootstrap-project.ts#L165-183](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L165-L183) [packages/cli/src/lib/bootstrap-project.ts#L186-221](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L186-L221)
- Template startup: the start/dev command loads remix/node-tsx and server.ts; router module initialization creates static/render middleware and maps the controller; server.ts creates the HTTP listener and calls listen(port). — [template/package.json#L5-10](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/package.json#L5-L10) [template/app/router.ts#L9-22](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/router.ts#L9-L22) [template/server.ts#L4-19](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/server.ts#L4-L19)
- Home request: createRequestListener → createRequest → router.fetch → createRequestContext → dispatchRouter → dispatchMatches → dispatchMatch → controller.home → context.render. — [packages/node-fetch-server/src/lib/request-listener.ts#L128-144](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/node-fetch-server/src/lib/request-listener.ts#L128-L144) [packages/fetch-router/src/lib/router.ts#L372-408](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L372-L408) [packages/fetch-router/src/lib/router.ts#L431-443](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L431-L443) [template/app/actions/controller.tsx#L12-14](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/actions/controller.tsx#L12-L14)
- HTML output: renderWith installs context.render; the render function calls renderToStream with frame/client-entry resolvers and the request signal, then wraps the stream using createHtmlResponse. — [packages/render-middleware/src/lib/render.ts#L36-41](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render.ts#L36-L41) [packages/render-middleware/src/lib/render-ui.ts#L73-90](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L73-L90) [packages/component/src/server/stream.ts#L269-312](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/server/stream.ts#L269-L312)
- Browser activation: template entry calls run → createStyleManager → createScheduler → createFrame(document) → startNavigationListener → topFrame.ready; hydrated exports are obtained through the entry's importModule loader. — [template/app/actions/public/entry.ts#L8-23](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/actions/public/entry.ts#L8-L23) [packages/component/src/runtime/run.ts#L140-174](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L140-L174)
- OAuth login: GitHub controller.login → startExternalAuth → getSession → createOAuthTransaction → sanitizeReturnTo → provider runtime createAuthorizationURL → session.set('__auth') → redirect response. — [demos/social-auth/app/actions/auth/github/controller.ts#L23-37](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/social-auth/app/actions/auth/github/controller.ts#L23-L37) [packages/auth/src/lib/start-external-auth.ts#L40-49](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/start-external-auth.ts#L40-L49) [packages/auth/src/lib/utils.ts#L20-35](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/utils.ts#L20-L35)
- OAuth callback persistence: controller.callback → finishExternalAuth → provider runtime handleCallback → resolveExternalAuth(db,result) → completeAuth → session.regenerateId(true) → session.set('auth') → redirect; enclosing session middleware subsequently saves the session. — [demos/social-auth/app/actions/auth/github/controller.ts#L41-60](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/social-auth/app/actions/auth/github/controller.ts#L41-L60) [packages/auth/src/lib/finish-external-auth.ts#L62-76](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/finish-external-auth.ts#L62-L76) [packages/auth/src/lib/complete-auth.ts#L12-17](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/complete-auth.ts#L12-L17) [packages/session-middleware/src/lib/session.ts#L46-71](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session-middleware/src/lib/session.ts#L46-L71)
- OAuth failure: finishExternalAuth rejects callback errors, missing/wrong-provider transactions, or invalid state and clears transaction data on failure; the demo controller catches errors, flashes a message, and redirects home. — [packages/auth/src/lib/finish-external-auth.ts#L52-83](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/finish-external-auth.ts#L52-L83) [demos/social-auth/app/actions/auth/github/controller.ts#L61-64](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/social-auth/app/actions/auth/github/controller.ts#L61-L64)
- Browser frame reload: defaultResolveFrame creates HTML/frame headers, encodes submitted form data, calls fetch with mode='same-origin' and an abort signal, and rejects 5xx or non-HTML error/redirect responses. — [packages/component/src/runtime/run.ts#L84-98](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L84-L98) [packages/component/src/runtime/run.ts#L114-131](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L114-L131) [packages/component/src/test/frame.test.tsx#L232-255](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/test/frame.test.tsx#L232-L255)
- Server nested frame: resolveFrame resolves src against the current frame URL, prepares headers, follows redirects through context.router.fetch, requires HTML, and pipes the returned stream with the outer request's abort signal. — [packages/render-middleware/src/lib/render-ui.ts#L100-119](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L100-L119) [packages/render-middleware/src/lib/render-ui.ts#L154-183](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L154-L183)
- Asset inspection: runAssetsCommand parses arguments → context.loadConfig → createAssetServer(watch:false) → getAssets or getAssetDetails → formatted stdout; finally it closes the asset server. — [packages/cli/src/lib/commands/assets.ts#L23-40](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/commands/assets.ts#L23-L40)

## Testing signals

Tests and CI were inspected, not executed; no passing result or measured coverage is asserted. The sampled packages use the repository's own test framework with Playwright integration rather than establishing Vitest as the main runner. Source tests cover routing aborts, cookie defaults, asset policies/cache behavior, frame requests, and a fake-provider OAuth flow. Browser projects and integration job filters limit which environments a configured run exercises, and this inspection does not establish exhaustive coverage.
- The template test imports describe/it from remix/test and assertions from remix/assert; scripts also use `remix test`. — [template/app/actions/controller.test.ts#L1-15](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/actions/controller.test.ts#L1-L15) [scripts/package.json#L18-20](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/scripts/package.json#L18-L20)
- The test runner discovers .test, .test.browser, and .test.e2e TypeScript/TSX files, defaults to a forks pool, and supports server, browser, and E2E test types. — [packages/test/src/lib/config.ts#L30-59](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/test/src/lib/config.ts#L30-L59) [packages/test/src/lib/config.ts#L62-72](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/test/src/lib/config.ts#L62-L72)
- The test package uses `remix test`, offers a Bun server-test command, and declares Playwright as an optional peer dependency. — [packages/test/package.json#L63-90](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/test/package.json#L63-L90)
- The inspected template controller test checks GET / status, HTML content type, and an html element; that individual test does not assert browser hydration or interaction. — [template/app/actions/controller.test.ts#L7-14](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/actions/controller.test.ts#L7-L14)
- Router abort tests assert rejection for pre-aborted requests, abort during handler processing, and aborted Request inputs. — [packages/fetch-router/src/lib/router-abort.test.ts#L10-70](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router-abort.test.ts#L10-L70)
- Session middleware tests verify protocol-derived Secure, explicit Secure overrides, and the default HTTP-only flag. — [packages/session-middleware/src/lib/session.test.ts#L25-85](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session-middleware/src/lib/session.test.ts#L25-L85)
- Asset-server tests create temporary source fixtures and assert that only allowlisted script/style/configured file assets appear, excluding private and denied test files. — [packages/assets/src/lib/asset-server.test.ts#L399-435](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/src/lib/asset-server.test.ts#L399-L435)
- Asset tests assert GET/HEAD support, POST fallthrough, no-cache headers, ETags, and a 304 response to matching If-None-Match. — [packages/assets/src/lib/asset-server.test.ts#L486-517](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/src/lib/asset-server.test.ts#L486-L517)
- Frame tests mock fetch and verify posted FormData, frame headers, same-origin mode, abort signals, and resulting DOM content; a separate test checks same-origin mode for an explicitly external src. — [packages/component/src/test/frame.test.tsx#L219-258](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/test/frame.test.tsx#L219-L258) [packages/component/src/test/frame.test.tsx#L320-339](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/test/frame.test.tsx#L320-L339)
- The OAuth integration test follows authorization, callback-cookie propagation, and protected dashboard access against a local fake provider; it does not demonstrate live provider compatibility. — [packages/auth/src/lib/oauth-flow.integration.test.ts#L88-117](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/oauth-flow.integration.test.ts#L88-L117)
- Component and UI Playwright configs select Chromium only; assets, component-HMR, the test framework, and the import-map polyfill select Chromium and Firefox. — [packages/component/playwright.config.ts#L1-5](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/playwright.config.ts#L1-L5) [packages/ui/playwright.config.ts#L1-5](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/ui/playwright.config.ts#L1-L5) [packages/assets/playwright.config.ts#L1-8](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/playwright.config.ts#L1-L8) [packages/component-hmr/playwright.config.ts#L1-8](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component-hmr/playwright.config.ts#L1-L8)
- The test framework and multiple-import-map polyfill also explicitly configure Chromium and Firefox projects. — [packages/test/playwright.config.ts#L1-8](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/test/playwright.config.ts#L1-L8) [packages/multiple-import-maps-polyfill/playwright.config.ts#L1-8](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/multiple-import-maps-polyfill/playwright.config.ts#L1-L8)
- Main CI defines Ubuntu, Bun, and Windows test jobs plus lint/typecheck; PR Bun and Windows jobs run changed-package selection from explicit base/head SHAs. — [.github/workflows/check-main.yaml#L139-180](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-main.yaml#L139-L180) [.github/workflows/check-main.yaml#L215-257](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-main.yaml#L215-L257) [.github/workflows/check-pr.yaml#L221-226](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-pr.yaml#L221-L226) [.github/workflows/check-pr.yaml#L273-278](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-pr.yaml#L273-L278)
- Main CI defines conditional Memcache, Redis, PostgreSQL, MySQL, SQLite, and LocalStack S3 integration checks with service-specific environment switches; their configuration is evidence of intended checks, not execution success. — [.github/workflows/check-main.yaml#L274-303](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-main.yaml#L274-L303) [.github/workflows/check-main.yaml#L305-339](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-main.yaml#L305-L339) [.github/workflows/check-main.yaml#L378-415](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-main.yaml#L378-L415) [.github/workflows/check-main.yaml#L543-554](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-main.yaml#L543-L554)

## Risk map

The inspected security-sensitive boundaries include proxy-derived URLs, browser-accessible source, raw HTML, OAuth/session state, filesystem writes, and subprocess module loading. Several protections are explicit, including signed-session requirements, callback state checks, return-path normalization, and header reduction for cross-origin frames. Backend limitations and application configuration remain important to the security model. These are source observations and labeled hypotheses, not confirmed vulnerabilities or a complete security audit.
- trustProxy allows Forwarded and X-Forwarded headers to affect request host, protocol, and client address; its documented precondition is a trusted proxy that overwrites those headers. — [packages/node-fetch-server/src/lib/request-listener.ts#L49-56](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/node-fetch-server/src/lib/request-listener.ts#L49-L56) [template/server.ts#L10-12](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/server.ts#L10-L12)
- Browser asset exposure is an explicit policy boundary: the template allows routes.ts and public descendants, allows the remix package, denies test files, and configures mounts outside its root for monorepo use. — [template/app/assets.ts#L9-23](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/assets.ts#L9-L23) [packages/assets/src/lib/access.ts#L90-113](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/src/lib/access.ts#L90-L113)
- Injected asset-runtime files are allowed before configured allow/deny matching, while ordinary allowed files can subsequently be denied; policy changes must preserve this intentional exception. — [packages/assets/src/lib/access.ts#L90-113](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/src/lib/access.ts#L90-L113)
- HostProps.innerHTML accepts UnsafeHTML and explicitly performs no sanitization; untrusted content passed through this API is an application-owned trust decision. — [packages/component/src/runtime/dom.ts#L31-43](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/dom.ts#L31-L43)
- The default browser frame resolver restricts fetch to same-origin mode but does not sanitize HTML; custom resolvers own request, redirect, and content trust policies. — [packages/component/src/runtime/run.ts#L24-33](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L24-L33) [packages/component/src/runtime/run.ts#L114-124](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L114-L124)
- Server frame resolution removes body/transport headers, strips sec-fetch headers, limits redirects to 20, and uses a reduced header allowlist when the frame URL changes origin. — [packages/render-middleware/src/lib/render-ui.ts#L21-51](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L21-L51) [packages/render-middleware/src/lib/render-ui.ts#L126-143](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L126-L143) [packages/render-middleware/src/lib/render-ui.ts#L154-179](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L154-L179) [packages/render-middleware/src/lib/render-ui.ts#L189-197](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render-ui.ts#L189-L197)
- OAuth callback processing validates stored provider and state and clears the transaction after success or failure; returnTo normalization rejects nonlocal origins and double-slash paths. — [packages/auth/src/lib/finish-external-auth.ts#L62-83](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/finish-external-auth.ts#L62-L83) [packages/auth/src/lib/utils.ts#L74-94](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/utils.ts#L74-L94)
- OAuthTransaction.providerState documentation requires providers to encrypt sensitive values because session storage does not guarantee confidentiality. — [packages/auth/src/lib/provider.ts#L70-85](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/provider.ts#L70-L85)
- Cookie session storage serializes all session data into JSON and explicitly warns that regenerated old session IDs cannot be deleted; session rotation therefore has different revocation properties across storage backends. — [packages/session/src/lib/session-storage/cookie.ts#L26-41](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session/src/lib/session-storage/cookie.ts#L26-L41) [packages/session/src/lib/session-storage/memory.ts#L38-49](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session/src/lib/session-storage/memory.ts#L38-L49) [packages/auth/src/lib/complete-auth.ts#L12-17](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/complete-auth.ts#L12-L17)
- Session middleware requires signed cookies and defaults HTTP-only/Secure, but honors explicit insecure overrides; Secure otherwise depends on the interpreted request protocol. — [packages/session-middleware/src/lib/session.ts#L19-26](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session-middleware/src/lib/session.ts#L19-L26) [packages/session-middleware/src/lib/session.ts#L63-70](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session-middleware/src/lib/session.ts#L63-L70)
- Scaffolding writes to a user-resolved target directory outside any fixed repository boundary; --force permits a nonempty directory and template copying overwrites matching files. — [packages/cli/src/lib/bootstrap-project.ts#L53-54](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L53-L54) [packages/cli/src/lib/bootstrap-project.ts#L165-183](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L165-L183) [packages/cli/src/lib/bootstrap-project.ts#L195-212](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L195-L212)
- Route inspection executes application module code in a child process through dynamic import; process separation is not a sandbox for an untrusted checkout. (inferred) — [packages/cli/src/lib/route-map.ts#L90-96](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/route-map.ts#L90-L96) [packages/cli/src/lib/load-route-map-worker.ts#L26-33](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/load-route-map-worker.ts#L26-L33)
- Hypothesis: concurrent first logins for one external identity could require transaction or uniqueness guarantees elsewhere, because the inspected resolver performs lookup, user creation, and account creation as separate awaited operations without an enclosing transaction in this function. (inferred) — [demos/social-auth/app/actions/auth/resolve-external-auth.ts#L21-74](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/social-auth/app/actions/auth/resolve-external-auth.ts#L21-L74)
- CI integration selection contains references to standalone integration-workflow paths while the inspected jobs are embedded in check-pr/check-main; edits to filtering or shared middleware merit checking whether integration jobs are selected. (inferred) — [.github/workflows/check-pr.yaml#L57-95](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-pr.yaml#L57-L95) [.github/workflows/check-main.yaml#L274-277](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/check-main.yaml#L274-L277)
- The automatic formatting workflow checks out with FORMAT_PAT and can commit/push changes on main; generated agentic workflows also expose write-capable automation, making workflow edits a privileged boundary. — [.github/workflows/format.yml#L18-22](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/format.yml#L18-L22) [.github/workflows/format.yml#L72-85](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/format.yml#L72-L85) [.github/workflows/aw-comment-router.lock.yml#L90-100](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.github/workflows/aw-comment-router.lock.yml#L90-L100)

## Extension points

Composition is the main extension mechanism: factories, middleware, route installers, renderers, provider runtimes, and storage interfaces connect focused modules. The umbrella alias manifest controls public distribution wiring. CLI features use explicit command dispatch and structured JSON configuration. Browser extension hooks carry their own trust responsibilities.
- Add umbrella aliases through packages/remix/manifest.json and its generator; the manifest explicitly excludes @remix-run/ui from automatic umbrella inclusion. — [packages/remix/manifest.json#L1-18](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/remix/manifest.json#L1-L18) [scripts/generate-remix.ts#L1-7](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/scripts/generate-remix.ts#L1-L7)
- RouterOptions exposes matcher, defaultHandler, and middleware replacement points, with createMultiMatcher as the default matcher. — [packages/fetch-router/src/lib/router.ts#L210-231](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L210-L231) [packages/fetch-router/src/lib/router.ts#L368-370](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L368-L370)
- RouteInstaller receives a RouteBuilder; mount joins route prefixes and invokes the installer on a child builder. — [packages/fetch-router/src/lib/router.ts#L191-195](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L191-L195) [packages/fetch-router/src/lib/router.ts#L567-575](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L567-L575)
- Controllers and actions can carry middleware; mapController merges controller middleware with each action's middleware before registration. — [packages/fetch-router/src/lib/router.ts#L489-527](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/fetch-router/src/lib/router.ts#L489-L527)
- Applications augment remix.RouterTypes.context using middleware-derived context; the template and bookstore demonstrate that typed integration. — [template/app/router.ts#L9-15](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/router.ts#L9-L15) [demos/bookstore/app/router.ts#L41-55](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/bookstore/app/router.ts#L41-L55)
- renderWith accepts a per-request renderer factory, allowing custom input/output rendering while keeping the same context.render/context-key integration. — [packages/render-middleware/src/lib/render.ts#L6-15](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render.ts#L6-L15) [packages/render-middleware/src/lib/render.ts#L28-41](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/render-middleware/src/lib/render.ts#L28-L41)
- run accepts a required module loader, an optional frame resolver, and optional client-entry preload processing; default frame behavior can be replaced. — [packages/component/src/runtime/run.ts#L15-36](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L15-L36) [packages/component/src/runtime/run.ts#L145-160](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/src/runtime/run.ts#L145-L160)
- createOAuthProvider binds a stable name to createAuthorizationURL, handleCallback, and optional refreshTokens hooks, with normalized profile/account/token result types. — [packages/auth/src/lib/provider.ts#L34-46](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/provider.ts#L34-L46) [packages/auth/src/lib/provider.ts#L91-104](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/provider.ts#L91-L104) [packages/auth/src/lib/provider.ts#L145-156](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/provider.ts#L145-L156)
- SessionStorage is the backend contract; read returns a Session and save returns a cookie value, null for no update, or an empty string for destruction. — [packages/session/src/lib/session-storage.ts#L10-27](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session/src/lib/session-storage.ts#L10-L27)
- createBookstoreRouter accepts injected Cookie and SessionStorage values, and createGitHubAuthController accepts an injected provider registry. — [demos/bookstore/app/router.ts#L58-65](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/bookstore/app/router.ts#L58-L65) [demos/social-auth/app/actions/auth/github/controller.ts#L16-19](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/social-auth/app/actions/auth/github/controller.ts#L16-L19)
- The CLI extends through runCommand's explicit lazy-import branches and RemixConfig's assets/db/doctor/test sections; config parsing rejects unknown top-level properties. — [packages/cli/src/lib/cli.ts#L96-133](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/cli.ts#L96-L133) [packages/cli/src/lib/remix-config.ts#L29-37](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/remix-config.ts#L29-L37) [packages/cli/src/lib/remix-config.ts#L200-207](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/remix-config.ts#L200-L207)
- The asset server receives loader and HMR configuration; the template installs componentHmr() and a lazily supplied browser HMR channel. — [packages/assets/src/lib/asset-server.ts#L436-466](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/src/lib/asset-server.ts#L436-L466) [template/app/assets.ts#L25-31](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/assets.ts#L25-L31)

## Contributor handoff

Read the owning package and its actual runtime boundaries before editing generated surfaces or application examples. Tests and CI were inspected, not executed, and this bounded source investigation supplies no passing baseline. The requested environment-file entrypoint was intentionally not read under the user's prohibition on environment files and secrets. Future implementation work should preserve package boundaries, generated wiring, source-run tests, and public API documentation.
- Read AGENTS.md first for dedicated public source entrypoints, implementation-only src/lib, direct cross-package imports, and Web API preferences; CLAUDE.md delegates to that guide. — [AGENTS.md#L5-11](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/AGENTS.md#L5-L11) [CLAUDE.md#L1-5](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/CLAUDE.md#L1-L5)
- Use pnpm and the root Node engine requirement; the workspace catalog centralizes TypeScript, Playwright, formatting, and other shared versions. — [package.json#L5-16](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/package.json#L5-L16) [pnpm-workspace.yaml#L7-16](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/pnpm-workspace.yaml#L7-L16)
- For request changes, read server.ts, router.ts, routes.ts, controller actions, and render integration together; these files connect the template's HTTP, route, and HTML boundaries. — [template/server.ts#L1-12](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/server.ts#L1-L12) [template/app/router.ts#L18-22](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/router.ts#L18-L22) [template/app/routes.ts#L1-6](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/routes.ts#L1-L6) [template/app/actions/controller.tsx#L7-15](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/app/actions/controller.tsx#L7-L15)
- For auth changes, read transaction helpers, callback validation, completeAuth, session middleware, and the chosen backend; backend deletion semantics affect the meaning of session rotation. — [packages/auth/src/lib/finish-external-auth.ts#L48-83](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/finish-external-auth.ts#L48-L83) [packages/auth/src/lib/complete-auth.ts#L12-17](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/auth/src/lib/complete-auth.ts#L12-L17) [packages/session-middleware/src/lib/session.ts#L38-71](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session-middleware/src/lib/session.ts#L38-L71) [packages/session/src/lib/session-storage/cookie.ts#L26-41](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/session/src/lib/session-storage/cookie.ts#L26-L41)
- Avoid manually changing generated umbrella entrypoints: cli-entry.ts is marked generated, and generate-remix.ts owns umbrella exports and documentation copies. — [packages/remix/src/cli-entry.ts#L1-5](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/remix/src/cli-entry.ts#L1-L5) [scripts/generate-remix.ts#L1-7](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/scripts/generate-remix.ts#L1-L7)
- CLI source scaffolding requires the prepared package template; its error directs developers to the CLI prepack script, which syncs that template. — [packages/cli/src/lib/bootstrap-project.ts#L107-121](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L107-L121) [packages/cli/package.json#L60-67](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/package.json#L60-L67)
- Use separate type imports/exports, .ts extensions, let for locals, const at module scope, and native private fields; Oxfmt enforces 100-column, semicolon-free, single-quoted formatting. — [AGENTS.md#L26-35](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/AGENTS.md#L26-L35) [.oxlintrc.json#L63-99](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/.oxlintrc.json#L63-L99) [oxfmt.config.ts#L3-8](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/oxfmt.config.ts#L3-L8)
- Tests run from source without a build; the documented narrow commands include package-filtered tests/typechecks and --only test-name selection. These are recommended future checks, not commands executed during this investigation. — [AGENTS.md#L18-20](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/AGENTS.md#L18-L20) [AGENTS.md#L37-42](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/AGENTS.md#L37-L42)
- The recommended fast loop includes metadata validation, lint, changed tests, and changed typechecks; changed commands compare against origin/main and include uncommitted changes. — [AGENTS.md#L13-24](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/AGENTS.md#L13-L24) [package.json#L35-40](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/package.json#L35-L40)
- Public API changes require related docs, JSDoc, examples, and tests; changes affecting published packages require change files. — [AGENTS.md#L42-44](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/AGENTS.md#L42-L44) [AGENTS.md#L52-55](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/AGENTS.md#L52-L55) [CONTRIBUTING.md#L60-66](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/CONTRIBUTING.md#L60-L66)
- Preserve SQL migrations as immutable artifacts; the migration decision rejects imports of evolving application schemas because they can alter old migrations and risk data loss. — [decisions/006-sql-migrations.md#L21-43](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/decisions/006-sql-migrations.md#L21-L43) [demos/bookstore/app/db.ts#L13-18](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/demos/bookstore/app/db.ts#L13-L18)
- Inspect browser project configuration before claiming cross-browser coverage: the component/UI configs list only Chromium while several supporting packages list Chromium and Firefox. — [packages/component/playwright.config.ts#L1-5](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/component/playwright.config.ts#L1-L5) [packages/ui/playwright.config.ts#L1-5](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/ui/playwright.config.ts#L1-L5) [packages/assets/playwright.config.ts#L1-8](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/assets/playwright.config.ts#L1-L8)
- Treat root clean and scaffolding force as mutation hazards: clean invokes git clean, and force permits copying into a nonempty target directory. — [package.json#L24-24](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/package.json#L24-L24) [packages/cli/src/lib/bootstrap-project.ts#L165-183](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L165-L183) [packages/cli/src/lib/bootstrap-project.ts#L195-212](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/packages/cli/src/lib/bootstrap-project.ts#L195-L212)
- The template TypeScript configuration is strict NodeNext with explicit TypeScript extensions, verbatim module syntax, no emit, and remix/component as the JSX import source; react-jsx here does not identify React as the component runtime. — [template/tsconfig.json#L2-16](https://github.com/remix-run/remix/blob/27bd7a4401594ec1acbe30ee3937518832270a30/template/tsconfig.json#L2-L16)

Source repository: https://github.com/remix-run/remix
Full evidence corpus: https://github.com/Codevetter/codevetter/tree/main/benchmarks/repo-unpacks/remix.json

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)