// Migrate a Dart web server from Shelf to Relic. Side-by-side reference for every API change. Use when converting Shelf code to Relic, replacing shelf/shelf_router/shelf_web_socket imports, or upgrading an existing server.
Bootstrap a Relic web server, configure RelicApp, start serving, and enable hot reload. Use when creating a new Relic project, setting up a server, or configuring the development workflow.
Create and apply middleware for auth, CORS, logging, and other cross-cutting concerns. Use context properties for type-safe request-scoped data. Use when adding middleware, request/response transformations, or passing data between middleware and handlers.
Handle HTTP requests and create responses with Body, headers, and status codes in Relic. Use when reading request data, parsing JSON, building API responses, working with headers, or streaming content.
Define routes with path parameters, wildcards, tail segments, and typed params in Relic. Use when adding endpoints, handling dynamic URLs, setting up URL patterns, or forwarding requests.
Serve static files and directories with caching and cache busting in Relic. Use when serving assets, images, CSS, JS, favicons, or configuring HTTP cache control headers.
Handle WebSocket connections and hijack connections for SSE or custom protocols in Relic. Use when implementing real-time communication, WebSocket endpoints, or server-sent events.
| name | relic-shelf-migration |
| description | Migrate a Dart web server from Shelf to Relic. Side-by-side reference for every API change. Use when converting Shelf code to Relic, replacing shelf/shelf_router/shelf_web_socket imports, or upgrading an existing server. |
Relic replaces shelf, shelf_router, and shelf_web_socket with a single package. Core concepts (handlers, middleware, requests, responses) carry over with improved type safety.
Remove Shelf packages, add Relic:
# Before (Shelf)
dependencies:
shelf: <version>
shelf_router: <version>
shelf_web_socket: <version>
# After (Relic)
dependencies:
relic: <latest_version>
Shelf:
import 'package:shelf_router/shelf_router.dart';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;
void main() async {
final app = Router();
// Add routes...
await io.serve(app, 'localhost', 8080);
}
Relic:
import 'package:relic/relic.dart';
Future<void> main() async {
final app = RelicApp()
..get('/users/:id', (Request request) {
final id = request.rawPathParameters[#id];
final name = request.url.queryParameters['name'] ?? 'Unknown';
return Response.ok(body: Body.fromString('User $id: $name'));
});
await app.serve(address: InternetAddress.loopbackIPv4, port: 8080);
}
Shelf:
Response handler(Request request) {
return Response.ok('Hello from Shelf!');
}
Relic: Handler returns Result (usually Response). Body requires explicit Body object:
Response handler(Request request) {
return Response.ok(body: Body.fromString('Hello from Relic!'));
}
Shelf: Path params use <id> and are passed as handler arguments:
final router = Router()
..get('/users/<id>', (Request request, String id) {
return Response.ok('User $id');
});
Relic: Path params use :id and are read from request.pathParameters:
final router = RelicApp()
..get('/users/:id', (Request request) {
final id = request.pathParameters.raw[#id];
return Response.ok(body: Body.fromString('User $id'));
});
Shelf: Accepts plain strings, sets Content-Type via headers map:
Response.ok('Hello, World!');
Response.ok(
'<html>...</html>',
headers: {'content-type': 'text/html'},
);
Relic: Requires Body object. Content-Length is automatic. MIME type is auto-detected or explicit:
Response.ok(body: Body.fromString('Hello, World!'));
Response.ok(
body: Body.fromString('<html>...</html>', mimeType: MimeType.html),
);
Shelf: String-based, manual parsing:
final contentType = request.headers['content-type']; // String?
final cookies = request.headers['cookie']; // String?
final date = request.headers['date']; // String?
Relic: Type-safe accessors with automatic parsing:
final contentType = request.body.bodyType?.mimeType; // MimeType?
final cookies = request.headers.cookie; // CookieHeader?
final date = request.headers.date; // DateTime?
Shelf: Pipeline applies middleware to all requests including 404s:
final app = Router()
..get('/api/users', (Request request) {
return Response.ok('User data');
});
final handler = Pipeline()
.addMiddleware(logRequests())
.addMiddleware(authentication())
.addHandler(app);
Relic: router.use() scopes middleware by path and only runs on matched routes:
final app = RelicApp()
..use('/', logRequests())
..use('/api', authentication())
..get('/api/users', (Request request) async {
return Response.ok(body: Body.fromString('User data'));
});
Unmatched requests (404s) bypass middleware and go directly to the fallback handler.
Shelf: Dynamic map with manual casting:
final modifiedRequest = request.change(context: {
'user': currentUser,
'session': sessionData,
});
// Later...
final user = request.context['user'] as User?;
Relic: Type-safe ContextProperty with extension methods:
final userProperty = ContextProperty<User>('user');
final sessionProperty = ContextProperty<Session>('session');
extension AuthContext on Request {
User get currentUser => userProperty[this];
Session get session => sessionProperty[this];
}
// Set in middleware
userProperty[req] = authenticatedUser;
// Read in handler -- type-safe, no casting
final user = req.currentUser;
final session = req.session;
Shelf: Requires separate shelf_web_socket package:
import 'package:shelf_web_socket/shelf_web_socket.dart';
var handler = webSocketHandler((webSocket) {
webSocket.stream.listen((message) {
print('Received: $message');
});
webSocket.sink.add('Hello!');
});
Relic: Built-in, return WebSocketUpgrade from any handler:
WebSocketUpgrade websocketHandler(Request request) {
return WebSocketUpgrade((ws) async {
ws.events.listen((event) {
log('Received: $event');
});
ws.trySendText('Hello!');
ws.sendText('Hello!');
});
}
import 'package:shelf/shelf.dart';
import 'package:shelf_router/shelf_router.dart';
import 'package:shelf/shelf_io.dart' as shelf_io;
void main() async {
final router = Router()
..get('/users/<id>', (Request request, String id) {
final name = request.url.queryParameters['name'] ?? 'Unknown';
return Response.ok('User $id: $name');
});
final handler = Pipeline()
.addMiddleware(logRequests())
.addHandler(router);
await shelf_io.serve(handler, 'localhost', 8080);
}
import 'package:relic/relic.dart';
Future<void> main() async {
final app = RelicApp()
..use('/', logRequests())
..get('/users/:id', (Request request) {
final id = request.rawPathParameters[#id];
final name = request.url.queryParameters['name'] ?? 'Unknown';
return Response.ok(body: Body.fromString('User $id: $name'));
});
await app.serve(address: InternetAddress.loopbackIPv4, port: 8080);
}
| Shelf | Relic |
|---|---|
import 'package:shelf/shelf.dart' | import 'package:relic/relic.dart' |
shelf_io.serve(handler, host, port) | RelicApp().serve(address: addr, port: port) |
Response.ok('text') | Response.ok(body: Body.fromString('text')) |
Router()..get('/path/<id>', (req, id) {...}) | RelicApp()..get('/path/:id', (req) {...}) |
request.headers['name'] | request.headers.name (typed) |
Pipeline().addMiddleware(mw).addHandler(h) | app.use('/', mw) |
request.change(context: {...}) | ContextProperty<T>()[req] = value |
shelf_web_socket package | Built-in WebSocketUpgrade |