STACK IT FAST
ALL RULES & SKILLS

Vite + React SPA + Hono (Edge API)

Raw .MD vite-react-hono-edge
CURATED RULE AGENTS.MD + CLAUDE.MD + .MDC + SKILL.MD

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

Vite React Hono TypeScript Cloudflare
CLI & AI Agent Import Verified in 4 production projects
AGENTS.md
Paste in your project root
SKILL.md
Installs to .claude/skills/vite-react-hono-edge
INTERACTIVE RULE & SKILL VIEWER (AGENTS.MD, CLAUDE.MD, .MDC & SKILL.MD)
Optimized for:CursorClaude CodeWindsurfAGY
AGENTS.md·37 lines · 3.3 KB
1# Project Architecture & Guidelines (Vite + React SPA + Hono Edge API)
2
3## 1. System Architecture
4- **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.
5- **API**: Hono running on Cloudflare Workers, exposing a typed REST or RPC API.
6- **Type Sharing**: Hono's RPC client (`hc<AppType>`) shares request/response types directly from the server code, no OpenAPI generation step needed.
7- **State**: TanStack Query for all server state; avoid duplicating server data into a separate global store.
8
9## 2. Vite SPA Conventions
10- 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.
11- 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.
12- Environment variables prefixed `VITE_` are the only ones exposed to client code — never put a secret behind a `VITE_` prefix.
13
14## 3. Hono API & Type-Safe RPC
15- Define the API with Hono's method chaining (`app.get('/projects', ...).post('/projects', ...)`) and export its type (`export type AppType = typeof app`).
16- 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.
17- Validate all input with Hono's `zValidator` middleware (`@hono/zod-validator`) before handler logic runs.
18
19## 4. Auth & Session Handling
20- 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.
21- Never store auth tokens in `localStorage` if XSS is a realistic threat for the app's content; prefer an httpOnly cookie.
22
23## 5. Common Pitfalls / Coding Standards
24- ❌ 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.
25- ❌ Duplicating TanStack Query cache data into Redux/Zustand — pick one source of truth for server state.
26- ✅ Use Hono's RPC client instead of hand-writing `fetch` calls and duplicating response types on the frontend.
27
28## 6. Testing Conventions
29- 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`).
30- Playwright for e2e coverage of the SPA's critical flows against a locally running Worker.
31- 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.
32
33## 7. Git Workflow & PR Conventions
34- Conventional Commits scoped to `api` or `web`, e.g. `feat(api): add pagination to GET /projects`.
35- 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.
36- Require `tsc --noEmit` and `bun run build` (both packages) green before merge.
37- Squash-merge; deploy the Worker before the Pages build if a request shape changed, to avoid a brief client/server mismatch window.
ARCHITECTURE NOTES & IMPLEMENTATION GUIDE
Export as Markdown

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.
FREQUENTLY ASKED QUESTIONS

Does this AGENTS.md work with Cursor, Claude Code, and Windsurf?

Yes — AGENTS.md is the open, cross-tool standard read by Cursor, Claude Code, Windsurf, and 30+ other agents. A dedicated .mdc file is also included for Cursor's native .cursor/rules format.

Why a pure client-side SPA instead of Next.js or Astro?

For tools that live entirely behind a login screen (internal dashboards, developer utilities), SSR and SEO add deployment complexity without a corresponding benefit -- there's no public page to rank in search, and every user is already authenticated before seeing content. A Vite SPA statically hosted on Cloudflare Pages, backed by a Hono API, minimizes both build complexity and time-to-interactive for this specific use case.

What does Hono's RPC client actually save over a typical REST client?

Normally, keeping a frontend's request/response types in sync with a backend API requires either hand-maintaining duplicate types or running an OpenAPI codegen step. Hono's `hc<AppType>()` imports the server's route types directly, so the frontend client is fully typed and a backend shape change becomes a compile error on the client immediately -- no codegen, no schema file, no drift.

MORE AI AGENT CODING RULES & SKILLS
View All Rules & Skills
4 FILE FORMATS Astro, Tailwind CSS

Astro SSR + Tailwind CSS + Cloudflare

Architecture rules for Astro server-side rendering, React client islands, Tailwind CSS, and Cloudflare Pages/Workers edge deployment.

5 techs Copy Rules
4 FILE FORMATS Bun, Hono

Bun + Hono + SQLite (libSQL & Drizzle ORM)

Ultra-fast edge API architecture using Bun.serve(), Hono v4, Drizzle ORM with embedded SQLite / Turso libSQL, and Zod OpenAPI validation.

6 techs Copy Rules
4 FILE FORMATS Django, Python

Django + PostgreSQL + Redis + Celery

Production guidelines for Django 5 enterprise applications, PostgreSQL connection pooling, Redis caching, and Celery async workers.

6 techs Copy Rules
4 FILE FORMATS FastAPI, Python

FastAPI + Python + PostgreSQL (Async SQLAlchemy & Pydantic v2)

Production guidelines for FastAPI, Pydantic v2 validation, Async SQLAlchemy 2.0 (asyncpg), Alembic migrations, and PostgreSQL/Redis.

7 techs Copy Rules