Skip to content
Mercury
English
Design Book
Menu
English

mx, the native toolchain

One Rust binary that takes a Mercury app from its mx.mod to a served page and a bundle, with no node on PATH.

mx is Mercury's native toolchain. It reads a module's mx.mod and a workspace's mx.work, serves an app with hot reload, checks its code, runs browser tests and builds distributable files.

This page follows a source build at 1fe54fe8, reporting mx 0.1.1. Publication of that build is pending; check the installation guide for the currently available downloads. Typechecking uses a native compiler sidecar; tests require Chromium. The native archive route does not require Node or npm.

What mx is

  • A module system after Go's. A module declares itself in mx.mod and pins what it downloaded in mx.sum. Modules developed together sit in one mx.work. The commands mx mod … and mx work … keep those files, as go mod and go work keep theirs.
  • A dev server. mx dev serves an app on 127.0.0.1 with its import map inline and compiles each module on request.
  • A bundler. mx build --bundle bundles the app's page with Rolldown, linked into mx itself, so the bundle is made with no node on PATH.
  • A test runner and the tools around them: mx test runs a module's tests in a headless browser that mx starts itself, mx compile runs the Hypercompiler on one file, and mx lsap starts the Hyperscript language server installed beside mx.

It is an independent Rust workspace in fiberfx/mx, not a Mix application.

For work on Mercury’s own sources, use mg — Mercury Go: discover commands, generate examples and get structured answers for automation. Begin with your first commands; mx continues to build and test applications.

mx new hello starts an app from the module cache. mx lint, mx fmt and mx typecheck check its code; mx quality runs all three stages. mx pack --npm prepares and verifies a package archive. Follow the tools lesson for setup and examples.

The commands

mx with no command prints its usage line and exits 2:

usage: mx exodus|pack|install|verify|importmap|resolve|scan|build|check|run|compile|work|dev|test|lint|fmt|typecheck|quality|new|lsap …

One more family is dispatched before that line is read and is missing from it: mx mod, whose own usage is usage: mx mod <init|tidy|verify|graph|why|download|cache>.

The commands that take flags print their usage when they are given one they don't know:

usage: mx dev [--root <dir>] [--port <n>] [--importmap] [--inspect]
usage: mx test [<path>...] [--root <dir>] [--timeout <seconds>] [--filter <words>]
usage: mx compile <file> [--options <json>] [--out <file>]
usage: mx build [--bundle] [--root <dir>] [--out <dir>]
usage: mx lsap [--mcp] | mx lsap --version
usage: mx work edit|use|init|sync|vendor …

mx build --help lists four build forms: the host, the app (--bundle), one library entry (--lib) and a library package (--package). It also says how mx picks one when no kind is given: mx.json makes a host build, index.html beside mx.mod makes an app bundle, and package exports with mercury-source entries select a library package. --help is help only as the first argument. The first lesson explains how mx build decides.

How mx answers

For the commands taught here, read the exit code together with the output:

Exit Meaning
0 success
1 findings or a refusal; the message names the reason
2 a usage error: the command line is wrong
3 a check could not run, such as an unavailable browser or compiler

An unavailable check has not passed. Quality commands can print findings on stdout. A single quality verb with --json returns one stage object; mx quality --json returns a list of stage objects. Other commands have their own output formats.

Install mx

Use Install mx to download the native Linux x86_64 archive and pinned starter, verify their SHA-256 checksums and run mx install and mx verify. This path needs no Rust, Node.js, npm CLI, BEAM or repository checkout. The first-page lesson creates a styled Card + Button counter.

The chapters

  1. MX0 — first app: an app is an index.html beside an mx.mod; serve it with mx dev, bundle it with mx build --bundle.
  2. MX1 — modules and workspace: mx.mod, mx.sum and mx mod, then mx.work and mx work.
  3. MX2 — dev loop and HMR: what mx dev serves and how a saved edit reaches the page.
  4. MX3 — build and ship: mx build --bundle, --lib and the host's build, and mx check.
  5. MX4 — the Hypercompiler: mx compile, and what it does to every module mx dev and mx build serve.
  6. MX5 — tools: create, check, test, cache and pack.

The course's capstone builds a native app with no node on PATH. The retained sites/mercury example can exercise that build; the live documentation website runs as the Phoenix mercury_lms application.

Release and source versions

The release metadata identifies the site's retained native archive and source revision. Use the installation guide for current publication and platform evidence; a landed source build is not automatically available from mx.jonnify.com or npm.

The measured mx new command writes mx 0.1.1 into the new module file. Older mx.mod and mx.work examples may declare mx 0.1.0; keep existing projects' declarations unless a module command or an explicit compatibility change calls for updating them.