Vite + React SPA + Hono (Edge API)

Curated rule Developer Tool & API · Internal Admin Tool Updated Sep 2026 Which file does my tool read?

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

Formats: 4 files
AGENTS.md: 37 lines
CLAUDE.md: 15 lines
Languages: TypeScript
Updated: Sep 2026
Used by: 4 projects

Install

Writes .claude/skills/vite-react-hono-edge/SKILL.md

$ curl -s --create-dirs -o .claude/skills/vite-react-hono-edge/SKILL.md https://stackitfast.com/rules/vite-react-hono-edge/SKILL.md

Rule files

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.

Works with Cursor · Claude Code · Windsurf · AGY

Architecture notes

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.

Used in production

Explore all stacks

Orca

Agentic Development Environment for Parallel Coding Agents · 6-20 people

Agent CLIs stay the user's own. Orca adds the orchestration layer around them: isolated git worktrees, a PTY daemon that outlives the UI, and a relay for mobile steering. It can support new agents without bundling them.

MindsHub (formerly MindsDB)

Desktop & Web AI Agent Workspace · 20+ People

Splitting the client, API and agent into separately versioned git submodules lets each ship on its own cadence (a signed desktop app, a PyPI server package, an agent package), while one Makefile and one docker-compose.yml still bring the whole stack up together.

Excalidraw

Canvas Editor · 2-5 people

A client-only canvas editor kept free of backend dependencies so it can be embedded anywhere; sharing, live collaboration and persistence are layered on in the app shell with Firebase and a Socket.IO relay.

crates.io

Package Registry · 1M+ MAU

crates.io runs one pinned-dependency Rust binary as migrate, web and worker processes, splits domains into small internal crates, and generates its TypeScript client from OpenAPI types so the SvelteKit frontend and Axum API share one contract.

Where this stack fits

Stack It First recommends it at:

Web · MVP · Tool

Walk the web roadmap

Every stack ships as files

More AI agent coding rules and skills

View all

astro-static-content/AGENTS.mdAstro Static Site + Content Collections + TailwindAstro · Tailwind CSS · TypeScript bun-hono-sqlite/AGENTS.mdBun + Hono + SQLite (libSQL & Drizzle ORM)Bun · Hono · SQLite django-postgres-redis/AGENTS.mdDjango + PostgreSQL + Redis + CeleryDjango · Python · PostgreSQL fastapi-jev-decision-service/AGENTS.mdFastAPI + Jev Decision Service (Python)Python · FastAPI · Jev