// Serve static files and directories with caching and cache busting in Relic. Use when serving assets, images, CSS, JS, favicons, or configuring HTTP cache control headers.
| name | relic-static-files |
| description | Serve static files and directories with caching and cache busting in Relic. Use when serving assets, images, CSS, JS, favicons, or configuring HTTP cache control headers. |
StaticHandler serves files with automatic MIME type detection, cache headers, and built-in security (path traversal protection, hidden file blocking, symlink safety).
Use a tail pattern (/**) so the handler knows which file to serve:
app.anyOf(
{Method.get, Method.head},
'/static/**',
StaticHandler.directory(
Directory('public'),
cacheControl: (req, fileInfo) => CacheControlHeader(maxAge: 86400),
).asHandler,
);
// public/style.css → http://localhost:8080/static/style.css
app.get(
'/logo.svg',
StaticHandler.file(
File('assets/logo.svg'),
cacheControl: (req, fileInfo) => CacheControlHeader(maxAge: 3600),
).asHandler,
);
StaticHandler.directory(
dir,
cacheControl: (req, fileInfo) => CacheControlHeader(
maxAge: 3600, // 1 hour
publicCache: true, // allow CDN/proxy caching
),
).asHandler
StaticHandler.directory(
dir,
cacheControl: (req, fileInfo) => CacheControlHeader(
maxAge: 31536000, // 1 year
publicCache: true,
immutable: true, // browsers never revalidate
),
).asHandler
Generates unique URLs based on file content hashes. When file content changes, the hash changes, forcing browsers to fetch the new version.
final buster = CacheBustingConfig(
mountPrefix: '/static',
fileSystemRoot: Directory('public'),
);
// Generate cache-busted URLs (e.g., /static/hello@6cb65f8d.txt)
app.get('/', respondWith((req) async {
final cssUrl = await buster.assetPath('/static/style.css');
final html = '<link rel="stylesheet" href="$cssUrl">';
return Response.ok(body: Body.fromString(html, mimeType: MimeType.html));
}));
// Serve with aggressive caching (safe because URL changes on content change)
app.anyOf(
{Method.get, Method.head},
'/static/**',
StaticHandler.directory(
Directory('public'),
cacheControl: (req, fileInfo) => CacheControlHeader(
maxAge: 31536000,
publicCache: true,
immutable: true,
),
cacheBustingConfig: buster,
).asHandler,
);
These protections are applied automatically:
../ attempts to escape the served directory.. (e.g., .env, .git).Bootstrap a Relic web server, configure RelicApp, start serving, and enable hot reload. Use when creating a new Relic project, setting up a server, or configuring the development workflow.
Create and apply middleware for auth, CORS, logging, and other cross-cutting concerns. Use context properties for type-safe request-scoped data. Use when adding middleware, request/response transformations, or passing data between middleware and handlers.
Handle HTTP requests and create responses with Body, headers, and status codes in Relic. Use when reading request data, parsing JSON, building API responses, working with headers, or streaming content.
Define routes with path parameters, wildcards, tail segments, and typed params in Relic. Use when adding endpoints, handling dynamic URLs, setting up URL patterns, or forwarding requests.
Migrate a Dart web server from Shelf to Relic. Side-by-side reference for every API change. Use when converting Shelf code to Relic, replacing shelf/shelf_router/shelf_web_socket imports, or upgrading an existing server.
Handle WebSocket connections and hijack connections for SSE or custom protocols in Relic. Use when implementing real-time communication, WebSocket endpoints, or server-sent events.