https://github.com/medz/spry
Spry - A HTTP middleware framework for Dart to make web applications and APIs server more enjoyable to write.
https://github.com/medz/spry
dart freamework http middleware router server spry web
Last synced: 16 days ago
JSON representation
Spry - A HTTP middleware framework for Dart to make web applications and APIs server more enjoyable to write.
- Host: GitHub
- URL: https://github.com/medz/spry
- Owner: medz
- License: mit
- Created: 2022-12-22T11:47:19.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-04-30T16:46:48.000Z (almost 2 years ago)
- Last Synced: 2024-05-01T14:14:58.348Z (almost 2 years ago)
- Topics: dart, freamework, http, middleware, router, server, spry, web
- Language: Dart
- Homepage: https://spry.fun
- Size: 2.38 MB
- Stars: 27
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Spry
[](https://github.com/medz/spry/actions/workflows/test.yml)
[](https://pub.dev/packages/spry)
[](https://github.com/medz/spry/blob/main/LICENSE)
[](https://twitter.com/shiweidu)
[](https://spry.medz.dev/)
[](https://app.netlify.com/projects/dart-spry/deploys)
Next-generation Dart server framework. Build modern servers and deploy them to the runtime you prefer.
## Quick Start
Install the package:
```bash
dart pub add spry
```
Create a minimal project structure:
```text
.
├─ routes/
│ └─ index.dart
└─ spry.config.dart
```
`spry.config.dart`
```dart
import 'package:spry/config.dart';
void main() {
defineSpryConfig(
host: '127.0.0.1',
port: 4000,
target: BuildTarget.vm,
);
}
```
`routes/index.dart`
```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:
```bash
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:
```dart
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:
```dart
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](https://spry.medz.dev/deploy/dart) |
| `exe` | Native executable | [Native executable](https://spry.medz.dev/deploy/dart#native-executable) |
| `aot` | AOT snapshot | [AOT snapshot](https://spry.medz.dev/deploy/dart#aot-snapshot) |
| `jit` | JIT snapshot | [JIT snapshot](https://spry.medz.dev/deploy/dart#jit-snapshot) |
| `kernel` | Kernel snapshot | [Kernel snapshot](https://spry.medz.dev/deploy/dart#kernel-snapshot) |
| `node` | Node.js | [Node.js](https://spry.medz.dev/deploy/node) |
| `bun` | Bun | [Bun](https://spry.medz.dev/deploy/bun) |
| `deno` | Deno | [Deno](https://spry.medz.dev/deploy/deno) |
| `cloudflare` | Cloudflare Workers | [Cloudflare Workers](https://spry.medz.dev/deploy/cloudflare) |
| `vercel` | Vercel | [Vercel](https://spry.medz.dev/deploy/vercel) |
| `netlify` | Netlify Functions | [Netlify Functions](https://spry.medz.dev/deploy/netlify) |
## WebSockets
Spry exposes websocket upgrades from the request event without introducing a
second routing system.
```dart
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
[](https://deepwiki.com/medz/spry)
Read the documentation at [spry.medz.dev](https://spry.medz.dev/).
Start here:
- [Getting Started](https://spry.medz.dev/getting-started)
- [File Routing](https://spry.medz.dev/guide/routing)
- [Configuration](https://spry.medz.dev/config)
- [Deploy Overview](https://spry.medz.dev/deploy/)
## License
[MIT](https://github.com/medz/spry/blob/main/LICENSE)
## Sponsors
Spry framework is an [MIT licensed](https://github.com/medz/spry/blob/main/LICENSE) 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)](https://github.com/sponsors/medz) development.
## Contributing
Thank you to all the people who already contributed to Spry!
[](https://github.com/medz/spry/graphs/contributors)