> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# React Router v7 Migration Brief (Context7-backed)

> Source: Context7 /websites/reactrouter. Use: Embed as "Research Brief" in PF-78 spec.

**Source:** Context7 `/websites/reactrouter`.\
**Use:** Embed as "Research Brief" in PF-78 spec.

***

## Execution status (2026-05-06)

* PF-78 migration is implemented on the main app branch.
* Runtime dependency is now `react-router-dom@^7.15.0` (compatibility path).
* `BrowserRouter` no longer uses `future` flags in `src/App.tsx`.
* Test warning suppression for "React Router Future Flag Warning" was removed from `tests/setup.ts`.
* Deferred follow-up: optional mechanical import migration from `react-router-dom` to `react-router`.

***

## Official upgrade path and prerequisites

* **Minimum versions:** node\@20, react\@18, react-dom\@18. (Ref: [Upgrading from v6](https://reactrouter.com/upgrading/v6).)
* **No breaking changes** if all v7 future flags are enabled before the version bump. Enable flags incrementally, commit (and optionally ship) after each step. (Ref: [Migration Strategy](https://reactrouter.com/7.11.0/upgrading/v6).)
* **This repo:** Uses **declarative routing** (`BrowserRouter` + `Routes`/`Route`), not data routers (`createBrowserRouter`/`RouterProvider`). Future flags are set on `BrowserRouter` in `src/App.tsx`.

***

## Future flags relevant to this repo

| Flag                             | Purpose                                                                | Repo status                                                      |
| -------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `v7_relativeSplatPath`           | Splat path behavior for relative routes                                | Enabled during v6 migration phase; no longer configured post-v7. |
| `v7_startTransition`             | Use `React.useTransition` for router state updates; can affect timing. | Enabled during v6 migration phase; no longer configured post-v7. |
| `v7_fetcherPersist`              | Fetcher lifecycle (idle-based).                                        | For data routers only; N/A for current declarative setup.        |
| `v7_skipActionErrorRevalidation` | Action error revalidation.                                             | For data routers only; N/A.                                      |

Data-router-only flags (`v7_fetcherPersist`, `v7_normalizeFormMethod`, `v7_skipActionErrorRevalidation`, etc.) apply only if the app later adopts `RouterProvider`/data APIs.

***

## Confirmed migration strategy (Context7)

1. **Keep** `v7_relativeSplatPath: true` as baseline.
2. **Enable** `v7_startTransition: true` on a branch; run route-heavy integration tests and smoke key flows (navigation, org slug routes, portal). *(Completed in PF-78 execution.)*
3. **Update test wrappers** so `MemoryRouter`/`BrowserRouter` in tests align with future behavior; remove or adjust "React Router Future Flag Warning" suppression in `tests/setup.ts` if appropriate.
4. **Bump** to `react-router-dom` v7 after all targeted flags are enabled and tests pass. *(Completed in PF-78 execution using the v7 compatibility package.)*
5. **If moving to data routers later:** Stage remaining v7 data-router flags in separate PRs.

***

## Repo compatibility notes

* **Router setup (post-migration):** `src/App.tsx` — declarative `BrowserRouter` without `future` props on v7.
* **Splat usage:** Root catch-all `path="/*"`; org-slug subtree `/o/:orgSlug` with child `path="*"`; `SlugNestedContent.tsx` uses `useParams<{ '*': string }>()`. Most navigation uses absolute paths; relative splat risk is low with `v7_relativeSplatPath` already on.
* **Sensitive areas:** `src/routes/platform.tsx`, `src/routes/SlugNestedContent.tsx`, `src/platform/organizations/routing/OrgSlugRoute.tsx`, `src/platform/organizations/OrgSiteSwitcher.tsx`, `src/platform/navigation/components/SubModuleSidebar.tsx`, `src/platform/navigation/Breadcrumbs.tsx`.
* **Tests:** `tests/setup.ts` no longer suppresses router future-flag warning; `tests/integration/route-integrity.test.ts` and route-heavy unit tests remain primary routing checks.

***

## Recommended rollout and rollback

1. **Enable** `v7_startTransition: true` in `src/App.tsx`; run `npm run validate` and `npm run test:baseline`; manual smoke of org-slug and catch-all routes.
2. **Bump** `react-router-dom` to ^7.x; `npm install`; fix any peer or type issues.
3. **Validate** full test suite and E2E smoke; adjust test setup if warnings or flakiness appear.
4. **Rollback:** Revert to `react-router-dom` ^6.x and set `v7_startTransition: false`; re-run validate and tests.