Getting Started

Prerequisites

• Node.js 22 or later (pure ESM)
• npm (ships with Node.js)

Installation

Both packages

npm install ergo ergo-router

ergo only

npm install ergo

Quick Start

Create a server with a single route that demonstrates all four Fast Fail stages:

import createRouter, { graceful } from "ergo-router";

const router = createRouter({
  defaults: {
    accepts: { types: ["application/json"] },
  },
});

router.get("/users/:id", {
  auth: {
    strategies: [
      {
        type: "Bearer",
        authorizer: async (attributes, token) => {
          if (!token) return { authorized: false, info: { statusCode: 401 } };
          return { authorized: true, info: { userId: token } };
        },
      },
    ],
  },
  validate: {
    params: {
      type: "object",
      properties: { id: { type: "string", minLength: 1 } },
      required: ["id"],
    },
  },
  execute: (req, res, acc) => ({
    response: {
      body: {
        id: acc.route.params.id,
        name: "Jane Doe",
        requestedBy: acc.auth.userId,
      },
    },
  }),
});

await graceful(router.handle(), { port: 3000 });

What Happens

Request	Result
GET /users/42 with Accept: text/xml	406 Not Acceptable — negotiation fails
GET /users/42 without Authorization	401 Unauthorized — authorization fails
GET /users/42 with valid Bearer token	200 OK — all stages pass

Every error response is a RFC 9457 Problem Details JSON object.

Next Steps

• Fast Fail Pipeline — understand the four stages in depth
• Standards Compliance — full list of implemented RFCs
• Security — how ergo addresses the OWASP API Security Top 10
• ergo API — middleware reference
• ergo-router API — router and pipeline builder