Full API

examples/full-api in the Routa repository exercises the whole public surface: layered middleware, route groups, tenant-scoped context, flat and directory routing, deprecation metadata, automatic OPTIONS, scaffold workflows, and a custom logger adapter.

pnpm install
pnpm --filter full-api dev

What Is Inside

• Directorysrc/

  • routa.ts host, port, logger, lifecycleHeaders
  • logger.ts optional Pino adapter
  • Directorymiddleware/ application-owned middleware

    • …
  • Directoryroutes/

    • middleware.ts withRequest, withSession
    • Directorystatus/

      • …
    • legacy.ts flat route with deprecation
    • legacy.$id.ts flat route with a dynamic segment
    • Directory(private)/

      • middleware.ts withAuth
      • Directoryadmin/

        • middleware.ts withAdmin
        • Directoryaudit-events/

          • …
        • reports.ts
      • Directorytenants/

        • Directory$tenantId/

          • middleware.ts withTenant
          • Directoryprojects/

            • …
    • Directoryshowcase/

      • Directory$itemId/

        • route.ts
    • Directorylogger-showcase/

      • route.ts

How It Works

The middleware chain accumulates down the tree. src/routes/middleware.ts provides requestId and session for everything. (private)/middleware.ts adds auth, and (private)/admin/middleware.ts adds admin on top of it. By the time audit-events/route.ts runs, ctx carries all four keys and each one is typed.

(private) is a route group: it shapes the middleware tree without appearing in any URL. /admin/audit-events is the real path, not /private/admin/audit-events.

src/routes/legacy.ts and legacy.$id.ts use flat routing in the same project as the directory-style routes, which is the clearest demonstration that the two styles mix.

Each middleware.ts re-exports contracts from src/middleware/, keeping the routing tree declarative while the implementations live in application-owned modules.

What to Study

File	Shows
src/routes/middleware.ts	Root middleware applied to every route
src/middleware/context.ts	Middleware input reading headers and cookies
src/middleware/admin.ts	requires, provides, rejects, and openapi.permissions together
src/routes/(private)/tenants/$tenantId/middleware.ts	Context derived from a path parameter
src/routes/legacy.ts	Deprecation metadata with a replacement
src/logger.ts	Adapting Pino to the RoutaLogger contract
src/routes/showcase/$itemId/route.ts	Logging from a handler through ctx.logger

The Logger Showcase

src/routes/logger-showcase/route.ts calls every RoutaLogger member: log, each level through silent, child, bindings, and isLevelEnabled. It is disabled by default because the sequence deliberately emits error and fatal events that would otherwise pollute normal output.

To run it, start the example with the showcase enabled and exercise it from a second terminal:

ROUTA_DEMO_LOGGER_SHOWCASE=on LOG_LEVEL=trace pnpm --filter full-api dev
pnpm --filter full-api logger:exercise

Restarting with ROUTA_DEMO_LOGGER=off runs the identical handler through Routa’s complete no-op logger, which is the point: handler code does not change when logging is disabled.

Limits

Pino belongs to this example only. @routa-ts/core exposes a structural logger contract and depends on no logging package, so the adapter in src/logger.ts is a demonstration rather than a requirement.

Demonstration credentials

The session middleware in this example verifies a signed demo token from an environment variable. It illustrates where authentication attaches, and it is not an authentication implementation to copy.

Next Steps

MiddlewareThe model these chains implement.

RoutingGroups and flat files as used here.

API evolutionThe deprecation workflow the legacy routes show.