Lightweight Frameworks Best Practices
A condensed summary of the 25 most important lightweight framework practices - drawn from every page in this section.
//
Search across all documentation pages
A condensed summary of the 25 most important lightweight framework practices - drawn from every page in this section.
Default to Hono for new lightweight work: Active ecosystem, edge portable - Hono Basics.
Do not start new Koa projects: Maintain existing ones; migrate on rewrite - Koa & Polka.
Use createApp() factory pattern: Shared between Node and edge entry points.
Node entry via @hono/node-server: Not raw node:http wrapping.
Validate with Zod at boundaries: @hono/zod-validator for typed input.
Centralized app.onError(): Consistent error JSON.
Use HTTPException for operational errors: 404, 401, 422 with status codes.
Typed context variables: c.set() / c.get() with generics.
Route groups before monolith file: app.route("/users", usersApp).
Built-in middleware first: hono/cors, hono/secure-headers, hono/logger.
Abstract Node-only APIs: No node:fs in shared app code - Hono on Node vs Edge.
HTTP-based DB drivers on edge: Neon serverless, Supabase, Prisma Accelerate.
Test with app.request(): No port binding needed.
Environment config via factory parameter: Not process.env in shared code.
Polka only for internal micro-sidecars: < 5 endpoints, no auth.
Add structure before 200 lines: Split into route modules early.
Run framework selection checklist: Before committing - Framework Selection Checklist.
Record ADR with revisit date: 12 months or at 10x load.
Do not mix frameworks in one service: One HTTP framework per deployable.
Profile before claiming size wins: I/O usually dominates over framework choice.
OpenAPI via @hono/zod-openapi: Contract-first documentation.
CORS explicit origins: Never wildcard with credentials.
Keep handlers thin: Business logic in separate service functions.
Plan Koa migration as a sprint: Not incremental; rewrite routes.
Edge for latency; Node for complexity: Split services by runtime need, not ideology.
Hono for new projects. Fastify if you need maximum Node throughput. Express if team familiarity is paramount.
On next major rewrite, yes. For stable low-churn apps, migration cost may not justify.
Below 3 endpoints on an internal port: raw HTTP is fine. Above 5: use Hono at minimum.
Hono and Fastify can. At that scale, consider NestJS for module boundaries or enforce strict route file conventions.
Route groups, service layer, Zod validation, and error handler from day one. Add structure at endpoint 10, not endpoint 50.
Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.
Reviewed by Chris St. John·Last updated Jul 19, 2026