vite-static 1.1.1

Embed Vite chunks into your Rust application and query them individually.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

# Vite Static

[![docs.rs](https://img.shields.io/docsrs/vite-static)](https://docs.rs/vite-static)
[![Crates.io Version](https://img.shields.io/crates/v/vite-static)](https://crates.io/crates/vite-static)
![Crates.io Total Downloads](https://img.shields.io/crates/d/vite-static)
[![License](https://img.shields.io/badge/License-LGPL--3.0-blue)](https://choosealicense.com/licenses/lgpl-3.0/)
[![Codeberg Stars](https://img.shields.io/gitea/stars/idkncc/vite-static?gitea_url=https%3A%2F%2Fcodeberg.org&logo=codeberg)](https://codeberg.org/idkncc/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`][manifest-trait] 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`][manifest-derive]
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

   ```shell
   cargo add vite-static
   ```

2. Enable `build.manifest` vite option.

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

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

3. Add [`Manifest`][manifest-derive] derive

   ```rust
   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](https://docs.rs/vite-static/latest/vite_static/derive.Manifest.html)

4. Use it!

   To see more use cases, look into [`examples/`](./examples/) folder and [`Manifest`][manifest-trait] trait.

## Features

Without any feature, you have [`Manifest`][manifest-trait] trait, that helps you query and resolve chunks.

| Feature     | Description                            |
|:------------|:---------------------------------------|
| `derive`    | adds `Manifest` derive macro (default) |
| `actix-web` | adds `ActixFiles` service              |
| `axum`      | WIP                                    |
| `rocket`    | WIP                                    |
| `html`      | adds `HTMLIntegration` builder         |

## Examples

| Filename                                                        | Description                                                |
|:----------------------------------------------------------------|:-----------------------------------------------------------|
| [getting-started.rs](examples/getting-started.rs)               | Getting started example.                                   |
| [getting-started-no-yap.rs](examples/getting-started-no-yap.rs) | Getting started example, no yapping.                       |
| [integrations/actix-web.rs](examples/integrations/actix-web.rs) | `actix-web` feature example.                               |
| [integrations/html.rs](examples/integrations/html.rs)           | `html` feature example.                                    |
| [options/base.rs](examples/options/base.rs)                     | `#[base = "..."]` derive option example.                   |
| [options/no-embedding.rs](examples/options/no-embedding.rs)     | `#[no_embedding]` derive option example (with explanation) |

## Q&A

- **Q:** Why should am I use this library, over [vite-rs](https://github.com/Wulf/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!](https://en.wikipedia.org/wiki/KISS_principle)

## Credits

- [vite-rs](https://github.com/Wulf/vite-rs) - good library to embed entire frontend into rust application
- [actix-web-static-files](https://github.com/kilork/actix-web-static-files) - `ActixFiles` service implementation is partially taken from this crate

[manifest-trait]: https://docs.rs/vite-static/latest/vite_static/trait.Manifest.html
[manifest-derive]: https://docs.rs/vite-static/latest/vite_static/derive.Manifest.html