Middleware and groups

app.use(async (ctx, next) => {
  const started = Date.now();
  await next();
  ctx.header("server-timing", `app;dur=${Date.now() - started}`);
});

const admin = routes().use(requireAdmin).get("/stats", () => stats());
app.mount("/admin", admin);

ctx.state carries things from middleware to the handler. A thrown problem() stops everything, wherever it is thrown.

Who may call itCopy Anchor Link

app.get("/me", { security: "bearer" }, …);                         // authorization: Bearer …
app.get("/feed", { security: { apiKey: "x-api-key" } }, …);       // also in: "query" or "cookie"
app.get("/either", { security: ["bearer", "basic"] }, …);         // any one will do

const admin = routes().security("bearer").get("/stats", …);      // every route of a group
app.security("bearer").get("/health", { security: false }, …);   // the whole app, and an open door

A request without the credentials a route asks for is a 401 problem with a www-authenticate header, before its input is even looked at. Whether the credentials are good stays yours, in an onRequest hook or a middleware: inkan only makes sure the docs cannot promise a lock that is not there. The schemes go into OpenAPI as securitySchemes, the docs page shows a lock on every route that asks, and its token field starts on the right header.

Headers an answer promises are part of the contract too:

app.post("/teas", {
  response: { 201: Tea },
  responseHeaders: { 201: { location: t.string().describe("Where the new tea lives") } },
}, ({ body, reply }) => reply(201, tea, { location: `/teas/${tea.id}` }));

They are in the document and on the docs page, and in development an answer without them breaks the contract like a wrong body does.

CORSCopy Anchor Link

OPTIONS answers on its own with an Allow header. For browsers on another origin, add cors():

import { cors } from "@vxnsin/inkan";

app.register(cors());                                                        // any origin
app.register(cors({ origins: ["https://shop.example"], credentials: true }));  // one origin, with cookies
app.register(cors({ origins: ["https://a.example", "https://b.example"], maxAge: 600 }));
app.register(cors({ origins: (origin) => origin?.endsWith(".shop.example") ?? false }));

cors is a shared plugin, so registered inside a plugin it covers only that plugin's routes. Preflights are answered before routing, and error answers carry the headers too, so the page can read a 404 instead of a CORS error. allowHeaders, exposeHeaders and methods are there when the defaults are not enough.

Routes from the file treeCopy Anchor Link

For a bigger API, one file per path:

routes/index.ts            /
routes/teas/index.ts       /teas
routes/teas/[id].ts        /teas/:id
routes/files/[...rest].ts  /files/*rest

// routes/teas/[id].ts
import { route, t } from "@vxnsin/inkan";

export const GET = route({ params: t.object({ id: t.int() }), response: { 200: Tea } }, ({ params }) => find(params.id));
export const DELETE = route({ params: t.object({ id: t.int() }) }, ({ params }) => remove(params.id));

app.load(new URL("./routes", import.meta.url));

Nothing happens at import time: load reads the folder when you call it, in order with the plugins, and listen waits for it. In a plugin the routes go under its prefix. They are routes like any other, with the same contracts, in OpenAPI and in inkan check. Files starting with _, .d.ts and test files are left alone, so helpers can live next to the routes.

More middlewareCopy Anchor Link

Next to the built-in ones, packages under @inkanjs add what not every app needs. They come with inkan 0.7.0:

Most are shared plugins: app.register(auth({ … })). proxy() brings routes of its own, and circuit() wraps a function. Each names the inkan versions it works with, inkan: ">=0.7.0 <0.8.0", the same range as its peer dependency, so register() throws on an app outside it instead of half-working. To write one of your own, see Writing a plugin.

Built-in, official and community: see everything on Hanko.