| name | routing-guidelines |
| description | Use this skill when creating, moving, renaming, or reviewing TanStack Start routes, route metadata, root document shell, stylesheet links, router configuration, generated route tree behavior, static/prerender output, or URL contracts. Covers `src/routes`, `__root.tsx`, `router.tsx`, `HeadContent`, `Scripts`, Tailwind CSS link wiring, and single-page generator routing. |
Routing Guidelines
Apply this skill when changing URL structure, TanStack Start route files, root route metadata, document shell, or router configuration.
Route Ownership
TanStack Start uses TanStack Router file-based routing. The initial app should expose the generator at / and avoid extra routes until product needs justify them.
Guidelines:
- MUST put file routes under
src/routes.
- MUST keep the root route in
src/routes/__root.tsx.
- MUST keep router creation in
src/router.tsx.
- MUST treat
src/routeTree.gen.ts as generated by TanStack Start tooling.
- MUST NOT add routes for marketing content when the user requested the generator app itself.
- SHOULD keep the initial public URL contract to
/ unless a requirement document approves additional routes.
Root Route and Document Shell
The root route owns the document shell and global head output. It is the right place for static metadata and the global stylesheet link.
Guidelines:
- MUST render
HeadContent inside <head> and Scripts inside <body> per TanStack Start requirements.
- MUST import the Tailwind CSS file into
__root.tsx with the ?url query when using explicit route head stylesheet links.
- MUST include
charset, viewport, title, description, and favicon metadata for the app.
- MUST keep metadata static and free of generated passwords, character pools, layout-specific generated values, or user-specific state.
- MUST preserve
<html lang="en"> unless language support requirements change.
- SHOULD check current TanStack Start docs before changing document-shell behavior.
Navigation and State
The generator's primary state is local UI state. It should not become route state until there is a clear shareable-URL requirement and privacy review.
Guidelines:
- MUST keep generated passwords out of route params and search params.
- MUST keep layout and option selections in component state for the initial version.
- MUST avoid route loaders and server functions for local-only password generation.
- MAY add URL-backed non-secret options later only if privacy impact is reviewed by Application Security Requirements.
- SHOULD keep new routes out of the app until they support a concrete user workflow.
Static and Deployment Behavior
Routing changes can affect the static/prerendered output that Cloudflare Workers serves.
Guidelines:
- MUST run
npm run build after route, metadata, router, or root document changes.
- MUST preserve prerender/static compatibility unless a product requirement explicitly adds server behavior.
- MUST consult Performance and Reliability Requirements when route changes affect build output or Cloudflare deployment.
- SHOULD browser-smoke-test
/ after route-shell changes.
