osrv 0.4.0

Unified Dart server runtime for Dart, Node, Bun, Cloudflare, and Vercel.

osrv

osrv is a unified server runtime for Dart applications.

It provides one portable Server contract and explicit runtime entrypoints for:

• dart
• node
• bun
• cloudflare
• vercel

osrv is a runtime layer focused on running the same server contract across different host families, while keeping runtime capabilities and host-specific extensions explicit.

Why osrv

Use osrv when you want:

• one request-handling contract across multiple runtime families
• explicit runtime selection instead of host auto-detection
• honest capability reporting instead of fake cross-platform uniformity
• typed runtime extensions for host-specific access

Features

• Unified Server contract built around Request, Response, and RequestContext
• Explicit runtime selection through runtime-specific serve(...) or defineFetchExport(...)
• Runtime capability model via RuntimeCapabilities
• Lifecycle hooks: onStart, onStop, and onError
• Typed runtime-specific extension access
• Separate entry models for listener runtimes and fetch-export runtimes

Installation

dart pub add osrv

Supported Runtimes

Runtime	Entry model	Import
dart	serve(server, host: ..., port: ...)	package:osrv/runtime/dart.dart
node	serve(server, host: ..., port: ...)	package:osrv/runtime/node.dart
bun	serve(server, host: ..., port: ...)	package:osrv/runtime/bun.dart
cloudflare	defineFetchExport(server)	package:osrv/runtime/cloudflare.dart
vercel	defineFetchExport(server)	package:osrv/runtime/vercel.dart

Target notes:

• package:osrv/runtime/dart.dart is the native Dart listener entry.
• package:osrv/runtime/node.dart, package:osrv/runtime/bun.dart, package:osrv/runtime/cloudflare.dart, and package:osrv/runtime/vercel.dart are JavaScript-target runtime entries and intentionally do not compile to native executables.

Quick Start

Serve-Based Runtime

import 'package:osrv/osrv.dart';
import 'package:osrv/runtime/dart.dart';

Future<void> main() async {
  final server = Server(
    fetch: (request, context) {
      return Response.json({
        'runtime': context.runtime.name,
        'path': request.url.path,
      });
    },
  );

  final runtime = await serve(
    server,
    host: '127.0.0.1',
    port: 3000,
  );

  print('Listening on ${runtime.url}');
}

Fetch-Export Runtime

import 'package:osrv/osrv.dart';
import 'package:osrv/runtime/cloudflare.dart';

void main() {
  defineFetchExport(
    Server(
      fetch: (request, context) => Response.text('Hello from osrv'),
    ),
  );
}

Example JavaScript shim:

import './cloudflare.dart.js';

export default { fetch: globalThis.__osrv_fetch__ };

For Vercel, use a bootstrap entry that sets globalThis.self ??= globalThis before importing the compiled Dart module. The deploying project must also include @vercel/functions, use an ESM entry such as .mjs, and provide a minimal vercel.json. See doc/runtime/vercel.md.

Core API

The public core entrypoint is package:osrv/osrv.dart.

Main exported concepts:

• Server
• Runtime
• RequestContext
• RuntimeCapabilities
• RuntimeExtension

For runtime entry APIs, use the matching runtime entrypoint such as package:osrv/runtime/dart.dart, package:osrv/runtime/node.dart, package:osrv/runtime/bun.dart, package:osrv/runtime/cloudflare.dart, or package:osrv/runtime/vercel.dart.

Documentation

• Documentation Index
• Architecture
• Configuration
• Capabilities
• Core API
• Runtime API
• Public Surface
• Runtime Guides
• Usage Examples

Examples

The example directory contains runnable minimal entries for:

• dart
• node
• bun
• cloudflare
• vercel

License

MIT