gsap-tanstack-router
Build or review TanStack Router for React and TanStack Start animation: GSAP page transitions, component enter/exit, scroll effects, useBlocker, pending UI, route reuse, and cleanup. Use even when GSAP is unnamed, including choosing viewTransition. Also covers hidden-content recovery and first-load performance. Not for Solid, other routers, React without routing, or isolated GSAP API questions.
johnpolacek · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add johnpolacek/animaxxing-skills --skill gsap-tanstack-router技能说明
name: gsap-tanstack-router description: "Build or review TanStack Router for React and TanStack Start animation: GSAP page transitions, component enter/exit, scroll effects, useBlocker, pending UI, route reuse, and cleanup. Use even when GSAP is unnamed, including choosing viewTransition. Also covers hidden-content recovery and first-load performance. Not for Solid, other routers, React without routing, or isolated GSAP API questions." license: MIT metadata: short-description: GSAP page and component lifecycles in TanStack Router
GSAP TanStack Router
mount → initial state → intro → settled → outro → end state → unmount
Mount and unmount belong to React; animation owns the five phases between them. TanStack Router preserves shared layouts and can reuse routes on parameter changes; pending UI and loaders also affect when the new page appears.
Keep the requested look and existing project conventions. Add GSAP/plugins only as needed; do not replace the chosen animation library unless asked.
This skill decides when motion runs. For what moves, and for a feel such as premium or playful, also load the animaxxing skill when it is installed: its recipes and its guide to finding the vibe plug into this lifecycle.
Start with the project
Read repository instructions, existing animation, layouts, navigation, CSS, accessibility conventions, and checks. Then:
- Confirm
@tanstack/react-router. Next.js belongs togsap-nextjs, React Router togsap-react-router, React without a router togsap-react. Solid Router is out of scope. - Read the installed
@tanstack/react-routerversion and, when present,@tanstack/react-start. Prefer their bundled types over memory:node_modules/@tanstack/router-core/dist/esm/router.d.tsforRouterOptions,RouterState, andRouterEvents,node_modules/@tanstack/react-router/dist/esm/useBlocker.d.tsfor the blocker,node_modules/@tanstack/history/dist/esm/index.d.tsfor history actions. The TanStack/router repository'sdocs/router/anddocs/start/are the source of truth. The loading architecture changed during the 1.16x and 1.17x releases;RouterState.isTransitioningis gone from router-core 1.171.2x, anduseBlockeris still marked experimental. - Tell file-based routes (
createFileRoute,routeTree.gen.ts,__root.tsx) from code-based routes (createRoute,createRootRoute). The lifecycle is the same; only where route options live differs. - Tell TanStack Start (SSR, a root document shell with
HeadContentandScripts) from a client-only Vite app (RouterProviderrendered into a div). Client-only apps paint nothing before React, so they need no pre-paint rule. Checkssrper route,defaultSsr,spa.enabled, and prerendering. - Read the router options:
defaultPreload,defaultPendingComponent,defaultPendingMs,defaultPendingMinMs,defaultViewTransition,scrollRestoration,defaultStaleTime,defaultRemountDeps. Each changes when pages mount and what the user sees while they load.
Choose the engine
Use defaultViewTransition or Link/navigate viewTransition for snapshot morphs or page crossfades. Use GSAP for live-DOM outros that gate navigation, interruptible sequences, split text, or scroll-linked motion. One engine per element; see combining engines.
Read only what you need
- Invisible entrances, failed initialization, indexing, and first-load performance: Initialization and recovery, plus the framework integration.
- Router APIs and the order of one navigation, outro before navigation with
useBlockeror an intercepted Link, the lock, back and forward, pending UI, the swap gap, scroll, focus, View Transitions: TanStack navigation. - Route reuse versus
remountDeps, layouts andOutlet, the React lifecycle for GSAP, conditional content, TanStack Start SSR and hydration, deferred data: Route lifetime. - The five phases, GSAP setup, show and hide, layout stability, scroll, text, plugins: Lifecycle implementation.
- Lenis, ScrollSmoother, or eased page scrolling across routes: Smooth scrolling, plus the TanStack integration.
- Curtains, first-visit preloaders, and shared-element morphs: Transition archetypes, plus where they live under TanStack Router.
- Touch, viewport changes, and device budgets: Devices and input.
- Tauri, Electron, or Wails desktop shells: Desktop webviews.
- Before calling work done: Verification.
Install the official GSAP skills alongside this repository. Load gsap-core for API details and gsap-react for component setup only as needed.
Rules
- Preserve invisible intros on successful setup; recover the current incoming owner on failure. Follow the initialization contract before adding hiding rules.
- GSAP runs only on the client.
useGSAPnever runs on the server; keep GSAP calls out of module scope in files Start renders on the server. Scope selectors. Clean up every tween, trigger, split, and listener. - Reserve final geometry with normal CSS and a stable wrapper; overlap outgoing/incoming content without doubling layout space.
- Mount, then set initial values, then paint. Successful initialization never flashes settled content before the intro. Under Start, server HTML paints before hydration, so hide intro targets only under a root attribute set by a
ScriptOnceinline script, only during the initial phase, with a no-JavaScript path. - Clear temporary st