Can I use this template for Hono on Node or Bun?
The routing and validation rules transfer, but the runtime rules do not. Change the hosting choice in the generator and remove the Workers-specific notes.
A Hono API running on Cloudflare Workers. Workers are not Node.js, and agents trained on Node code reach for APIs that do not exist at the edge; these rules set the runtime expectations.
# AGENTS.md
Project: hono-worker. A Hono API running on Cloudflare Workers with D1 (SQLite) bindings.
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: Hono
- Database: SQLite
- Hosting: Cloudflare
- Tests: Vitest
- Package manager: pnpm
## Commands
Run these from the repository root.
- Install dependencies: `pnpm install`
- Run locally: `pnpm wrangler dev`
- Build: `pnpm wrangler deploy --dry-run`
- Run all tests: `pnpm vitest run`
- Run one test file: `pnpm vitest run test/path.test.ts`
- Lint: `pnpm lint`
- Type-check: `pnpm tsc --noEmit`
- Format: `pnpm prettier --write .`
## Project layout
- `src/index.ts`: The Hono app and route registration
- `src/routes/`: Route groups
- `migrations/`: D1 SQL migrations
- `wrangler.jsonc`: Worker config: bindings, compatibility date
- `worker-configuration.d.ts`: Generated binding types (run wrangler types)
## 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.
## 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 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.
- Ask before creating, editing or running database migrations, and never edit a migration that has already been applied.
- Never run destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, `DROP TABLE`, deleting cloud resources) without explicit approval.
- 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
- The runtime is Cloudflare Workers, not Node.js. Use Web APIs (`fetch`, `Request`, `crypto.subtle`); do not import Node built-ins unless `nodejs_compat` is enabled and they are listed as supported.
- Access bindings (D1, KV, R2, secrets) through `c.env` typed by the `Bindings` generic; never read `process.env`.
- Add secrets with `wrangler secret put`; never put them in `wrangler.jsonc` vars.
- After changing bindings, run `pnpm wrangler types` to regenerate `worker-configuration.d.ts`; do not hand-edit it.
- Create D1 migrations with `wrangler d1 migrations create` and apply locally with `--local` first.
- Do no work at module scope that depends on a request; there is no per-request global state between invocations.
- Validate inputs with `@hono/zod-validator` on each route.
## Project phase
This project is in active development. Follow the patterns that already exist; consistency beats novelty.
# 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.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.
# Copilot instructions
Project: hono-worker. A Hono API running on Cloudflare Workers with D1 (SQLite) bindings.
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: Hono
- Database: SQLite
- Hosting: Cloudflare
- Tests: Vitest
- Package manager: pnpm
## Commands
- Install dependencies: `pnpm install`
- Run locally: `pnpm wrangler dev`
- Build: `pnpm wrangler deploy --dry-run`
- Run all tests: `pnpm vitest run`
- Run one test file: `pnpm vitest run test/path.test.ts`
- Lint: `pnpm lint`
- Type-check: `pnpm tsc --noEmit`
- Format: `pnpm 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 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.
- Ask before creating, editing or running database migrations, and never edit a migration that has already been applied.
- Never run destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, `DROP TABLE`, deleting cloud resources) without explicit approval.
- Change only what the task needs. Do not refactor, rename or reformat unrelated code.
---
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.
The preset describes a a Hono API running on Cloudflare Workers with D1 (SQLite) bindings. Its AGENTS.md is 52 non-empty lines with 8 exact commands, 5 key directories, and 7 stack-specific rules on top of the shared working rules.
pnpm install, pnpm wrangler dev, pnpm wrangler deploy --dry-run, pnpm vitest run, pnpm vitest run test/path.test.ts, pnpm lint, pnpm tsc --noEmit, pnpm prettier --write ..src/index.ts, src/routes/, migrations/, wrangler.jsonc, worker-configuration.d.ts.Agents import fs, path or Buffer out of habit. Some work under the compatibility flag, many do not, and the error appears only at deploy. Naming the runtime first reframes every suggestion the agent makes.
Configuration arrives on the context object per request. Code that reads process.env will be undefined in production even if it seemed to work in a Node test.
Values under vars in the Wrangler config are committed to the repository and visible in the dashboard. Secrets must be set separately.
The type file is produced from the config. Editing it by hand drifts from reality the moment someone adds a binding.
fetch, Request, crypto.subtle); do not import Node built-ins unless nodejs_compat is enabled and they are listed as supported.c.env typed by the Bindings generic; never read process.env.wrangler secret put; never put them in wrangler.jsonc vars.pnpm wrangler types to regenerate worker-configuration.d.ts; do not hand-edit it.wrangler d1 migrations create and apply locally with --local first.@hono/zod-validator on each route.Want different commands or rules? Load this preset into the generator, change anything, and download your own set.
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.
All presets are on the stacks page.
The routing and validation rules transfer, but the runtime rules do not. Change the hosting choice in the generator and remove the Workers-specific notes.
Workers have no separate build step in many projects; a dry run bundles the worker and reports errors without publishing it, which makes it a safe verification command.
The Cloudflare Vitest pool runs tests inside the Workers runtime with local bindings. Configure it once and the test command above covers routes and D1 queries.
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.
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.
F12, or Cmd+Option+I on a Mac, and select the Network tab.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.