remix-run/react-router
github.com/remix-run/react-router ↗ · 1187 files · 8.5 MB
[![npm package][npm-badge]][npm] [![build][build-badge]][build] [npm-badge]: https://img.shields.io/npm/v/react-router.svg [npm]: https://www.npmjs.org/package/react-router [build-badge]: https://img.shields.io/github/actions/workflow/status/remix-run/react-ro
Overview
React Router is a React routing library and application framework for developers who need nested navigation, loader/action data handling, and server rendering. This pinned checkout packages the browser routing engine, Vite tooling, server adapters, session utilities, and unstable React Server Component integrations in a pnpm monorepo. Its distinctive architecture shares routing semantics across browser and server runtimes while keeping framework compilation and platform adaptation in separate packages.
System map
The repository distributes a routing engine and framework tooling rather than one deployed application. Browser history, React rendering, Fetch-based server handling, and Vite compilation form distinct boundaries. Persistence is supplied through session strategies rather than a central database. The inspected configuration establishes pnpm, Jest, Playwright, and package-specific builds.
- The root workspace builds package projects and discovers Jest projects under packages/*; packageManager is pnpm@11.7.0.
- react-router exposes separate root, DOM, route-pattern, and React server conditional entrypoints.
- createRouter owns route normalization, an ID-keyed manifest, DataRoutes, and the selected data strategy.
- createBrowserRouter adapts browser history, hydration data, context, instrumentation, and route discovery into the shared engine.
- @react-router/dev publishes configuration, route helpers, Vite integration, and the react-router CLI.
- The server runtime builds a static handler from compiled routes and dispatches requests using Fetch Request/Response interfaces.
- Express and Cloudflare adapters bridge platform context into the same core request handler.
- Session persistence supports strategy callbacks, whole-cookie storage, and a Node filesystem implementation.
- The RSC framework playground combines unstable_reactRouterRSC, React, MDX preprocessing, and @vitejs/plugin-rsc.
- Core package builds use Wireit to run tsdown for ordinary and RSC outputs; published files include dist and documentation.
Feature catalog
The user-facing surface primarily consists of developer APIs and CLI commands. Inspected capabilities include browser routing, data loading, mutation submission, independent fetchers, URL state, server rendering, and session persistence. Framework tooling adds route configuration, type generation, and server/client separation. Playground entrypoints demonstrate ordinary framework, RSC, and Cloudflare integration shapes.
- Data mode applications declare routes with loaders and Components, mount RouterProvider, and consume results with useLoaderData.
- useSubmit supports navigation submissions and non-navigation fetcher submissions with configurable method, encoding, body, and revalidation behavior.
- useSearchParams returns URLSearchParams and a setter that performs navigation while accepting functional updates.
- History navigation blockers can restore a blocked POP, proceed later, or reset to idle.
- The CLI dispatches routes, build, reveal, dev, and typegen commands; help exposes JSON route output and watched type generation.
- Framework route modules support clientLoader, clientAction, clientMiddleware, metadata, links, ErrorBoundary, HydrateFallback, and Layout exports.
- The server runtime supports SPA fallback behavior and rejects non-prerendered .data paths when SSR is disabled.
- flatRoutes offers optional filesystem routing with ignoredRouteFiles and a configurable route directory.
- Cookie session storage persists the entire session in a cookie and rejects serialized values over 4096 characters.
- Cloudflare Pages handling tries ASSETS.fetch first, accepts successful or redirect asset responses, then falls back to application routing.
Data flow
Route configuration becomes normalized route objects and runtime matching state. Browser submissions become Fetch Requests whose results update route data and errors. Server adapters convert platform inputs into the same request abstraction and return streamed responses. Session data follows a separate cookie-to-storage lifecycle controlled by application code.
- createBrowserRouter feeds route objects, browser history, and hydration data into createRouter before initialization.
- navigate resolves relative targets through normalizeTo and transforms navigation options into a path, submission, or error.
- startNavigation aborts the previous navigation, matches the new location, and creates a Request with an AbortController signal.
- Mutation submissions run handleAction before handleLoaders; completion commits action data, loader data, errors, and working fetchers.
- Express copies request headers, streams non-GET/HEAD bodies into Fetch Requests, and aborts when the response closes before finishing.
- Document rendering collects loaderData, actionData, and sanitized errors into a Turbo Stream handoff alongside build metadata.
- callRouteHandler forwards request, URL, params, context, and route pattern, converting redirect data wrappers into thrown Responses.
- getSession parses a cookie identifier and reads backing data; commitSession updates or creates backing data and serializes the identifier.
- File sessions serialize data and expiry as JSON, generate random hexadecimal IDs, and remove expired data during reads.
- Type generation creates context, clears the generated type directory, and writes generated server-build and route files.
Behavior traces
Four concrete flows were followed through source: browser startup, mutation submission, server document handling, and file session persistence. These traces describe call order and state transitions without asserting runtime success. Initialization and submissions converge on the shared navigation machinery. Server and persistence flows cross explicit adapter and serialization boundaries.
- Browser startup begins in playground/data/src/main.tsx: createBrowserRouter(route array) constructs the router before createRoot renders RouterProvider.
- Startup continues through createRouter → initialize → history.listen; when state is not initialized, initialize starts a POP navigation with initialHydration.
- Initial loading enters startNavigation → createClientSideRequest → handleLoaders → completeNavigation, committing loader results for the playground Component to read.
- Submission begins with useSubmit → getFormSubmissionInfo → router.navigate, or router.fetch when navigate is false.
- Mutation navigation enters handleAction, interrupts active loads, updates navigation to submitting, and returns a 405 error when the targeted route has neither action nor lazy.
- After the action, startNavigation builds loading navigation, calls handleLoaders, and commits action and loader results through completeNavigation.
- Express document handling follows createRemixRequest → getLoadContext → core handleRequest → handleDocumentRequest → staticHandler.query → renderHtml → sendRemixResponse.
- The response path sets status and headers, flushes event-stream headers, streams the body, and cancels the body if the Express response is already closed.
- New file-session persistence follows createFileSessionStorage → createSessionStorage → commitSession → createData → getFile → mkdir/writeFile → cookie.serialize.
- A subsequent session read follows cookie.parse → readData → getFile → readFile/JSON.parse → expiry check → createSession; destroySession deletes backing data and expires the cookie.
Testing signals
Tests and CI were inspected, not executed; test existence is not a passing result. The inspected unit configuration uses Jest, with jsdom for the core React package and Node overrides for filesystem sessions. Playwright integration tests exercise application fixtures and browser behavior. This is a bounded inspection, so coverage outside the cited tests remains unassessed.
- The root test script invokes Jest with experimental VM modules, and Jest enumerates package projects.
- Shared Jest configuration maps workspace imports to source, transforms JS/TS, and matches *-test files.
- The core package uses jest-environment-jsdom, a package setup file, and jest-dom matchers.
- Navigation tests assert committed loaderData, valid null results, and JSON Response unwrapping.
- Fetcher action tests assert submitting → loading → idle and distinguish fetcher action data from revalidated page loaderData.
- Node session tests cover persistence across requests, cookie tampering, invalid IDs, and destroying an empty session.
- Middleware integration tests use PlaywrightFixture and assert client middleware effects before/after loaders and actions.
- Playwright runs tests in parallel, marks package modules external, forbids focused tests in CI, and retries three times in CI.
- Unit CI configures Node 22.22 and 24, then installs, builds, typechecks, lints, and invokes pnpm test; these configured steps were not executed in this investigation.
- Integration CI installs a selected Playwright browser and invokes pnpm test:integration with that browser; root scripts add a pre-build and post-run cleanup.
Risk map
The observations below identify security and correctness boundaries, not confirmed vulnerabilities. Cookie signing, filesystem identifiers, client/server module separation, request origins, and proxy-derived URLs deserve focused review when changed. The shared navigation engine has a large behavioral blast radius because cancellation, hydration, actions, and loading meet there. Runtime failures, deployment policy, and uninspected tests remain unverified.
- Cookie signing is optional: createCookie defaults secrets to an empty array, while session storage warns about unsigned cookies rather than rejecting them.
- Cookie session content is JSON/base64 encoded and optionally HMAC signed, so signing supplies integrity rather than encryption.
- The cookie defaults shown set path and sameSite=lax; this default construction does not set secure or httpOnly.
- File storage performs filesystem IO beneath a caller-selected dir, and getFile rejects identifiers outside the 16-character hexadecimal format before path construction.
- Hypothesis: concurrent file-session updates merit additional verification because updateData directly overwrites JSON without locking or atomic replacement in the inspected implementation. (inferred)
- Document mutation requests invoke throwIfPotentialCSRFAttack with configured allowedActionOrigins and return 400 when that check throws.
- Express request URL construction depends on trust proxy, forwarded host/host ports, and req.protocol; hostname delimiters are stripped before URL creation.
- Client/server separation depends on both removal of server-only route exports and the dot-server resolve hook rejecting surviving client references.
- Application scaffolding can launch package-manager installation through child_process.spawn with a supplied working directory.
- The shared navigation path aborts previous work and later commits combined action, loader, error, and fetcher state, making edits here relevant across several observable behaviors.
- Typegen removes generated directories before writing, and root clean scripts invoke git clean; these commands have filesystem side effects and were not run.
Extension points
Extension seams exist at route configuration, data execution, context injection, observability, persistence, and platform adaptation. Framework route exports provide a convention-based interface, while Data mode exposes explicit constructor options. Filesystem routing is an adapter over route configuration rather than the only route discovery model. Most seams are typed factory inputs or exports rather than a single global plugin registry.
- Browser router options accept dataStrategy, patchRoutesOnNavigation, getContext, and instrumentations.
- createRouter wraps mapRouteProperties with instrumentation-derived updates and selects a custom data strategy or defaultDataStrategyWithMiddleware.
- @react-router/dev/routes exports route, index, layout, prefix, relative, and getAppDirectory helpers.
- The routes.ts architecture accepts exported route configuration arrays and deliberately places filesystem conventions in a separate package.
- flatRoutes converts a convention-generated route manifest into RouteConfigEntry objects and exposes directory and ignore options.
- SessionIdStorageStrategy supplies readData, updateData, and deleteData, while createSessionStorage also receives createData and cookie configuration.
- Express getLoadContext can incorporate middleware-generated platform values before invoking the core handler.
- Server entry modules can supply handleError, handler instrumentation, and handleDataRequest response customization.
- Framework route export lists explicitly distinguish server execution hooks from client data hooks and rendering components.
- RSC and Cloudflare integrations compose with ordinary Vite plugins at playground configuration entrypoints.
Contributor handoff
Use the pinned checkout and mode-specific source as the authority for future work. Tests and CI were inspected, not executed, and this inventory is bounded rather than exhaustive. Start edits at the runtime or tooling boundary responsible for the behavior, preserving generated artifacts and package conventions. Any future validation report must distinguish configured checks from commands actually run.
- Identify Declarative, Data, Framework, RSC Data, or RSC Framework scope before changing a feature.
- For browser data behavior, first read createBrowserRouter, useSubmit, and startNavigation; they expose the constructor-to-request-to-state path.
- For adapter work, inspect both platform conversion and the core runtime context check: initialContext must be a RouterContextProvider instance.
- Use the repository's Jest and Playwright scripts when execution is authorized; the inspected scripts and CI are configuration evidence, not passing results.
- For fetcher mutations, preserve separate fetcher action data and page loaderData, including submitting/loading/idle transitions asserted in the inspected test.
- Generated API documentation and generated route types are not direct edit targets; modify JSDoc or generators instead.
- User-affecting changes require a package-local patch, minor, major, or unstable change file; existing unshipped change files should be updated rather than duplicated.
- Do not assume older package requirements: this core manifest declares version 8.4.0, React peers >=19.2.7, and Node >=22.22.0.
- Preserve explicit client/server separation when editing framework transforms; the architecture decision requires server-export removal and errors for remaining .server imports.
- Choose mode-appropriate unit or integration validation, rebuild after package changes for integration work, and use Chromium unless explicitly directed otherwise.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 667 | 93% |
| Markdown | 287 | docs/config |
| JSON | 86 | docs/config |
| JavaScript | 46 | 6% |
| YAML | 26 | docs/config |
| CSS | 20 | docs/config |
| Shell | 3 | 0% |
| TOML | 2 | 0% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (474 files)
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 474 |
playground/ | 216 |
docs/ | 209 |
integration/ | 160 |
.github/ | 33 |
scripts/ | 26 |
decisions/ | 20 |
.agents/ | 12 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdLICENSE.mdREADME.mddocs/api/components/Await.mddocs/api/components/Form.mddocs/api/components/Link.mddocs/api/components/Links.mddocs/api/components/Meta.md
Package
package.json — @remix-run/react-router, 41 declared dependencies.
@babel/core@babel/preset-env@babel/preset-react@babel/preset-typescript@eslint/compat@mdx-js/rollup@playwright/test@types/jest@types/jsdom@types/react@types/react-dom@types/react-test-renderer
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructionsplayground/framework-express/vite.config.ts— Vite configplayground/middleware/vite.config.ts— Vite configplayground/framework/vite.config.ts— Vite configplayground/rsc-vite-framework/vite.config.ts— Vite configplayground/rsc-vite-7-framework/vite.config.ts— Vite configplayground/framework-vite-7/vite.config.ts— Vite configplayground/vite-plugin-cloudflare/vite.config.ts— Vite config
Structural health signals
Average score 5.4/10 across 96 analyzed source files; 89 hotspots surfaced.
packages/react-router/__tests__/router/ssr-test.ts— 1624 lines, score 4 (Large file, Deep nesting)packages/react-router/lib/dom/ssr/components.tsx— 1046 lines, score 4 (Large file, Deep nesting)packages/react-router/__tests__/router/utils/data-router-setup.ts— 770 lines, score 4.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
a6090382ed462026-09-30 — chore(deps): bump github/gh-aw-actions/setup from 0.89.21 to 0.89.22 (#15574)54fd9629cc462026-09-28 — chore(deps): bump github/gh-aw-actions/setup from 0.89.17 to 0.89.21 (#15564)291a913bf1322026-09-27 — docs(useNavigation): fix JSDoc comment parsing and clean up generated documentation (#15561)40faa3305d3c2026-09-25 — Document Session API methods, including session.flash (#15555)2d9827bc09bc2026-09-23 — chore(deps): bump github/gh-aw-actions/setup from 0.89.13 to 0.89.17 (#15536)