Vite Architecture

@architecture-rules.md @rules/conventions.md @rules/routes.md @rules/services.md @rules/hooks.md @rules/execution-model.md @rules/platform.md @rules/validation.md @references/official/current-docs-2026-06-02.md

Vite + TanStack Router Architecture Enforcement

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.

• Confirm a repository is a Vite + TanStack Router project before enforcing architecture rules.
• Enforce safety boundaries for client-reachable loaders, route modules, service layers, env usage, generated route trees, and platform setup.
• Apply Hypercore/repo-local conventions for route folders, hooks, services, naming, and nested shared folders such as src/lib/<domain>/ and src/services/<domain-or-provider>/.
• Keep current Vite and TanStack Router facts in references/official/ so rapidly changing tool behavior can be refreshed without bloating the core skill.

Use this skill for architecture enforcement, implementation guidance, or review in existing Vite + TanStack Router projects. This includes route structure, route-local folders, loaders, validateSearch, service/query layers, custom hooks, Vite plugin setup, generated route tree handling, env/alias safety, and shared nested folder organization.

Do not use this skill when the project uses @tanstack/react-start / app.config.ts, when the project is generic Vite without TanStack Router, or when the task is a docs-only summary with no project audit or implementation guidance. Route TanStack Start work to tanstack-start-architecture.

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

Overview

Enforces hypercore Vite + TanStack Router architecture rules with strict validation before editing code.

This skill is RIGID. Follow exactly. No exceptions.

OPERATING MODE: This skill must stay self-contained. Do not block on external orchestration surfaces just to apply architecture rules. If a repo-local persistence loop is already active, carry these gates into that loop. Otherwise proceed directly with this skill.

NOTE: Some rules in this skill are stricter than TanStack Router defaults. Treat them as hypercore team conventions unless the user explicitly asks to follow official TanStack defaults instead.

Positive examples:

• "Audit this Vite + TanStack Router app for route structure, validateSearch, and service boundaries before editing."
• "Add a new route folder in a Vite + TanStack Router app and keep hooks/services compliant."
• "Refactor a TanStack Router page so the UI stays in the route and logic moves into -hooks/."
• "Vite Router 프로젝트에서 tanstackRouter plugin order와 routeTree.gen.ts 처리를 점검해줘."
• "src/lib/utils.ts 말고 src/lib/auth/session.ts, src/services/billing/queries.ts처럼 nested folders로 묶어줘."

Negative examples:

• "Create a new Codex skill for browser QA."
• "Review a TanStack Start app that uses createServerFn and @tanstack/react-start."
• "Review a generic Vite app that does not use TanStack Router."

Boundary examples:

• "Make a tiny copy-only text change in a Vite route file." Direct editing can be enough if the change does not cross an architecture boundary, but touched files still need a quick compliance check.
• "The repo actually uses @tanstack/react-start." Route away to tanstack-start-architecture instead of forcing Vite rules onto a Start project.

1. Read architecture-rules.md before code changes or architecture findings.
2. Read the topic rule file that matches the touched surface: rules/routes.md, rules/services.md, rules/hooks.md, rules/execution-model.md, rules/platform.md, rules/conventions.md, or rules/validation.md.
3. Read the directly linked official current-docs reference only when Vite, TanStack Router, plugin, env, route tree, search, or loader behavior may be API-drift sensitive.
4. Run scripts/validate-vite-architecture-skill.mjs after editing this skill folder.

Step 1: Project Validation

Before any work, confirm a Vite + TanStack Router project:

# Check for Vite + TanStack Router indicators (ANY of these)
grep -r "@tanstack/react-router" package.json 2>/dev/null
grep -r "vite" package.json 2>/dev/null
ls vite.config.ts 2>/dev/null
ls src/routes/__root.tsx 2>/dev/null

If NONE found: STOP. This skill does not apply. Inform the user and return to the normal implementation or review path.

If @tanstack/react-start or app.config.ts is present: STOP. Route to tanstack-start-architecture.

If the repo matches Vite + TanStack Router: proceed with architecture enforcement.

Step 2: Read Architecture Rules

Load the detailed rules reference:

REQUIRED: Read architecture-rules.md in this skill directory before writing any code. Read references/official/current-docs-2026-06-02.md when Vite config, env handling, TanStack Router plugin setup, routeTree generation, or search/load behavior may be API-drift sensitive.

For detailed patterns and examples, also read the relevant rule files:

• rules/conventions.md - naming, TypeScript, imports, comments
• rules/routes.md - route folder structure, route.tsx, loaders, search params
• rules/services.md - public API services, query options, mutations, client boundaries
• rules/hooks.md - custom hook separation and internal order
• rules/execution-model.md - loader/runtime boundaries, SSR-aware caveats, env safety
• rules/platform.md - vite.config.ts, router setup, generated files, env and alias rules
• rules/validation.md - project/skill validation and readback checks

Step 3: Pre-Change Validation Checklist

Before writing ANY code, verify the planned change against these gates:

Brownfield Adoption Rule

• Do not treat every untouched legacy deviation as an immediate project-wide failure.
• Safety or boundary issues still block immediately, especially in touched files.
• Hypercore-specific style or structure drift in untouched legacy code can be recorded as migration backlog.
• Any file you touch should be brought into compliance unless that would require a materially risky migration.

Gate 1: Layer Violations

Routes -> Services -> External API

Gate 2: Route Structure

Gate 3: Services

Gate 4: Hooks

Gate 5: Conventions

Gate 6: Execution Model

Gate 7: Platform Setup

Step 3.5: Auto-Remediation Policy

Auto-fix directly when the issue is local, reversible, and low-risk.

• add missing validateSearch
• move direct route/hook network access into services/
• add missing pendingComponent or errorComponent
• create missing -components/ or -hooks/ folders for touched pages
• add or correct tanstackRouter() plugin setup, router scaffolding, or explicit env/alias wiring

Do not auto-apply broad or potentially breaking migrations without explicit justification.

• mass route/file renames
• sweeping route-tree restructures across many pages
• introducing SSR/manual server rendering where the repo was SPA-only
• large auth or API-client rewrites

Step 4: Implementation

Carry these acceptance criteria into the active task:

- [ ] Layer architecture respected (Routes -> Services -> External API)
- [ ] Route uses folder structure with -components/ and -hooks/
- [ ] export const Route = createFileRoute(...) used
- [ ] No Start-only server-function APIs in this Vite project
- [ ] Search params use zodValidator from @tanstack/zod-adapter
- [ ] Custom Hooks live in -hooks/ with correct internal order
- [ ] Loaders stay public-safe and SSR-safe
- [ ] Vite/router platform setup stays explicit (router plugin, router file, generated files)
- [ ] All filenames kebab-case
- [ ] Korean block comments present
- [ ] const arrow functions with explicit return types

Step 5: Post-Change Verification

After writing code, verify:

1. Structure check: confirm each touched page still has -components/ and -hooks/ and no -functions/
2. Export check: grep for export const Route
3. Layer check: no direct fetch/axios in touched route or hook files
4. Convention check: no camelCase filenames, no function keyword declarations
5. Hook order check: read touched hooks and verify State -> Global -> Query -> Handlers -> Memo -> Effect
6. Execution check: loaders and route modules do not touch secrets, DB clients, or private env values directly
7. Platform check: vite.config.ts, src/router.tsx, env wiring, and generated router files remain coherent