web_modules 0.5.1

Pure-Rust, buildless toolchain for ES modules and Web Components
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

//! Pure-Rust, buildless toolchain for **ES modules and Web Components**. No Node, no
//! bundler.
//!
//! It vendors each npm package into a `web_modules/` tree with an import map
//! (Snowpack-style) and serves them through an on-the-fly transform dev server
//! (like `@web/dev-server`), built entirely in Rust on
//! [`npm-utils`](https://docs.rs/npm-utils), [oxc] and [`grass`](https://docs.rs/grass).
//! It emits native ES modules and leaves bare-specifier resolution to the browser's
//! import map; it is **not** a bundler.
//!
//! # Modules
//!
//! **Core** (always on):
//! - [`vendor`]: resolve, download and extract npm packages into a `web_modules/`
//!   tree (via `npm-utils`) and accumulate the import map.
//! - [`importmap`]: a deterministic import-map composer (build, merge fragments,
//!   render the `<script type="importmap">`).
//!
//! **Processors** (applied to your source and assets):
//! - [`typescript`]: TypeScript and modern JS → browser JS via oxc, with legacy
//!   decorators configured for Lit.
//! - [`scss`]: SCSS → CSS via grass.
//! - [`minify`]: JS minification via oxc_minifier.
//! - [`dts`]: `.d.ts` emission. [`i18n`]: XLIFF merge. [`icons`]: favicons from a PNG.
//!
//! **Toolchain** (build and serve):
//! - [`build`]: vendor, transform and render into an output dir.
//! - `bundle`: fold an app plus its `node_modules/` (CommonJS and all) into one
//!   browser ESM file via rolldown, for React-class packages that ship only CommonJS.
//! - [`templates`]: HTML templating (importmap injection).
//! - [`server`] / [`dev`]: serve embedded assets, or compile on the fly with
//!   file-watching and live-reload.
//!
//! [oxc]: https://oxc.rs

mod error;
pub use error::{Error, Result};

// Always-on core, grouped under `core/`: vendoring, import maps, the mount model,
// TypeScript `tsconfig` generation and static-file copying. Re-exported here so callers
// use `web_modules::vendor` etc. — the `core` module itself is private.
mod core;
pub use core::mount::Mount;
pub use core::symlinks::SymlinkMode;
pub use core::{importmap, mount, reject, static_files, symlinks, tsconfig, vendor};
// Crate-internal for now: the graph's overwrite/ownership semantics are still
// settling, so it is not part of the public API yet.
pub(crate) use core::module_graph;
// Crate-internal: resolving `npm://` symlink targets into node_modules, used by the
// build's preflight walk/emit and the dev/static server.
pub(crate) use core::npm_link;

/// Feature-gated source/asset processors, each re-exported at the crate root (e.g.
/// `web_modules::scss`). Grouped to separate "what we apply to your source" from the
/// vendor/import-map core and the build/serve toolchain.
mod processors;

/// The decorator-lowering mode (`web_modules::Decorators`), always available so the build
/// [`Processors`](build::Processors) set can carry it regardless of which processors are compiled.
pub use processors::Decorators;

#[cfg(feature = "dts")]
pub use processors::dts;
#[cfg(feature = "i18n")]
pub use processors::i18n;
#[cfg(feature = "icons")]
pub use processors::icons;
#[cfg(feature = "minify")]
pub use processors::minify;
#[cfg(feature = "scss")]
pub use processors::scss;
#[cfg(feature = "typescript")]
pub use processors::typescript;

/// CLI scaffolding (the `feature_args!` macro + the `NoConfig` placeholder) that lets
/// each compiler processor carry its own clap config. Compiled only with `cli`, so the
/// library path stays clap-free.
#[cfg(feature = "cli")]
pub mod cli_config;

/// Shared fluent-builder methods (the `source_builder_methods!` macro) stamped onto the
/// [`Build`] and [`Dev`] builders, behind the `builder` feature.
#[cfg(feature = "builder")]
mod builder_shared;

// Build-time toolchain, grouped under `build/`: the `build` pipeline plus the emit helpers
// `bundle` / `compress` / `templates`, each re-exported at its historical crate root path. The
// pipeline depends only on the always-on vendor/import-map core — each source processor (TypeScript,
// SCSS, Tera, gzip) applies only when its feature is on — so the module is always available.
pub mod build;

/// The fluent build builder (feature `builder`), at the crate root alongside [`Frontend`].
#[cfg(feature = "builder")]
pub use build::Build;

#[cfg(feature = "bundle")]
pub use build::bundle;
#[cfg(feature = "compress")]
pub use build::compress;
#[cfg(feature = "tera")]
pub use build::templates;

/// Re-export of [`npm_utils`] as `web_modules::npm`, the vendoring + transitive `node_modules`
/// install engine, behind the `npm` feature. Lets consumers reach the npm API without a separate
/// `npm-utils` dependency: install a tree with `web_modules::npm::install::node_modules`, then
/// bundle it via `web_modules::bundle` (enable the `bundle` feature too).
#[cfg(feature = "npm")]
pub use npm_utils as npm;

// Runtime serving, grouped under `serve/`: the axum `Frontend` router and the dev server,
// over a shared (private) `serving` containment boundary. Re-exported at historical paths.
mod serve;

#[cfg(feature = "dev")]
pub use serve::dev;

/// The fluent dev-server builder (feature `builder`), at the crate root alongside [`Frontend`].
#[cfg(all(feature = "builder", feature = "dev"))]
pub use serve::dev::Dev;

#[cfg(feature = "axum")]
pub use serve::server;
#[cfg(feature = "axum")]
pub use serve::server::{serve, Frontend};

/// Re-export of the `include_dir` crate for the [`include_dir::Dir`] type. Use the
/// `include_dir` crate **directly** for the `include_dir!` macro; it emits
/// `include_dir::`-qualified paths that don't resolve through a re-export.
#[cfg(feature = "axum")]
pub use include_dir;