srvx Documentation

To avoid dependency conflicts and tsc failures caused by overlapping global declarations (e.g., @types/bun and @types/deno both declaring globals), srvx uses minimal, custom type declarations for each runtime.

These types are structurally compatible with official runtime objects (like Bun.Server, Deno.HttpServer, or AWS Lambda events), meaning you can pass real runtime objects into srvx functions without error. However, because these types only cover the properties that srvx specifically reads or forwards, they are not exhaustive.

When to use official types: If you need access to the full API surface of a specific runtime object beyond what srvx uses, you should cast the object to its official type from the corresponding provider package.

When running behind a reverse proxy (like Nginx or an AWS ALB), set trustProxy to ensure request.url and request.ip are derived correctly from X-Forwarded-* headers.

• false (default): Ignores headers; uses real connection info.
• true: Trusts all hops in the chain.
• "loopback": Trusts only hops on a loopback address (127.0.0.0/8 or ::1).
• string[]: An allowlist of trusted addresses.

srvx uses hop-aware, right-to-left resolution. It treats addresses in the trusted set as proxies you control and identifies the client as the rightmost address not in the trusted set.

import { serve } from "srvx";

serve({
  // Behind a reverse proxy you control:
  trustProxy: true,
  fetch: (request) => new Response(new URL(request.url).protocol),
});

While srvx uses the standard Request object, you can use the ServerRequest type exported from srvx to access extended properties provided by the runtime. These properties include client IP, TLS state, runtime-specific server instances, and lifecycle management methods.

import { serve, type ServerRequest } from "srvx";

serve({
  fetch: (request: ServerRequest) => {
    // Access extended properties here
  }
});

You can extend server behavior using middleware or plugins:

• Middleware: An array of functions (request, next) => Response executed before the main handler.
• Plugins: Synchronous functions that receive the server instance. They are useful for registering middleware or augmenting the server instance during initialization. All plugin-registered middleware is applied before the first request is handled.

import { serve } from "srvx";

// Using middleware
serve({
  middleware: [
    (request, next) => {
      console.log(`[${request.method}] ${request.url}`);
      return next();
    },
  ],
  fetch: () => new Response("👋 Hello there!"),
});

// Using plugins
const myPlugin = (server) => {
  server.options.middleware.push((request, next) => next());
};

serve({
  plugins: [myPlugin],
  fetch: () => new Response("👋 Hello there!"),
});

After creating your server handler, you can start the server using your preferred runtime's CLI tool.

Node.js

Use npx, pnpx, or yarn dlx to run the srvx package.

Deno

Use deno -A npm:srvx to run with all permissions.

Bun

Use bunx --bun srvx for native Bun execution.

# Node.js
$ npx srvx       # npm
$ pnpx srvx      # pnpm
$ yarn dlx srvx  # yarn

# Deno
$ deno -A npm:srvx

# Bun
$ bunx --bun srvx

To serve over HTTPS, provide a tls object containing cert and key in the serve configuration. srvx will automatically switch the protocol to https.

Values for cert and key can be either file paths or inline PEM content. If the string starts with -----BEGIN , it is treated as inline PEM; otherwise, it is treated as a file path.

Security Note: Never commit private keys to version control. Use environment variables or a secret manager to load them.

import { serve } from "srvx";

serve({
  tls: { cert: "./server.crt", key: "./server.key" },
  fetch: () => new Response("👋 Secure hello!"),
});

A request handler in srvx is defined using the fetch key in the configuration object passed to serve. The handler follows the standard Fetch API pattern: it accepts a Request object as input and must return a Response object or a Promise that resolves to a Response if the handler is async.

import { serve } from "srvx";

serve({
  async fetch(request) {
    return new Response(
      `
        <h1>👋 Hello there</h1>
        <p>You are visiting ${request.url} from ${request.ip}</p>
      `,
      { headers: { "Content-Type": "text/html" } },
    );
  },
});

The fetch mode (or curl alias) allows you to test your server by making requests directly from the CLI. It behaves similarly to curl.

Common Fetch Commands

• Fetch default entry: srvx fetch
• Fetch specific path: srvx fetch /api/users
• Fetch with specific entry: srvx fetch --entry ./server.ts /api/users
• POST request: srvx fetch -X POST /api/users
• Add headers: srvx fetch -H "Content-Type: application/json" /api
• Send body: srvx fetch -d '{"name":"foo"}' /api
• Body from stdin: echo '{"name":"foo"}' | srvx fetch -d @- /api
• Verbose output: srvx fetch -v /api/users (shows headers)

Exit Codes

• 0: Success (2xx response)
• 22: Failure (non-2xx response)

# POST a JSON body to an API
$ srvx fetch -X POST -H "Content-Type: application/json" -d '{"name":"foo"}' /api