HadiCherkaoui/axum

Axum Web Framework Skill (v0.8)

ALWAYS load relevant sub-guidelines BEFORE writing Axum code. This skill covers axum 0.8.x with Tower 0.5 and tower-http 0.6.

When to Load Which File

| Task | Load | |------|------| | Creating routes, handlers, extractors (Path, Query, Json, Form) | 01_fundamentals.md | | Application state, middleware, Tower layers, CORS, tracing | 02_state_middleware.md | | Response types, IntoResponse, error handling, custom errors | 03_responses_errors.md | | WebSocket, SSE, multipart uploads, testing, graceful shutdown | 04_advanced.md | | Leptos SSR integration, server functions, cargo-leptos | 05_leptos_integration.md |

Required Dependencies

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
tower = "0.5"
# Common additions:
tower-http = "0.6"   # TraceLayer, CorsLayer, CompressionLayer, etc.
serde = { version = "1", features = ["derive"] }

Version Compatibility (axum 0.8.x)

| Crate | Compatible Version | Latest Verified | |-------|-------------------|-----------------| | axum | 0.8 | 0.8.8 | | axum-extra | 0.12 | 0.12.5 | | axum-core | 0.5 | 0.5.5 | | tokio | ^1.44 | 1.44+ | | tower | 0.5 | 0.5.3 | | tower-http | 0.6 | 0.6.8 | | hyper | ^1.1.0 | 1.x | | http | ^1.0.0 | 1.x | | matchit | =0.8.4 | 0.8.4 | | leptos_axum | 0.8 | 0.8.7 |

10 Core Rules

1. Path params use {param} syntax (NOT :param). Wildcards: {*path} (NOT *path)
2. Body-consuming extractors MUST be the last handler parameter — only one per handler
3. Router<S> means state S is MISSING — call .with_state(s) to get Router<()> before serving
4. .layer() only applies to routes declared BEFORE it — order matters
5. Overlapping routes panic at startup — static /foo and dynamic /{key} are NOT overlapping
6. Always use #[debug_handler] when debugging handler type errors (requires macros feature)
7. Never hold std::sync::Mutex across .await — use tokio::sync::Mutex instead
8. Default body limit is 2MB for Bytes/String/Json/Form — configure via DefaultBodyLimit
9. Nested routes strip the prefix — use OriginalUri if you need the full path
10. For Leptos SSR: prefer provide_context over State<T> for sharing data with components/server fns

Feature Flags

Default: http1, json, form, query, matched-path, original-uri, tokio, tower-log, tracing

Enable as needed: http2, macros, multipart, ws

New in 0.8

• NestedPath extractor — returns the path prefix stripped by nesting
• RawPathParams, RawForm, RawQuery extractors
• NoContent response type (HTTP 204)
• #[debug_middleware] attribute macro (requires macros feature)
• OptionalFromRequestParts / OptionalFromRequest traits for Option<T> extraction
• Router::without_v07_checks() — allows legacy :param syntax during migration
• Router::method_not_allowed_fallback() — custom 405 handler
• Router::has_routes() — check if router has any routes
• from_extractor / from_extractor_with_state middleware
• map_request / map_response middleware functions

Migration Notes (0.7 -> 0.8)

• Path params: /:id -> /{id}, /*path -> /{*path}
• Remove #[async_trait] from custom FromRequest/FromRequestParts impls (native async fn in traits)
• Option<T> extractor: T must now impl OptionalFromRequestParts / OptionalFromRequest
• Upgraded: tower 0.5, tower-http 0.6, hyper 1.x, http 1.0
• Router::without_v07_checks() available for gradual migration of :param -> {param}
• Message::Text in WebSocket now wraps Utf8Bytes (not String)