Spry

Next-generation Dart server framework. Build modern servers and deploy them to the runtime you prefer.

Quick Start

Install the package:

dart pub add spry

Create a minimal project structure:

.
├─ routes/
│  └─ index.dart
└─ spry.config.dart

spry.config.dart

import 'package:spry/config.dart';

void main() {
  defineSpryConfig(
    host: '127.0.0.1',
    port: 4000,
    target: BuildTarget.vm,
  );
}

routes/index.dart

import 'package:spry/spry.dart';

Response handler(Event event) {
  return Response.json({
    'message': 'hello from spry',
    'runtime': event.context.runtime.name,
    'path': event.url.path,
  });
}

Start the dev server:

dart run spry serve

Core Ideas

• routes/ defines request handlers with file routing
• middleware/ and _middleware.dart shape cross-cutting request behavior
• _error.dart provides scoped error handling
• defineHandler(...) adds handler-local middleware and error handling
• public/ serves static assets directly
• spry.config.dart selects the runtime target and build behavior

OpenAPI

Spry can generate an openapi.json document as part of the normal build pipeline.

Use package:spry/config.dart for the build-side config and package:spry/openapi.dart for the document objects:

import 'package:spry/config.dart';
import 'package:spry/openapi.dart';

void main() {
  defineSpryConfig(
    openapi: OpenAPIConfig(
      document: OpenAPIDocumentConfig(
        info: OpenAPIInfo(title: 'Spry API', version: '1.0.0'),
      ),
      output: OpenAPIOutput.route('openapi.json'),
    ),
  );
}

Route files can expose top-level openapi metadata:

import 'package:spry/openapi.dart';

final openapi = OpenAPI(
  summary: 'List users',
  tags: ['users'],
);

Key rules:

• OpenAPIConfig.document.components defines document-level components.
• Route-level OpenAPI(..., globalComponents: ...) is lifted into document components during generation.
• A route without a method suffix expands to GET, POST, PUT, PATCH, DELETE, and OPTIONS in OpenAPI.
• HEAD is only emitted when a route explicitly defines .head.dart.
• OpenAPIOutput.route('openapi.json') writes the file into public/, so it is served like any other static asset.

Runtime Targets

Spry can emit output for:

Target	Runtime	Deploy Docs
vm	Dart VM	Dart VM
exe	Native executable	Native executable
aot	AOT snapshot	AOT snapshot
jit	JIT snapshot	JIT snapshot
kernel	Kernel snapshot	Kernel snapshot
node	Node.js	Node.js
bun	Bun	Bun
deno	Deno	Deno
cloudflare	Cloudflare Workers	Cloudflare Workers
vercel	Vercel	Vercel
netlify	Netlify Functions	Netlify Functions

WebSockets

Spry exposes websocket upgrades from the request event without introducing a second routing system.

import 'package:spry/spry.dart';
import 'package:spry/websocket.dart';

Response handler(Event event) {
  if (!event.ws.isSupported || !event.ws.isUpgradeRequest) {
    return Response('plain http fallback');
  }

  return event.ws.upgrade((ws) async {
    ws.sendText('connected');

    await for (final message in ws.events) {
      switch (message) {
        case TextDataReceived(text: final text):
          ws.sendText('echo:$text');
        case BinaryDataReceived():
        case CloseReceived():
          break;
      }
    }
  }, protocol: 'chat');
}

Current websocket support follows the underlying osrv runtime surface:

• supported: Dart VM, Node.js, Bun, Deno, Cloudflare Workers
• unsupported: Vercel, current Netlify Functions runtime

Documentation

Read the documentation at spry.medz.dev.

Start here:

• Getting Started
• File Routing
• Configuration
• Deploy Overview

License

MIT

Sponsors

Spry framework is an MIT licensed open source project with its ongoing development made possible entirely by the support of these awesome backers. If you'd like to join them, please consider sponsoring Seven(@medz) development.

Contributing

Thank you to all the people who already contributed to Spry!