API reference

Complete reference for @outerjs/server: the Outer constructor, every builder method and its config, the schema() builder, plugins, and the object .build() / .start() returns.

For task-oriented explanations, start with the guides — Schema, Permissions, and Procedures.

Package entry points

Import the core builder from the root and the rest from subpath entries:

The schema, secrets, and storage members are only importable from their subpaths — the root exports the builder and context types.

new Outer(params)

import { Outer } from "@outerjs/server";
import { pglite } from "@outerjs/server/pglite";

const outer = new Outer({
  name: "My App",
  baseUrl: "https://api.example.com",
  db: pglite(),
  cors: { origins: ["https://app.example.com"], credentials: true },
});

RateLimitConfig

Over-limit requests get 429 with Retry-After and RateLimit-* headers.

The default store is in-process, so each replica counts separately: behind a load balancer, the effective limit is max × replicas. If your proxy strips both forwarded-IP headers, every anonymous caller shares one bucket — pass key explicitly there.

The header fallback is only trustworthy behind a proxy you control: x-forwarded-for / x-real-ip are plain request headers, so if traffic can reach the server directly a caller spoofs a fresh value per request and never hits the limit. In that setup, set key to something you can trust — a verified client IP or an API-key id.

CorsConfig

pglite(config?)

Embedded, zero-infra Postgres from @outerjs/server/pglite. Returns a { dialect, kind: "postgres" } pair to pass as db.

Bundled extensions

pglite() loads two PGlite extensions into the instance it builds. It returns { dialect, kind, live, client } — live backs Sola’s live queries, and client is the PGlite instance for anything neither the query builder nor Sola covers.

Both packages are optional peers you install yourself: bun add @electric-sql/pglite @electric-sql/pglite-pgvector.

Builder methods

Call them in this order: .schema() → .middleware() → .procedure() → .start() (or .build()).

.auth(), .openapi(), .mcp(), .admin(), .files(), .route(), .resource(), and .use() can appear anywhere before .start() / .build(). .resource() needs a prior .schema() that defines its table.

.schema(schemaResult)

Registers a schema version built with schema(). Every call becomes one migration step, and the latest version types context.db. It takes a single SchemaResult argument and no options.

.auth(config)

Enables Better Auth and mounts ALL /api/auth/**. It narrows context.auth to non-null and resolves the session once per request into context.user and context.session — no getSession middleware, and no extra query however many procedures or checks read it.

AuthConfig is Better Auth’s full BetterAuthOptions minus database, which Outer wires from your db dialect:

.middleware(mw)

Adds an oRPC middleware to the base context. Whatever it returns via next({ context }) is merged into context — and into the types — for every procedure defined after it.

.procedure(name, cb, options?)

Registers an RPC procedure. Dot notation nests namespaces: "user.me" is served at POST /rpc/user/me. The callback receives the oRPC base builder, so chain .input(), .output(), and .handler() on it. Names must be unique, and the _admin namespace is reserved.

options guards the procedure without a hand-written check:

There is no "owner" — that needs a row, which a bare procedure has none of. Use .resource(), or check inside the handler. Any non-public permission is registered at .build(), so forgetting .auth() throws at startup instead of failing per request.

.route(method, path, handler)

Mounts a raw H3 route for webhooks and custom REST endpoints, alongside your RPC routes. handler(event, context) receives the H3 event and the same context procedures get (headers, db, auth, user, session, storage), including the already-resolved session. Raw routes are registered before /rpc/** and win on overlapping paths.

.resource(name, options?)

Generates typed CRUD procedures — list, get, create, update, delete — for a table defined in the latest .schema(). Throws at build time if the table does not exist.

ResourceOptions:

ResourcePermissions — each of list, get, create, update, and delete accepts:

.openapi(config?)

Mounts GET /openapi.json and a plain-JSON REST surface under /rest/** matching the spec. Requires the optional peers @orpc/openapi and @orpc/zod.

.mcp(config?)

Serves the router as an MCP server over Streamable HTTP, so agents can call procedures as tools. Requires the optional peers orpc-mcp and @orpc/zod.

Exposure is opt-in per procedure: only those tagged with the mcp meta helper (mcp.tool(), mcp.resource(), mcp.prompt(), re-exported from @outerjs/server) are visible. The _admin namespace and file.* routes never are. Dots become underscores in tool names, so post.search is called as post_search.

.files(config?)

Mounts the upload surface — file.upload, list, get, delete, attach, detach, plus GET /files/:id — over the tables schema().files() registers. Requires an OuterStorage on the constructor or in config. Full guide: File uploads.

OuterStorage

Three methods, so core depends on no storage vendor. fromUnstorage(storage), fromS3(client, commands, bucket), and memoryStorage() ship with the package; anything else is an object literal.

type OuterStorage = {
  get(key: string): Promise<Uint8Array | null>;
  set(key: string, bytes: Uint8Array): Promise<void>;
  delete(key: string): Promise<void>;
};

OuterSecrets

Runtime-agnostic accessor for env secrets and bindings, passed as new Outer({ secrets }) and surfaced as context.secrets. fromSchema(schema, env) (validates a Zod / Standard Schema and infers the types), fromEnv() (process.env), fromRecord(record) (a typed env object), and memorySecrets(values?) ship with the package. Full guide: Secrets.

type OuterSecrets<T = Record<string, string | undefined>> = {
  get<K extends keyof T & string>(key: K): T[K];
  require<K extends keyof T & string>(key: K): NonNullable<T[K]>; // throws when unset/empty
  readonly all: T;
};

.admin(config?)

Enables the admin API — meta and schema introspection, migration status, and table CRUD — under the reserved _admin namespace at /rpc/_admin/**. Every admin procedure requires a signed-in session with an admin role, so you must also call .auth() or .build() throws.

.use(plugin)

Registers an OuterPlugin. Can appear anywhere before .start() / .build(). Double-registering the same plugin.name throws. Full guide: Plugins.

.build()

Finalizes the chain and returns a BuiltOuter. Throws if any resource permission or .admin() requires auth but .auth() was never called. Does not run migrations — call migrator.migrateToLatest() yourself, or use .start() instead.

.start()

Convenience for the common build() + migrateToLatest() pair. Returns a Promise<BuiltOuter> and throws if migration fails. Prefer this on self-hosted startups; keep .build() when you need manual migration control (deploy scripts, logging the result).

const server = await new Outer({ db: pglite() }).schema(v1_0).start();

BuiltOuter

OuterPlugin

Extension point for third-party and app-specific features. Pass an instance to .use(). Full guide: Plugins.

type OuterPlugin = {
  name: string;
  configure?(): void;
  validate?(ctx: PluginContext): void;
  build?(ctx: PluginContext): PluginResult | void;
};

type PluginResult = {
  procedures?: Record<string, AnyProcedure>;
  routes?: Array<{ method: string; path: string; handler: (event, context) => unknown }>;
  middleware?: Array<(event, next) => Promise<unknown>>;
};

Plugin middleware runs after CORS and rate-limit middleware, before routes. PluginContext exposes resources (read-only), base (oRPC builder), schemas, and name.

schema() builder

import { schema, timestamps } from "@outerjs/server/schema";

export const v1_0_0 = schema("1.0.0")
  .auth()
  .table("post", (t) => ({
    id: t.serial().primaryKey(),
    title: t.text(),
    body: t.text().nullable(),
    authorId: t.text().references("user", "id"),
    meta: t.jsonb().nullable(),
    ...timestamps(t),
  }))
  .relation("user", (rel) => rel.hasMany("post", { from: "id", to: "authorId" }))
  .build();

schema(version)

Starts a schema version. version is a free-form string, such as "1.0.0", shown in the OpenAPI spec and the admin API.

.auth()

Registers the Better Auth core tables (user, session, account, verification) with the admin plugin’s fields (user.role, banned, banReason, banExpires, and session.impersonatedBy) plus their relations.

Extend an auth table by re-declaring extra columns with .table("user", ...) after this call — columns merge, and yours win on name collisions. Never remove or rename the core auth columns.

session.userId and account.userId cascade on delete, so removing a user is never blocked by their sessions.

.files(options?)

Registers a file metadata table for blobs held in an object store — the counterpart to .auth() for uploads. Columns: id (primary key), key (unique, the storage key the bytes live under, so a blob can never be double-registered), name, type (MIME), size, userId (nullable, references user), plus timestamps(t). Exported as FileTables.

The schema stops there: it does not read, write, or serve the bytes. That is .files() on the builder chain.

.table(name, define)

Defines a table, or extends one — re-declaring merges columns, and the later definition wins. define receives the column builder t:

Column modifiers chain, and each returns the column:

timestamps(t)

Returns createdAt and updatedAt timestamp columns with .defaultSql("CURRENT_TIMESTAMP"). Spread it into a .table() column object.

.relation(fromTable, define)

Declares a relation used by context.db.query (Sola) and by resource include. define receives a chain with:

.extend(previous)

Deep-merges another SchemaResult’s tables and relations into this builder. Existing builder columns win on collision (same as re-declaring via .table()). Relations are concatenated and deduped by identity. Call it anywhere in the chain:

const v1_1 = schema("1.1.0")
  .extend(v1_0)
  .table("post", (t) => ({ tags: t.text().nullable() }))
  .build();

Full guide: Schema → Extend a previous version.

.build()

Freezes and returns the SchemaResult you pass to .schema().

Type helpers

context.user and context.session

After .auth(), both are resolved once per request and shared with every procedure, raw route, and permission check. Their types narrow from optional to SessionUser | null and UserSession | null, so you skip the ?. dance:

.procedure("user.me", (base) => base.handler(({ context }) => context.user))

Both are null for anonymous callers, and always null when you never called .auth().