trellis_shelf
trellis_shelf wires the Trellis engine into a
Shelf server: middleware that injects the
engine, response helpers that render pages and fragments, HTMX detection, CSRF
protection, and security-header defaults.
Installation
dependencies:
trellis: ^0.13.0
trellis_shelf: ^0.13.0
Quick start
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;
import 'package:trellis/trellis.dart';
import 'package:trellis_shelf/trellis_shelf.dart';
void main() async {
final engine = Trellis();
final handler = const Pipeline()
.addMiddleware(trellisSecurityHeaders())
.addMiddleware(trellisEngine(engine))
.addMiddleware(trellisCsrf(secret: 'your-secret-key'))
.addHandler(myHandler);
await io.serve(handler, 'localhost', 8080);
}
Future<Response> myHandler(Request request) async {
return renderPage(request, 'index', {'title': 'Hello'});
}
Engine middleware
trellisEngine(engine) injects a Trellis engine into the Shelf request
context so handlers can retrieve it without globals:
// Add to pipeline
.addMiddleware(trellisEngine(engine))
// Retrieve in handler
final engine = getEngine(request);
getEngine() throws StateError if the middleware has not been applied.
Response helpers
These use getEngine(), merge request-context values (such as the CSRF token),
and return an htmlResponse():
// Full page (or a fragment for HTMX requests)
return renderPage(request, 'index', {'title': 'Home'},
htmxFragment: 'content');
// Single fragment
return renderFragment(request, 'todos', 'todo-list', {'items': todos});
// Multiple fragments for HTMX out-of-band swaps
return renderOobFragments(request, 'todos',
['todo-list', 'todo-count'], {'items': todos, 'count': 5});
The response utility is available directly too:
return htmlResponse('<h1>Hello</h1>');
return htmlResponse('Not Found', statusCode: 404);
htmlResponse() returns a Response with
content-type: text/html; charset=utf-8.
HTMX helpers
Convenience functions for reading HTMX request headers:
if (isHtmxRequest(request)) {
final target = htmxTarget(request); // id of the swap target, or null
final source = htmxSource(request); // id of the triggering element, or null
final boosted = isHtmxBoosted(request);
}
The helpers read the HTMX 2 headers (HX-Target, HX-Trigger, bare ids) and the HTMX 4 headers
(HX-Target, HX-Source, tag#id) alike, so handler code is the same on either version.
htmxTrigger() is deprecated in favour of htmxSource().
Security headers
trellisSecurityHeaders() adds configurable security headers to all responses:
| Header | Default |
|---|---|
X-Content-Type-Options |
nosniff |
X-Frame-Options |
DENY |
Referrer-Policy |
strict-origin-when-cross-origin |
X-XSS-Protection |
0 |
Content-Security-Policy |
Sensible defaults via CspBuilder |
// Use defaults
.addMiddleware(trellisSecurityHeaders())
// Customize CSP
.addMiddleware(trellisSecurityHeaders(
csp: CspBuilder(
scriptSrc: "'self' 'unsafe-inline'",
connectSrc: "'self' ws:",
),
))
// Disable CSP entirely
.addMiddleware(trellisSecurityHeaders(enableCsp: false))
CSRF protection
trellisCsrf(secret: ...) uses a double-submit cookie pattern with HMAC-SHA256
signing. It generates a token on safe methods (GET/HEAD/OPTIONS) and validates
on state-changing methods (POST/PUT/DELETE/PATCH):
.addMiddleware(trellisCsrf(secret: 'your-secret-key'))
Access the token in handlers or templates:
// In a handler
final token = csrfToken(request);
<!-- In a template — automatically merged by the response helpers -->
<input type="hidden" name="_csrf" tl:attr="value=${csrfToken}">
HTMX requests can submit the token from the request-configuration event (htmx:configRequest
in HTMX 2, htmx:config:request in HTMX 4). Add this to your base layout:
<!-- In <head>: render the token into a meta tag -->
<meta name="csrf-token" tl:attr="content=${csrfToken}" content="">
<!-- Also in <head>: inject it into every HTMX request -->
<script>
(function () {
function setCsrfHeader(headers) {
var token = document.querySelector('meta[name="csrf-token"]').content;
if (token) headers['X-CSRF-Token'] = token;
}
document.addEventListener('htmx:configRequest', function(evt) { setCsrfHeader(evt.detail.headers); });
document.addEventListener('htmx:config:request', function(evt) { setCsrfHeader(evt.detail.ctx.request.headers); });
})();
</script>
Configuration options:
trellisCsrf(
secret: 'your-secret-key',
cookieName: '__csrf', // cookie name (default)
fieldName: '_csrf', // form field name (default)
headerName: 'X-CSRF-Token', // header name (default)
excludedPaths: ['/api/webhook'], // paths that skip validation
)
Middleware ordering
Apply middleware in this order for correct behavior:
const Pipeline()
.addMiddleware(trellisSecurityHeaders()) // outermost — wraps response
.addMiddleware(trellisEngine(engine)) // injects engine for handlers
.addMiddleware(trellisCsrf(secret: '...')) // CSRF after engine
.addHandler(handler);
Security headers should be outermost so they apply to all responses. CSRF
middleware must come after trellisEngine() because the response helpers need
the engine from the request context.
For live browser refresh during development, add trellis_dev to the pipeline.