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

1. Middleware Composition: Everything flows through Pipeline; compose handlers with addMiddleware and addHandler
2. Handler Simplicity: A Handler is just FutureOr<Response> Function(Request) -- keep it functional
3. Immutable Requests: Use request.change() to pass data downstream via context
4. Cascade Routing: Use Cascade to try multiple handlers in sequence until one succeeds
5. 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)