Skip to content
Oxide
Esc
↑↓navigate↵open⌘Jpreview
On this page

Server Entry

Own the routes you care about. Return nothing and Oxide serves static files (and SPA navigations).

When src/server.ts exists, requests reach that entry after middleware and actions. Export a fetch — named or on the default export. Missing the default path is fine: Oxide still serves actions and static assets. On preset: "worker" the runtime also passes Worker env and ctx, the same pair actions read with useEnv() / useFetchCtx().

Type it with FetchHandler:

import type { type FetchHandler<Env extends object = { [key: string]: OxidejsJson; }> = (request: Request, env: Env, ctx: ExecutionContext) => FetchResult | Promise<FetchResult>
`src/server.ts` fetch handler. The generated wrapper always calls
`fetch(request, env, ctx)` — `env` may be `{}` on Node without the `env` option.
Return `undefined` (or bare `return`) to fall through to assets.
FetchHandler } from "oxidejs";

type 
type Env = {
    SECRET?: string;
}
Env = { SECRET?: string | undefinedSECRET?: string };

export const const fetch: (request: Request, _env: Env, ctx: ExecutionContext) => Response | undefinedfetch = ((request: Requestrequest, _env: Env_env, ctx: ExecutionContextctx) => {
  if (new var URL: new (url: string | URL, base?: string | URL) => URL
The **`URL`** interface is used to parse, construct, normalize, and encode URLs. It works by providing properties which allow you to easily read and modify the components of a URL.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/URL)
URL(request: Requestrequest.Request.url: string
The **`url`** read-only property of the Request interface contains the URL of the request.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/url)
url).URL.pathname: string
The **`pathname`** property of the URL interface represents a location in a hierarchical structure. It is a string constructed from a list of path segments, each of which is prefixed by a / character.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/pathname)
pathname === "/api/ok") {
    ctx: ExecutionContextctx.ExecutionContext.waitUntil?: ((promise: PromiseLike<OxidejsJson | object | null | undefined>) => void) | undefinedwaitUntil?.(var Promise: PromiseConstructor
Represents the completion of an asynchronous operation
Promise.PromiseConstructor.resolve<null>(value: null): Promise<null> (+2 overloads)
Creates a new resolved promise for the provided value.
@paramvalue A promise.@returnsA promise whose internal state matches the provided promise.
resolve(null));
    return new var Response: new (body?: BodyInit | null, init?: ResponseInit) => Response
The **`Response`** interface of the Fetch API represents the response to a request.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Response)
Response("ok");
  }
  return;
}) satisfies type FetchHandler<Env extends object = { [key: string]: OxidejsJson; }> = (request: Request, env: Env, ctx: ExecutionContext) => FetchResult | Promise<FetchResult>
`src/server.ts` fetch handler. The generated wrapper always calls
`fetch(request, env, ctx)` — `env` may be `{}` on Node without the `env` option.
Return `undefined` (or bare `return`) to fall through to assets.
FetchHandler<
type Env = {
    SECRET?: string;
}
Env>;

Bare return (or undefined) means fall through. With a page in the project, Oxide tries a matching static file, then index.html for navigations (Sec-Fetch-Dest: document or Accept: text/html). A fetch for /missing.js stays 404 — not a silent SPA rewrite.

export default { fetch } works when you prefer an object entry (or need scheduled / queue on the default for Cloudflare Workers mode). If both a default fetch and a named fetch exist, the default wins.

On Node, public/ is copied next to the client. Hashed assets get Cache-Control: immutable and ETag / 304. index.html is no-cache. Without a page, the build is only the server bundle — there is nothing to fall through to.

Named exports such as scheduled and queue are re-exported (export *). Put them on export default { … } as well when the host only reads the default.

On Node the generated server handles SIGTERM / SIGINT: stop accepting connections, drain in-flight requests, force exit after 5 seconds.

FetchHandler

import type { type FetchHandler<Env extends object = { [key: string]: OxidejsJson; }> = (request: Request, env: Env, ctx: ExecutionContext) => FetchResult | Promise<FetchResult>
`src/server.ts` fetch handler. The generated wrapper always calls
`fetch(request, env, ctx)` — `env` may be `{}` on Node without the `env` option.
Return `undefined` (or bare `return`) to fall through to assets.
FetchHandler } from "oxidejs";

// request, env, ctx — return Response, or fall through with bare `return`
declare const 
const fetch: FetchHandler<{
    SECRET?: string;
}>
fetch: type FetchHandler<Env extends object = { [key: string]: OxidejsJson; }> = (request: Request, env: Env, ctx: ExecutionContext) => FetchResult | Promise<FetchResult>
`src/server.ts` fetch handler. The generated wrapper always calls
`fetch(request, env, ctx)` — `env` may be `{}` on Node without the `env` option.
Return `undefined` (or bare `return`) to fall through to assets.
FetchHandler<{ SECRET?: string | undefinedSECRET?: string }>;

Env defaults to a JSON-compatible binding bag. Pass your Worker / env shape as the type argument. The wrapper always supplies env and ctx.

Prefer satisfies FetchHandler<Env> so parameters pick up types without annotations. Under noImplicitReturns, use a bare return when you want fallthrough.

ServerEntry

import type { type FetchHandler<Env extends object = { [key: string]: OxidejsJson; }> = (request: Request, env: Env, ctx: ExecutionContext) => FetchResult | Promise<FetchResult>
`src/server.ts` fetch handler. The generated wrapper always calls
`fetch(request, env, ctx)` — `env` may be `{}` on Node without the `env` option.
Return `undefined` (or bare `return`) to fall through to assets.
FetchHandler, interface ServerEntry<Env extends object = { [key: string]: OxidejsJson; }>
Default export shape for `src/server.ts`.
ServerEntry } from "oxidejs";

type 
type Env = {
    SECRET?: string;
}
Env = { SECRET?: string | undefinedSECRET?: string };

declare const const fetch: FetchHandler<Env>fetch: type FetchHandler<Env extends object = { [key: string]: OxidejsJson; }> = (request: Request, env: Env, ctx: ExecutionContext) => FetchResult | Promise<FetchResult>
`src/server.ts` fetch handler. The generated wrapper always calls
`fetch(request, env, ctx)` — `env` may be `{}` on Node without the `env` option.
Return `undefined` (or bare `return`) to fall through to assets.
FetchHandler<
type Env = {
    SECRET?: string;
}
Env>;
declare const const entry: ServerEntry<Env>entry: interface ServerEntry<Env extends object = { [key: string]: OxidejsJson; }>
Default export shape for `src/server.ts`.
ServerEntry<
type Env = {
    SECRET?: string;
}
Env>;

Object form:

import type { type FetchHandler<Env extends object = { [key: string]: OxidejsJson; }> = (request: Request, env: Env, ctx: ExecutionContext) => FetchResult | Promise<FetchResult>
`src/server.ts` fetch handler. The generated wrapper always calls
`fetch(request, env, ctx)` — `env` may be `{}` on Node without the `env` option.
Return `undefined` (or bare `return`) to fall through to assets.
FetchHandler, interface ServerEntry<Env extends object = { [key: string]: OxidejsJson; }>
Default export shape for `src/server.ts`.
ServerEntry } from "oxidejs";

type 
type Env = {
    SECRET?: string;
}
Env = { SECRET?: string | undefinedSECRET?: string };

const const fetch: (request: Request, _env: Env) => Response | undefinedfetch = ((request: Requestrequest, _env: Env_env) => {
  if (new var URL: new (url: string | URL, base?: string | URL) => URL
The **`URL`** interface is used to parse, construct, normalize, and encode URLs. It works by providing properties which allow you to easily read and modify the components of a URL.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/URL)
URL(request: Requestrequest.Request.url: string
The **`url`** read-only property of the Request interface contains the URL of the request.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/url)
url).URL.pathname: string
The **`pathname`** property of the URL interface represents a location in a hierarchical structure. It is a string constructed from a list of path segments, each of which is prefixed by a / character.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/pathname)
pathname === "/api/ok") {
    return new var Response: new (body?: BodyInit | null, init?: ResponseInit) => Response
The **`Response`** interface of the Fetch API represents the response to a request.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/Response)
Response("ok");
  }
  return;
}) satisfies type FetchHandler<Env extends object = { [key: string]: OxidejsJson; }> = (request: Request, env: Env, ctx: ExecutionContext) => FetchResult | Promise<FetchResult>
`src/server.ts` fetch handler. The generated wrapper always calls
`fetch(request, env, ctx)` — `env` may be `{}` on Node without the `env` option.
Return `undefined` (or bare `return`) to fall through to assets.
FetchHandler<
type Env = {
    SECRET?: string;
}
Env>;

export default { ServerEntry<Env>.fetch: FetchHandler<Env>fetch } satisfies interface ServerEntry<Env extends object = { [key: string]: OxidejsJson; }>
Default export shape for `src/server.ts`.
ServerEntry<
type Env = {
    SECRET?: string;
}
Env>;

Was this page helpful?