Bundla
Bundle HTML, CSS, and JS/TS for prod or dev with live-reload.
Features
- Prod build
src/intodist/with minification and hashed filenames, - Dev build
src/intodev/unminified with sourcemaps, - Option to watch and rebuild on change,
- Option to filter watched files by name or suffix,
- Option to serve the bundle.
Built with Rust on the webadev server.
Conventions
- Every
.htmlfile undersrcis a page entry, mirrored todev/dist. <link rel="stylesheet">, CSS@importand<script type="module">references are bundled (one output per asset, cached across pages) and rewritten in place.type="module"is required for scripts.- TypeScript entries work (e.g. ./scripts.ts). The rewritten ref is .js (scripts.js in dev, scripts-.js in prod).
?query/#fragmentsuffixes on references are preserved.- By default, remote and root-relative URLs are left unchanged and resolved by the browser.
- Option (
--base) to bundle and rewrite root-relative references starting with the base prefix. - Everything else under
srcis copied as-is (static assets), preserving the relative layout. - The live-reload script is patched into HTTP responses, never written to
devordist.
CLI
# build `src/` into `dist/` (minified, hashed)
Options
--dev/-d: dev build, unminified with sourcemaps, output dirdev/.--minify <targets>: comma-separated output targets to minify:css,js,html, orall/none(default:allfor prod builds,nonewith--dev). There is a known bug for templates.--watch/-w: build on every change tosrc/.--filter <suffixes>: comma-separated file name suffixes to watch (requires--watch; default: all files; e.g.--filter html,cssor--filter one-file.html). An item matches when the file name equals<item>or ends with.<item>. Items are lowercased, a leading dot or path separator is rejected, and empty items are ignored.--serve/-s: build once, then serve the output directory.--src <dir>: source directory (default:src).--dist <dir>: output directory (default:dist/, ordev/with--dev).--base <path>: URL prefix where the output is served (default: none; must start with/; e.g./app; normalized: trailing/removed, invalid segments rejected). Root-relative references starting with this base are bundled and rewritten with the prefix. With--serve, the built-in server serves the output under this prefix too. Use--basefor subpath hosting (GitHub Pages project sites, reverse proxies).
Server config (requires --serve)
--port <n>: port to listen on (default: random free port).--ip <addr>: IP address to bind to (default 127.0.0.1, use0.0.0.0to access from other devices).--open: open the page in the browser on start.--index <file>: file served by default for the root and directory requests (default:index.html).--header: additional HTTP header on every response (repeatable), e.g.--header "Access-Control-Allow-Origin: *".
Examples
Prod build
# prod build, watch `src/` and rebuild on change
# watch only html/css/js changes (static assets are copied on those rebuilds)
# prod build once, then serve the output
# prod build, watch and serve (live reload; css changes reload the full page)
# prod build with custom source and output directories
# prod build with root-relative references starting with /app (e.g. `/app/styles/main.css`)
# same, served under /app
# prod build for a server-rendered template: minify css/js, keep the html
Dev build
# dev build of `src/` into `dev/` with sourcemaps
# watch: build into `dev/` on change, no server
# development loop: watch `src/`, build into `dev/` on change, serve with live reload
Library
1. Serve only
use IpAddr;
use ;
let config = ServerConfig ;
let server = serve.await?;
server.run.await?;
ServerConfig and Server are re-exported from webadev.
Set config.base to a URL prefix (e.g. "/app") to serve under it. An empty string serves at the root.
Use 0 as config.port to let the OS pick a free port (actual port visible in server.url).
2. Build only
use Path;
use ;
let warnings = build.await?;
for warning in warnings
On success, build returns the warnings collected during the build (unreadable assets, non-module scripts, bundler warnings).
BuildOptions presets:
BuildOptions::DEV: no minification, with sourcemaps, no hashed filenames.BuildOptions::PROD: minifies CSS, JS, and HTML, hashed filenames, no sourcemaps.
Combine a BuildOptions preset with a base:
let options = BuildOptions ;
Build your own options:
use ;
let options = BuildOptions ;
BuildOptions::minify is a set of targets:
use Minify;
// minify everything (the prod default)
let all = ALL;
// minify css and js, keep the html untouched
let assets = CSS | JS;
// parse the CLI form
let targets: Minify = "css,js".parse.unwrap;
3. Watch and rebuild, no serve
use Path;
use broadcast;
use ;
let = channel;
// Build `src/` into `dev/` on startup, then on every change of an
// `.html`, `.css` or `.js` file; pass `&[]` to watch every file
let watcher = watch
.await?;
// runtime logs are reported on your broadcast channel:
// (sent on `tx_log`, consumed with `rx_log.recv()`)
// - `WatchLog::Built { cause, reload_type, paths }`: successful builds
// `cause`: `BuildCause::Startup`, `Change` or `Lagged`
// `reload_type`: `ReloadType::Page` or `ReloadType::Css`
// `paths`: `Vec<PathBuf>`
// - `WatchLog::Warn(String)`: build warnings
// - `WatchLog::Error(String)`: build failures during watch (previous build is kept)
spawn;
watcher.run.await?; // rebuilds until the future is dropped
Watch is the handle returned by watch. watch_serve below runs the same rebuild loop behind the server, with the same name/suffix filter (&[] watches every file).
4. Watch, rebuild and serve (live reload)
use IpAddr;
use Path;
use broadcast;
use ;
let config = ServerConfig ;
let = channel;
// `BuildOptions::DEV` for the dev loop; `&[]` watches every file
let server = watch_serve.await?;
println!;
// runtime logs are reported on your broadcast channel (see example above)
spawn;
server.run.await?; // blocks until shutdown
The served prefix ServerConfig.base has to match the build prefix BuildOptions.base.
When building and serving manually, use BuildOptions.server_base() to populate ServerConfig.base (String) from options.base (Option) and ensure consistency.
In watch_serve, ServerConfig.base is ignored and overwritten by BuildOptions.base using BuildOptions.server_base().
Feature flag
The default features:
- are required for:
serve,watch_serve,ServerandServerConfig, - are not required for:
build,watch,Watch,WatchLog,MinifyandBuildOptions.
To build or watch without the server (and drop the axum dependency):
= { = "0.8", = false }
Local installation
# clone the repo
# build the project
# watch `client/src`, serve `client/dev`
# install globally from the local package
# compiles and copies the binary to `~/.cargo/bin/bundla`
# use from anywhere
# from the current directory, build `src/` into `dist/`
# update later after source changes
Known bug
HTML minification and templates
HTML is minified by minify-html, which parses the inside of a start tag as an attribute list. Template tags placed between attributes can therefore be corrupted. This is an upstream bug in minify-html, not a bundla limitation: wilsonzlin/minify-html#232.
If your templates place tags inside HTML start tags (e.g. conditional boolean attributes), leave the html target out for now: