feat: add @tanstack/intent AI agent skills for Router and Start#6866
feat: add @tanstack/intent AI agent skills for Router and Start#6866tannerlinsley wants to merge 2 commits intomainfrom
Conversation
Add SKILL.md files across 11 packages to help AI coding agents generate correct TanStack Router and Start code. Skills cover common patterns, API usage, and failure modes that agents frequently get wrong. Packages with skills: - router-core (10 skills): core concepts, search/path params, navigation, data loading, auth/guards, code splitting, not-found/errors, type safety, SSR - react-router (3): React bindings, Router+Query composition, migration from React Router - start-client-core (6): Start setup, server functions, middleware, execution model, server routes, deployment - react-start (2): React Start bindings, migration from Next.js - virtual-file-routes (1): programmatic route tree building - router-plugin (1): bundler plugin configuration - start-server-core (1): server-side runtime - solid-router (1): Solid bindings - vue-router (1): Vue bindings - solid-start (1): Solid Start bindings - vue-start (1): Vue Start bindings Each package includes bin/intent.js shim, _artifacts/ metadata, and @tanstack/intent devDependency.
📝 WalkthroughWalkthroughAdds extensive documentation and skill artifacts for TanStack Router and Start ecosystems, plus CLI bootstrap bin scripts and package.json updates across multiple packages to publish skills and expose an Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Comment |
|
| Command | Status | Duration | Result |
|---|---|---|---|
nx affected --targets=test:eslint,test:unit,tes... |
❌ Failed | 10m 26s | View ↗ |
nx run-many --target=build --exclude=examples/*... |
✅ Succeeded | 2m 5s | View ↗ |
☁️ Nx Cloud last updated this comment at 2026-03-09 21:34:47 UTC
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 17
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (28)
packages/router-core/skills/router-core/search-params/SKILL.md-26-28 (1)
26-28:⚠️ Potential issue | 🟡 MinorFix the split blockquote.
The blank line between these two quoted warnings trips markdownlint MD028 and can make the docs check fail. Keep them in one contiguous blockquote or turn them into separate paragraphs.
📝 Proposed fix
> **CRITICAL**: Use `fallback()` from `@tanstack/zod-adapter`, NOT zod's `.catch()`. Using `.catch()` makes the output type `unknown`, destroying type safety. - > **CRITICAL**: Types are fully inferred. Never annotate the return of `useSearch()`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/search-params/SKILL.md` around lines 26 - 28, Remove the blank line splitting the two quoted warnings so they form a single contiguous blockquote (or alternatively render each as its own paragraph); specifically, merge the lines containing "**CRITICAL**: Use `fallback()` from `@tanstack/zod-adapter`, NOT zod's `.catch()`." and "**CRITICAL**: Types are fully inferred. Never annotate the return of `useSearch()`." into one blockquote section to fix the MD028 markdownlint error.packages/router-core/skills/router-core/not-found-and-errors/SKILL.md-23-23 (1)
23-23:⚠️ Potential issue | 🟡 MinorRemove blank line between blockquotes.
The blank line between the two blockquote sections violates markdownlint rule MD028. Either merge the blockquotes or remove the blank line for consistency.
📝 Proposed fix
> **CRITICAL**: Do NOT use the deprecated `NotFoundRoute`. When present, `notFound()` and `notFoundComponent` will NOT work. Remove it and use `notFoundComponent` instead. - > **CRITICAL**: `useLoaderData` may be undefined inside `notFoundComponent`. Use `useParams`, `useSearch`, or `useRouteContext` instead.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/not-found-and-errors/SKILL.md` at line 23, Remove the blank line between the two blockquote sections in SKILL.md to satisfy markdownlint MD028; locate the two consecutive blockquote blocks (the lines starting with ">") and either merge them into a single continuous blockquote or delete the empty line between them so they appear as one contiguous block.packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md-23-25 (1)
23-25:⚠️ Potential issue | 🟡 MinorFix the markdownlint warnings in this new skill doc.
Line 24 triggers MD028 because the blockquote is split by a raw blank line, and Line 462 triggers MD040 because the fence has no language. Small issues, but they keep the doc lint output noisy.
Suggested doc tweak
> **CRITICAL**: If your UI is blank after migration, open the console. Errors like "cannot use useNavigate outside of context" mean React Router imports remain alongside TanStack Router imports. Uninstall `react-router` to surface them as TypeScript errors. - +> > **CRITICAL**: TanStack Router uses `to` + `params` for navigation, NOT template literal paths. Never interpolate params into the `to` string.-``` +```text React Router: /posts/:postId TanStack Router: /posts/$postId</details> Also applies to: 462-465 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md
around lines 23 - 25, The markdown has two lint issues: a blockquote split by a
raw blank line (MD028) and a fenced code block with no language (MD040) in the
SKILL.md content; fix by removing the stray blank line inside the blockquote so
the two CRITICAL lines remain contiguous, and add a language identifier (e.g.,
text) to the triple-backtick fence shown in the suggested example (also
update the same fence at the other occurrence referenced) so the linter stops
flagging MD028 and MD040.</details> </blockquote></details> <details> <summary>packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md-388-395 (1)</summary><blockquote> `388-395`: _⚠️ Potential issue_ | _🟡 Minor_ **Include `react-router-dom` in the cleanup search.** Line 391 and Line 392 only catch `from 'react-router'`, so stale `react-router-dom` imports slip past this checklist step. `npx tsc --noEmit` later helps, but the search itself is incomplete. <details> <summary>Suggested doc tweak</summary> ```diff - grep -r "from 'react-router" src/ - grep -r 'from "react-router' src/ + grep -rE "from ['\"]react-router(-dom)?['\"]" src/🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md` around lines 388 - 395, Update the cleanup checklist in SKILL.md so the search for remaining imports also catches react-router-dom; modify the two grep commands that currently search for "from 'react-router" / 'from "react-router' (the lines containing those grep commands) to either add equivalent grep lines for "react-router-dom" or broaden the pattern to match both packages, so stale react-router-dom imports are flagged before running npx tsc --noEmit.packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md-199-201 (1)
199-201:⚠️ Potential issue | 🟡 MinorFix the active-state styling example to match TanStack Router's
activePropsAPI.The description mentions "automatic
activedata attribute," but TanStack Router's Link component uses theactivePropsprop to apply styles when a link is active—not automatic data attributes. The exampleclassName="[&.active]:font-bold"doesn't align with this API; it should beactiveProps={{ className: 'font-bold' }}to properly demonstrate how to style active links in TanStack Router.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md` around lines 199 - 201, The active-state styling example is incorrect: replace the suggestion to use an automatic `active` data attribute and the `className="[&.active]:font-bold"` example with TanStack Router's `activeProps` API on the `Link` component (e.g., use `activeProps={{ className: 'font-bold' }}`) and update the text to explain `activeProps` applies props when a link is active; keep the existing notes that `to` is a route path pattern and `params` are separate typed props but remove the mention of an automatic `active` data attribute.packages/react-router/skills/compositions/router-query/SKILL.md-87-112 (1)
87-112:⚠️ Potential issue | 🟡 MinorAdd missing import for
QueryClientProvider.Line 102 uses
QueryClientProviderbut it's not included in the imports (lines 89-91). For consistency with other examples in this document (lines 37 and 160 show the import), and to prevent readers from copying incomplete code, add the import.📦 Proposed fix
// src/router.tsx -import { QueryClient } from '@tanstack/react-query' +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' import { createRouter } from '@tanstack/react-router' import { routeTree } from './routeTree.gen'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/react-router/skills/compositions/router-query/SKILL.md` around lines 87 - 112, The file is missing the QueryClientProvider import used in createAppRouter's Wrap component; add QueryClientProvider to the existing import from '@tanstack/react-query' (alongside QueryClient) at the top of the file so createAppRouter and its Wrap JSX can reference QueryClientProvider correctly.packages/router-core/skills/router-core/search-params/references/validation-patterns.md-241-247 (1)
241-247:⚠️ Potential issue | 🟡 MinorSame issue: installation includes unused adapter.
Line 243 states "No adapter needed" but line 246 includes
@tanstack/arktype-adapterin the installation. Unlike the Valibot section, there's no alternative example showing adapter usage here. Either remove the adapter from the installation command or add a section explaining when it's needed.📝 Suggested fix
## ArkType (Standard Schema) ArkType 2.0-rc+ implements Standard Schema. No adapter needed — pass the type directly to `validateSearch`. ```bash -npm install arktype `@tanstack/arktype-adapter` +npm install arktype</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@packages/router-core/skills/router-core/search-params/references/validation-patterns.md
around lines 241 - 247, The install command incorrectly includes
@tanstack/arktype-adapterdespite the preceding text saying "No adapter needed"
for ArkType 2.0-rc+; update the documentation in the ArkType (Standard Schema)
block by removing the adapter from the npm install line so it reads just "npm
install arktype", or alternatively keep the adapter but add a brief clarifying
sentence and example that explains when and why@tanstack/arktype-adapteris
required (mirroring the Valibot section) and show the adapter usage; update the
surrounding text to remain consistent with the chosen approach.</details> </blockquote></details> <details> <summary>packages/router-core/skills/router-core/search-params/references/validation-patterns.md-174-179 (1)</summary><blockquote> `174-179`: _⚠️ Potential issue_ | _🟡 Minor_ **Clarify installation command vs. "no adapter needed" statement.** Line 176 states "No adapter wrapper needed" but line 179 includes `@tanstack/valibot-adapter` in the installation command. Since the adapter is shown as an "Alternative" approach later (line 222), consider either: - Moving the adapter installation to line 224 (near the alternative section), or - Adding a note explaining the adapter is optional for advanced use cases This will reduce confusion about which packages users actually need. <details> <summary>📝 Suggested clarification</summary> ```diff ## Valibot (Standard Schema) Valibot 1.0+ implements Standard Schema. No adapter wrapper needed — pass the schema directly to `validateSearch`. ```bash -npm install valibot `@tanstack/valibot-adapter` +npm install valibotThen in the alternative section: ```diff ### Valibot with Adapter (Alternative) If you need explicit input/output type control: +```bash +npm install `@tanstack/valibot-adapter` +``` + ```tsx import { valibotValidator } from '@tanstack/valibot-adapter'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/search-params/references/validation-patterns.md` around lines 174 - 179, The docs currently say "No adapter wrapper needed" but the install line includes `@tanstack/valibot-adapter` which contradicts that; update the Valibot section so the primary install command installs only valibot (for use with validateSearch) and either move the `@tanstack/valibot-adapter` install into the "Alternative" section near the valibotValidator example or add a one-line note that the adapter is optional for advanced use cases; ensure references to validateSearch and valibotValidator remain unchanged so readers can locate the usage examples.packages/router-core/skills/router-core/navigation/SKILL.md-402-417 (1)
402-417:⚠️ Potential issue | 🟡 MinorChange the comment from "no accessibility" to "no link semantics."
Native
<button>elements are accessible by default—they're focusable, keyboard-activable, and expose proper semantics to assistive technologies. The real issue here is that the button lacks link semantics and router affordances likehref, Cmd/Ctrl+Click behavior, and active/inactive states. Calling it "no accessibility" teaches the wrong model and obscures why<Link>is the better choice.Suggested wording
-// WRONG — no href, no cmd+click, no preloading, no accessibility +// WRONG — no href, no cmd+click, no preloading, and no link semantics🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/navigation/SKILL.md` around lines 402 - 417, Update the explanatory comment in the MEDIUM example to replace "no accessibility" with "no link semantics" and explain that using useNavigate in the BadNav example (function BadNav) results in a button element that lacks link semantics and router affordances (no href, no Cmd/Ctrl-click, no preloading, no active state), while the GoodNav example (function GoodNav using Link) preserves those link semantics; edit the text around useNavigate/BadNav/GoodNav to reflect this corrected phrasing and rationale.packages/router-core/skills/router-core/navigation/SKILL.md-171-171 (1)
171-171:⚠️ Potential issue | 🟡 MinorClarify freshness vs eviction here.
This sentence currently teaches the wrong knob: TanStack Router uses
defaultPreloadStaleTimefor how long preloaded data is considered fresh, while unused preloaded data is evicted based ondefaultPreloadMaxAge. As written, an agent trying to change retention will likely edit the stale-time setting instead.Suggested wording
-Preloaded data is cached for 30 seconds by default (`defaultPreloadStaleTime`). When using an external cache like TanStack Query, set `defaultPreloadStaleTime: 0` to let the external library control freshness. +Preloaded data is considered fresh for 30 seconds by default (`defaultPreloadStaleTime`). Unused preloaded data is evicted after 30 seconds by default (`defaultPreloadMaxAge`). When using an external cache like TanStack Query, set `defaultPreloadStaleTime: 0` to let the external library control freshness.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/navigation/SKILL.md` at line 171, The docs confuse freshness vs eviction: update the sentence to state that defaultPreloadStaleTime controls how long preloaded data is considered fresh, while defaultPreloadMaxAge controls how long unused preloaded data is kept (evicted after this age); mention that when delegating retention to an external cache like TanStack Query you should set defaultPreloadMaxAge appropriately (e.g., 0) if you want the external cache to control eviction, and set defaultPreloadStaleTime to 0 only if you want the external library to control freshness. Reference the symbols defaultPreloadStaleTime and defaultPreloadMaxAge when making this change.packages/router-core/skills/router-core/path-params/SKILL.md-277-287 (1)
277-287:⚠️ Potential issue | 🟡 MinorAdd missing imports to code snippets using
redirectandnotFound.Both examples read like full route files, but
redirectandnotFoundare standalone exports from@tanstack/react-routerthat must be explicitly imported. Other skill files in the codebase consistently include these imports in similar examples. Omitting them makes it easy for developers to copy-paste non-compiling code.✏️ Suggested doc fix
+import { createFileRoute, redirect } from '@tanstack/react-router' + export const Route = createFileRoute('/posts/$postId')({ beforeLoad: async ({ params }) => { // params.postId available here const canView = await checkPermission(params.postId) if (!canView) throw redirect({ to: '/unauthorized' }) }, loader: async ({ params }) => { return fetchPost(params.postId) }, })+import { createFileRoute, notFound } from '@tanstack/react-router' + export const Route = createFileRoute('/posts/$postId')({ loader: async ({ params }) => { const id = parseInt(params.postId, 10) if (isNaN(id)) throw notFound() return fetchPost(id) }, })Also applies to: 359-381
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/path-params/SKILL.md` around lines 277 - 287, The example route snippets use the standalone exports redirect and notFound but don't import them; update the Route examples using createFileRoute (and related examples at the other location) to add an explicit import for redirect and/or notFound from "@tanstack/react-router" so the beforeLoad, loader and notFound usage compiles when copy-pasted—locate the examples referencing redirect, notFound, Route, createFileRoute, beforeLoad and loader and add the appropriate import statements.packages/router-core/skills/router-core/path-params/SKILL.md-317-335 (1)
317-335:⚠️ Potential issue | 🟡 MinorClarify route syntax vs. param key for splat routes.
The current section conflates
$(route syntax) with_splat(param access). While technically correct that$is used for routes and_splatfor params, the wording "The captured value is under_splat, not*" is misleading—*is a v1 backwards-compatibility alias, not an error. For AI skill documentation, explicitly separate the two concepts:✏️ Suggested wording
-TanStack Router uses `$` for splat routes. The captured value is under `_splat`, not `*`. +TanStack Router uses `$` in the route path for splat routes. The captured value is available under the `_splat` param key. ... -> Note: `*` works in v1 for backwards compatibility but will be removed in v2. Always use `_splat`. +> Note: Prefer `$` for route syntax and `_splat` for param access. The `*` key is a v1-only backwards-compatibility alias and will be removed in v2.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/path-params/SKILL.md` around lines 317 - 335, Reword the paragraph in SKILL.md to separate route syntax from param access: state that routes use `$` in path syntax (e.g., File: src/routes/files.$.tsx) while the captured value is available as the `_splat` param via Route.useParams(); clarify that `*` is only a v1 backwards-compatibility alias (not the param name) and will be removed in v2, and update the example and wording to reflect that distinction (reference symbols: createFileRoute, Route.useParams(), `_splat`, `$`, and `*`).packages/virtual-file-routes/skills/_artifacts/skill_spec.md-9-15 (1)
9-15:⚠️ Potential issue | 🟡 MinorDomain name inconsistency between tables.
Line 9 uses "Virtual Route Configuration" (title case) while Line 15 uses "virtual-route-config" (hyphenated lowercase). Consider using a consistent format across both tables to avoid potential tooling mismatches.
Proposed fix
| Skill | Type | Domain | What it covers | Failure modes | | ------------------- | ---- | -------------------- | ---------------------------------------------------------- | ------------- | -| virtual-file-routes | core | virtual-route-config | rootRoute, index, route, layout, physical, subtree configs | 2 | +| virtual-file-routes | core | Virtual Route Configuration | rootRoute, index, route, layout, physical, subtree configs | 2 |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/virtual-file-routes/skills/_artifacts/skill_spec.md` around lines 9 - 15, The "Virtual Route Configuration" title in the first table and the "virtual-route-config" domain cell in the Skill Inventory table are inconsistent; update one so both use the same normalized format (pick either Title Case or hyphenated-lowercase) — e.g., change "Virtual Route Configuration" to "virtual-route-config" OR change the domain cell "virtual-route-config" to "Virtual Route Configuration" — and ensure both occurrences (the table header and the Domain column entry) match exactly.packages/router-plugin/skills/_artifacts/skill_spec.md-9-15 (1)
9-15:⚠️ Potential issue | 🟡 MinorDomain name inconsistency between tables.
Line 9 uses "Bundler Integration" (title case) while Line 15 uses "bundler-integration" (hyphenated lowercase). This pattern appears across multiple skill_spec.md files in this PR—consider normalizing all domain references to a single format.
Proposed fix
| Skill | Type | Domain | What it covers | Failure modes | | ------------- | ---- | ------------------- | -------------------------------------------------------------- | ------------- | -| router-plugin | core | bundler-integration | Vite/Webpack/Rspack/esbuild plugins, route gen, code splitting | 2 | +| router-plugin | core | Bundler Integration | Vite/Webpack/Rspack/esbuild plugins, route gen, code splitting | 2 |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-plugin/skills/_artifacts/skill_spec.md` around lines 9 - 15, The domain string is inconsistent: change the header cell "Bundler Integration" in the first table to match the inventory format "bundler-integration" so both table entries use the same lowercase hyphenated form; update the header in the top table (the cell under the first table's second column) to "bundler-integration" and scan other skill_spec.md files to normalize any other occurrences to this same format (e.g., ensure the "router-plugin" row's Domain value remains "bundler-integration").packages/vue-router/skills/_artifacts/skill_spec.md-9-15 (1)
9-15:⚠️ Potential issue | 🟡 MinorDomain name inconsistency between tables.
Line 9 uses "Vue Router Bindings" (title case with spaces) while Line 15 uses "vue-router-bindings" (hyphenated lowercase). If the intent tooling performs case-sensitive domain matching, this mismatch could cause lookup failures.
Proposed fix
| Skill | Type | Domain | What it covers | Failure modes | | ---------- | --------- | ------------------- | --------------------------------------------------------------- | ------------- | -| vue-router | framework | vue-router-bindings | Ref<T> returns, defineComponent, h(), provide/inject, Html/Body | 2 | +| vue-router | framework | Vue Router Bindings | Ref<T> returns, defineComponent, h(), provide/inject, Html/Body | 2 |Or normalize to the hyphenated form in both tables, depending on the convention used by
@tanstack/intent.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/vue-router/skills/_artifacts/skill_spec.md` around lines 9 - 15, The domain string is inconsistent between the top table title "Vue Router Bindings" and the Skill Inventory domain value "vue-router-bindings"; normalize them to the same form (prefer the hyphenated lowercase convention used by `@tanstack/intent`) by changing the title or the domain value so both read "vue-router-bindings" and ensure the domain column for the "vue-router" skill and the table header use that exact string.packages/router-plugin/bin/intent.js-8-19 (1)
8-19:⚠️ Potential issue | 🟡 MinorDisambiguate transitive dependency failures from missing
@tanstack/intent.The catch block at lines 8–19 treats any
ERR_MODULE_NOT_FOUNDorMODULE_NOT_FOUNDas "@tanstack/intent is not installed," but Node.js throws these errors for any unresolved module during import—including missing transitive dependencies or broken internal modules within@tanstack/intent. This masks the actual problem: a broken install or incompatible version.Check the error message for
@tanstack/intentto distinguish the two cases. Only show the friendly install hint when the missing package is@tanstack/intentitself; rethrow other resolution failures unchanged.Proposed fix
try { await import('@tanstack/intent/intent-library') } catch (e) { - if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') { + const code = e && typeof e === 'object' ? e.code : undefined + const message = e instanceof Error ? e.message : String(e) + const isMissingIntent = + (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') && + /@tanstack\/intent(\/intent-library)?/.test(message) + + if (isMissingIntent) { console.error('@tanstack/intent is not installed.') console.error('') console.error('Install it as a dev dependency:') console.error(' npm add -D `@tanstack/intent`') console.error('')Note: This pattern appears in 12 files across the repository and should be updated consistently.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-plugin/bin/intent.js` around lines 8 - 19, The catch block in packages/router-plugin/bin/intent.js currently treats any ERR_MODULE_NOT_FOUND/MODULE_NOT_FOUND as “@tanstack/intent is not installed”; change it to inspect the error text to ensure the missing module is actually '@tanstack/intent' before showing the friendly install hint: check e.message (or e?.stack) for the exact string "Cannot find module" or the module name "'@tanstack/intent'" (or "@tanstack/intent") and only print the install/help output in that case; for all other ERR_MODULE_NOT_FOUND/MODULE_NOT_FOUND errors rethrow e unchanged so transitive dependency or internal module failures are not masked. Apply the same check pattern to other similar catch blocks found across the repo.packages/start-client-core/bin/intent.js-8-19 (1)
8-19:⚠️ Potential issue | 🟡 MinorDon't treat every
MODULE_NOT_FOUNDas "intent is missing".This catch block only checks
e.code. If@tanstack/intent/intent-libraryis present but one of its imports is missing, the shim will print the install hint and exit with a misleading error message. Narrow the guard to errors that specifically mention@tanstack/intent/intent-libraryin the error message before applying the fallback message.♻️ Suggested guard
} catch (e) { - if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') { + const isMissingIntentLibrary = + (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') && + String(e?.message ?? '').includes('@tanstack/intent/intent-library') + + if (isMissingIntentLibrary) { console.error('@tanstack/intent is not installed.') console.error('') console.error('Install it as a dev dependency:') @@ process.exit(1) } throw e }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/bin/intent.js` around lines 8 - 19, The catch block currently treats any ERR_MODULE_NOT_FOUND/MODULE_NOT_FOUND as if `@tanstack/intent` is missing; update the guard in the catch to also verify the error message references the specific module path (e.g. '@tanstack/intent/intent-library') before printing the install hint and exiting—keep the existing e.code checks (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') but require e.message (or e.toString()) to include the module identifier string before running the console.error/install instructions in the same catch block.packages/start-server-core/package.json-89-98 (1)
89-98:⚠️ Potential issue | 🟡 MinorConsider making the npx fallback automatic or moving
@tanstack/intentto dependencies.When
./bin/intent.jsis called by a consumer without@tanstack/intentinstalled, it fails gracefully with error messaging that suggests runningnpx@tanstack/intent@latest. However, this requires user intervention. If the binary should work seamlessly for consumers of this package, either:
- Move
@tanstack/intentfromdevDependenciestodependencies, or- Automatically invoke the npx fallback instead of just suggesting it.
The current error handling is present but reactive rather than proactive.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-server-core/package.json` around lines 89 - 98, The package currently lists "@tanstack/intent" under devDependencies but exposes a bin "intent" that requires it; update package.json to move "@tanstack/intent" from devDependencies into dependencies so consumers get it installed, or alternatively modify the runtime in ./bin/intent.js (the "intent" entry point) to programmatically attempt to require("@tanstack/intent") and, on failure, spawn an automatic "npx `@tanstack/intent`@latest" fallback instead of only printing instructions; pick one approach, ensure the change references the "@tanstack/intent" dependency and the "./bin/intent.js" bin entry, and update package.json accordingly.packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md-214-219 (1)
214-219:⚠️ Potential issue | 🟡 MinorThe documentation comment is contradictory and should be clarified.
Lines 215 and 218 contradict each other: line 215 says "does NOT create a /dashboard URL" while line 218 says "The URL is /dashboard". The intended point—that
layout()contributes no path segment—gets lost. Update to clarify thatlayout()itself is pathless while the child route provides the segment:Suggested fix
-// This does NOT create a /dashboard URL +// `layout()` itself does not add a URL segment layout('dashboardLayout.tsx', [route('/dashboard', 'dashboard.tsx')]) -// The URL is /dashboard, and dashboardLayout.tsx wraps it +// `/dashboard` comes from the child route; the layout only wraps it🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md` around lines 214 - 219, The comment is contradictory about whether layout('dashboardLayout.tsx', [route('/dashboard', 'dashboard.tsx')]) creates the /dashboard path; update the doc to state clearly that layout() is pathless and does not add a URL segment, while the child route(route('/dashboard', 'dashboard.tsx')) supplies the /dashboard path and is wrapped by dashboardLayout.tsx. Mention the symbols layout(), route(), dashboardLayout.tsx and dashboard.tsx so readers can find the example.packages/start-client-core/skills/start-core/middleware/SKILL.md-23-25 (1)
23-25:⚠️ Potential issue | 🟡 MinorRemove the blank line inside the CRITICAL blockquote.
The empty line here trips
markdownlintMD028.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/skills/start-core/middleware/SKILL.md` around lines 23 - 25, Remove the empty line inside the CRITICAL blockquote in SKILL.md so the two CRITICAL sentences about method order (`middleware()` → `inputValidator()` → `client()` → `server()`) and `sendContext` validation appear as a single continuous blockquote paragraph; edit the blockquote to join the sentences without a blank line to satisfy markdownlint MD028.packages/react-router/skills/react-router/SKILL.md-29-33 (1)
29-33:⚠️ Potential issue | 🟡 MinorKeep the CRITICAL callouts in one blockquote.
The blank lines on Line 30 and Line 32 trigger
markdownlintMD028.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/react-router/skills/react-router/SKILL.md` around lines 29 - 33, Combine the three separate CRITICAL blockquotes into a single blockquote by merging the three lines starting with "**CRITICAL**: TanStack Router types...", "**CRITICAL**: TanStack Router is CLIENT-FIRST...", and "**CRITICAL**: Do not confuse `@tanstack/react-router`..." into one contiguous blockquote with no blank lines between them to satisfy markdownlint MD028 (remove the blank lines that currently exist between those CRITICAL callouts).packages/start-client-core/skills/start-core/execution-model/SKILL.md-23-27 (1)
23-27:⚠️ Potential issue | 🟡 MinorRemove the blank lines inside the CRITICAL blockquote.
The empty lines between these three callouts trip
markdownlintMD028.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/skills/start-core/execution-model/SKILL.md` around lines 23 - 27, Remove the empty lines inside the CRITICAL blockquote in SKILL.md so the three bullet sentences are contiguous (no blank lines between the three lines beginning with "**CRITICAL**: ALL code...", "**CRITICAL**: Module-level `process.env`...", and "**CRITICAL**: `VITE_` prefixed..."). Edit the blockquote so it reads as three consecutive lines with no blank lines to satisfy markdownlint MD028.packages/react-start/skills/_artifacts/skill_tree.yaml-11-12 (1)
11-12:⚠️ Potential issue | 🟡 MinorPath resolution for
generated_fromreference needs clarification.The
generated_fromreferences_artifacts/start_domain_map.yaml. The actual file exists at the repository root (_artifacts/start_domain_map.yaml), but the YAML file is located inpackages/react-start/skills/_artifacts/. If the consuming tool resolves paths relative to the YAML file's location, the reference will fail. Confirm whether paths are resolved from the repository root or relative to the file's directory, and adjust the path accordingly if needed.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/react-start/skills/_artifacts/skill_tree.yaml` around lines 11 - 12, The generated_from reference in skill_tree.yaml points to start_domain_map.yaml but may be resolved relative to the YAML file instead of the repository root; check how the consuming tool resolves paths, and then update the generated_from value in skill_tree.yaml so it correctly points to start_domain_map.yaml (either by changing it to a repo-root absolute reference or by rewriting it as the correct relative path from the skill_tree.yaml location) so the resolver finds the start_domain_map.yaml file.packages/solid-router/skills/solid-router/SKILL.md-27-33 (1)
27-33:⚠️ Potential issue | 🟡 MinorRemove the blank lines inside this blockquote.
markdownlint already flags MD028 here, so this doc will ship with avoidable warnings.
🧹 Proposed fix
> **CRITICAL**: TanStack Router types are FULLY INFERRED. Never cast, never annotate inferred values. - > **CRITICAL**: TanStack Router is CLIENT-FIRST. Loaders run on the client by default, not on the server. - > **CRITICAL**: Most hooks return `Accessor<T>` — you MUST call the accessor (`value()`) to read the reactive value. This is the `#1` difference from the React version. - > **CRITICAL**: Do not confuse `@tanstack/solid-router` with `@solidjs/router`. They are completely different libraries with different APIs.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/solid-router/skills/solid-router/SKILL.md` around lines 27 - 33, The blockquote containing the four "**CRITICAL**" lines currently has empty blank lines inside it which triggers markdownlint MD028; remove the extra blank lines so the blockquote is a contiguous set of lines (ensure each line begins with ">" and there are no empty ">" lines between them), preserving the exact text of the "**CRITICAL**" entries (e.g., the lines starting with "> **CRITICAL**: TanStack Router types...", "> **CRITICAL**: TanStack Router is CLIENT-FIRST...", "> **CRITICAL**: Most hooks return `Accessor<T>`...", "> **CRITICAL**: Do not confuse `@tanstack/solid-router`...") to resolve the lint warning.packages/router-core/skills/router-core/auth-and-guards/SKILL.md-23-23 (1)
23-23:⚠️ Potential issue | 🟡 MinorFix the relative link to the parent skill.
From
packages/router-core/skills/router-core/auth-and-guards/, this target walks up one directory too many and resolves to a non-existent path.../SKILL.mdpoints at the sibling parent skill.🔗 Proposed fix
-This skill builds on router-core. Read [router-core](../../../router-core/skills/router-core/SKILL.md) first for foundational concepts. +This skill builds on router-core. Read [router-core](../SKILL.md) first for foundational concepts.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/auth-and-guards/SKILL.md` at line 23, Update the broken relative link in packages/router-core/skills/router-core/auth-and-guards/SKILL.md so it points to the parent skill one directory up; replace the incorrect ../../SKILL.md (which climbs too many levels) with ../SKILL.md to reference the sibling parent skill correctly.packages/start-client-core/skills/start-core/server-routes/SKILL.md-254-263 (1)
254-263:⚠️ Potential issue | 🟡 MinorAdd a language tag to the route-conflict example fence.
The fence opened at Line 256 is unlabeled, so it trips MD040 and loses syntax highlighting.
textwould be enough here.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/skills/start-core/server-routes/SKILL.md` around lines 254 - 263, The code block in the "1. MEDIUM: Duplicate route paths" example is an unlabeled fenced code block (the triple-backtick fence containing "# WRONG — both resolve to /users, causes error" and the following lines), which triggers MD040; add a language tag (e.g., change ``` to ```text) on that fence so the example is labelled and gains correct syntax highlighting and linter compliance.packages/start-client-core/skills/start-core/server-functions/SKILL.md-22-24 (1)
22-24:⚠️ Potential issue | 🟡 MinorFix the markdownlint warnings in this skill doc.
Line 23 still trips MD028 because the adjacent blockquotes are separated by a raw blank line, and the fence opened at Line 228 should be tagged as
text/plaintextto satisfy MD040.Also applies to: 228-233
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/skills/start-core/server-functions/SKILL.md` around lines 22 - 24, Fix the markdownlint issues by removing the raw blank line between the two adjacent blockquotes (the pair starting with "**CRITICAL**: Loaders are ISOMORPHIC..." and the subsequent "**CRITICAL**: Do not use..." block) so they are consecutive blockquote lines (resolves MD028), and update the fenced code block near the bottom of SKILL.md (the fence opened as an untyped triple-backtick block around the example text) to include an explicit language tag of either "text" or "plaintext" (resolves MD040); ensure no other blank lines separate those blockquotes and that the fence uses ```text or ```plaintext.packages/start-client-core/skills/start-core/SKILL.md-21-25 (1)
21-25:⚠️ Potential issue | 🟡 MinorFix the markdownlint warnings in the overview skill.
Lines 21-25 still have raw blank lines between adjacent blockquotes (MD028), and the decision tree opened at Line 39 should declare a language such as
textso MD040 stays clean.Also applies to: 39-54
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/skills/start-core/SKILL.md` around lines 21 - 25, Fix the markdownlint issues: remove the raw blank lines between adjacent blockquotes in the overview so the multiple consecutive > lines are contiguous (address MD028) and add a language identifier (e.g., "text") to the fenced decision-tree code block opened around the decision tree (the fenced block starting near Line 39) to satisfy MD040; update the SKILL.md blockquote group and the code fence declaration accordingly.
🧹 Nitpick comments (5)
packages/router-core/skills/router-core/type-safety/SKILL.md (1)
24-26: Optional: Address markdownlint warning for stricter compliance.The blank line between blockquotes improves readability by separating two distinct critical warnings, but markdownlint flags this as MD028. If strict linter compliance is required, you can remove the blank line or merge the blockquotes.
🔧 Optional fix to merge blockquotes
> **CRITICAL**: NEVER use `as Type`, explicit generic params, `satisfies` on hook returns, or type annotations on inferred values. Every cast masks real type errors and breaks the inference chain. - +> > **CRITICAL**: Do NOT confuse TanStack Router with Next.js or React Router. There is no `getServerSideProps`, no `useSearchParams()`, no `useLoaderData()` from `react-router-dom`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/type-safety/SKILL.md` around lines 24 - 26, The markdown contains two adjacent blockquotes that are separated by a blank line which triggers markdownlint MD028; edit SKILL.md to either remove the blank line between the two CRITICAL blockquotes or merge them into a single blockquote so the warnings remain intact but the file passes the linter (target the two lines containing the "**CRITICAL**:" messages and adjust spacing accordingly).packages/router-core/skills/router-core/data-loading/SKILL.md (1)
483-484: Consider using markdown links for cross-references.The cross-references are formatted as bold text. If these SKILL.md files are meant to be navigable or if the skill system supports linking, consider using standard markdown link syntax for consistency:
-- See also: **router-core/search-params/SKILL.md** — `loaderDeps` consumes validated search params as cache keys -- See also: **compositions/router-query/SKILL.md** — for external cache coordination with TanStack Query +- See also: [router-core/search-params](../search-params/SKILL.md) — `loaderDeps` consumes validated search params as cache keys +- See also: [compositions/router-query](../../../compositions/router-query/SKILL.md) — for external cache coordination with TanStack QueryAlternatively, if the bold text format is the standard convention for the
@tanstack/intentskill system, this is fine as-is.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-core/skills/router-core/data-loading/SKILL.md` around lines 483 - 484, Replace the bold cross-reference lines that currently read "**router-core/search-params/SKILL.md** — `loaderDeps` consumes validated search params as cache keys" and "**compositions/router-query/SKILL.md** — for external cache coordination with TanStack Query" with standard markdown links so the references are navigable (e.g. use [router-core/search-params/SKILL.md](router-core/search-params/SKILL.md) and [compositions/router-query/SKILL.md](compositions/router-query/SKILL.md)), keeping the trailing explanatory text and the code span `loaderDeps` intact.packages/router-plugin/package.json (1)
103-103: Consider linting or syntax-checking the new bin.These lines make
bin/intent.jspart of the shipped surface, but this package’s current CI only lint-checks./src. A tinynode --check ./bin/intent.jsor adding./binto the ESLint target would keep publish-time regressions from slipping through.Also applies to: 154-155
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/router-plugin/package.json` at line 103, The package.json now exposes "bin" (making bin/intent.js part of the shipped surface) but CI only lints ./src, so add a publish-time syntax check for the new bin or include ./bin in linting: update CI to run `node --check ./bin/intent.js` (or equivalent syntax check) and/or add ./bin to the ESLint target so bin/intent.js (and the other bin entry at lines 154-155) are checked before publishing.packages/react-start/skills/_artifacts/skill_tree.yaml (1)
1-1: Header comment doesn't match actual file path.The comment indicates
skills/_artifacts/start_skill_tree.yamlbut the file is located atpackages/react-start/skills/_artifacts/skill_tree.yaml.📝 Suggested fix
-# skills/_artifacts/start_skill_tree.yaml +# packages/react-start/skills/_artifacts/skill_tree.yaml🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/react-start/skills/_artifacts/skill_tree.yaml` at line 1, The header comment at the top of the YAML incorrectly references "start_skill_tree.yaml"; update that comment to match the actual file name "skill_tree.yaml" by replacing the text "skills/_artifacts/start_skill_tree.yaml" in the top-of-file comment (the line that currently starts with "# ") with "skills/_artifacts/skill_tree.yaml" so the header accurately reflects this file's name and prevents confusion.packages/start-server-core/skills/_artifacts/domain_map.yaml (1)
48-63: Keep the failure-mode records schema-consistent with the other artifacts.These entries omit
source, while the pairedpackages/start-server-core/skills/_artifacts/skill_spec.mdalready records one and the reviewed client-core domain map does the same in YAML. Adding it here would keep the machine-readable shape uniform.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-server-core/skills/_artifacts/domain_map.yaml` around lines 48 - 63, The two failure_mode entries under failure_modes (the ones with mistake values "Missing AsyncLocalStorage setup" and "Incorrect handler export for deployment target") are missing the required source field; update each entry to include a source key with an appropriate identifier string (matching the schema used in skill_spec.md and the client-core domain map) so the records are schema-consistent while preserving existing keys mistake, mechanism, priority, and status.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d232371a-f31e-496c-b398-32a3e2447e98
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (83)
_artifacts/domain_map.yaml_artifacts/skill_spec.md_artifacts/skill_tree.yaml_artifacts/start_domain_map.yaml_artifacts/start_skill_tree.yamlpackages/react-router/bin/intent.jspackages/react-router/package.jsonpackages/react-router/skills/compositions/router-query/SKILL.mdpackages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.mdpackages/react-router/skills/react-router/SKILL.mdpackages/react-start/bin/intent.jspackages/react-start/package.jsonpackages/react-start/skills/_artifacts/domain_map.yamlpackages/react-start/skills/_artifacts/skill_spec.mdpackages/react-start/skills/_artifacts/skill_tree.yamlpackages/react-start/skills/lifecycle/migrate-from-nextjs/SKILL.mdpackages/react-start/skills/react-start/SKILL.mdpackages/router-core/bin/intent.jspackages/router-core/package.jsonpackages/router-core/skills/router-core/SKILL.mdpackages/router-core/skills/router-core/auth-and-guards/SKILL.mdpackages/router-core/skills/router-core/code-splitting/SKILL.mdpackages/router-core/skills/router-core/data-loading/SKILL.mdpackages/router-core/skills/router-core/navigation/SKILL.mdpackages/router-core/skills/router-core/not-found-and-errors/SKILL.mdpackages/router-core/skills/router-core/path-params/SKILL.mdpackages/router-core/skills/router-core/search-params/SKILL.mdpackages/router-core/skills/router-core/search-params/references/validation-patterns.mdpackages/router-core/skills/router-core/ssr/SKILL.mdpackages/router-core/skills/router-core/type-safety/SKILL.mdpackages/router-plugin/bin/intent.jspackages/router-plugin/package.jsonpackages/router-plugin/skills/_artifacts/domain_map.yamlpackages/router-plugin/skills/_artifacts/skill_spec.mdpackages/router-plugin/skills/_artifacts/skill_tree.yamlpackages/router-plugin/skills/router-plugin/SKILL.mdpackages/solid-router/bin/intent.jspackages/solid-router/package.jsonpackages/solid-router/skills/_artifacts/domain_map.yamlpackages/solid-router/skills/_artifacts/skill_spec.mdpackages/solid-router/skills/_artifacts/skill_tree.yamlpackages/solid-router/skills/solid-router/SKILL.mdpackages/solid-start/bin/intent.jspackages/solid-start/package.jsonpackages/solid-start/skills/_artifacts/domain_map.yamlpackages/solid-start/skills/_artifacts/skill_spec.mdpackages/solid-start/skills/_artifacts/skill_tree.yamlpackages/solid-start/skills/solid-start/SKILL.mdpackages/start-client-core/bin/intent.jspackages/start-client-core/package.jsonpackages/start-client-core/skills/_artifacts/domain_map.yamlpackages/start-client-core/skills/_artifacts/skill_spec.mdpackages/start-client-core/skills/_artifacts/skill_tree.yamlpackages/start-client-core/skills/start-core/SKILL.mdpackages/start-client-core/skills/start-core/deployment/SKILL.mdpackages/start-client-core/skills/start-core/execution-model/SKILL.mdpackages/start-client-core/skills/start-core/middleware/SKILL.mdpackages/start-client-core/skills/start-core/server-functions/SKILL.mdpackages/start-client-core/skills/start-core/server-routes/SKILL.mdpackages/start-server-core/bin/intent.jspackages/start-server-core/package.jsonpackages/start-server-core/skills/_artifacts/domain_map.yamlpackages/start-server-core/skills/_artifacts/skill_spec.mdpackages/start-server-core/skills/_artifacts/skill_tree.yamlpackages/start-server-core/skills/start-server-core/SKILL.mdpackages/virtual-file-routes/bin/intent.jspackages/virtual-file-routes/package.jsonpackages/virtual-file-routes/skills/_artifacts/domain_map.yamlpackages/virtual-file-routes/skills/_artifacts/skill_spec.mdpackages/virtual-file-routes/skills/_artifacts/skill_tree.yamlpackages/virtual-file-routes/skills/virtual-file-routes/SKILL.mdpackages/vue-router/bin/intent.jspackages/vue-router/package.jsonpackages/vue-router/skills/_artifacts/domain_map.yamlpackages/vue-router/skills/_artifacts/skill_spec.mdpackages/vue-router/skills/_artifacts/skill_tree.yamlpackages/vue-router/skills/vue-router/SKILL.mdpackages/vue-start/bin/intent.jspackages/vue-start/package.jsonpackages/vue-start/skills/_artifacts/domain_map.yamlpackages/vue-start/skills/_artifacts/skill_spec.mdpackages/vue-start/skills/_artifacts/skill_tree.yamlpackages/vue-start/skills/vue-start/SKILL.md
| "bin": { | ||
| "intent": "./bin/intent.js" | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
How do npm, pnpm, and Yarn handle package.json bin name collisions when multiple installed packages declare the same binary name?
💡 Result:
npm
- Local installs (
node_modules/.bin): bin name collisions are not treated as an error; the link/shim for a bin name can be replaced (effectively “last one linked wins”), becausebin-links’ conflict check is skipped unless it’s a top-level global install (or--forceis used). This is explicitly called out bybinLinks.checkBins()“always returns successfully ifglobalortopare false”. [1] - Global installs: modern npm refuses to overwrite an existing global bin unless the existing bin is already owned by the same package being installed (or you use
--force). [2]
pnpm
- pnpm links bins via
@pnpm/link-bins, which deduplicates by bin name and resolves collisions deterministically before writing:- If pnpm knows the project manifest, it prefers bins from direct dependencies over non-direct/hoisted ones (
preferDirectCmds). [4] - If there’s still a collision for the same bin name, it chooses based on:
- whether the bin name matches the package’s own name (
ownNamewins), - otherwise by package name (lexicographic),
- and if it’s the same package, by version (higher wins). [4]
- whether the bin name matches the package’s own name (
- The skipped option is logged (debug) via a “bins-conflict” logger. [4]
- If pnpm knows the project manifest, it prefers bins from direct dependencies over non-direct/hoisted ones (
Yarn
- Yarn Classic (v1) (and Yarn’s
node-moduleslinker behavior) relies on the same underlyingbin-linksbehavior: it can check for conflicting bins that would prevent linking, but that check is primarily relevant to top-level global installs; for local installs, the conflict check is effectively bypassed (same rule:global/topmust be true to enforce). [1], [5] - Additionally, the
bin-linksadvisory history notes that (historically) global bin overwrites were possible, while this behavior was “still allowed in local installations”. [3]
Avoid publishing the same intent bin from every package.
Line 178 adds a public intent binary here, but the PR does the same in multiple TanStack packages. When a consumer installs @tanstack/react-router, they will also have @tanstack/router-core in node_modules, and only one node_modules/.bin/intent shim can be active. In npm and Yarn, the last package linked wins (order-dependent); in pnpm, the binary is resolved based on dependency precedence rules. In all cases, which intent implementation gets invoked is outside your control and may not be the one consumers expect. Consider publishing intent from a single package or namespacing these binaries instead.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/router-core/package.json` around lines 178 - 180, This package
currently exposes a top-level CLI via the "bin" entry ("intent":
"./bin/intent.js"), which conflicts with identical bins published from other
TanStack packages; remove or change this export so consumers don't get an
ambiguous / conflicting node_modules/.bin/intent. Either remove the "bin" entry
from this package.json so only a single chosen package publishes "intent", or
rename/namespace the binary here (e.g., "intent-router-core") and update the
corresponding ./bin/intent.js filename and any references; update whichever
package will remain the authoritative publisher to keep the original "intent"
bin.
packages/router-core/skills/router-core/auth-and-guards/SKILL.md
Outdated
Show resolved
Hide resolved
| ```ts | ||
| // vite.config.ts | ||
| import { defineConfig } from 'vite' | ||
| import react from '@vitejs/plugin-react' | ||
| import { tanstackRouter } from '@tanstack/router-plugin/vite' | ||
| import { routes } from './routes' | ||
|
|
||
| export default defineConfig({ | ||
| plugins: [ | ||
| tanstackRouter({ | ||
| target: 'react', | ||
| virtualRouteConfig: routes, | ||
| }), | ||
| react(), | ||
| ], |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
fd -t f "SKILL.md" packages/virtual-file-routes 2>/dev/null | head -5Repository: TanStack/router
Length of output: 123
🏁 Script executed:
cat -n packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md | head -150Repository: TanStack/router
Length of output: 4823
🏁 Script executed:
cat -n packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md | sed -n '120,220p'Repository: TanStack/router
Length of output: 3131
🏁 Script executed:
rg "target:" packages/virtual-file-routes -A 2 -B 2Repository: TanStack/router
Length of output: 894
🏁 Script executed:
rg "solid\|vue\|angular" packages/virtual-file-routes/skills -iRepository: TanStack/router
Length of output: 41
🏁 Script executed:
fd -t f "\.md$" packages/router-plugin | head -10Repository: TanStack/router
Length of output: 253
🏁 Script executed:
rg "target.*solid\|target.*vue" packages --max-count 5Repository: TanStack/router
Length of output: 41
🏁 Script executed:
cat -n packages/router-plugin/skills/router-plugin/SKILL.md | head -200Repository: TanStack/router
Length of output: 8268
🏁 Script executed:
rg "target.*['\"]" packages/router-plugin -A 1 -B 1 | head -50Repository: TanStack/router
Length of output: 3500
Show framework-agnostic integration example for virtual-file-routes.
The virtual-file-routes library is framework-agnostic, but the integration example (lines 126–141) hardcodes React setup with @vitejs/plugin-react, react(), and target: 'react'. This will mislead users building with Solid or Vue into copying React-specific configuration. Show only the router plugin setup with a placeholder for the target framework.
✏️ Suggested adjustment
// vite.config.ts
import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
import { routes } from './routes'
export default defineConfig({
plugins: [
tanstackRouter({
- target: 'react',
+ target: 'react', // or 'solid', 'vue'
virtualRouteConfig: routes,
}),
- react(),
+ // Add your framework's Vite plugin here
],
})🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md` around
lines 126 - 140, The example in SKILL.md hardcodes React-specific setup; instead
update the vite.config.ts snippet to show only the tanstackRouter plugin
configuration with virtualRouteConfig: routes and a placeholder for the target
(e.g., target: '<framework>') so users know to substitute 'react'/'solid'/'vue';
reference the tanstackRouter call, the virtualRouteConfig option, and the routes
identifier when making this change.
- Fix incorrect createTanstackRouter → createRouter in router-query examples - Fix missing React type imports (ComponentPropsWithoutRef, FormEvent) - Fix hardcoded localhost:3000 in SSR example, use req headers instead - Fix session.update/clear to use await with data payload - Fix start-setup → start-core slug mismatch in domain_map + skill_spec - Make start-client-core skill_tree self-contained (remove react-start refs) - Add framework-agnostic comments to execution-model and middleware skills - Make virtual-file-routes vite example framework-agnostic - Fix solid-router domain_map: Link is primary, createLink for wrappers - Fix vue-router domain_map: scope Ref unwrapping to script, not templates - Fix vue-router SKILL.md: tsx → vue fence language for template snippets - Fix virtual-file-routes domain_map failure mode wording - Fix MD028 blockquote blank lines across 11 files - Fix MD040 missing fence languages across 4 files - Update pnpm-lock.yaml
Bundle Size Benchmarks
Trend sparkline is historical gzip bytes ending with this PR measurement; lower is better. |
There was a problem hiding this comment.
Actionable comments posted: 10
♻️ Duplicate comments (4)
packages/start-client-core/skills/_artifacts/domain_map.yaml (1)
8-17:⚠️ Potential issue | 🟠 MajorMake the package-local domain map describe the package it ships with.
This file lives under
packages/start-client-core, but Lines 9-17 still identify it as@tanstack/react-startwithprimary_framework: 'React'. That conflicts with the sibling package-localskill_tree.yaml, and it makes the published metadata look React-specific even though this package is the framework-agnostic core. Either align thelibraryblock with@tanstack/start-client-core, or move this consolidated React Start descriptor to the repo-level artifact instead.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/skills/_artifacts/domain_map.yaml` around lines 8 - 17, The library metadata in the domain_map.yaml is incorrect for this package: update the library block that currently sets name: '@tanstack/react-start' and primary_framework: 'React' so it accurately describes this package (e.g., name '@tanstack/start-client-core' and a framework-agnostic primary_framework) or remove/move this consolidated React-specific descriptor to the repo-level artifact; edit the library block in domain_map.yaml (the fields name, version if needed, description, and primary_framework) to align with the package-local skill_tree.yaml and the actual package purpose.packages/start-client-core/skills/start-core/server-routes/SKILL.md (1)
24-77:⚠️ Potential issue | 🟠 MajorKeep this core skill framework-agnostic.
Lines 26-27, 45-46, 112-113, and 129-130 hard-code
@tanstack/react-router, and Lines 46-77 add a React-onlyuseStateUI example. Because this file ships frompackages/start-client-core, agents following it for Solid/Vue Start will learn the wrong bindings. Please rewrite these snippets with framework-neutral placeholders or move the binding-specific examples into the framework package skills.Also applies to: 110-154, 198-249
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/skills/start-core/server-routes/SKILL.md` around lines 24 - 77, The file hard-codes React and `@tanstack/react-router` usage (imports of "@tanstack/react-router", createFileRoute usage tied to React, and the HelloComponent using useState) which makes the core skill framework-specific; replace those snippets with framework-neutral placeholders or abstract examples: remove the direct import of "@tanstack/react-router" and instead reference a generic "createFileRoute" or "router-lib" placeholder, replace the React-only HelloComponent and useState example with a neutral client-side example (e.g., describe a fetch POST workflow or show pseudocode for a UI handler) or move the React-specific example into the React framework skill package, and update all occurrences of Route, createFileRoute, HelloComponent, and any React hooks so the core package remains framework-agnostic.packages/start-client-core/skills/start-core/execution-model/SKILL.md (1)
44-154:⚠️ Potential issue | 🟠 MajorThis still teaches React bindings in a framework-neutral skill.
Lines 46, 63, 77, 88, 103, 121, and 147 still hard-code
@tanstack/react-start,@tanstack/react-router, andReact.ReactNode. Agents using the core skill from Solid/Vue Start will copy the React packages/types from here. Keep this skill binding-agnostic and move concrete React snippets intoreact-start.Based on learnings, Separate framework-agnostic core logic from React/Solid bindings.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/start-client-core/skills/start-core/execution-model/SKILL.md` around lines 44 - 154, The SKILL.md contains framework-specific React bindings (imports and types) that make the core skill non-agnostic; replace hard-coded usages of `@tanstack/react-start`, `@tanstack/react-router`, and React.ReactNode in the examples and prose with framework-neutral placeholders (e.g., `@tanstack/`<framework>-start or “your framework’s start package”) and generic types (e.g., “Component children” or “framework-specific node”), and relocate the concrete React examples for createServerFn, createServerOnlyFn, createClientOnlyFn, ClientOnly, useHydrated, and createIsomorphicFn into the react-start/react-router package docs so the core SKILL.md only shows framework-agnostic snippets and references where framework-specific implementations live.packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md (1)
143-149:⚠️ Potential issue | 🟡 MinorKeep the file-path example framework-agnostic too.
Line 147 still hardcodes
target: 'react'. Since this skill is framework-agnostic, that alternate snippet can still steer Solid/Vue agents toward an invalid plugin target.✏️ Suggested adjustment
tanstackRouter({ - target: 'react', + target: '<framework>', // 'react' | 'solid' | 'vue' virtualRouteConfig: './routes.ts', })Verify by comparing the two snippets in this file and scanning other
virtualRouteConfigexamples:#!/bin/bash set -euo pipefail echo "Generic integration example in this skill:" sed -n '126,140p' packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md echo echo "File-path variant under review:" sed -n '143,149p' packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md echo echo "Other tanstackRouter + virtualRouteConfig examples in docs/skills:" rg -n -C2 "virtualRouteConfig|target:\s*'(react|solid|vue)'|target:\s*'<framework>'" \ packages/virtual-file-routes \ packages/router-plugin \ docs/router \ -g '*.md'Expected result: the file-path variant should follow the same framework-agnostic pattern as the main example instead of leaving a React-only default.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md` around lines 143 - 149, The example snippet hardcodes target: 'react' which breaks the skill's framework-agnostic intent; update the file-path variant that uses tanstackRouter and virtualRouteConfig ('./routes.ts') to either remove the hardcoded target or replace it with a neutral placeholder like target: '<framework>' so it matches the generic example elsewhere in SKILL.md and avoids steering Solid/Vue users to an invalid plugin target.
🧹 Nitpick comments (1)
packages/vue-router/skills/vue-router/SKILL.md (1)
66-90: Consider clarifying JSX setup or using SFC examples.The route component examples use JSX syntax (fragments
<>, function components returning JSX), but the Vite config only shows@vitejs/plugin-vue. Vue JSX requires@vitejs/plugin-vue-jsx. Most Vue developers use SFC templates, so this could cause confusion.Consider either:
- Adding a note that JSX requires
@vitejs/plugin-vue-jsx- Using Vue SFC (
.vuefiles) for these examples to match typical Vue patterns🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/vue-router/skills/vue-router/SKILL.md` around lines 66 - 90, The example uses JSX (RootLayout with fragments and Link/Outlet JSX) but the docs/config only mention `@vitejs/plugin-vue`; update the example or note: either add a clarifying comment that using JSX/TSX requires installing and enabling `@vitejs/plugin-vue-jsx` in Vite, or replace the snippet with an equivalent Single File Component (.vue) example (e.g., export default component using <template> with <router-link> and <router-view>), and reference the createRootRoute, Route, and RootLayout symbols so readers can find and update the code consistently.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/react-router/skills/compositions/router-query/SKILL.md`:
- Around line 340-358: Rename the example functions to avoid shadowing the
imported createRouter: change both example function declarations from
createRouter() to createAppRouter() (and update any internal references) so they
call the imported createRouter from `@tanstack/react-router` instead of recursing;
ensure both the "WRONG" and "CORRECT" snippets use createAppRouter and keep the
context/queryClient logic identical to the shown examples.
In `@packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md`:
- Around line 34-39: The installation instructions wrongly mark
`@tanstack/react-router-devtools` as a devDependency even though the guide
imports/uses TanStackRouterDevtools at runtime; update the commands so
`@tanstack/react-router-devtools` is installed as a regular dependency (move it
from the -D line into the main npm install command) and keep only
`@tanstack/router-plugin` as a devDependency, ensuring the runtime import
(TanStackRouterDevtools) is available in production builds.
- Around line 23-24: Update the CRITICAL migration note and the cleanup/search
instructions to include react-router-dom alongside react-router: modify the
warning sentence that currently references only `react-router` (the CRITICAL
note) to mention both `react-router` and `react-router-dom`, and add
corresponding grep/search commands for `react-router-dom` where the current grep
commands for `react-router` appear (the grep lines referenced near the end of
the document) so stale `react-router-dom` imports are detected and removed
during the uninstall/cleanup step.
In `@packages/react-router/skills/react-router/SKILL.md`:
- Around line 451-472: The example incorrectly recreates the router with
changing auth (useMemo) instead of creating the router once with a placeholder
context and injecting the live auth via RouterProvider; update the code so
createRouter({ routeTree, context: { auth: undefined! } }) is called once (e.g.,
at module scope or top-level of App), remove the useMemo recreation in App,
create an InnerApp that calls useAuth(), and render <RouterProvider
router={router} context={{ auth }} /> inside that InnerApp, wrapping InnerApp
with your AuthProvider in App.
In `@packages/router-core/skills/router-core/type-safety/SKILL.md`:
- Around line 252-266: The code fence redeclares `const props` and places an
`import` after statements, producing invalid TypeScript; split into separate,
self-contained snippets so each example compiles independently: (1) show the
wrong example with `import type { LinkProps }` at the top and `const props:
LinkProps = { to: '/posts' }`, (2) show the correct `as const satisfies
LinkProps` variant with its own import if needed, and (3) show the narrowed
generic example with `import type { RegisteredRouter }` (and `LinkProps`) at the
top and `const props = { to: '/posts' } as const satisfies
LinkProps<RegisteredRouter, string, '/posts'>`; ensure no duplicate `const
props` in the same snippet and place imports before usage so each snippet is
independently valid.
- Around line 107-115: The route example throws redirect(...) in beforeLoad but
never imports redirect, making the snippet invalid; update the top import to
include redirect alongside createFileRoute (e.g., import { createFileRoute,
redirect } from '@tanstack/react-router') so Route's beforeLoad can call
redirect; ensure the symbol names referenced are createFileRoute, redirect, and
beforeLoad in the Route definition.
In `@packages/start-server-core/bin/intent.js`:
- Around line 8-18: The catch block that currently treats any
ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND as "@tanstack/intent is not installed"
is too broad; update the handler to verify the missing-module message actually
references "@tanstack/intent" (e.g., inspect e.message or e.requireStack for
"Cannot find module '@tanstack/intent'" or the module name string) before
printing the install prompt, otherwise rethrow or print the original error and
exit; modify the catch around the dynamic import (the try/catch handling e) to
check e?.code and e?.message.includes('@tanstack/intent') (or similar) and only
show the installation/helpful console.error lines and process.exit(1) when the
missing module is indeed `@tanstack/intent`, otherwise surface the real error.
In `@packages/start-server-core/skills/start-server-core/SKILL.md`:
- Around line 20-22: The two consecutive blockquote paragraphs in SKILL.md (the
lines starting with "**CRITICAL**: These utilities are SERVER-ONLY..." and
"**CRITICAL**: Types are FULLY INFERRED...") currently have an extra blank line
that trips markdownlint MD028; remove the empty line between those blockquote
lines (or merge them into a single contiguous blockquote) so there is no blank
line inside the blockquote, preserving the existing wording and punctuation.
- Around line 53-64: Several markdown code blocks in SKILL.md call
createServerFn but omit its import; update every snippet that invokes
createServerFn (the blocks showing serverFn =
createServerFn({...}).handler(...)) to include the missing import statement: add
import { createServerFn } from '@tanstack/react-start' at the top of each of
those code fences so each example is self-contained and copy-pasteable.
In `@packages/vue-router/skills/vue-router/SKILL.md`:
- Around line 304-315: The Vue SFC example includes JavaScript-style comments
outside a <script> block (the "// SFC template... MyRoute.component.vue" line)
which will break if copied into an .vue file; replace that leading // comment
with an HTML comment (e.g., <!-- MyRoute.component.vue - SFC template -->) or
move the explanatory text above the code block in markdown, leaving the
<template> and <script setup> (and the useLoaderData/data usage) intact.
---
Duplicate comments:
In `@packages/start-client-core/skills/_artifacts/domain_map.yaml`:
- Around line 8-17: The library metadata in the domain_map.yaml is incorrect for
this package: update the library block that currently sets name:
'@tanstack/react-start' and primary_framework: 'React' so it accurately
describes this package (e.g., name '@tanstack/start-client-core' and a
framework-agnostic primary_framework) or remove/move this consolidated
React-specific descriptor to the repo-level artifact; edit the library block in
domain_map.yaml (the fields name, version if needed, description, and
primary_framework) to align with the package-local skill_tree.yaml and the
actual package purpose.
In `@packages/start-client-core/skills/start-core/execution-model/SKILL.md`:
- Around line 44-154: The SKILL.md contains framework-specific React bindings
(imports and types) that make the core skill non-agnostic; replace hard-coded
usages of `@tanstack/react-start`, `@tanstack/react-router`, and React.ReactNode in
the examples and prose with framework-neutral placeholders (e.g.,
`@tanstack/`<framework>-start or “your framework’s start package”) and generic
types (e.g., “Component children” or “framework-specific node”), and relocate
the concrete React examples for createServerFn, createServerOnlyFn,
createClientOnlyFn, ClientOnly, useHydrated, and createIsomorphicFn into the
react-start/react-router package docs so the core SKILL.md only shows
framework-agnostic snippets and references where framework-specific
implementations live.
In `@packages/start-client-core/skills/start-core/server-routes/SKILL.md`:
- Around line 24-77: The file hard-codes React and `@tanstack/react-router` usage
(imports of "@tanstack/react-router", createFileRoute usage tied to React, and
the HelloComponent using useState) which makes the core skill
framework-specific; replace those snippets with framework-neutral placeholders
or abstract examples: remove the direct import of "@tanstack/react-router" and
instead reference a generic "createFileRoute" or "router-lib" placeholder,
replace the React-only HelloComponent and useState example with a neutral
client-side example (e.g., describe a fetch POST workflow or show pseudocode for
a UI handler) or move the React-specific example into the React framework skill
package, and update all occurrences of Route, createFileRoute, HelloComponent,
and any React hooks so the core package remains framework-agnostic.
In `@packages/virtual-file-routes/skills/virtual-file-routes/SKILL.md`:
- Around line 143-149: The example snippet hardcodes target: 'react' which
breaks the skill's framework-agnostic intent; update the file-path variant that
uses tanstackRouter and virtualRouteConfig ('./routes.ts') to either remove the
hardcoded target or replace it with a neutral placeholder like target:
'<framework>' so it matches the generic example elsewhere in SKILL.md and avoids
steering Solid/Vue users to an invalid plugin target.
---
Nitpick comments:
In `@packages/vue-router/skills/vue-router/SKILL.md`:
- Around line 66-90: The example uses JSX (RootLayout with fragments and
Link/Outlet JSX) but the docs/config only mention `@vitejs/plugin-vue`; update the
example or note: either add a clarifying comment that using JSX/TSX requires
installing and enabling `@vitejs/plugin-vue-jsx` in Vite, or replace the snippet
with an equivalent Single File Component (.vue) example (e.g., export default
component using <template> with <router-link> and <router-view>), and reference
the createRootRoute, Route, and RootLayout symbols so readers can find and
update the code consistently.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4b8d9909-3c64-4d2e-86ed-62f9fe37b901
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (33)
packages/react-router/bin/intent.jspackages/react-router/skills/compositions/router-query/SKILL.mdpackages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.mdpackages/react-router/skills/react-router/SKILL.mdpackages/react-start/bin/intent.jspackages/router-core/skills/router-core/auth-and-guards/SKILL.mdpackages/router-core/skills/router-core/not-found-and-errors/SKILL.mdpackages/router-core/skills/router-core/search-params/SKILL.mdpackages/router-core/skills/router-core/ssr/SKILL.mdpackages/router-core/skills/router-core/type-safety/SKILL.mdpackages/router-plugin/bin/intent.jspackages/solid-router/bin/intent.jspackages/solid-router/skills/_artifacts/domain_map.yamlpackages/solid-router/skills/solid-router/SKILL.mdpackages/solid-start/bin/intent.jspackages/start-client-core/bin/intent.jspackages/start-client-core/skills/_artifacts/domain_map.yamlpackages/start-client-core/skills/_artifacts/skill_spec.mdpackages/start-client-core/skills/_artifacts/skill_tree.yamlpackages/start-client-core/skills/start-core/SKILL.mdpackages/start-client-core/skills/start-core/execution-model/SKILL.mdpackages/start-client-core/skills/start-core/middleware/SKILL.mdpackages/start-client-core/skills/start-core/server-functions/SKILL.mdpackages/start-client-core/skills/start-core/server-routes/SKILL.mdpackages/start-server-core/bin/intent.jspackages/start-server-core/skills/start-server-core/SKILL.mdpackages/virtual-file-routes/bin/intent.jspackages/virtual-file-routes/skills/_artifacts/domain_map.yamlpackages/virtual-file-routes/skills/virtual-file-routes/SKILL.mdpackages/vue-router/bin/intent.jspackages/vue-router/skills/_artifacts/domain_map.yamlpackages/vue-router/skills/vue-router/SKILL.mdpackages/vue-start/bin/intent.js
✅ Files skipped from review due to trivial changes (2)
- packages/router-core/skills/router-core/not-found-and-errors/SKILL.md
- packages/router-core/skills/router-core/search-params/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (13)
- packages/start-client-core/skills/_artifacts/skill_spec.md
- packages/react-router/bin/intent.js
- packages/start-client-core/bin/intent.js
- packages/vue-start/bin/intent.js
- packages/start-client-core/skills/start-core/SKILL.md
- packages/router-core/skills/router-core/ssr/SKILL.md
- packages/vue-router/skills/_artifacts/domain_map.yaml
- packages/start-client-core/skills/start-core/server-functions/SKILL.md
- packages/react-start/bin/intent.js
- packages/start-client-core/skills/start-core/middleware/SKILL.md
- packages/virtual-file-routes/bin/intent.js
- packages/solid-start/bin/intent.js
- packages/solid-router/bin/intent.js
| ```tsx | ||
| // WRONG — shared across SSR requests | ||
| const queryClient = new QueryClient() | ||
| export function createRouter() { | ||
| return createRouter({ | ||
| routeTree, | ||
| context: { queryClient }, | ||
| }) | ||
| } | ||
|
|
||
| // CORRECT — new QueryClient per createRouter call | ||
| export function createRouter() { | ||
| const queryClient = new QueryClient() | ||
| return createRouter({ | ||
| routeTree, | ||
| context: { queryClient }, | ||
| }) | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Fix function naming collision in common mistake example.
Both the "WRONG" and "CORRECT" examples define a function named createRouter that calls createRouter internally. This creates a naming collision where the function name shadows the imported createRouter from @tanstack/react-router, leading to potential infinite recursion and confusion.
The function should be named createAppRouter to match the naming convention used consistently in earlier SSR examples (lines 93, 129, 164).
🐛 Proposed fix
// WRONG — shared across SSR requests
const queryClient = new QueryClient()
-export function createRouter() {
+export function createAppRouter() {
return createRouter({
routeTree,
context: { queryClient },
})
}
// CORRECT — new QueryClient per createRouter call
-export function createRouter() {
+export function createAppRouter() {
const queryClient = new QueryClient()
return createRouter({
routeTree,
context: { queryClient },
})
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/react-router/skills/compositions/router-query/SKILL.md` around lines
340 - 358, Rename the example functions to avoid shadowing the imported
createRouter: change both example function declarations from createRouter() to
createAppRouter() (and update any internal references) so they call the imported
createRouter from `@tanstack/react-router` instead of recursing; ensure both the
"WRONG" and "CORRECT" snippets use createAppRouter and keep the
context/queryClient logic identical to the shown examples.
| > **CRITICAL**: If your UI is blank after migration, open the console. Errors like "cannot use useNavigate outside of context" mean React Router imports remain alongside TanStack Router imports. Uninstall `react-router` to surface them as TypeScript errors. | ||
| > **CRITICAL**: TanStack Router uses `to` + `params` for navigation, NOT template literal paths. Never interpolate params into the `to` string. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -name "SKILL.md" | grep -i "migrate-from-react-router"Repository: TanStack/router
Length of output: 134
🏁 Script executed:
# Get the file size first to determine how to read it
wc -l packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.mdRepository: TanStack/router
Length of output: 136
🏁 Script executed:
# Read the specific lines mentioned in the review
sed -n '20,30p' packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.mdRepository: TanStack/router
Length of output: 635
🏁 Script executed:
# Also check lines 381-392
sed -n '375,395p' packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.mdRepository: TanStack/router
Length of output: 411
🌐 Web query:
React Router v7 react-router-dom compatibility re-export
💡 Result:
In React Router v7, react-router-dom is kept only as a compatibility/migration package: it is still published and re-exports everything from react-router to ease upgrades from v6, but the recommended direction is to import from react-router going forward. [1]
If you’re coming from Remix: Remix notes that React Router v7 is released, and Remix itself re-exports the React Router DOM APIs, so you typically don’t need to install React Router separately in a Remix app. [2]
Implication: for v7 apps, prefer import { ... } from "react-router"; keep react-router-dom only to avoid churn while migrating older code that imports from "react-router-dom". [1]
Sources:
[1] React Router changelog (migration note about react-router-dom re-exporting react-router) (reactrouter.com)
[2] Remix docs discussion of React Router v7 / re-exports (v2.remix.run)
Citations:
- 1: https://reactrouter.com/start/start/changelog?utm_source=openai
- 2: https://v2.remix.run/docs/discussion/react-router/?utm_source=openai
Add react-router-dom to cleanup instructions and grep searches.
React Router v7 re-exports react-router-dom from react-router for migration compatibility. The CRITICAL message at line 23 and the grep commands at lines 389–390 should include react-router-dom alongside react-router. The npm uninstall command already covers both, but the search steps miss react-router-dom imports, leaving stale ones undetected.
Update line 23 to mention both packages, and add grep commands for react-router-dom:
Suggested fix
-> **CRITICAL**: If your UI is blank after migration, open the console. Errors like "cannot use useNavigate outside of context" mean React Router imports remain alongside TanStack Router imports. Uninstall `react-router` to surface them as TypeScript errors.
+> **CRITICAL**: If your UI is blank after migration, open the console. Errors like "cannot use useNavigate outside of context" mean React Router imports remain alongside TanStack Router imports. Uninstall `react-router` and `react-router-dom` to surface them as TypeScript errors.
grep -r "from 'react-router" src/
grep -r 'from "react-router' src/
+grep -r "from 'react-router-dom" src/
+grep -r 'from "react-router-dom' src/🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md`
around lines 23 - 24, Update the CRITICAL migration note and the cleanup/search
instructions to include react-router-dom alongside react-router: modify the
warning sentence that currently references only `react-router` (the CRITICAL
note) to mention both `react-router` and `react-router-dom`, and add
corresponding grep/search commands for `react-router-dom` where the current grep
commands for `react-router` appear (the grep lines referenced near the end of
the document) so stale `react-router-dom` imports are detected and removed
during the uninstall/cleanup step.
| - [ ] **Install TanStack Router alongside React Router temporarily** | ||
|
|
||
| ```bash | ||
| npm install @tanstack/react-router | ||
| npm install -D @tanstack/router-plugin @tanstack/react-router-devtools | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check if the file exists and read the relevant sections
fd "SKILL.md" packages/react-router/skills/lifecycle/migrate-from-react-router/Repository: TanStack/router
Length of output: 132
🏁 Script executed:
# Read the file to see the context around the installation command and devtools usage
cat -n packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md | head -100Repository: TanStack/router
Length of output: 3557
🏁 Script executed:
# Check if there are any other installation examples in the codebase
rg "@tanstack/react-router-devtools" -A 3 -B 3 -iRepository: TanStack/router
Length of output: 50374
🏁 Script executed:
# Look for package.json files in the repo to see how devtools is installed elsewhere
fd "package.json" -x grep -l "@tanstack/react-router-devtools" {} \;Repository: TanStack/router
Length of output: 4855
🏁 Script executed:
# Check the other SKILL.md file for the same pattern
grep -n "@tanstack/react-router-devtools" packages/react-router/skills/react-router/SKILL.mdRepository: TanStack/router
Length of output: 208
🏁 Script executed:
# Verify the package structure - check if devtools is truly a runtime dependency
cat packages/react-router-devtools/package.json | head -20Repository: TanStack/router
Length of output: 600
Install @tanstack/react-router-devtools as a runtime dependency, not -D.
The guide imports and renders TanStackRouterDevtools in application code, but documents it as a devDependency. Teams running npm install --production in CI will have production builds fail with missing imports. Move @tanstack/react-router-devtools to the main install command and keep only @tanstack/router-plugin as -D.
Suggested fix
npm install `@tanstack/react-router`
-npm install -D `@tanstack/router-plugin` `@tanstack/react-router-devtools`
+npm install `@tanstack/react-router-devtools`
+npm install -D `@tanstack/router-plugin`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - [ ] **Install TanStack Router alongside React Router temporarily** | |
| ```bash | |
| npm install @tanstack/react-router | |
| npm install -D @tanstack/router-plugin @tanstack/react-router-devtools | |
| ``` | |
| - [ ] **Install TanStack Router alongside React Router temporarily** | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/react-router/skills/lifecycle/migrate-from-react-router/SKILL.md`
around lines 34 - 39, The installation instructions wrongly mark
`@tanstack/react-router-devtools` as a devDependency even though the guide
imports/uses TanStackRouterDevtools at runtime; update the commands so
`@tanstack/react-router-devtools` is installed as a regular dependency (move it
from the -D line into the main npm install command) and keep only
`@tanstack/router-plugin` as a devDependency, ensuring the runtime import
(TanStackRouterDevtools) is available in production builds.
| ### 2. HIGH: Wrapping RouterProvider inside an auth provider incorrectly | ||
|
|
||
| If you use `createRootRouteWithContext<{ auth: AuthState }>()`, the auth state must be available when the router is created — not injected after. | ||
|
|
||
| ```tsx | ||
| // WRONG — router created before auth is available | ||
| const router = createRouter({ routeTree, context: {} }) | ||
|
|
||
| function App() { | ||
| const auth = useAuth() // too late | ||
| return <RouterProvider router={router} /> | ||
| } | ||
|
|
||
| // CORRECT — provide context at creation time | ||
| function App() { | ||
| const auth = useAuth() | ||
| const router = useMemo( | ||
| () => createRouter({ routeTree, context: { auth } }), | ||
| [auth], | ||
| ) | ||
| return <RouterProvider router={router} /> | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
TanStack Router v1 React authenticated routes RouterProvider context auth createRootRouteWithContext
💡 Result:
To do authenticated routes in TanStack Router v1 (React) using router context, you:
- Type the router context at the root with
createRootRouteWithContext - Provide a “placeholder” context when creating the router (so TS knows the shape)
- Inject the real auth value at runtime via
<RouterProvider context={...} /> - Gate protected routes with
beforeLoadandthrow redirect(...) - Invalidate the router when auth changes so
beforeLoad/loaders re-run
1) Root route with typed context
// routes/__root.tsx
import { createRootRouteWithContext, Outlet } from '@tanstack/react-router'
export type RouterContext = {
auth: {
isAuthenticated: boolean
user?: { id: string } | null
}
}
export const Route = createRootRouteWithContext<RouterContext>()({
component: () => <Outlet />,
})This is the canonical pattern for typed router context. [1]
2) Create the router with a placeholder context
// router.ts
import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
export const router = createRouter({
routeTree,
context: {
auth: undefined!, // filled in by <RouterProvider />
},
})TanStack’s docs show providing an initial/placeholder context in createRouter. [1]
3) Inject auth via RouterProvider (and invalidate on auth change)
// main.tsx / AppShell.tsx
import { RouterProvider, useRouter } from '@tanstack/react-router'
import { router } from './router'
function useAuth() {
// your auth hook/store
return { isAuthenticated: false, user: null }
}
function App() {
const r = useRouter()
const auth = useAuth()
// when auth changes, invalidate so route guards/loaders see fresh auth
// (pattern shown in the docs)
// useEffect(() => { r.invalidate() }, [auth.isAuthenticated, auth.user?.id])
// (or call r.invalidate() inside your auth subscription callback)
return <RouterProvider router={router} context={{ auth }} />
}TanStack Router docs explicitly recommend router.invalidate() when external state (like auth) changes. [1]
4) Protect a route (or layout “group”) with beforeLoad + redirect
// routes/_authenticated.tsx (file-based layout route) OR any route definition
import { createFileRoute, redirect, Outlet } from '@tanstack/react-router'
export const Route = createFileRoute('/_authenticated')({
beforeLoad: ({ context, location }) => {
if (!context.auth.isAuthenticated) {
throw redirect({
to: '/login',
search: { redirect: location.href },
})
}
},
component: () => <Outlet />,
})beforeLoadruns before the route loads and can block/redirect navigation. [2]redirect()can be thrown frombeforeLoad/loaderto navigate away. [3]
Key gotcha: don’t rely on a React context/hook inside beforeLoad—instead, pass the hook result through the router context (because hooks can’t run in beforeLoad). [1]
Sources:
[1] TanStack Router Docs – Router Context (typed context, RouterProvider injection, invalidation) https://tanstack.com/router/latest/docs/guide/router-context
[2] TanStack Router Docs – Data Loading (role of beforeLoad and context merging) https://tanstack.dev/router/latest/docs/framework/react/guide/data-loading
[3] TanStack Router Docs – redirect function (throw/return redirect from beforeLoad/loader) https://zh-hans.tanstack.dev/router/latest/docs/framework/react/api/router/redirectFunction
Use RouterProvider's context prop for auth instead of recreating the router.
TanStack Router's canonical React pattern creates the router once with a placeholder context ({ auth: undefined! }), then injects the live auth value through <RouterProvider context={{ auth }} />. The "CORRECT" example here recreates the router in useMemo whenever auth changes, which contradicts the official API and will steer agents toward unnecessary complexity.
Suggested fix
-If you use `createRootRouteWithContext<{ auth: AuthState }>()`, the auth state must be available when the router is created — not injected after.
+If you use `createRootRouteWithContext<{ auth: AuthState }>()`, keep the router instance stable and pass the current auth state through `RouterProvider`'s `context` prop.
```tsx
-// WRONG — router created before auth is available
-const router = createRouter({ routeTree, context: {} })
+// WRONG — auth is never passed into router context
+const router = createRouter({
+ routeTree,
+ context: { auth: undefined! },
+})
function App() {
- const auth = useAuth() // too late
return <RouterProvider router={router} />
}
-// CORRECT — provide context at creation time
-function App() {
+// CORRECT — inject auth through RouterProvider
+const router = createRouter({
+ routeTree,
+ context: { auth: undefined! },
+})
+
+function InnerApp() {
const auth = useAuth()
- const router = useMemo(
- () => createRouter({ routeTree, context: { auth } }),
- [auth],
- )
- return <RouterProvider router={router} />
+ return <RouterProvider router={router} context={{ auth }} />
+}
+
+function App() {
+ return (
+ <AuthProvider>
+ <InnerApp />
+ </AuthProvider>
+ )
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/react-router/skills/react-router/SKILL.md` around lines 451 - 472,
The example incorrectly recreates the router with changing auth (useMemo)
instead of creating the router once with a placeholder context and injecting the
live auth via RouterProvider; update the code so createRouter({ routeTree,
context: { auth: undefined! } }) is called once (e.g., at module scope or
top-level of App), remove the useMemo recreation in App, create an InnerApp that
calls useAuth(), and render <RouterProvider router={router} context={{ auth }}
/> inside that InnerApp, wrapping InnerApp with your AuthProvider in App.
| // src/routes/dashboard.tsx | ||
| import { createFileRoute } from '@tanstack/react-router' | ||
|
|
||
| export const Route = createFileRoute('/dashboard')({ | ||
| beforeLoad: ({ context }) => { | ||
| // context.auth is already typed as { userId: string; role: 'admin' | 'user' } | null | ||
| // NO annotation needed | ||
| if (!context.auth) throw redirect({ to: '/login' }) | ||
| return { user: context.auth } |
There was a problem hiding this comment.
Import redirect in this route example.
beforeLoad throws redirect(...), but the snippet only imports createFileRoute. As written, this example is incomplete for copy/paste and teaches an invalid route module.
🩹 Proposed fix
- import { createFileRoute } from '@tanstack/react-router'
+ import { createFileRoute, redirect } from '@tanstack/react-router'📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // src/routes/dashboard.tsx | |
| import { createFileRoute } from '@tanstack/react-router' | |
| export const Route = createFileRoute('/dashboard')({ | |
| beforeLoad: ({ context }) => { | |
| // context.auth is already typed as { userId: string; role: 'admin' | 'user' } | null | |
| // NO annotation needed | |
| if (!context.auth) throw redirect({ to: '/login' }) | |
| return { user: context.auth } | |
| // src/routes/dashboard.tsx | |
| import { createFileRoute, redirect } from '@tanstack/react-router' | |
| export const Route = createFileRoute('/dashboard')({ | |
| beforeLoad: ({ context }) => { | |
| // context.auth is already typed as { userId: string; role: 'admin' | 'user' } | null | |
| // NO annotation needed | |
| if (!context.auth) throw redirect({ to: '/login' }) | |
| return { user: context.auth } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/router-core/skills/router-core/type-safety/SKILL.md` around lines
107 - 115, The route example throws redirect(...) in beforeLoad but never
imports redirect, making the snippet invalid; update the top import to include
redirect alongside createFileRoute (e.g., import { createFileRoute, redirect }
from '@tanstack/react-router') so Route's beforeLoad can call redirect; ensure
the symbol names referenced are createFileRoute, redirect, and beforeLoad in the
Route definition.
| ```tsx | ||
| import type { LinkProps } from '@tanstack/react-router' | ||
|
|
||
| // WRONG — LinkProps is a massive union, extremely slow TS check | ||
| const props: LinkProps = { to: '/posts' } | ||
|
|
||
| // CORRECT — infer a precise type, validate against LinkProps | ||
| const props = { to: '/posts' } as const satisfies LinkProps | ||
|
|
||
| // EVEN BETTER — narrow LinkProps with generic params | ||
| import type { RegisteredRouter } from '@tanstack/react-router' | ||
| const props = { | ||
| to: '/posts', | ||
| } as const satisfies LinkProps<RegisteredRouter, string, '/posts'> | ||
| ``` |
There was a problem hiding this comment.
Split the LinkProps variants into separate snippets or make each variant self-contained.
This fence is not valid TypeScript as written: it redeclares const props multiple times and adds an import after statements on Line 262. For an AI-skill doc, that makes the "better" pattern harder to extract correctly.
🩹 Proposed fix
import type { LinkProps } from '@tanstack/react-router'
+import type { RegisteredRouter } from '@tanstack/react-router'
// WRONG — LinkProps is a massive union, extremely slow TS check
-const props: LinkProps = { to: '/posts' }
+const wrongProps: LinkProps = { to: '/posts' }
// CORRECT — infer a precise type, validate against LinkProps
-const props = { to: '/posts' } as const satisfies LinkProps
+const goodProps = { to: '/posts' } as const satisfies LinkProps
// EVEN BETTER — narrow LinkProps with generic params
-import type { RegisteredRouter } from '@tanstack/react-router'
-const props = {
+const narrowedProps = {
to: '/posts',
} as const satisfies LinkProps<RegisteredRouter, string, '/posts'>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/router-core/skills/router-core/type-safety/SKILL.md` around lines
252 - 266, The code fence redeclares `const props` and places an `import` after
statements, producing invalid TypeScript; split into separate, self-contained
snippets so each example compiles independently: (1) show the wrong example with
`import type { LinkProps }` at the top and `const props: LinkProps = { to:
'/posts' }`, (2) show the correct `as const satisfies LinkProps` variant with
its own import if needed, and (3) show the narrowed generic example with `import
type { RegisteredRouter }` (and `LinkProps`) at the top and `const props = { to:
'/posts' } as const satisfies LinkProps<RegisteredRouter, string, '/posts'>`;
ensure no duplicate `const props` in the same snippet and place imports before
usage so each snippet is independently valid.
| } catch (e) { | ||
| if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') { | ||
| console.error('@tanstack/intent is not installed.') | ||
| console.error('') | ||
| console.error('Install it as a dev dependency:') | ||
| console.error(' npm add -D @tanstack/intent') | ||
| console.error('') | ||
| console.error('Or run directly:') | ||
| console.error(' npx @tanstack/intent@latest list') | ||
| process.exit(1) | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n packages/start-server-core/bin/intent.jsRepository: TanStack/router
Length of output: 906
🏁 Script executed:
# Search for similar error handling patterns in the codebase
rg -t js 'ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND' --context 3Repository: TanStack/router
Length of output: 5999
Check error messages to distinguish missing @tanstack/intent from its transitive failures.
The catch block treats all ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND errors as "@tanstack/intent is not installed", but this masks failures in @tanstack/intent's own dependencies. When @tanstack/intent/intent-library exists but one of its imports is missing, users see the wrong remediation. Verify that the error message references the target module before showing the install prompt.
🛠️ Suggested fix
} catch (e) {
- if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') {
+ const isModuleNotFound =
+ e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND'
+ const missingIntentLibrary =
+ typeof e?.message === 'string' &&
+ e.message.includes('@tanstack/intent/intent-library')
+
+ if (isModuleNotFound && missingIntentLibrary) {
console.error('@tanstack/intent is not installed.')
console.error('')
console.error('Install it as a dev dependency:')📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| } catch (e) { | |
| if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') { | |
| console.error('@tanstack/intent is not installed.') | |
| console.error('') | |
| console.error('Install it as a dev dependency:') | |
| console.error(' npm add -D @tanstack/intent') | |
| console.error('') | |
| console.error('Or run directly:') | |
| console.error(' npx @tanstack/intent@latest list') | |
| process.exit(1) | |
| } | |
| } catch (e) { | |
| const isModuleNotFound = | |
| e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND' | |
| const missingIntentLibrary = | |
| typeof e?.message === 'string' && | |
| e.message.includes('@tanstack/intent/intent-library') | |
| if (isModuleNotFound && missingIntentLibrary) { | |
| console.error('@tanstack/intent is not installed.') | |
| console.error('') | |
| console.error('Install it as a dev dependency:') | |
| console.error(' npm add -D `@tanstack/intent`') | |
| console.error('') | |
| console.error('Or run directly:') | |
| console.error(' npx `@tanstack/intent`@latest list') | |
| process.exit(1) | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/start-server-core/bin/intent.js` around lines 8 - 18, The catch
block that currently treats any ERR_MODULE_NOT_FOUND / MODULE_NOT_FOUND as
"@tanstack/intent is not installed" is too broad; update the handler to verify
the missing-module message actually references "@tanstack/intent" (e.g., inspect
e.message or e.requireStack for "Cannot find module '@tanstack/intent'" or the
module name string) before printing the install prompt, otherwise rethrow or
print the original error and exit; modify the catch around the dynamic import
(the try/catch handling e) to check e?.code and
e?.message.includes('@tanstack/intent') (or similar) and only show the
installation/helpful console.error lines and process.exit(1) when the missing
module is indeed `@tanstack/intent`, otherwise surface the real error.
| > **CRITICAL**: These utilities are SERVER-ONLY. Import them from `@tanstack/<framework>-start/server`, not from the main entry point. They throw if called outside a server request context. | ||
|
|
||
| > **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values. |
There was a problem hiding this comment.
Fix the blockquote blank line here.
Line 21 still trips markdownlint MD028, so this new skill file will fail lint as-is.
🧹 Suggested fix
> **CRITICAL**: These utilities are SERVER-ONLY. Import them from `@tanstack/<framework>-start/server`, not from the main entry point. They throw if called outside a server request context.
-
+>
> **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| > **CRITICAL**: These utilities are SERVER-ONLY. Import them from `@tanstack/<framework>-start/server`, not from the main entry point. They throw if called outside a server request context. | |
| > **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values. | |
| > **CRITICAL**: These utilities are SERVER-ONLY. Import them from `@tanstack/<framework>-start/server`, not from the main entry point. They throw if called outside a server request context. | |
| > | |
| > **CRITICAL**: Types are FULLY INFERRED. Never cast, never annotate inferred values. |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 21-21: Blank line inside blockquote
(MD028, no-blanks-blockquote)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/start-server-core/skills/start-server-core/SKILL.md` around lines 20
- 22, The two consecutive blockquote paragraphs in SKILL.md (the lines starting
with "**CRITICAL**: These utilities are SERVER-ONLY..." and "**CRITICAL**: Types
are FULLY INFERRED...") currently have an extra blank line that trips
markdownlint MD028; remove the empty line between those blockquote lines (or
merge them into a single contiguous blockquote) so there is no blank line inside
the blockquote, preserving the existing wording and punctuation.
| ```ts | ||
| import { | ||
| getRequest, | ||
| getRequestHeaders, | ||
| getRequestHeader, | ||
| getRequestIP, | ||
| getRequestHost, | ||
| getRequestUrl, | ||
| getRequestProtocol, | ||
| } from '@tanstack/react-start/server' | ||
|
|
||
| const serverFn = createServerFn({ method: 'GET' }).handler(async () => { |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Locate the skill file
find . -name "SKILL.md" -path "*/start-server-core/skills/*" 2>/dev/null | head -20Repository: TanStack/router
Length of output: 121
🏁 Script executed:
# If found, check the file size and examine the relevant sections
if [ -f "packages/start-server-core/skills/start-server-core/SKILL.md" ]; then
echo "=== File found ==="
wc -l "packages/start-server-core/skills/start-server-core/SKILL.md"
echo ""
echo "=== Lines 50-70 ==="
sed -n '50,70p' "packages/start-server-core/skills/start-server-core/SKILL.md"
echo ""
echo "=== Lines 75-95 ==="
sed -n '75,95p' "packages/start-server-core/skills/start-server-core/SKILL.md"
echo ""
echo "=== Lines 100-115 ==="
sed -n '100,115p' "packages/start-server-core/skills/start-server-core/SKILL.md"
echo ""
echo "=== Lines 140-155 ==="
sed -n '140,155p' "packages/start-server-core/skills/start-server-core/SKILL.md"
echo ""
echo "=== Lines 155-165 ==="
sed -n '155,165p' "packages/start-server-core/skills/start-server-core/SKILL.md"
echo ""
echo "=== Lines 185-195 ==="
sed -n '185,195p' "packages/start-server-core/skills/start-server-core/SKILL.md"
fiRepository: TanStack/router
Length of output: 2566
🏁 Script executed:
# Search for all occurrences of createServerFn in the file to understand context
if [ -f "packages/start-server-core/skills/start-server-core/SKILL.md" ]; then
rg "createServerFn" "packages/start-server-core/skills/start-server-core/SKILL.md" -n
fiRepository: TanStack/router
Length of output: 706
🏁 Script executed:
# Check package.json to verify the correct import path for createServerFn
rg "createServerFn" packages/start-client-core/ packages/start-server-core/ -l --type ts | head -10Repository: TanStack/router
Length of output: 377
🏁 Script executed:
# Examine broader context to see if these are separate code blocks
sed -n '65,80p' "packages/start-server-core/skills/start-server-core/SKILL.md"Repository: TanStack/router
Length of output: 404
🏁 Script executed:
# Check structure around line 80-105 to see block boundaries
sed -n '90,105p' "packages/start-server-core/skills/start-server-core/SKILL.md"Repository: TanStack/router
Length of output: 355
🏁 Script executed:
# Check around line 140-160 for session code block
sed -n '135,165p' "packages/start-server-core/skills/start-server-core/SKILL.md"Repository: TanStack/router
Length of output: 856
Import createServerFn in code snippets that call it.
Each of these separate code blocks uses createServerFn(...) but lacks the necessary import statement. Skill files must contain self-contained, copy-pasteable examples. Add import { createServerFn } from '@tanstack/react-start' to every snippet that calls createServerFn, or explicitly mark the import as intentionally omitted.
Affected snippets: lines 53–70, 80–98, 103–115, 140–161, 185–195.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/start-server-core/skills/start-server-core/SKILL.md` around lines 53
- 64, Several markdown code blocks in SKILL.md call createServerFn but omit its
import; update every snippet that invokes createServerFn (the blocks showing
serverFn = createServerFn({...}).handler(...)) to include the missing import
statement: add import { createServerFn } from '@tanstack/react-start' at the top
of each of those code fences so each example is self-contained and
copy-pasteable.
| ```vue | ||
| // SFC template (most common for user code) // MyRoute.component.vue | ||
| <template> | ||
| <div>{{ data.title }}</div> | ||
| </template> | ||
|
|
||
| <script setup> | ||
| import { useLoaderData } from '@tanstack/vue-router' | ||
| const data = useLoaderData({ from: '/posts/$postId' }) | ||
| </script> | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Invalid comment syntax in Vue SFC example.
Line 305 has JavaScript-style comments (// SFC template...) outside any <script> block. In Vue SFC files, // comments are only valid inside <script> sections—this would cause a syntax error if copied directly.
Proposed fix: move comment to markdown or use HTML comment
```vue
-// SFC template (most common for user code) // MyRoute.component.vue
+<!-- MyRoute.component.vue - SFC template (most common for user code) -->
<template>
<div>{{ data.title }}</div>
</template>Alternatively, place the description above the code block in markdown:
+SFC template (most common for user code) in `MyRoute.component.vue`:
+
```vue
-// SFC template (most common for user code) // MyRoute.component.vue
<template>🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/vue-router/skills/vue-router/SKILL.md` around lines 304 - 315, The
Vue SFC example includes JavaScript-style comments outside a <script> block (the
"// SFC template... MyRoute.component.vue" line) which will break if copied into
an .vue file; replace that leading // comment with an HTML comment (e.g., <!--
MyRoute.component.vue - SFC template -->) or move the explanatory text above the
code block in markdown, leaving the <template> and <script setup> (and the
useLoaderData/data usage) intact.
| // ensureQueryData returns cached data if fresh, fetches if stale | ||
| return context.queryClient.ensureQueryData(postsQueryOptions) |
There was a problem hiding this comment.
I don't think ensureQueryData "fetches if stale". I think it's just "fetch if not at all in cache". For "fetch if stale" you need
return context.queryClient.ensureQueryData({...postsQueryOptions, revalidateIfStale: true})|
|
||
| return ( | ||
| <ul> | ||
| {posts.map((post: any) => ( |
There was a problem hiding this comment.
We shouldn't encourage any, right? But also queryFn: () => fetch('/api/posts').then((r) => r.json()), will be any so maybe for the sake of the example it's ok.
| ```tsx | ||
| const { postId } = Route.useParams() | ||
| ``` | ||
|
|
There was a problem hiding this comment.
We need to add a section on "how to replace useLocation" because i think most react-router apps rely on this hook heavily, and when they see tanstack/router has one with the same name they assume it can be used the same. (See issue: #3110)
useLocation is about the "live" URL, what you care about is most likely "what is currently rendered":
- the routes => useMatch, useMatches, useChildMatches, useParentMatches
- the params => useParams, useSearch
| // CORRECT — provide context at creation time | ||
| function App() { | ||
| const auth = useAuth() | ||
| const router = useMemo( | ||
| () => createRouter({ routeTree, context: { auth } }), | ||
| [auth], | ||
| ) | ||
| return <RouterProvider router={router} /> |
There was a problem hiding this comment.
Isn't that a risky pattern? If auth changes, the router is re-created, which resets caches, rebuilds the tree, ...
| <Await promise={deferredData}>{(data) => <div>{data}</div>}</Await> | ||
| </Suspense> | ||
| ``` | ||
|
|
There was a problem hiding this comment.
idk where we should put this, but a question i've seen come up a bunch was "how to create a reusable component that contains tanstack router hooks?". I had a hard time finding a nice pattern until Manuel showed me this one:
function MyComponent({ from }: { from: '/a/$id' | '/b/$id' }) {
const { id } = useParams({ from })
// ...
}| }) | ||
| } | ||
| }, | ||
| component: () => <Outlet />, |
There was a problem hiding this comment.
component defaults to Outlet, should we still declare it anyway to be explicit / avoid surprises?
| function InnerApp() { | ||
| const auth = useAuth() | ||
| return <RouterProvider router={router} context={{ auth }} /> | ||
| } |
There was a problem hiding this comment.
This is not the same pattern as packages/react-router/skills/react-router/SKILL.md so it might be confusing
2 participants
Summary
Adds
@tanstack/intentSKILL.md files across 11 packages to help AI coding agents (Claude, Cursor, Copilot, etc.) generate correct TanStack Router and Start code. Each skill covers patterns, API usage, and common failure modes that agents frequently get wrong.What's included
28 SKILL.md files across 11 packages:
router-corereact-routerstart-client-corereact-startvirtual-file-routesrouter-pluginstart-server-coresolid-routervue-routersolid-startvue-startPer-package scaffolding:
bin/intent.jsshim fornpx intentdiscoveryskills/_artifacts/metadata (domain_map.yaml, skill_spec.md, skill_tree.yaml)@tanstack/intentdevDependencyfilesandbinentriesRoot-level artifacts:
_artifacts/skill_tree.yaml— consolidated Router skill tree (13 skills)_artifacts/start_skill_tree.yaml— consolidated Start skill tree (8 skills)_artifacts/domain_map.yamland_artifacts/start_domain_map.yaml— domain mapsKey design decisions:
router-core,start-client-core)react-router,solid-router,vue-router, etc.)@tanstack/intent validate(under 500 lines, correct frontmatter)GitHub labels created: 28
skill:*labels for issue/PR categorizationSummary by CodeRabbit
New Features
intentCLI command across multiple packages to surface skill docs and tooling guidance.Documentation
Chores