erika.florist
Rust library to generate static websites
1---
2title: "Scripts"
3description: "Learn how to import and use JavaScript and TypeScript files in your Maudit site."
4section: "core-concepts"
5---
6
7Maudit supports adding JavaScript and TypeScript files to your site.
8
9To import a script, add it anywhere in your project's directory, and use the [`ctx.assets.add_script()`](https://docs.rs/maudit/latest/maudit/assets/struct.RouteAssets.html#method.add_script) method to add it to a page's assets.
10
11This function will return an error if the image file does not exist, or cannot be read for any reason. If you'd rather not deal with errors, you can use the `add_script_unchecked()` method, which will instead panic on failure.
12
13```rs
14use maudit::route::prelude::*;
15use maud::{html, Markup};
16
17#[route("/")]
18pub struct Index;
19
20impl Route for Index {
21 fn render(&self, ctx: &mut PageContext) -> impl Into<RenderResult> {
22 let script = ctx.assets.add_script("script.js")?;
23
24 // Access the URL of the script using the `url()` method.
25 // This is useful when you want to manually add the script to your template.
26 format!(
27 r#"<script src="{}" type="module"></script>"#,
28 script.url()
29 );
30
31 // In supported templating languages, the return value of `ctx.assets.add_script()` can be used directly in the template.
32 Ok(html! {
33 (script) // Generates <script src="SCRIPT_URL" type="module"></script>
34 })
35 }
36}
37```
38
39Alternatively, the [`include_script()`](https://docs.rs/maudit/latest/maudit/assets/struct.RouteAssets.html#method.include_script) method can be used to automatically include the script in the page, without needing to manually add it to the template. This can be useful when a layout or component need to include their own scripts.
40
41```rs
42fn render(&self, ctx: &mut PageContext) -> impl Into<RenderResult> {
43 layout(&ctx, "Look ma, no explicit script tag!")
44}
45
46fn layout(ctx: &PageContext, content: &str) -> impl Into<RenderResult> {
47 ctx.assets.include_script("script.js")?;
48
49 Ok(html! {
50 head {
51 title { "My page" }
52 // No need to manually add the script here.
53 }
54 body {
55 (PreEscaped(content))
56 }
57 })
58}
59```
60
61When using `include_script()`, the script will be included inside the `head` tag with the `type="module"` attribute. [Note that this attribute implicitely means that your script will be deferred](https://v8.dev/features/modules#defer) after the page has loaded. Note that, at this time, pages without a `head` tag won't have the script included.
62
63In both cases, paths are relative to the project's current working directory, not the file where the method is called. It is possible to resolve relatively to the current file using Rust's [`file!()`](https://doc.rust-lang.org/std/macro.file.html) macro, if needed:
64
65```rs
66let script = ctx.assets.add_script(
67 std::path::Path::new(file!())
68 .parent()
69 .unwrap()
70 .join("script.js")
71 .to_str()
72 .unwrap(),
73)?;
74```
75
76## Transformation & Bundling
77
78Maudit uses [Rolldown](https://rolldown.rs) to process and bundle scripts and styles. Rolldown will automatically chunk, minify, transpile, etc. your scripts and stylesheets, optimizing them for production. Features like tree shaking, minification, TypeScript support and more are all included out of the box.
79
80At this time, Maudit does not support customizing the transformation process, but this will be added in the future.