Skip to main content
api-common

Reusable, framework-agnostic building blocks for Node.js APIs — errors, auth, rate limiting, validation, config, logging, and OpenAPI docs, with Express and Hono adapters.

server.ts
import { loadEnv } from '@rtorcato/api-config'
import { NotFoundError } from '@rtorcato/api-errors'
import { errorHandler } from '@rtorcato/api-errors-express'
import { ok } from '@rtorcato/api-response'
import { validate } from '@rtorcato/api-validation'
import { z } from 'zod'

const env = loadEnv(z.object({ PORT: z.coerce.number().default(3000) }))

app.post('/users', (req, res) => {
const body = validate(z.object({ name: z.string() }), req.body)
res.status(201).json(ok(body))
})

app.get('/users/:id', (req, res) => {
throw new NotFoundError('User not found')
})

app.use(errorHandler())
npm install @rtorcato/api-errors
Mix and match
Mix and match
Focused packages — errors, auth, rate limiting, validation, config, logging, OpenAPI. Install only what you need.
One response contract
One response contract
Errors map to `{ error, code, message }`, successes to `{ success, data }` — identical JSON across Express and Hono.
TypeScript-first
TypeScript-first
Strict types, typed handler options, JSDoc-rich in your IDE. Zero runtime dependencies in the core.
Bring your own framework
Bring your own framework
Express and Hono adapters keep the framework as a peer dependency — you control the version.
OpenAPI

Docs that can't drift

Build an OpenAPI 3.1 document from the same Zod schemas you validate requests with, then serve a Scalar or Swagger UI on Express or Hono. Change a schema and the reference changes with it — no hand-written spec to fall out of sync.

  • Schema-first — one source for validation and docs
  • Scalar & Swagger UI, Express & Hono adapters
  • ts-rest contracts render docs out of the box

One toolkit, one contract

Install only the pieces you need — each package is independent, with framework adapters as peer deps.

Browse the guides →
@rtorcato/api-errors
Errors

Framework-agnostic HTTP error classes: HttpError plus 400/401/403/404/409/500 subclasses, each carrying status + code.

CoreExpressHono
@rtorcato/api-auth
Auth

JWT utilities — sign, verify, and extract bearer tokens — with an Express adapter for auth and optional-auth middleware.

CoreExpress
@rtorcato/api-rate-limit
Rate limit

In-memory sliding-window rate limiter with matching Express and Hono middleware adapters.

CoreExpressHono
@rtorcato/api-openapi
API docs

HTML generators for Swagger UI and Scalar API Reference, plus Express and Hono adapters to serve them from an OpenAPI spec.

Swagger UIScalarExpressHono
@rtorcato/api-validation
Validation

Zod request validation that throws a BadRequestError on failure — wires straight into the error handler.

zodBadRequestError
@rtorcato/api-response
Responses

Consistent success-response envelope for JSON APIs — the success-path counterpart to api-errors.

envelope
@rtorcato/api-config
Config

Load and validate environment variables with dotenv + zod at startup, failing fast on bad config.

dotenvzod
@rtorcato/api-logger
Logging

Pino logger factory — pretty output in development, structured JSON in production.

pino
@rtorcato/api-cors-express
CORS

Opinionated CORS middleware for Express with sane defaults and a small config surface.

Express
@rtorcato/api-express-utils
Express utils

Small Express helpers — client IP extraction and route listing for boot-time logging.

getIPlogRoutes
@rtorcato/api-testing
Testing

Helpers for testing Express and Hono routes against the shared error and response contract.

ExpressHono

Sibling projects

More from @rtorcato — same conventions, same release pipeline.