static-serve 0.1.0

A helper for compressing and embedding static assets in an Axum webserver
Documentation

Static Serve

A Rust library for compressing and embedding static assets in a web server using Axum. This crate provides efficient asset embedding with optional compression (gzip and zstd) and conditional requests support.

Features

  • Embed static assets at compile-time for efficient serving
  • Automatic compression with gzip and zstd
  • ETag support for conditional requests and caching
  • Seamless Axum integration with request extraction for encoding and caching headers

Installation

Add the following to your Cargo.toml:

[dependencies]
static-serve = "0.1"
axum = "0.8"

Usage

Embedding Static Assets

Use the embed_assets! macro to create a static_router() function in scope which will include your static files, embedding them into your binary:

use static_serve::embed_assets;

embed_assets!("assets", compress = true);
let router = static_router();

This will:

  • Include all files from the assets directory
  • Compress them using gzip and zstd (if beneficial)
  • Generate a static_router() function to serve these assets

Conditional Requests & Caching

The crate automatically handles:

  • Accept-Encoding header to serve compressed versions if available
  • If-None-Match header for ETag validation, returning 304 Not Modified if unchanged

Required parameter

  • path_to_dir - a valid Rust identifier or &str of the path to the static files to be included

Optional parameters

  • compress = false - compress static files with zstd and gzip, true or false (defaults to false)
  • ignore_dirs = [my_ignore_dir, other_ignore_dir] - a bracketed list of valid Rust identifiers or &strs of the paths/subdirectories inside the target directory, which should be ignored and not included. (If this parameter is missing, no subdirectories will be ignored)

Example

use axum::{Router, Server};
use static_serve::embed_assets;

embed_assets!("public", compress = true);

#[tokio::main]
async fn main() {
    let router = static_router();
    Server::bind(&"0.0.0.0:3000".parse().unwrap())
        .serve(router.into_make_service())
        .await
        .unwrap();
}

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.