Tanstack Start Architecture

@architecture-rules.md @rules/project-structure.md @rules/routes.md @rules/services.md @rules/hooks.md @rules/import-protection.md @rules/middleware.md @rules/execution-model.md @rules/server-routes.md @rules/ssr-hydration.md @rules/platform.md @rules/validation.md @references/official/tanstack-start-2026-04-30.md @references/official/tanstack-router-2026-04-30.md @references/official/api-drift-notes.md @references/official/current-docs-2026-06-02.md

TanStack Start Architecture Enforcement

Apply hypercore's TanStack Start architecture rules without confusing team conventions with official TanStack requirements.

Default all user-facing deliverables, saved artifacts, reports, plans, generated docs, summaries, handoff notes, commit/message drafts, and validation notes to Korean, even when this canonical skill file is written in English.

Preserve source code identifiers, CLI commands, file paths, schema keys, JSON/YAML field names, API names, package names, proper nouns, and quoted source excerpts in their required or original language.

Use a different language only when the user explicitly requests it, an existing target artifact must stay in another language for consistency, or a machine-readable contract requires exact English tokens. If a localized template or reference exists (for example *.ko.md or *.ko.json), prefer it for user-facing artifacts.

• Validate that the project is a TanStack Start / TanStack Router project before applying this skill.
• Enforce safety boundaries for loaders, server functions, import protection, middleware, server routes, and SSR/hydration.
• Apply hypercore conventions for route folders, hooks, file naming, comments, and layering when they are in scope.
• Keep official TanStack API facts in references/official/ so rapidly changing framework details can be refreshed without bloating the core skill.

This skill is self-contained. Do not depend on global skills or external orchestration before applying it.

Rules are classified as:

• Official — documented TanStack behavior or API requirement.
• Safety policy — local blocking rule for security/runtime correctness.
• Hypercore convention — local/team standard that may be stricter than official TanStack defaults.

If a user explicitly asks for official TanStack defaults, relax hypercore-only conventions but keep official and safety rules.

Use this skill when the requested output is architecture enforcement, implementation guidance, or review for an existing TanStack Start / TanStack Router project. This includes route structure, route-local folders, loaders, server functions, server routes, middleware, import protection, SSR/hydration, platform setup, and shared nested folder organization.

Do not use this skill when:

• the project is not TanStack Start or TanStack Router
• the user only wants a generic React/Vite architecture review
• the task is a docs-only summary with no project audit or implementation guidance
• the main task is security, deployment, or test repair unrelated to Start architecture

When official TanStack guidance and Hypercore conventions differ, enforce official and safety rules first, then apply Hypercore conventions only to touched architecture surfaces.

Positive examples:

• "Audit this TanStack Start app for server-function, loader, and importProtection violations."
• "Add a TanStack Start route with search params and keep the architecture compliant."
• "Refactor Start route folders, hooks, and server functions to follow hypercore rules."
• "Check the loader boundaries and server function structure in this TanStack Start project."
• "Review this TanStack Start folder structure and enforce nested src/modules or src/lib grouping."

Negative examples:

• "Review this generic React/Vite app that does not use TanStack Start."
• "Create a browser QA skill for Codex."
• "Summarize TanStack Router docs without changing or auditing a project."

Boundary examples:

• "Make a copy-only edit in a static TanStack Start privacy page." Use this skill only for a quick boundary check. Publishing-only pages do not need generated -hooks/, -components/, or -functions/ folders; add route-local folders only when interactive UI or route-only server actions are introduced.

Before enforcing rules, confirm at least one Start/Router indicator exists:

ls app.config.ts 2>/dev/null
grep -r "@tanstack/react-start" package.json 2>/dev/null
grep -r "@tanstack/react-router" package.json 2>/dev/null
ls src/routes/__root.tsx 2>/dev/null

If none are present, stop using this skill and route to the normal implementation/review path.

Read only what the task needs:

1. architecture-rules.md for the rule taxonomy and blocking gate summary.
2. Topic rules by changed surface:
   • rules/project-structure.md — official Start project shape, src/routes, route tree generation, custom route directory, shared nested folders.
   • rules/routes.md — route organization, search validation, loaders, route lifecycle.
   • rules/services.md — server functions, validation, query/mutation layering.
   • rules/hooks.md — hook extraction, internal hook order, useServerFn wrapper policy.
   • rules/import-protection.md — client/server import boundaries and vite.config.ts deny rules.
   • rules/middleware.md — function/request middleware and sendContext validation.
   • rules/execution-model.md — isomorphic loaders and environment-only functions.
   • rules/server-routes.md — justified HTTP endpoints vs internal app RPC.
   • rules/ssr-hydration.md — deterministic first render, ClientOnly, route SSR modes.
   • rules/platform.md — getRouter(), env validation, path aliases, operational endpoints.
3. references/official/tanstack-start-2026-04-30.md when Start API behavior matters.
4. references/official/tanstack-router-2026-04-30.md when Router/file-route/search/loading behavior matters.
5. references/official/current-docs-2026-06-02.md when current Start docs, plugin config, import protection, server functions, or execution-control APIs affect the decision.
6. references/official/api-drift-notes.md when docs conflict or current package behavior is uncertain.
7. rules/validation.md before claiming completion.

Always block or fix before proceeding when touched code would:

• Read secrets, DB clients, filesystem, or privileged SDKs from isomorphic loader/client-reachable code.
• Keep server-only imports alive outside compiler-recognized boundaries such as createServerFn or createServerOnlyFn.
• Disable import protection or overwrite an existing tanstackStart() config instead of extending it.
• Use server functions for mutations without runtime input validation.
• Treat untrusted sendContext values as validated server data.
• Introduce hydration-unstable first render output such as Date.now(), random IDs, or locale/time-zone divergence without a stabilization strategy.

Apply these to touched files unless the user asks for official defaults only:

• Prefer route directories over flat route files for app pages.
• Pages/components with interactive logic extract logic into -hooks/; publishing-only static pages are exempt.
• Server-integrated pages call server functions from src/modules/<domain>/<feature>/ through route-local hooks by default. Use route-local -functions/ only as an exception for single-route actions.
• Use export const Route = createFileRoute(...) for file routes.
• Keep routes thin: route/page UI -> hooks/query -> route-local exception or module server functions -> modules/lib/db/integrations layer.
• Place server functions in src/modules/<domain>/<feature>/<resource>.functions.ts by default. Use route-local -functions/<resource>.functions.ts only for single-route actions.
• Split server function wrappers into .functions.ts, DB/secret/filesystem helpers into .server.ts, and validation/DTO/query-key code into client-safe schema/helper files.
• Enforce nested shared folders such as src/modules/<domain>/<feature>/, src/lib/<domain>/, src/db/<area>/, src/server/<area>/, src/integrations/<provider>/, and src/config/<area>/ when touched shared code is added or reorganized; do not add new direct leaf files like src/modules/foo.ts or src/lib/foo.ts unless an explicit project exception is recorded.
• Do not mix safe exports with server-only exports in functions/index.ts or src/modules/<domain>/<feature>/index.ts.
• Use kebab-case filenames, explicit return types, no any, const arrow functions, and Korean block comments for meaningful code groups.

Before declaring the work done:

• Run the task-specific checks in rules/validation.md.
• Confirm official-vs-hypercore labels are preserved in any edited rule.
• Confirm support files are directly linked from SKILL.md and do not require following an indirect reference chain.
• Confirm English and Korean entrypoints still describe the same trigger, boundary, workflow, contract, and read order.
• Confirm touched src/modules, src/lib, src/integrations, and similar shared folders use logical nested grouping or record an explicit exception.
• Confirm server-function-heavy changes preserve .functions.ts / .server.ts split, static direct imports, and auth/CSRF boundaries.
• Record any unresolved TanStack API ambiguity with a source link and exact date.