hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-architecture
hyper-architecture
Verified[Hyper] Use this skill when the user asks for architecture, project setup, or performance work - building, auditing, restructuring, or reviewing project structure, routes, data or server boundaries, the lint/format/type tooling baseline (oxlint, Prettier, tsconfig, rustfmt, clippy), or build and runtime performance - in a Next.js App Router, TanStack Start, Vite with TanStack Router, Astro, Expo, Lynx (ReactLynx), Hono, Axum, Tauri v2, Electron, or Rust CLI, WASM, or MCP server project. It detects the stack from manifests and config files, routes each touched package of a monorepo separately, and applies the matching bundled stack guide, the shared setup baseline, and that stack's performance rules. Do not use it for stacks outside those eleven or for work that crosses no architecture, setup, or performance boundary, such as copy edits, a plain dependency bump, or one build failure.
references/official/tanstack-start/tanstack-router-2026-11-04.md
View on GitHub# TanStack Router Official Snapshot
- last_verified_at: 2026-11-04
- next_re_verification: 2027-05-04 (or earlier if a Refresh Trigger below fires)
- packages_checked:
- `@tanstack/react-router`: `1.170.46` (npm `latest` dist-tag, published 2026-10-22)
- `@tanstack/router-plugin`: `1.168.48`
- `@tanstack/router-generator`: `1.167.46`
- `@tanstack/router-core`: `1.171.39`
- `@tanstack/zod-adapter`: `1.167.0`
- source_priority: latest docs pages > API pages > examples
Use this file when Router behavior affects route, search, loader, context, or SSR rules.
## Contents
- [Official Facts Used By This Skill](#official-facts-used-by-this-skill)
- [File routes, `createFileRoute`, and the `Route` export](#file-routes-createfileroute-and-the-route-export)
- [Flat, directory, and mixed route structures](#flat-directory-and-mixed-route-structures)
- [`routeTree.gen.ts` is generated, should be committed, and is not hand-edited](#routetreegents-is-generated-should-be-committed-and-is-not-hand-edited)
- [Ignore prefix and route/index tokens](#ignore-prefix-and-routeindex-tokens)
- [`autoCodeSplitting` is a bundler-plugin option](#autocodesplitting-is-a-bundler-plugin-option)
- [Search param transformation](#search-param-transformation)
- [Search parameter validation](#search-parameter-validation)
- [Route lifecycle, `beforeLoad`, and `loader`](#route-lifecycle-beforeload-and-loader)
- [Router context](#router-context)
- [Where the "loaders are isomorphic" statement lives](#where-the-loaders-are-isomorphic-statement-lives)
- [Refresh Triggers](#refresh-triggers)
- [Sources](#sources)
## Official Facts Used By This Skill
### File routes, `createFileRoute`, and the `Route` export
- File-based routes are configured with the **curried** form `createFileRoute(path)(options)`.
- `createFileRoute` accepts a single `string` argument (the file route's path) and returns a function that accepts a single `RouteOptions` argument. The path is automatically inserted and updated by `tsr generate` / `tsr watch`.
- The file route instance must be exported using the `Route` identifier for `tsr generate` and `tsr watch` to work correctly.
- Sources:
- <https://tanstack.com/router/latest/docs/api/router/createFileRouteFunction>
- <https://tanstack.com/router/latest/docs/routing/routing-concepts>
### Flat, directory, and mixed route structures
- Router officially supports directory routes, flat routes (`.` denotes nesting levels), and mixed flat/directory structures.
- Hypercore may still prefer route directories for app pages, but that is a team convention, not an official Router requirement.
- Source: <https://tanstack.com/router/latest/docs/routing/file-based-routing>
### `routeTree.gen.ts` is generated, should be committed, and is not hand-edited
- `routeTree.gen.ts` is generated by the Router bundler plugin or CLI. The API reference's default for `generatedRouteTree` is `./src/routeTree.gen.ts`.
- The FAQ says it **should be committed**: "Although the route tree file (i.e., `routeTree.gen.ts`) is generated by TanStack Router, it is essentially part of your application's runtime, not a build artifact." and "You should commit this file into git so that other developers can use it to build your application."
- Files and folders excluded from route generation are not added to `routeTree.gen.ts`.
- The API reference advises ignoring the generated route tree path from your linter and formatter to avoid conflicts.
- Do not hand-edit the generated file (Hypercore convention).
- Sources:
- <https://tanstack.com/router/latest/docs/faq>
- <https://tanstack.com/router/latest/docs/api/file-based-routing>
- <https://tanstack.com/router/latest/docs/routing/routing-concepts>
### Ignore prefix and route/index tokens
- `routeFileIgnorePrefix` default is `-`: "By default, this value is set to `-`." This default is what legitimizes the `-hooks/`, `-components/`, and `-functions/` co-location convention — the docs' own example shows an ignored `-components` directory living beside `index.tsx` and `route.tsx`.
- `routeToken` default is `route`; `indexToken` default is `index`.
- Both tokens now accept a **regex** — `{ "regex": "...", "flags": "..." }` in `tsr.config.json`, or a native `RegExp` inline — and support `[x]` **escaping** to keep a segment literal (e.g. `[home-page].tsx`).
- `routeFileIgnorePattern` default is `undefined`.
- Warning: do not set `routeFilePrefix`, `routeFileIgnorePrefix`, or `routeFileIgnorePattern` to match any token used in the File Naming Conventions guide.
- Sources:
- <https://tanstack.com/router/latest/docs/api/file-based-routing>
- <https://tanstack.com/router/latest/docs/routing/routing-concepts>
### `autoCodeSplitting` is a bundler-plugin option
- `autoCodeSplitting` is only available when using the TanStack Router Bundler Plugin. Default is `false`; the next major release (v2) will default it to `true`.
- It **cannot** be passed through `tanstackStart()`: the Start plugin omits `autoCodeSplitting` and `target` from the router config it accepts.
- Source: <https://tanstack.com/router/latest/docs/api/file-based-routing>
### Search param transformation
- The current search-transform API is `search.middlewares` — functions that transform search params when generating new links for a route or its descendants, also executed on navigation after search validation.
- Router ships generic helpers for the common cases: `retainSearchParams` and `stripSearchParams`.
- The legacy `preSearchFilters` / `postSearchFilters` are marked deprecated in the API reference ("⚠️ deprecated, use `search.middlewares` instead") and no longer appear anywhere in the search-params guide.
- Sources:
- <https://tanstack.com/router/latest/docs/guide/search-params>
- <https://tanstack.com/router/latest/docs/how-to/validate-search-params>
- <https://tanstack.com/router/latest/docs/api/router/RouteOptionsType>
- <https://registry.npmjs.org/@tanstack/zod-adapter/latest>
### Search parameter validation
- `validateSearch` is a planning callback: "It must be deterministic and side-effect-free for the same input; do not navigate or mutate application/router state from it."
- Zod v4: pass the Zod schema directly to `validateSearch`; "the adapter is no longer necessary". `@tanstack/zod-adapter`'s `peerDependencies` pin `zod: ^3.23.8`, so it cannot be installed alongside Zod 4 at all.
- Zod v3: use `@tanstack/zod-adapter` (`zodValidator`, `fallback`).
- Note a live doc inconsistency: the middleware guide still shows a `zodValidator` import in one example. Treat `how-to/validate-search-params` and `guide/search-params` as the authority for the Zod version split.
- Sources:
- <https://tanstack.com/router/latest/docs/how-to/validate-search-params>
- <https://tanstack.com/router/latest/docs/api/router/RouteOptionsType>
- <https://tanstack.com/router/latest/docs/guide/search-params>
### Route lifecycle, `beforeLoad`, and `loader`
- `beforeLoad` runs before a route is loaded; if it fails, the route's loader and its descendants do not run. It may return a context object that is merged into the route context and made available to `loader` and child routes.
- `loader` runs when a route is matched. Both are async and may return a promise, in which case the route enters a pending state until it resolves (showing `pendingComponent` once the `pendingMs` threshold is reached).
- `loaderDeps` is a planning/cache-key function: deterministic and side-effect-free for the same validated search input.
- `staleReloadMode` on the object-form `loader` selects `'background'` (stale-while-revalidate) or `'blocking'`.
- Source: <https://tanstack.com/router/latest/docs/api/router/RouteOptionsType>
### Router context
- Root route context is created with `createRootRouteWithContext<MyRouterContext>()`; `beforeLoad` can extend context for loaders and child routes.
- Source: <https://tanstack.com/router/latest/docs/routing/routing-concepts>
### Where the "loaders are isomorphic" statement lives
- The authoritative statement that route loaders are isomorphic lives in the **Start** docs, not the Router docs. Start's execution-model guide says "Route `loader`s are isomorphic - they run on both server and client, not just the server."
- None of the Router docs pages retrieved for this snapshot states that loaders are isomorphic, so do not attribute the claim to Router.
- Source: <https://tanstack.com/start/latest/docs/framework/react/guide/execution-model>
## Refresh Triggers
Refresh this snapshot when:
- Router file naming conventions, route generation requirements, or the `routeToken` / `indexToken` / `routeFileIgnorePrefix` defaults change.
- Search validation guidance changes for Zod/adapter usage, or the search-transform API (`search.middlewares`) changes.
- Loader / `beforeLoad` lifecycle, pending behavior, or `staleReloadMode` semantics change.
- **Official doc pages change**, and run an advisory check on the pinned version. Do **not** key this trigger on "local package versions move materially". Router and Start stay on `1.x` and absorb breaking changes in patch releases, while a run of patch releases can carry no behavior change at all: 1.170.41 through 1.170.46 shipped only internal composition and link-hydration work, plus publishing the packages' own agent skills. A version bump is therefore not a reliable drift signal in either direction.
## Sources
> Sources checked 2026-11-04, the date this snapshot records as `last_verified_at`; every claim above names the TanStack Router (or Start) docs page it came from. Each page below resolved with HTTP 200 on that date and none was re-fetched from a cached copy. `custom-route-directories` is deliberately not cited — that page does not exist; the file-based-routing config surface lives at `api/file-based-routing`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |