Skip to content

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.

Terminal window
rudder module new bonus
created the module bonus 0.1.0 in /work/my-game/bonus; rudder module test and rudder module build run in it

Creates 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.

Terminal window
rudder module test
rudder module test -v -run TestClaim
rudder module test --json

Generates, 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.

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.

FlagMeaning
--allow-breakingAccept 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.

Generates, then compiles <directory name>.wasm and writes the built manifest next to it as <directory name>.manifest.json.

FlagMeaning
--allow-breakingAs for generate.
--compilertinygo (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/toolchain
rudder: TinyGo 0.42.0 ready in 11s

Downloads exist for macOS (Intel and Apple silicon), Linux (x86-64 and ARM64) and Windows (x86-64).

Terminal window
rudder module require inventory@^1.0
required inventory ^1.0, wrote requires/inventory.json with inventory 1.0.0

rudder 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>.

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 project
installed into the draft
staging is at version 12

With --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.

FlagMeaning
--releasePublish the version of manifest.json as it is, the one to promote, and write rudder.lock.json.
--sharedPublish 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-breakingSkip the local check and, with --release, rewrite rudder.lock.json after the upload; for the first version of a new line.
--compilerAs for build.

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.

Besides those of the CLI:

VariableMeaning
RUDDER_TINYGO, WASMOPTYour own TinyGo and binaryen wasm-opt, instead of the ones the CLI downloads.

In CI, publish with a personal access token in RUDDER_TOKEN:

Terminal window
rudder module publish --json