# Vite + React SPA + Hono (Edge API) — AI Agent Guidelines & Architecture Rules

> Architecture guidelines for zero-server-lag single-page apps built with Vite and React, backed by a Hono API on Cloudflare Workers.
> Technologies: Vite, React, Hono, TypeScript, Cloudflare

---

## AGENTS.md
```markdown
# 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.
```

---

## CLAUDE.md
```markdown
# CLAUDE.md — Vite + React SPA + Hono Edge API

Refer to @AGENTS.md for complete architectural constraints.

## Common Commands
- `bun run dev` - Start Vite dev server (frontend) and `wrangler dev` (API) concurrently
- `bun run build` - Build the production SPA bundle
- `bunx wrangler deploy` - Deploy the Hono API to Cloudflare Workers
- `bun run test` - Run the Vitest suite for both API and frontend

## Claude Specific Directives
- Use Hono's `hc<AppType>()` RPC client for all API calls from the frontend; never hand-write duplicate fetch/response types.
- Only expose environment variables prefixed `VITE_` to client code; never put secrets behind that prefix.
```

---

## .cursor/rules/stack.mdc
```markdown
---
description: Vite + React SPA + Hono edge API architecture rules
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---

# Vite + React SPA + Hono Edge API

- Vite + React as a pure client-side SPA (no SSR); Hono API on Cloudflare Workers.
- Share types via Hono's RPC client (`hc<AppType>()`) -- never hand-write duplicate frontend types for API responses.
- Validate all Hono handler input with `zValidator` (`@hono/zod-validator`) before touching business logic.
- TanStack Query is the single source of truth for server state; don't duplicate it into Redux/Zustand.
- Only `VITE_`-prefixed env vars reach client code; never put secrets there.
- Route-level code splitting via `React.lazy()`; audit bundle size when adding dependencies -- instant load is this pattern's whole point.
```

---

## Architecture Overview & Best Practices
## Architecture Overview

Standardized production guidelines for **Vite**, **React** (as a pure SPA), and **Hono** running on **Cloudflare Workers** — a minimal-latency pattern for behind-login developer tools and internal dashboards where SEO and SSR add no value.

### Verified Real-World Adoption

**Hoppscotch**, an open-source API testing client, follows this class of architecture: a fast client-rendered app paired with a lightweight edge-deployable API layer, prioritizing instant load and zero server-side rendering overhead.

### Key Architectural Nuances

- **Type Sharing Without Codegen**: Hono's RPC client imports the API's route types directly into the frontend, eliminating the OpenAPI-generation step that most REST-based type-sharing setups require.
- **SSR Is a Deliberate Non-Goal**: Skipping server rendering entirely is correct here specifically because the target audience is always authenticated, removing the SEO/first-paint arguments that justify SSR elsewhere in this catalog.