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

code

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)

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

dart

// 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)

dart

// 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.

dart

// 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.

dart

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

Writing Middleware

dart

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

dart

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

dart

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.

dart

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

dart

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

bash

# 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 Framework Guide

Core Principles

Project Structure

Dependencies (pubspec.yaml)

Application Entry Point

Entry Point Rules

Configuration

Application Setup (Pipeline + Router)

Pipeline Rules

Handlers

Handler Rules

Middleware

Writing Middleware

Error Handling Middleware

Middleware Rules

Request and Response

Reading Request Data

Building Responses

Request/Response Rules

Routing with shelf_router

Routing Rules

Cascade (Fallback Routing)

Cascade Rules

Custom Exception Types

Exception Rules

Commands

Best Practices Summary

Advanced Topics

External References