Skip to content

docs: add Express-to-Hono migration guide#124

Merged
PAMulligan merged 1 commit into
mainfrom
20-add-migration-guide-from-expressjs-to-nervahono
Jun 13, 2026
Merged

docs: add Express-to-Hono migration guide#124
PAMulligan merged 1 commit into
mainfrom
20-add-migration-guide-from-expressjs-to-nervahono

Conversation

@PAMulligan

Copy link
Copy Markdown
Contributor

Summary

Adds docs/migration/from-express.md — a side-by-side migration guide helping Express.js developers transition to Nerva/Hono. Express is the most common starting point for backend developers evaluating Nerva, so a clear, familiar-pattern → Nerva-pattern mapping directly addresses the #1 question new users have.

What's covered

All required topics, each with Express → Hono comparisons:

  • App setup and middleware registration (express() + app.use()new Hono() + app.use("*", ...), with the npm packages Hono replaces built in)
  • Route definition (app.get/post/put/patch/delete — near-identical, plus chaining)
  • Request/response handling (req.bodyawait c.req.json(), res.jsonreturn c.json, the full input/output mapping)
  • Middleware patterns ((req, res, next)(c, next), before/after split by await next(), short-circuit by returning, typed c.set/c.get vs req.user)
  • Error handling (error middleware → app.onError, throw vs next(err), app.notFound)
  • Route grouping (express.Router()new Hono() + app.route(), group-scoped middleware)
  • Static files (express.staticserveStatic, plus the Workers [assets] caveat)
  • Environment variables and config (the process.env vs Workers c.env trap, centralized through Nerva's Zod-validated config module)

Plus:

  • An Express ↔ Hono cheat-sheet table for quick reference
  • A porting-gotchas checklist (forgotten return, async body, etc.)
  • A "What Nerva adds on top of Hono" section (10-phase pipeline, 24 agents, 12 skills, templates/deployment targets)

Grounding

Examples mirror the actual generated snippets (templates/snippets/node and cloudflare): Zod-validated config.ts, c.env bindings on Workers, the real middleware stack, app.onError with typed errors, and chained new Hono() sub-apps — so the guide stays consistent with what the generator emits.

Docs index

Linked from the README documentation table.

CI

All internal links resolve to existing files; external links limited to hono.dev, hono.dev/docs/api/exception (already used elsewhere in docs), and expressjs.com to keep lychee link validation green.

Fixes #20

🤖 Generated with Claude Code

Add docs/migration/from-express.md mapping every common Express pattern
to its Hono/Nerva equivalent: app setup and middleware registration,
route definition, request/response handling, middleware patterns,
error handling, route grouping, static files, and environment/config.

Includes an Express to Hono cheat-sheet table, a porting-gotchas
checklist, and a section on what Nerva layers on top of Hono (pipeline,
agents, skills, templates). Examples are grounded in the generated
Node and Cloudflare snippets (Zod-validated config, c.env bindings,
app.onError with typed errors, chained Hono sub-apps).

Link the guide from the README documentation index.

Fixes #20

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@PAMulligan PAMulligan linked an issue Jun 13, 2026 that may be closed by this pull request
6 tasks
@github-actions github-actions Bot added the area: docs Documentation label Jun 13, 2026
@PAMulligan PAMulligan self-assigned this Jun 13, 2026
@PAMulligan PAMulligan moved this to In Progress in PMDS Open Source Roadmap Jun 13, 2026
@PAMulligan PAMulligan merged commit b973046 into main Jun 13, 2026
13 checks passed
@github-project-automation github-project-automation Bot moved this from In Progress to Done in PMDS Open Source Roadmap Jun 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs Documentation

Projects

Development

Successfully merging this pull request may close these issues.

Add migration guide from Express.js to Nerva/Hono

1 participant