Shelf Framework Guide

Applies to: Shelf 1.x, Dart 3.x, REST APIs, Microservices, Backend Services Complements: .claude/skills/dart-guide/SKILL.md

Core Principles

Middleware Composition: Everything flows through Pipeline; compose handlers with addMiddleware and addHandler
Handler Simplicity: A Handler is just FutureOr<Response> Function(Request) -- keep it functional
Immutable Requests: Use request.change() to pass data downstream via context
Cascade Routing: Use Cascade to try multiple handlers in sequence until one succeeds
Separation of Concerns: Handlers call services, services call repositories -- no business logic in middleware

Project Structure

myapp/
├── bin/
│   └── server.dart               # Entry point (thin: config, serve, shutdown)
├── lib/
│   ├── src/
│   │   ├── app.dart              # Pipeline + Router assembly
│   │   ├── config/
│   │   │   └── config.dart       # Environment-based configuration
│   │   ├── handlers/
│   │   │   ├── health_handler.dart
│   │   │   └── users_handler.dart
│   │   ├── middleware/
│   │   │   ├── auth_middleware.dart
│   │   │   ├── cors_middleware.dart
│   │   │   └── logging_middleware.dart
│   │   ├── models/
│   │   │   └── user.dart
│   │   ├── repositories/
│   │   │   └── user_repository.dart
│   │   └── services/
│   │       └── user_service.dart
│   └── myapp.dart                # Library barrel export
├── test/
│   ├── handlers/
│   │   └── users_handler_test.dart
│   └── middleware/
│       └── auth_middleware_test.dart
├── pubspec.yaml
├── analysis_options.yaml
└── Dockerfile

Architectural rules:

bin/server.dart is thin: load config, create handler, call shelf_io.serve, wire shutdown
lib/src/app.dart owns the Pipeline and Router composition
Handlers are organized by resource; each handler class exposes a Router get router
Middleware functions return Middleware (a typedef for Handler Function(Handler))
Models use freezed for immutability and json_serializable for serialization
Services contain business logic; repositories handle data access

Dependencies (pubspec.yaml)

dependencies:
  shelf: ^1.4.0
  shelf_router: ^1.1.0
  shelf_static: ^1.1.0        # Static file serving
  shelf_web_socket: ^1.0.0    # WebSocket support

  # Data
  freezed_annotation: ^2.4.0
  json_annotation: ^4.8.0

  # Auth
  dart_jsonwebtoken: ^2.12.0
  bcrypt: ^1.1.0

dev_dependencies:
  test: ^1.24.0
  mocktail: ^1.0.0
  build_runner: ^2.4.0
  freezed: ^2.4.0
  json_serializable: ^6.7.0

Application Entry Point

// bin/server.dart
import 'dart:io';
import 'package:shelf/shelf_io.dart' as shelf_io;
import 'package:myapp/myapp.dart';

Future<void> main() async {
  final config = Config.fromEnvironment();
  final app = Application(config);
  final handler = await app.createHandler();

  final server = await shelf_io.serve(
    handler,
    InternetAddress.anyIPv4,
    config.port,
  );

  print('Server running on http://${server.address.host}:${server.port}');

  // Graceful shutdown
  ProcessSignal.sigint.watch().listen((_) async {
    print('Shutting down...');
    await app.close();
    await server.close();
    exit(0);
  });
}

Entry Point Rules

Load configuration from environment variables (never hardcode secrets)
Wire graceful shutdown via ProcessSignal.sigint
Call app.close() before server.close() to release database connections
Keep main() under 25 lines

Configuration

Use a Config class with factory Config.fromEnvironment() reading from Platform.environment
Provide dev defaults for non-secret values (port, database URL)
Throw StateError in production if critical secrets are missing (JWT_SECRET, API keys)
Use const constructor for Config to enable compile-time checks
Never log secret values

Application Setup (Pipeline + Router)

// lib/src/app.dart
import 'package:shelf/shelf.dart';
import 'package:shelf_router/shelf_router.dart';

class Application {
  final Config config;
  late final UserRepository _userRepository;
  late final UserService _userService;

  Application(this.config);

  Future<Handler> createHandler() async {
    _userRepository = UserRepository();
    _userService = UserService(_userRepository, config);

    final healthHandler = HealthHandler();
    final usersHandler = UsersHandler(_userService);

    final router = Router()
      ..mount('/health', healthHandler.router.call)
      ..mount('/api/v1/users', usersHandler.router.call);

    final pipeline = const Pipeline()
        .addMiddleware(loggingMiddleware())
        .addMiddleware(corsMiddleware())
        .addMiddleware(handleErrors())
        .addHandler(router.call);

    return pipeline;
  }

  Future<void> close() async {
    await _userRepository.close();
  }
}

Pipeline Rules

Middleware order: logging -> CORS -> error handling -> router
Logging outermost so it captures all requests including CORS preflight
Error handling wraps the router so thrown exceptions are caught
Always call .call when mounting a Router or passing to addHandler
Use const Pipeline() for the initial empty pipeline

Handlers

Handlers are classes that expose a Router get router property. Each route method receives a Request and returns a Response.

// lib/src/handlers/users_handler.dart
class UsersHandler {
  final UserService _userService;

  UsersHandler(this._userService);

  Router get router {
    final router = Router();

    // Public routes
    router.post('/register', _register);
    router.post('/login', _login);

    // Protected routes
    router.get('/', _withAuth(_getAll));
    router.get('/<id>', _withAuth(_getById));
    router.put('/<id>', _withAuth(_update));
    router.delete('/<id>', _withAuth(_delete));

    return router;
  }

  Handler _withAuth(Handler handler) {
    return const Pipeline()
        .addMiddleware(authMiddleware())
        .addHandler(handler);
  }

  Future<Response> _register(Request request) async {
    final body = await request.readAsString();
    final json = jsonDecode(body) as Map<String, dynamic>;

    final user = await _userService.register(
      email: json['email'] as String,
      password: json['password'] as String,
      name: json['name'] as String,
    );

    return Response(
      201,
      body: jsonEncode(user.toJson()),
      headers: {'Content-Type': 'application/json'},
    );
  }
}

Handler Rules

One handler class per resource (UsersHandler, ProductsHandler)
Keep handler methods under 20 lines; delegate business logic to services
Use _withAuth(handler) helper to wrap individual routes with auth middleware
Parse request body with request.readAsString() then jsonDecode()
Always set Content-Type: application/json on JSON responses
Return appropriate status codes: 201 for creation, 204 for deletion, 200 for reads/updates
Use shelf_router path parameters with angle brackets: /<id>

Middleware

A Middleware is a function that takes a Handler and returns a new Handler.

// Middleware type signature
typedef Middleware = Handler Function(Handler innerHandler);

Writing Middleware

Middleware loggingMiddleware() {
  return (Handler innerHandler) {
    return (Request request) async {
      final stopwatch = Stopwatch()..start();
      print('[${DateTime.now()}] ${request.method} ${request.requestedUri}');

      final response = await innerHandler(request);

      stopwatch.stop();
      print(
        '[${DateTime.now()}] ${request.method} ${request.requestedUri} '
        '${response.statusCode} ${stopwatch.elapsedMilliseconds}ms',
      );

      return response;
    };
  };
}

Error Handling Middleware

Middleware handleErrors() {
  return (Handler innerHandler) {
    return (Request request) async {
      try {
        return await innerHandler(request);
      } on NotFoundException catch (e) {
        return _jsonError(404, e.message);
      } on ValidationException catch (e) {
        return _jsonError(422, e.message, errors: e.errors);
      } on UnauthorizedException {
        return _jsonError(403, 'Unauthorized');
      } catch (e, stack) {
        print('Error: $e\n$stack');
        return _jsonError(500, 'Internal server error');
      }
    };
  };
}

Response _jsonError(int status, String message, {Map<String, dynamic>? errors}) {
  return Response(
    status,
    body: jsonEncode({
      'error': message,
      if (errors != null) 'errors': errors,
    }),
    headers: {'Content-Type': 'application/json'},
  );
}

Middleware Rules

Return Middleware (a function), not Handler directly
Always await innerHandler(request) -- never skip calling the inner handler unless short-circuiting (auth failure, rate limit)
Use request.change(context: {...request.context, 'key': value}) to pass data downstream
Error-handling middleware must catch all exceptions and return proper HTTP responses
Never let unhandled exceptions propagate to shelf_io.serve

Request and Response

Reading Request Data

Source	How	Example
Body	`await request.readAsString()` then `jsonDecode()`	`final json = jsonDecode(await request.readAsString())`
Query params	`request.url.queryParameters['key']`	`int.tryParse(request.url.queryParameters['page'] ?? '1') ?? 1`
Path params	Extra function arguments (shelf_router)	`Future<Response> _getById(Request request, String id)`
Headers	`request.headers['Header-Name']`	`request.headers['Authorization']`
Context	`request.context['key']`	`request.context['user'] as User`

Building Responses

Status	Method
200 OK	`Response.ok(jsonEncode(data), headers: {'Content-Type': 'application/json'})`
201 Created	`Response(201, body: jsonEncode(data), headers: {'Content-Type': 'application/json'})`
204 No Content	`Response(204)`
404 Not Found	`Response.notFound(jsonEncode({'error': 'Not found'}), headers: {'Content-Type': 'application/json'})`
Modify response	`response.change(headers: {...response.headers, 'X-Custom': 'value'})`

Request/Response Rules

Parse query parameters defensively with int.tryParse and defaults
Read the body only once (it is a stream); do not call readAsString() twice
Use request.change(context:) for downstream data, never mutable globals
Set Content-Type on every response that has a body

Routing with shelf_router

final router = Router()
  ..get('/health', _health)
  ..get('/users', _listUsers)
  ..get('/users/<id>', _getUser)
  ..post('/users', _createUser)
  ..put('/users/<id>', _updateUser)
  ..delete('/users/<id>', _deleteUser);

// Mount sub-routers with path prefix
final root = Router()
  ..mount('/api/v1', apiRouter.call)
  ..mount('/ws', webSocketHandler);

Routing Rules

Use ..method('/path', handler) cascade syntax for readability
Mount sub-routers with ..mount('/prefix', router.call)
Path parameters use angle brackets: /<id>, /<slug>
Always version API routes: /api/v1/...
Group related routes in a single handler class

Cascade (Fallback Routing)

Cascade tries handlers in order until one returns a non-404 response.

import 'package:shelf/shelf.dart';
import 'package:shelf_static/shelf_static.dart';

final cascade = Cascade()
    .add(apiRouter)
    .add(createStaticHandler('public', defaultDocument: 'index.html'));

final handler = const Pipeline()
    .addMiddleware(loggingMiddleware())
    .addHandler(cascade.handler);

Cascade Rules

Place specific handlers (API) before generic handlers (static files)
Cascade treats 404 and 405 as "not handled" by default
Use statusCodes parameter to customize which codes trigger fallthrough
Useful for SPAs: API routes first, then static file handler as fallback

Custom Exception Types

class UnauthorizedException implements Exception {
  final String message;
  UnauthorizedException([this.message = 'Unauthorized']);
}

class NotFoundException implements Exception {
  final String message;
  NotFoundException(this.message);
}

class ValidationException implements Exception {
  final String message;
  final Map<String, List<String>> errors;
  ValidationException(this.message, [this.errors = const {}]);
}

Exception Rules

Define domain exceptions that implement Exception (not Error)
Map exceptions to HTTP status codes in error-handling middleware only
Never throw generic Exception('message') -- use typed exceptions
Include structured error details (field-level validation errors)

Commands

# Development
dart run bin/server.dart            # Start server
dart run --enable-vm-service bin/server.dart  # With debugger

# Code generation (freezed, json_serializable)
dart run build_runner build --delete-conflicting-outputs
dart run build_runner watch         # Watch mode for codegen

# Testing
dart test                           # Run all tests
dart test test/handlers/            # Run specific directory
dart test --coverage                # With coverage

# Quality
dart format .                       # Format all files
dart analyze                        # Static analysis
dart fix --apply                    # Auto-fix lint issues

# Build
dart compile exe bin/server.dart -o server  # AOT compile to native binary

Best Practices Summary

Pipeline: Compose middleware with Pipeline; order matters (outermost runs first)
Handlers: Keep thin; delegate to services; one class per resource
Error Handling: Centralize in middleware; catch all exceptions; return structured JSON errors
Context: Pass data between middleware and handlers via request.change(context:)
Testing: Use shelf directly in tests (no HTTP server needed); mock services with mocktail
Security: Validate all inputs; use parameterized database queries; never log secrets
Performance: Compile to native executable for production; use streaming for large responses

Advanced Topics

For detailed middleware examples, WebSocket support, static files, authentication flows, rate limiting, and testing patterns, see:

references/patterns.md -- Full middleware patterns, WebSocket handler, static file serving, JWT auth, rate limiting, repository pattern, integration testing, Dockerfile

shelf