Skip to main content

Breaking: router-coupled hooks and Breadcrumb moved to @trackunit/react-router-components

@trackunit/react-components 4.0.0 removes usePersistedState, useSearchParamSync, useCursorUrlSync, MAX_URL_LENGTH, the UrlPersistenceLocation type and Breadcrumb. They now live in the new package @trackunit/react-router-components (first published as 1.0.2), with no compatibility shim: if your code imports any of them, bumping to 4.0.0 without running the migration is a compile failure, not a deprecation warning. Repos that never used them are unaffected.

Run these two commands in the consuming repo:

npx nx g @trackunit/migrations:migrate
npx nx g @trackunit/migrations:run-migrations

Then re-install dependencies (npm install), because the migration adds @trackunit/react-router-components to your package.json.

Why this changed​

These hooks and Breadcrumb read and write the URL through TanStack Router. @trackunit/react-router-components is now the one published package for components and hooks that depend on @tanstack/react-router, so router-aware code has a single home instead of being spread across general-purpose packages. Trackunit's own published packages are now linted against importing @tanstack/react-router directly. That rule does not apply to your app code.

When it affects you​

Nothing changes until you bump the package. From @trackunit/react-components 4.0.0, the names below are no longer exported from it and any import of them stops compiling until migrated:

ExportBeforeAfter
usePersistedState@trackunit/react-components@trackunit/react-router-components
UrlPersistenceLocation (type)@trackunit/react-components@trackunit/react-router-components
useSearchParamSync@trackunit/react-components@trackunit/react-router-components
MAX_URL_LENGTH@trackunit/react-components@trackunit/react-router-components
useCursorUrlSync@trackunit/react-components@trackunit/react-router-components
Breadcrumb@trackunit/react-components@trackunit/react-router-components

Names, props and behavior are unchanged; only the import path moves. Everything else, including Prompt, is still imported from @trackunit/react-components.

@trackunit/react-router-components declares @tanstack/react-router (^1.114.29) and react (^19.0.0) as peer dependencies, the same peers @trackunit/react-components 4.0.0 declares, so an app that already runs react-components needs no new peer.

// before
import { Breadcrumb, Button, usePersistedState } from "@trackunit/react-components";

// after
import { Button } from "@trackunit/react-components";
import { Breadcrumb, usePersistedState } from "@trackunit/react-router-components";

What the migration does​

The @trackunit/react-components 4.0.0 migration (v4-0-0-move-to-router-components) runs as part of run-migrations:

  • It rewrites imports and re-exports of the moved names to @trackunit/react-router-components, including type-only and aliased imports. In an import that mixes moved and unmoved names, it splits the import and keeps the other names on @trackunit/react-components.
  • When it rewrote anything, it adds @trackunit/react-router-components to your root package.json, next to @trackunit/react-components (in dependencies or devDependencies, wherever that one is). It keeps an existing entry. Other package.json files that declare @trackunit/react-components are listed in the log: add the new package there yourself if that project uses the moved names.
  • Any usage it can't rewrite with confidence is left untouched and logged as manual review needed at <file>:<line> rather than guessed at. That covers namespace imports (import * as RC from "@trackunit/react-components") that use a moved name, export * from "@trackunit/react-components" (the moved names silently drop out of it), export * as, require() and dynamic import(), import() types, and vi.mock()/jest.mock() calls on @trackunit/react-components in files that use a moved name.

Also in @trackunit/react-router-components​

The package also exports useRouterDrawer, which keeps a Drawer's selected id in a search or path param, and RouteLink, a text link to a route inside your app. Use ExternalLink from @trackunit/react-components for links that leave the app.