Module commands
rudder module new <name>rudder module test [directory] [go test flags]rudder module generate [--allow-breaking] [directory]rudder module build [--allow-breaking] [--compiler tinygo|go] [directory]rudder module require <module>@<range> [directory]rudder module require <dependency directory> [directory]rudder module publish [--release] [--shared] [--allow-breaking] [--compiler tinygo|go] [directory]These commands come with the CLI (Download); they take the flags common to
every command of the CLI. directory is the module directory, the
current one by default.
The module commands need nothing but the CLI. It carries the Module SDK of its own version and
writes go.work into the module directory, ignored by git, which points Go at that SDK, so
plain go test, go vet and your editor work in the module too. They use the Go on your
PATH when it is 1.25 to 1.27, and otherwise Go 1.27.3, downloaded once into the cache of your
user. go mod tidy does not work in a module yet: run tests through rudder module test.
rudder module new
Section titled “rudder module new”rudder module new bonuscreated the module bonus 0.1.0 in /work/my-game/bonus; rudder module test and rudder module build run in itCreates the directory <name> with a module of that name: manifest.json, main.go with the
mutation click, main_test.go with its test, AGENTS.md with the rules of writing a module,
go.mod, .gitignore, and the generated files; no rudder.lock.json, which the first publish
writes. rudder module test and rudder module build pass in it at once. A name is lowercase
letters and digits, starting with a letter; any other name is refused with exit 2, usage. A
directory that is not empty is refused with exit 5, directory_not_empty.
rudder module test
Section titled “rudder module test”rudder module testrudder module test -v -run TestClaimrudder module test --jsonGenerates, then runs go test ./... in the module, with the output of go test on stdout. The
first argument that is not a flag is the directory; every other argument goes to go test.
With --json it runs go test -json and passes its events through as they are. A failed test
exits with 1, tests_failed; with --json the error object follows the events.
rudder module generate
Section titled “rudder module generate”Reads manifest.json and the Go package and writes rudder_gen.go (types, catalogs, the
wiring of fields and functions), rudder_gen_test.go (the test client) and the packages of
requires/. Fails with the reason on anything the Module SDK does not
accept, on a module in manifest.json that is not lowercase letters and digits starting with
a letter (exit 6, path module), and with exit 5 on a breaking change against
rudder.lock.json when the module has one. It never writes rudder.lock.json.
| Flag | Meaning |
|---|---|
--allow-breaking | Accept a breaking change; rudder.lock.json stays as it is until the next publish. |
A module usually runs it through //go:generate rudder module generate and go generate.
rudder module build
Section titled “rudder module build”Generates, then compiles <directory name>.wasm and writes the built manifest next to it as
<directory name>.manifest.json.
| Flag | Meaning |
|---|---|
--allow-breaking | As for generate. |
--compiler | tinygo (default) or go, the standard Go toolchain on your PATH, for a module that hits a limit of TinyGo. |
With tinygo, the CLI uses TinyGo and wasm-opt from RUDDER_TINYGO and WASMOPT, then from
PATH, and otherwise downloads its pinned versions (TinyGo 0.42.0, binaryen 133) once into the
cache of your user, each checked against its SHA-256, together with Go 1.27.3 when no Go 1.25 to
1.27 is on PATH. Later builds reuse them. The first build prints:
rudder: downloading TinyGo 0.42.0 (163 MB) into ~/Library/Caches/rudder/toolchainrudder: TinyGo 0.42.0 ready in 11sDownloads exist for macOS (Intel and Apple silicon), Linux (x86-64 and ARM64) and Windows (x86-64).
rudder module require
Section titled “rudder module require”rudder module require inventory@^1.0required inventory ^1.0, wrote requires/inventory.json with inventory 1.0.0rudder module require <module>@<range> [directory] finds the newest published version of the
module, of the marketplace or of the project, that fits the caret range, writes its contract
(its built manifest, with its version) into requires/<module>.json of your module (the
directory, the current one by default) and sets requires.<module> of manifest.json to the
range. It needs a project and a sign-in. With --json: {"module", "range", "version"}. No
version that fits exits with 4, module_not_found.
rudder module require <dependency directory> [directory] copies the contract of a module
from its source directory instead, without asking Rudder. Run either again when the required
module changes; generation then updates the package requires/<module>.
rudder module publish
Section titled “rudder module publish”Builds, then uploads the module, its built manifest and samples/ to the project as a dev
build of the version of manifest.json (0.4.1 is published as 0.4.1-dev.3, the next number
of that version), puts it into the draft and publishes the next release of staging with it:
the newest release of staging with this module put in, and nothing else of the draft. Prints:
published bonus 0.4.1-dev.3 for the projectinstalled into the draftstaging is at version 12With --json: {"module", "version", "shared", "release"}, without release when nothing went
onto staging. The environment must be staging; anything else exits with 2. A release whose rows
do not fit the version exits with 5, release_refused, with the problems, and changes nothing.
A dev build of a version that is released exits with 5, version_behind. A release of staging
that holds a dev build is not promoted; see Dev builds.
With --release the version is published as manifest.json gives it and goes onto staging the
same way. Once Rudder accepted it, publish writes rudder.lock.json, the contract later
versions are checked against; commit it. Rudder refuses a version that breaks the contract of
an earlier version of its line with exit 5, incompatible_contract, even with
--allow-breaking; see Version lines. Without
rudder.lock.json it checks against the contract of the published version of the line before
the upload.
| Flag | Meaning |
|---|---|
--release | Publish the version of manifest.json as it is, the one to promote, and write rudder.lock.json. |
--shared | Publish to the marketplace of every project instead, which only Rudder may do; with a project set it also goes onto the staging of that project. |
--allow-breaking | Skip the local check and, with --release, rewrite rudder.lock.json after the upload; for the first version of a new line. |
--compiler | As for build. |
Errors
Section titled “Errors”The output of the compiler goes to stderr, so stdout holds the result only. With --json, the
path of an error is, when known, the place in manifest.json (types.<name>,
content.<catalog>, events.<event>, requires.<module>) or the field of a row the error is
about:
{"error": {"code": "invalid_module", "message": "...", "path": "types.Offer"}}The exit codes are those of the CLI.
Environment variables
Section titled “Environment variables”Besides those of the CLI:
| Variable | Meaning |
|---|---|
RUDDER_TINYGO, WASMOPT | Your own TinyGo and binaryen wasm-opt, instead of the ones the CLI downloads. |
In CI, publish with a personal access token in RUDDER_TOKEN:
rudder module publish --json