refactor(router-core): strip internal types from public build by Sheraff · Pull Request #4907 · TanStack/router

Sheraff · 2025-08-10T08:03:33Z

This PR proposes we use the @internal JSDoc tag, and --stripInternal typescript compiler option to remove internal keys from the public .d.ts files.

Docs for stripInternal: https://www.typescriptlang.org/tsconfig/#stripInternal

This helps ensuring internal values aren't considered as part of the public API surface by users, allowing us more flexibility in refactoring.

Warning

This PR proposes we add stripInternal to the entire repo, not just router-core. However there are already some values marked as internal that weren't added by this PR:

InferStructuralSharing in react-router
handleHashScroll in router-core > scrollRestoration
many InferFoo types in router-core > typePrimitives

as a result of this, we might have to switch some of those @internal tags to something else (like @private maybe?) because they are, in fact, necessary for the build to be correct.

Example:

export type Foo = {
  a: number,
  /** @internal */
  b: number,
}

/** @internal */
export function hello() {
  return 'world'
}

export const answer = 42

gets compiled as .d.ts to

export type Foo = {
  a: number
}
export const answer = 42

nx-cloud · 2025-08-10T08:04:00Z

View your CI Pipeline Execution ↗ for commit 52a8552

Command	Status	Duration	Result
`nx affected --targets=test:eslint,test:unit,tes...`	✅ Succeeded	5m 4s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	1m 34s	View ↗

☁️ Nx Cloud last updated this comment at 2025-08-10 10:10:39 UTC

pkg-pr-new · 2025-08-10T08:08:26Z

More templates

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@4907

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@4907

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@4907

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@4907

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@4907

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@4907

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@4907

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@4907

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@4907

@tanstack/react-start-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-plugin@4907

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@4907

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@4907

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@4907

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@4907

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@4907

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@4907

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@4907

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@4907

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@4907

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@4907

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@4907

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@4907

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@4907

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@4907

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@4907

@tanstack/solid-start-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-plugin@4907

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@4907

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@4907

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@4907

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@4907

@tanstack/start-server-functions-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-functions-client@4907

@tanstack/start-server-functions-fetcher

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-functions-fetcher@4907

@tanstack/start-server-functions-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-functions-server@4907

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@4907

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@4907

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@4907

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@4907

commit: 52a8552

… .d.ts files (#5134) Fixes #5116 ### Root Cause In PR #4907, the TypeScript compiler option `stripInternal` was enabled in tsconfig.json, which causes TypeScript to remove any declarations marked with `@internal` from the published `.d.ts` files. This resulted in TypeScript compilation errors for library users who have set the TypeScript compiler option `skipLibCheck` to `false`, because the following members were missing: - `InferStructuralSharing` type in `react-router` - `handleHashScroll` function in `router-core > scrollRestoration` ### Fix - This PR replaces the `@internal` annotation with the `@private` annotation.  ## Summary by CodeRabbit * **Documentation** * Updated internal API annotations in routing packages to mark certain items as private, improving the accuracy of generated developer documentation. * No changes to public APIs, behavior, or performance. * No user-facing impact.

…dratedMatch `DehydratedMatch['b']` is typed as `MakeRouteMatch['__beforeLoadContext']`, an indexed-access into `RouteMatch['__beforeLoadContext']`. That field has been tagged `@internal` since TanStack#4600 (2025-07-11); TanStack#4907 (2025-08-10) then enabled `stripInternal` repo-wide specifically to remove `@internal` members from the published `.d.ts`. From `router-core@1.171.16` onward the published types no longer have `RouteMatch.__beforeLoadContext`, but `ssr/types.ts` (moved to its current path by TanStack#6118, content otherwise unchanged) still indexes into it, leaving a dangling reference. This went unnoticed by plain SPA consumers for weeks because nothing in the always-imported client path pulled `ssr/types.ts` into their type graph. TanStack#7805's `load-client.ts` rewrite (2026-08-04) changed that: it imports `TsrSsrGlobal` from `./ssr/types`, and `load-client.ts` is core hydration code every consumer's `tsc` walks, SSR or not. Combined with `skipLibCheck: false` (the TS default), that's enough to fail with: error TS2339: Property '__beforeLoadContext' does not exist on type 'MakeRouteMatch'. Since `__beforeLoadContext` is declared as `Record<string, unknown>` in source, give `b` that concrete type directly instead of indexing into the stripped member. Verified against a built package: the emitted `dist/esm/ssr/types.d.ts` no longer references the internal member, and a minimal consumer repro (`skipLibCheck: false`, importing `createRouter`/`createRootRoute`) type- checks cleanly with this dist swapped in.

`DehydratedMatch['b']` indexes into `RouteMatch['__beforeLoadContext']`, which is tagged `@internal`. `stripInternal` (enabled in TanStack#4907) strips `@internal` members from the published `.d.ts`, so this reference has been dangling since `router-core@1.171.16`. TanStack#6118 later moved the interface to its current file unchanged. TanStack#7805's `load-client.ts` rewrite started importing from `./ssr/types`, surfacing the dangling reference for any consumer with `skipLibCheck: false`: error TS2339: Property '__beforeLoadContext' does not exist on type 'MakeRouteMatch'. Give `b` `__beforeLoadContext`'s declared source type directly instead of indexing into the stripped member. Verified against a built package: the emitted `dist/esm/ssr/types.d.ts` no longer references the internal member, and a minimal consumer repro type-checks cleanly with this dist swapped in.

`DehydratedMatch['b']` indexes into `RouteMatch['__beforeLoadContext']`, which is tagged `@internal`. `stripInternal` (enabled in fd341ad (PR TanStack#4907)) strips `@internal` members from the published `.d.ts`, so this reference has been dangling since `router-core@1.171.16`. f330532 (PR TanStack#6118) later moved the interface to its current file unchanged. 45c4ad8 (PR TanStack#7805)'s `load-client.ts` rewrite started importing from `./ssr/types`, surfacing the dangling reference for any consumer with `skipLibCheck: false`: error TS2339: Property '__beforeLoadContext' does not exist on type 'MakeRouteMatch'. Give `b` `__beforeLoadContext`'s declared source type directly instead of indexing into the stripped member. Verified against a built package: the emitted `dist/esm/ssr/types.d.ts` no longer references the internal member, and a minimal consumer repro type-checks cleanly with this dist swapped in.

`DehydratedMatch['b']` indexes into `RouteMatch['__beforeLoadContext']`, which is tagged `@internal`. `stripInternal` (enabled in fd341ad (PR TanStack#4907)) strips `@internal` members from the published `.d.ts`, so this reference has been dangling since `router-core@1.171.16`. f330532 (PR TanStack#6118) later moved the interface to its current file unchanged. 45c4ad8 (PR TanStack#7805)'s `load-client.ts` rewrite started importing from `./ssr/types`, surfacing the dangling reference for any consumer with `skipLibCheck: false`: error TS2339: Property '__beforeLoadContext' does not exist on type 'MakeRouteMatch'. Type `b` directly as `Record<string, unknown>` — the type `__beforeLoadContext` has in source — instead of indexing into the stripped member. Verified against a built package: the emitted `dist/esm/ssr/types.d.ts` no longer references the internal member, and a minimal consumer repro type-checks cleanly with this dist swapped in.

`DehydratedMatch['b']` indexes into `RouteMatch['__beforeLoadContext']`, which is tagged `@internal`. `stripInternal` (enabled in fd341ad (PR TanStack#4907)) strips `@internal` members from the published `.d.ts`, so this reference has been dangling since `router-core@1.171.16`. f330532 (PR TanStack#6118) later moved the interface to its current file unchanged. 45c4ad8 (PR TanStack#7805)'s `load-client.ts` rewrite started importing from `./ssr/types`, surfacing the dangling reference for any consumer with `skipLibCheck: false`: error TS2339: Property '__beforeLoadContext' does not exist on type 'MakeRouteMatch'. Give `b` the declared type of `__beforeLoadContext` instead of indexing into the stripped member. Verified against a built package: the emitted `dist/esm/ssr/types.d.ts` no longer references the internal member, and a minimal consumer repro type-checks cleanly with this dist swapped in.

`DehydratedMatch['b']` is typed by `RouteMatch['__beforeLoadContext']`. The problem is that `RouteMatch['__beforeLoadContext']` is tagged `@internal`. `stripInternal` (enabled in fd341ad(PR TanStack#4907)) strips `@internal` members from the published `.d.ts`, so this reference has been dangling since `router-core@1.171.16`. f330532 (PR TanStack#6118) later moved the interface to its current file unchanged. 45c4ad8 (PR TanStack#7805)'s `load-client.ts` rewrite started importing from `./ssr/types`, surfacing the dangling reference for any consumer with `skipLibCheck: false`: error TS2339: Property '__beforeLoadContext' does not exist on type 'MakeRouteMatch'. We solve this by giving `b` the declared type of `__beforeLoadContext`, instead of indexing into the stripped member. Verified against a built package: the emitted `dist/esm/ssr/types.d.ts` no longer references the internal member, and a minimal consumer repro type-checks cleanly with this dist swapped in.

`DehydratedMatch['b']` is typed by `RouteMatch['__beforeLoadContext']`, and `RouteMatch['__beforeLoadContext']` is tagged `@internal`. This worked fine until `stripInternal` was enabled in fd341ad(PR TanStack#4907), which strips `@internal` members from the published `.d.ts`. This has made this reference dangling since `router-core@1.171.16`. f330532 (PR TanStack#6118) later moved the interface to its current file unchanged. When 45c4ad8 (PR TanStack#7805) rewrote to `load-client.ts` and started importing from `./ssr/types`, the dangling reference was surfaced for consumers with `skipLibCheck: false` in this error: error TS2339: Property '__beforeLoadContext' does not exist on type 'MakeRouteMatch'. We solve this by giving `b` the declared type of `__beforeLoadContext`, instead of indexing into the stripped member. Verified against a built package: the emitted `dist/esm/ssr/types.d.ts` no longer references the internal member, and a minimal consumer repro type-checks cleanly with this dist swapped in.

refactor(router-core): strip internal types from public build

7d06131

github-actions Bot added the package: router-core label Aug 10, 2025

Sheraff requested a review from schiller-manuel August 10, 2025 08:03

ci: apply automated fixes

140f4b2

InferFoo types are not internal to router-core, used in react-router

52a8552

Sheraff merged commit fd341ad into main Aug 10, 2025
5 checks passed

Sheraff deleted the refactor-strip-internal-types branch August 10, 2025 21:38

vedant416 mentioned this pull request Sep 11, 2025

fix: restore InferStructuralSharing and handleHashScroll in published .d.ts files #5134

Merged

oddsund mentioned this pull request Aug 31, 2026

router-core: ssr/types.d.ts references stripped @internal field, breaks tsc for consumers typechecking libs #8203

Open

oddsund mentioned this pull request Aug 31, 2026

fix(router-core): fix dangling reference to stripped field #8206

Open

5 tasks

Navigation Menu

Uh oh!

Uh oh!

refactor(router-core): strip internal types from public build - #4907

refactor(router-core): strip internal types from public build#4907
Sheraff merged 3 commits into
mainfrom
refactor-strip-internal-types

Sheraff commented Aug 10, 2025 •

edited

Loading

Uh oh!

nx-cloud Bot commented Aug 10, 2025 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 10, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

Sheraff commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nx-cloud Bot commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Sheraff commented Aug 10, 2025 •

edited

Loading

nx-cloud Bot commented Aug 10, 2025 •

edited

Loading

pkg-pr-new Bot commented Aug 10, 2025 •

edited

Loading