Handlers

A handler is the built-in code that a route runs. When you write handler: "readAll" on a route, you do not pass a function: you choose one of the operations that StarkForge already implements, and the route decides where it is served and who may call it. This page lists every handler by collection type, shows how a route picks one and explains what to do when none of them fits.

Choosing a Handler

A route names its handler with a string. The type of the collection decides which names are valid, and the method and path of the route decide where the handler is served:

// src/collections/products.ts (excerpt)
routes: defineRoutes([
  { method: "get", path: "/", handler: "readAll", auth: "public" },
  { method: "post", path: "/", handler: "create", auth: "authenticated", validation: "create" },
]),

Names are case-sensitive, and one handler may serve several routes. StarkForge checks every handler name when it builds the app, so a wrong name stops the server before it listens. The message ends with the list of names that the collection type offers:

ConfigurationError (CONFIGURATION_ERROR): Invalid 'things' collection:
 - GET /things/: handler 'list' is not available for collections of type 'crud'. Available: read, readAll, create, createBulk, update, remove, removeMultiple, removeAll, addFile, updateFile, deleteFile.

In TypeScript, the handler property accepts the name of any built-in handler. Your editor catches a misspelled name, but not a valid name on the wrong type, such as login on a crud collection. The start-up check catches that one.

CRUD Handlers

A crud collection stores documents in the database. It has eight database handlers and three file handlers. The routes in the tables are the convention that this documentation uses. You are free to choose others, as Routes explains.

Database Handlers

File Handlers

The three file handlers work on one document, so their paths start with its id. Each one needs a files entry on the route and the Cloudinary options, as Uploads shows.

Authentication Handlers

You rarely list these yourself. builtinConfig.auth generates an auth collection that holds the routes below, and it adds the routes for magic links, social sign-in and two-factor codes only when you configure those features. You list handlers yourself only when you write your own auth collection. The Authentication page covers both ways.

Account Handlers

The account collection works on the record of the signed-in user. builtinConfig.account generates it with the four handlers below, and every route requires sign-in.

Health Handlers

A health collection has one handler for each HTTP method: healthGet, healthPost, healthPut, healthPatch and healthDelete. All five do the same work. They ping the database and answer 200 when it responds, or 503 when it does not. StarkForge adds GET /api/v1/health for you. Declare a health collection of your own to change its path or its access level.

The Deprecated Admin Handlers

The admin collection type has two handlers, checkRole and checkAdmin, that answer GET /admin/check. The type is kept for 1.x apps. checkAdmin is the old name of checkRole and logs a warning when you use it. New code should use checkRole in the account collection, as Collections explains.

When No Handler Fits

A route can name only the handlers in the tables above. There is no way to pass your own function as handler, because the handler is what validates the body, applies ownership, hides private fields and writes the response in the common format. When you need logic of your own, use the smallest tool that does the job:

A feature module is a class that extends FeatureModule, sets a type and returns a map of handler functions from handlers(). The crud, auth, account, health and admin types are feature modules too, and registering a module with one of those types replaces the built-in one. This is an advanced extension point. The TypeScript types of collection() list only the built-in types and handler names, so a collection for your own type needs a type assertion.

Your Own Express Routes

forge.app is the Express app that StarkForge serves, and you can add routes to it. StarkForge has no hook for adding routes or middleware inside its own pipeline, so where you add a route decides what happens to it:

A route added before start() suits a simple endpoint that does not need those stages. It also suits a webhook that must read the raw body, because no StarkForge parser has touched the request yet, so Express's own express.raw() can read it. This server adds a ping route in the right place:

// src/server.ts
import { Forge } from "@starklabs/forge";

const forge = new Forge();

// This route runs before StarkForge's stages: no body parsing, CORS or rate limit.
forge.app.get("/ping", (_req, res) => {
  res.json({ pong: true });
});

await forge.start();

If an endpoint needs authentication, ownership, validation or the standard error format, build it as a collection, or as a feature module when no built-in handler does the work.

Where to Go Next

:::