trellis_relic
trellis_relic integrates the Trellis engine with
Serverpod Relic: response helpers, HTMX
detection, and security headers.
Installation
dependencies:
trellis: ^0.13.0
trellis_relic: ^0.13.0
Quick start
import 'package:relic/relic.dart';
import 'package:trellis/trellis.dart';
import 'package:trellis_relic/trellis_relic.dart';
final engine = Trellis();
void main() async {
final app = RelicApp()
..use('/', trellisSecurityHeaders())
..get('/', (request) async {
return renderPage(request, engine, 'pages/index', {
'title': 'Home',
});
});
await app.serve(port: 8080);
}
Engine pattern
Unlike trellis_shelf, Relic has no dependency
injection mechanism. Pass the Trellis engine explicitly to each response
helper:
final engine = Trellis(
loader: FileSystemLoader(templateDirectory: 'templates'),
);
// Pass the engine directly to helpers
return renderPage(request, engine, 'pages/home', {'title': 'Home'});
Response helpers
renderPage
Renders a full page template. When htmxFragment is provided and the request is
an HTMX request, it renders only the named fragment instead:
Future<Response> handler(Request request) async {
return renderPage(
request,
engine,
'pages/todos',
{'items': todos},
htmxFragment: 'todo-list', // rendered for HTMX, ignored for full-page
);
}
renderFragment
Renders a single named fragment directly, regardless of request type:
Future<Response> handler(Request request) async {
return renderFragment(request, engine, 'pages/todos', 'todo-list', {'items': todos});
}
renderOobFragments
Renders multiple fragments concatenated – useful for HTMX out-of-band swaps:
Future<Response> handler(Request request) async {
return renderOobFragments(
request,
engine,
'pages/todos',
['todo-list', 'todo-count'],
{'items': todos, 'count': todos.length},
);
}
HTMX helpers
Inspect HTMX-specific request headers:
isHtmxRequest(request) // HX-Request: true
htmxTarget(request) // id of the swap target (nullable)
htmxSource(request) // id of the triggering element (nullable)
isHtmxBoosted(request) // HX-Boosted: true
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().
Relic returns headers as Iterable<String>?. These helpers use .first
internally, consistent with HTMX's single-value headers.
Security headers
Add security headers to all matched-route responses:
final app = RelicApp()
..use('/', trellisSecurityHeaders())
..get('/', myHandler);
Default headers applied:
| Header | Default value |
|---|---|
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 |
Customise the CSP:
trellisSecurityHeaders(
csp: CspBuilder(
scriptSrc: "'self' 'unsafe-inline'",
connectSrc: "'self' ws:",
),
)
Set any directive to null to omit it. Pass enableCsp: false to disable CSP
entirely.
Middleware scoping
Relic middleware only fires for matched routes, so security headers are not
added to 404/405 responses – this differs from Shelf's Pipeline, where
middleware runs for every request. Attach the middleware at '/' to cover all
matched routes.
CSRF protection
CSRF middleware is not included in trellis_relic. Relic lacks a built-in
form-body parser, which is required to implement the double-submit cookie
pattern. If you need CSRF protection:
- Implement it manually once Relic adds form-parsing support.
- Use a JavaScript fetch API with custom headers instead of form submissions
(HTMX supports this via
hx-headers).