REACT + VITE SPA AGENTS.MD

A classic single-page React application built with Vite. The rules keep components small and testable, steer state to the right place, and make sure the agent runs the type-checker that Vite itself skips.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
The React + Vite SPA filesCustomize in the generator
AGENTS.mdFor Codex, Cursor, Copilot, Jules, Windsurf and more
# AGENTS.md

Project: react-vite-app. A React single-page app built with Vite and TypeScript.

This file is the single source of truth for every coding agent working in this repository. The tool-specific files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md and .cursor/rules/project.mdc) point here. Edit this file, not those.

## Stack

- Language: TypeScript
- Framework: React + Vite
- Hosting: Netlify
- Tests: Vitest
- Package manager: npm

## Commands

Run these from the repository root.

- Install dependencies: `npm install`
- Run locally: `npm run dev`
- Build: `npm run build`
- Run all tests: `npx vitest run`
- Run one test file: `npx vitest run src/path/to/file.test.tsx`
- Lint: `npm run lint`
- Type-check: `npx tsc -b --noEmit`
- Format: `npx prettier --write .`

## Project layout

- `src/components/`: Reusable presentational components
- `src/features/`: Feature folders: components, hooks and tests that belong together
- `src/hooks/`: Shared custom hooks
- `src/lib/`: Framework-free helpers and API clients
- `public/`: Static files copied as-is

## Code style

- Indent with 2 spaces. Never tabs.
- TypeScript runs in strict mode. Do not use `any`; use `unknown` and narrow it, or write the real type.
- Match the style and patterns of the surrounding code, even where you would personally choose differently.
- Use named exports. Do not add default exports.
- Never swallow an error. Handle it where you can act on it, or rethrow it with context about what failed.
- Commit messages follow Conventional Commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, with an imperative summary under 72 characters.
- Every new UI control works with a keyboard, has a visible focus state and an accessible name.

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Never delete, skip or loosen a test to make it pass. If a test is wrong, say why and ask before changing it.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.

## Product constraints

- Watch the performance budget: no new blocking requests on page load, and justify any bundle-size increase in the change description.

## Project-specific notes

- `vite build` does not type-check. Always run the type-check command as well before saying a change is done.
- Function components and hooks only; no class components.
- Do not add `useEffect` to derive state from props or other state; compute it during render or with `useMemo`.
- Only variables prefixed `VITE_` reach the browser, and everything in the bundle is public. Never put secrets in them.
- Test behavior with React Testing Library queries by role and label (`getByRole`), not implementation details or snapshot dumps.
- Keep server data in the data-fetching library (for example TanStack Query); do not copy it into global state.
- Lazy-load route-level components with `React.lazy` so the initial bundle stays small.

## Project phase

This project is in active development. Follow the patterns that already exist; consistency beats novelty.
CLAUDE.mdFor Claude Code
# CLAUDE.md

@AGENTS.md

## Claude Code

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file, so every agent stays in sync.
- Put Claude-only preferences below this line. Personal, uncommitted notes belong in CLAUDE.local.md.
GEMINI.mdFor Gemini CLI
# GEMINI.md

@./AGENTS.md

## Gemini CLI

- The shared project instructions are imported from AGENTS.md on the line above. Edit AGENTS.md, not this file.
- Alternative: delete this file and set "context": { "fileName": ["AGENTS.md"] } in .gemini/settings.json so Gemini CLI reads AGENTS.md directly.
.github/copilot-instructions.mdFor GitHub Copilot
# Copilot instructions

Project: react-vite-app. A React single-page app built with Vite and TypeScript.

The full instructions are in AGENTS.md at the repository root. Read it before you change code; if anything here disagrees with it, AGENTS.md wins. The essentials are repeated below for Copilot surfaces that only read this file.

## Stack

- Language: TypeScript
- Framework: React + Vite
- Hosting: Netlify
- Tests: Vitest
- Package manager: npm

## Commands

- Install dependencies: `npm install`
- Run locally: `npm run dev`
- Build: `npm run build`
- Run all tests: `npx vitest run`
- Run one test file: `npx vitest run src/path/to/file.test.tsx`
- Lint: `npm run lint`
- Type-check: `npx tsc -b --noEmit`
- Format: `npx prettier --write .`

## Working rules

- Before you say a task is done, run the test, lint and type-check commands above and make sure they pass. If you could not run them, say so.
- Never delete, skip or loosen a test to make it pass. If a test is wrong, say why and ask before changing it.
- Never write secrets, API keys, tokens or passwords into code, tests, fixtures, logs or commits. Read them from environment variables, and never commit `.env` files.
- Do not add a new dependency without asking first. Prefer the standard library and what is already installed.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.
.cursor/rules/project.mdcFor Cursor
---
description: Project instructions for every task (mirrors AGENTS.md)
globs:
alwaysApply: true
---

# Project rules

The project instructions live in @AGENTS.md at the repository root, which Cursor loads automatically. They are not repeated here, so they cost context only once. Edit AGENTS.md, not this rule.

Before you change code, check the Commands and Working rules sections of AGENTS.md, and run its test and lint commands before you say a task is done.

Put Cursor-only rules below, or add scoped rules as more .mdc files with `globs` (for example `src/components/**/*.tsx`).

These are the exact files the generator writes for this preset. Change any command or rule in the generator and download your own set.

About the React + Vite SPA preset

What Is in the React + Vite SPA AGENTS.md?

The preset describes a a React single-page app built with Vite and TypeScript. Its AGENTS.md is 51 non-empty lines with 8 exact commands, 5 key directories, and 7 stack-specific rules on top of the shared working rules.

  • Commands: npm install, npm run dev, npm run build, npx vitest run, npx vitest run src/path/to/file.test.tsx, npm run lint, npx tsc -b --noEmit, npx prettier --write ..
  • Layout: src/components/, src/features/, src/hooks/, src/lib/, public/.
  • Wrappers: CLAUDE.md and GEMINI.md import AGENTS.md; the Copilot file repeats the essentials; the Cursor rule points to AGENTS.md.

Why These Rules for React + Vite SPA?

Vite does not type-check

Vite strips types with esbuild and never reports type errors. An agent that runs npm run build, sees success and declares victory may have shipped broken types. Naming the separate type-check command closes that gap.

Effects are the most common React mistake

Agents reach for useEffect plus setState to keep two values in sync. That causes extra renders and subtle bugs. The React docs call this pattern unnecessary; the rule makes the agent compute derived values directly.

VITE_ variables are public

The prefix is an opt-in for exposure, not a secret store. Anything with it is inlined into JavaScript that every visitor downloads.

Test what users see

Queries by role and label survive refactors and double as accessibility checks. Snapshot tests mostly record whatever the agent generated and approve it.

Which Stack Rules Does the File Add?

  • vite build does not type-check. Always run the type-check command as well before saying a change is done.
  • Function components and hooks only; no class components.
  • Do not add useEffect to derive state from props or other state; compute it during render or with useMemo.
  • Only variables prefixed VITE_ reach the browser, and everything in the bundle is public. Never put secrets in them.
  • Test behavior with React Testing Library queries by role and label (getByRole), not implementation details or snapshot dumps.
  • Keep server data in the data-fetching library (for example TanStack Query); do not copy it into global state.
  • Lazy-load route-level components with React.lazy so the initial bundle stays small.

How Do You Add These Files to a React + Vite SPA Repository?

  1. Download the zip above. It is laid out exactly as the files go into the repository.
  2. Unzip it at the repository root. AGENTS.md, CLAUDE.md and GEMINI.md go next to your README; the Copilot file goes in .github/ and the Cursor rule in .cursor/rules/.
  3. Open AGENTS.md and check every command against your package scripts or Makefile.
  4. Delete wrappers for tools your team does not use, and any old .cursorrules or .windsurfrules file.
  5. Commit, then run the linter on AGENTS.md whenever you change it.

Want different commands or rules? Load this preset into the generator, change anything, and download your own set.

Which Agents Will Read These Files?

AGENTS.md is read directly by Codex, Cursor, Windsurf, Cline, Zed and Jules, and by GitHub Copilot's cloud agent, code review and CLI. Claude Code reads it through the generated CLAUDE.md, and Gemini CLI through GEMINI.md. See the compatibility table for details, last verified 2026-11-13.

Which Similar Stacks Are in the Library?

All presets are on the stacks page.

Frequently Asked Questions

Should a React SPA use Next.js instead?

Not necessarily. A client-rendered app behind a login, a dashboard or an internal tool rarely needs server rendering. If SEO or first-load speed for public pages matters, use one of the framework templates instead.

Why does the template choose Vitest over Jest?

Vitest shares the Vite config and transforms, so tests run against the same module resolution as the app with no extra Babel setup. Pick Jest in the generator if your project already uses it.

Can I use Create React App with these rules?

Create React App is deprecated. The rules still apply to component and test style, but switch the commands to your actual scripts in the generator.

Are these React + Vite SPA files free to use?

Yes. Copy them into any project, commercial or not, without attribution. They are a starting point: adjust the commands and rules to match your repository.

How Can You Verify That Nothing Leaves This Browser?

You do not have to take our word for it. Developer tools show every request a page makes, so you can watch this page work and confirm that nothing you type is sent. The check takes under a minute.

  1. Open your browser developer tools with F12, or Cmd+Option+I on a Mac, and select the Network tab.
  2. Reload the page and let it finish. You will see the page's own files, its web fonts, and one anonymous page-view request. Nothing has been typed yet, so none of them can contain your input.
  3. Click the clear icon in the Network tab so that the log is empty.
  4. Switch between the file tabs, copy a file and download the zip.
  5. Look at the Network tab again. It is still empty. Downloads are built in the page as Blob URLs, so even the zip never touches a server. For extra proof, turn on offline mode after the page loads: everything keeps working.

Only the feedback form can add a line to that log, and it sends only the vote and comment you type into it. 2prompt has no server code at all: no API, no model and no database of your files. The production site also sends a Content-Security-Policy header that tells your browser to refuse connections to anywhere except this site, the fonts and the anonymous analytics endpoint.

Was this helpful?