tower_embed/lib.rs
1//! This crate provides a [`tower`] service designed to provide embedded static
2//! assets support for web application. This service includes the following HTTP features:
3//!
4//! - Support for GET and HEAD requests
5//! - `Content-Type` header generation based on file MIME type guessed from extension.
6//! - `ETag` header generation and validation.
7//! - `Last-Modified` header generation and validation.
8//! - Customizable 404 page.
9//!
10//! In `debug` mode, assets are served directly from the filesystem to facilitate rapid
11//! development. Both `ETag` and `Last-Modified` headers are not generated in this mode.
12//!
13//! The optional feature `astro` can be used to enable support for embedding [Astro] project. In
14//! release mode the project is build and embedded as static assets, while in debug mode the
15//! service acts as a proxy server pointing to the development server.
16//!
17//! ## Features
18//!
19//! * **astro** - Enable support for [Astro] projects.
20//!
21//! ## Usage
22//!
23//! ```no_run
24//! use axum::Router;
25//! use tower_embed::{EmbedExt, EmbedFolder, ServeEmbed};
26//!
27//! #[derive(Embed)]
28//! #[embed(folder = "assets")]
29//! struct Assets;
30//!
31//! #[tokio::main]
32//! async fn main() {
33//! let assets = ServeEmbed::<Assets>::new().with_not_found(Assets::not_found_page("404.html"));
34//! let router = Router::new().fallback_service(assets);
35//!
36//! let listener = tokio::net::TcpListener::bind("127.0.0.1:8080")
37//! .await
38//! .unwrap();
39//! axum::serve::serve(listener, router).await.unwrap();
40//! }
41//! ```
42//!
43//! Please see the [examples] directory for working examples.
44//!
45//! [`tower`]: https://crates.io/crates/tower
46//! [examples]: https://github.com/mattiapenati/tower-embed/tree/main/examples
47//! [Astro]: https://astro.build/
48
49#[cfg(not(feature = "tokio"))]
50compile_error!("Only tokio runtime is supported, and it is required to use `tower-embed`.");
51
52#[doc(inline)]
53pub use tower_embed_impl::Embed;
54
55#[doc(hidden)]
56pub use tower_embed_core as core;
57
58#[doc(inline)]
59pub use tower_embed_core::{Embed, EmbedExt, EmbedFolder, ServeEmbed};