tanstack-vue-router-skilld
Modern and scalable routing for Vue applications. ALWAYS use when writing code importing \"@tanstack/vue-router\". Consult for debugging, best practices, or modifying @tanstack/vue-router, tanstack/vue-router, tanstack vue-router, tanstack vue router, router.
skilld-dev · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-router-skilldAbout this skill
name: tanstack-vue-router-skilld description: "Modern and scalable routing for Vue applications. ALWAYS use when writing code importing "@tanstack/vue-router". Consult for debugging, best practices, or modifying @tanstack/vue-router, tanstack/vue-router, tanstack vue-router, tanstack vue router, router." metadata: version: 1.166.7 generated_at: 2026-03-11 references_synced_at: 2026-05-05
TanStack/router @tanstack/vue-router
Modern and scalable routing for Vue applications
Version: 1.166.7 (Mar 2026) Deps: @tanstack/vue-store@^0.9.1, @vue/runtime-dom@^3.5.25, isbot@^5.1.22, jsesc@^3.0.2, tiny-invariant@^1.3.3, tiny-warning@^1.0.3, @tanstack/history@1.161.4, @tanstack/router-core@1.166.7 Tags: latest: 1.166.7 (Mar 2026)
References: Docs — API reference, guides
API Changes
This section documents version-specific API changes — prioritize recent major/minor releases.
-
BREAKING:
NotFoundRoute&routerOptions.notFoundRoute— deprecated in v1.x; usenotFoundComponentin route options ordefaultNotFoundComponentincreateRouterinstead source -
DEPRECATED: Router Classes (
Router,Route,RootRoute,FileRoute) — all class-based APIs are deprecated; use factory functionscreateRouter,createRoute,createRootRoute, andcreateFileRouteinstead source -
DEPRECATED:
opts.navigate— thenavigateargument insidebeforeLoadandloaderis deprecated; usethrow redirect({ to: '...' })for navigation-triggered redirects instead source -
DEPRECATED:
parseParams&stringifyParams— top-level route properties deprecated in favor of the nestedparams.parseandparams.stringifyobjects source -
DEPRECATED:
preSearchFilters&postSearchFilters— deprecated in favor ofsearch.middlewaresarray which provides a composable middleware pipeline for transforming search params source -
DEPRECATED:
<ScrollRestoration />component — deprecated; configure scroll restoration viascrollRestoration: trueincreateRouteroptions instead source -
NEW:
protocolAllowlist—createRouteroption acceptingArray<string>of allowed URL protocols (e.g.'https:','mailto:'); absolute URLs with unlisted protocols are blocked to prevent XSS; also exportsDEFAULT_PROTOCOL_ALLOWLISTconstant source -
NEW:
search.middlewares— route option accepting an array of middleware functions({search, next}) => searchfor composable search param transformation when generating links; use withretainSearchParamsandstripSearchParamshelpers source -
NEW:
head,headers,scripts— route option methods for server-side document management;head()injects<meta>,<link>,<style>into<head>;headers()sets HTTP response headers;scripts()injects<script>tags source -
NEW: Validation Adapters —
@tanstack/zod-adapter,@tanstack/valibot-adapter, and@tanstack/arktype-adapterprovide schema-based validation for search params and route params with distinct input/output type inference source -
NEW:
defaultViewTransition—createRouteroption acceptingboolean | ViewTransitionOptionsto enable native View Transitions API (document.startViewTransition()) during navigation; supportstypesarray viaViewTransitionOptionssource -
NEW:
rewrite—createRouteroption accepting{ input?, output? }for bidirectional URL transformation between browser URL and router's internal URL;inputtransforms before matching,outputtransforms before writing to history source -
NEW:
Wrap&InnerWrap—createRouteroptions for injecting global providers;Wrapsurrounds the entire router,InnerWrapwraps inner content and has access to router context and hooks source -
NEW:
codeSplitGroupings— route optionArray<Array<'loader' | 'component' | 'pendingComponent' | 'notFoundComponent' | 'errorComponent'>>for fine-grained control over how lazy-loaded route assets are bundled into chunks source
Also changed: rootRouteWithContext deprecated → use createRootRouteWithContext · useCanGoBack() new experimental hook · defaultRemountDeps new router option · defaultStructuralSharing new router option · search.strict new router option · disableGlobalCatchBoundary new router option · scrollToTopSelectors new router option · composeRewrites new export · ClientOnly / ScriptOnce / HeadContent / Asset new components · SearchSchemaInput tag for optional search params · state.__TSR_key replaces deprecated state.key
Best Practices
-
Use
zodValidator()adapter withfallback()instead of Zod's.catch()for search param validation —.catch()widens types tounknown, losing type inference, whilefallback(z.number(), 1).default(1)retains correct types and makessearchoptional in<Link>props source -
In
loaderDeps, extract only the search params actually used in the loader — returning the entiresearchobject causes the loader to re-run on any search param change, even unrelated ones likeviewModeor `sortDi