Vite Static

Embed Vite chunks into your Rust application and query them individually.

Note, that library is unfinished and rough on edges until v1.0.0 release, where it will become stable.

How it works

Vite Static has Manifest trait and has methods to query chunks and resolve output filename (g.e. main.HASH.js) from manifest key (g.e. src/main.tsx).

Vite Static provides derive feature (enabled by default), that adds Manifest derive to automatically implement that trait.

Also, Vite Static has integrations with web frameworks, to easily serve your static files.

Usage

WARNING

There's no Windows support. Use unix-like system or WSL :D

1. Add vite-static library

   cargo add vite-static
   

2. Enable build.manifest vite option.

   In path/to/vite-project/vite.config.js:

   export default defineConfig({
       // <snip>
       base: "/static", // <-- most of the time YOU want this
       build: {
           manifest: true, // <-- required
       }
       // <snip>
   })
   

3. Add Manifest derive

   use vite_static::Manifest;
   
   #[derive(Manifest)]
   #[vite_dist = "path/to/vite-project/dist"] // relative to Cargo.toml
   // OR: #[vite_dist = "/absolute/path/to/dist"]
   // OR: #[vite_dist = "env:ENVIRONMENT_VARIABLE_TO_DIST"] // that specifies relative or absolute path
   // OR: #[vite_dist = "env:ENVIRONMENT_VARIABLE_TO_DIST|/default/path/to/dist"] // with default value
   #[base = "/static"] // because we set it in `vite.config.js`!
   #[cfg_attr(debug_assertions, no_embedding)] // (OPTIONAL, but recommended to speed up debug builds)
   struct MyViteStatic;
   

   Options breakdown:

   • #[vite_dist = ""] specifies path to your vite project's dist/ folder.

   • #[base = ""] specifies base path for URLs.

   • #[no_embedding] makes macro to NOT embed manifest and chunks. It will lazily read manifest and read specified chunk, when needed.

     The whole purpose of this library is to embed static, but you can enable it only for debug builds (f.e. by checking debug_assertions cfg) to speed up builds.

   See more available options

4. Use it!

   To see more use cases, look into examples/ folder and Manifest trait.

Features

Without any feature, you have Manifest trait, that helps you query and resolve chunks.

Examples

Q&A

• Q: Why should am I use this library, over vite-rs?

  A: It depends on your needs.

  You should use vite-rs, when you have frontend built with Vite, including routing and HTML, and you need a library to embed whole frontend into application.

  You should use vite-static, when you have assets (JS, CSS, PNGs, etc.) built with Vite, but you use HTML templating to build faster and lighter websites, so you need to embed only assets.

  Because of vite-static use case and lightness, it doesn't have development server and auto-running npm build in derive macro.

• Q: Why it doesn't run npm build automatically?

  A: Because it only adds problems.

  First, it will run npm build on every rust compilation and will require adding additional options.

  Second, it will make configuration only harder. For example you use nix. While building release, you build vite project in separate derivation, but during development you would use automatic npm build.

  So it's simpler to just open 2 terminals: first to watch and re-run cargo run, second to run vite watch.

  KISS principle!

Credits

• vite-rs - good library to embed entire frontend into rust application
• actix-web-static-files - ActixFiles service implementation is partially taken from this crate