AgentSkillsCN

tanstack-router

在 Electron + React 桌面应用中，使用 TanStack Router 实现基于文件的路由，并采用内存历史记录机制。 适用于：创建新路由、添加导航功能、修改路由布局、处理路由参数、配置路由器实例，或调试路由树生成问题时使用。

SKILL.md
--- frontmatter
name: tanstack-router
description: |
  Implements file-based routing with TanStack Router in an Electron + React desktop app using memory history.
  Use when: creating new routes, adding navigation, modifying route layouts, working with route parameters,
  configuring the router instance, or debugging route tree generation issues.
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs

TanStack Router Skill

File-based, type-safe routing for the EFIS Checklist Editor Electron app. Uses memory history (not browser history) since Electron has no URL bar. Routes auto-generate a typed route tree via a Vite plugin — never edit src/routeTree.gen.ts manually.

Quick Start

Creating a New Route

Create a file in src/routes/. The filename determines the URL path:

typescript
// src/routes/editor.tsx
import { createFileRoute } from "@tanstack/react-router";

function EditorPage() {
  return <div className="flex h-full">Editor content</div>;
}

export const Route = createFileRoute("/editor")({
  component: EditorPage,
});

The route tree regenerates automatically. No manual registration needed.

Programmatic Navigation

typescript
import { useNavigate } from "@tanstack/react-router";

function MyComponent() {
  const navigate = useNavigate();
  return <button onClick={() => navigate({ to: "/editor" })}>Open Editor</button>;
}

Declarative Navigation

typescript
import { Link } from "@tanstack/react-router";

<Link to="/editor">Open Editor</Link>

Key Concepts

ConceptThis ProjectNotes
HistorycreateMemoryHistoryRequired for Electron — no browser URL bar
Route discoveryFile-based in src/routes/Vite plugin auto-generates route tree
Root layoutsrc/routes/__root.tsxWraps ALL routes with <Outlet />
Code splittingAutomaticEnabled via autoCodeSplitting: true in Vite config
Type safetyModule augmentationRegister interface in src/utils/routes.ts
Route treesrc/routeTree.gen.tsNEVER edit — auto-generated

Common Patterns

Route with Custom Layout

Routes can use their own layout instead of the root BaseLayout:

typescript
// src/routes/editor.tsx
import { createFileRoute } from "@tanstack/react-router";
import EditorLayout from "@/layouts/editor-layout";

function EditorPage() {
  return <EditorLayout />;
}

export const Route = createFileRoute("/editor")({
  component: EditorPage,
});

Route File Naming

FileRoute Path
src/routes/index.tsx/
src/routes/editor.tsx/editor
src/routes/settings.tsx/settings
src/routes/__root.tsxRoot layout (wraps all)

WARNING: Common Anti-Patterns

NEVER use browser history in Electron

typescript
// BAD — breaks in Electron
import { createBrowserHistory } from "@tanstack/react-router";
const router = createRouter({ history: createBrowserHistory() });

// GOOD — memory history for Electron
import { createMemoryHistory } from "@tanstack/react-router";
const router = createRouter({
  history: createMemoryHistory({ initialEntries: ["/"] }),
});

NEVER edit routeTree.gen.ts

This file is regenerated on every build. Changes are overwritten silently.

See Also

  • •patterns — Route patterns, layouts, navigation
  • •workflows — Adding routes, debugging, route guards

Related Skills

  • •See the react skill for component patterns used in route pages
  • •See the typescript skill for type safety patterns with route params
  • •See the vite skill for the TanStack Router Vite plugin configuration
  • •See the electron skill for why memory history is required

Documentation Resources

Fetch latest TanStack Router documentation with Context7.

How to use Context7:

  1. •Use mcp__context7__resolve-library-id to search for "tanstack-router"
  2. •Query with mcp__context7__query-docs using the resolved library ID

Library ID: /tanstack/router (benchmark score 94.5, 3,146 snippets) Alternative: /websites/tanstack_router (website docs, 2,334 snippets)

Recommended Queries:

  • •"file-based routing setup with createFileRoute"
  • •"createMemoryHistory for non-browser environments"
  • •"route layout nesting with Outlet"
  • •"type-safe navigation with useNavigate"