Route conventions

Every application declares the URL prefixes it owns.

The gateway matches the longest registered prefix and proxies the unchanged request to the application's baseUrl.

Use standard application prefixes

Declare only the prefixes the application serves.

An application with an anonymous page should declare a separate page prefix. Do not place a page below /public/<app-id>; that path is for static files.

Framework-owned paths

app.start() handles these before the application router:

When an application has no basePath, its island chunks use /_ssr/*.

The gateway, Core, OAuth, and other platform applications also own special top-level routes such as /auth, /oauth, and /.well-known/....

Do not reuse a platform prefix.

/_cloud/ready is intentionally checked on the application's private service address, not through the gateway. It responds only after app.start() has completed registration and all awaited lifecycle startup work.

Match and normalize prefixes

A prefix must start with /.

A trailing slash is removed except for /. Query strings do not affect route selection.

The gateway uses the longest matching segment path. For example, /app/inventory/admin wins over /app/inventory when both are registered.

Exact duplicate prefixes are skipped and reported as route warnings. The first application in the deterministic registry ordering keeps the prefix.

Use public IDs in resource routes

When a route addresses an application resource, use that resource's canonical public ID in the path or query. Do not expose an internal database key merely because the router can pass it directly to a query.

Short IDs are optional. If an application adopts them, the same ID belongs in its URLs, APIs, Capabilities, and other public surfaces. See Public resource identifiers for the decision and consistency rules.

Align route declarations

For an API, these values must describe the same public path:

1. defineApp({ routes });
2. the Hono .route() mount;
3. the browser client's baseUrl;
4. the OpenAPI mount when present.

For a page, align the declared route, Hono page mount, and navigation href.

See Routing for an application example.