---
name: vite-react-hono-edge
description: "Use when building, refactoring, or reviewing a Vite + React SPA + Hono (Edge API) project (Vite, React, Hono, TypeScript, Cloudflare). Architecture guidelines for zero-server-lag single-page apps built with Vite and React, backed by a Hono API on Cloudflare Workers."
license: MIT
metadata:
  source: https://stackitfast.com/rules/vite-react-hono-edge
  version: "2026-09-10"
---

# Vite + React SPA + Hono (Edge API) — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a Vite + React SPA + Hono (Edge API) codebase.
- Whenever the project depends on Vite, React, Hono, TypeScript, Cloudflare.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (Vite + React SPA + Hono Edge API)

## 1. System Architecture
- **Frontend**: Vite + React, built as a pure client-side SPA (no SSR) — appropriate for tools that live behind a login and don't need SEO.
- **API**: Hono running on Cloudflare Workers, exposing a typed REST or RPC API.
- **Type Sharing**: Hono's RPC client (`hc<AppType>`) shares request/response types directly from the server code, no OpenAPI generation step needed.
- **State**: TanStack Query for all server state; avoid duplicating server data into a separate global store.

## 2. Vite SPA Conventions
- Single entry point (`src/main.tsx`) mounting a React Router (or TanStack Router) tree; route-level code splitting via `React.lazy()` for anything not needed on first paint.
- Keep the production bundle lean: this pattern's whole value proposition is instant load, so audit bundle size (`vite-bundle-visualizer`) whenever a new dependency is added.
- Environment variables prefixed `VITE_` are the only ones exposed to client code — never put a secret behind a `VITE_` prefix.

## 3. Hono API & Type-Safe RPC
- Define the API with Hono's method chaining (`app.get('/projects', ...).post('/projects', ...)`) and export its type (`export type AppType = typeof app`).
- Import `AppType` on the frontend and create a client with `hc<AppType>(apiUrl)` — this gives full autocomplete and compile-time errors on the client for any API shape mismatch, without a separate schema/codegen step.
- Validate all input with Hono's `zValidator` middleware (`@hono/zod-validator`) before handler logic runs.

## 4. Auth & Session Handling
- Since the frontend and API are separately deployed (SPA on Pages, API on Workers), use a signed JWT or session cookie with the `SameSite`/`Secure` attributes set correctly for cross-origin requests, or deploy both behind the same domain via Workers routing to avoid CORS entirely.
- Never store auth tokens in `localStorage` if XSS is a realistic threat for the app's content; prefer an httpOnly cookie.

## 5. Common Pitfalls / Coding Standards
- ❌ Reaching for SSR/Next.js when the app is purely behind-login tooling with no SEO requirement — it adds deployment complexity this pattern is meant to avoid.
- ❌ Duplicating TanStack Query cache data into Redux/Zustand — pick one source of truth for server state.
- ✅ Use Hono's RPC client instead of hand-writing `fetch` calls and duplicating response types on the frontend.

## 6. Testing Conventions
- Vitest for both the Hono API (using Hono's built-in `app.request()` test helper, no real network needed) and React components (`@testing-library/react`).
- Playwright for e2e coverage of the SPA's critical flows against a locally running Worker.
- Run `tsc --noEmit` on both the API and frontend packages as a required check — this is where the RPC type-sharing pays off, catching API/client drift at compile time.

## 7. Git Workflow & PR Conventions
- Conventional Commits scoped to `api` or `web`, e.g. `feat(api): add pagination to GET /projects`.
- A change to the Hono API's shape and its frontend caller ship in the same PR — the RPC types make it obvious when they drift.
- Require `tsc --noEmit` and `bun run build` (both packages) green before merge.
- Squash-merge; deploy the Worker before the Pages build if a request shape changed, to avoid a brief client/server mismatch window.

## Source
Maintained at https://stackitfast.com/rules/vite-react-hono-edge — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.