Crust

@crustjs/crust provides the crust CLI. crust build stages runtime packages or standalone binaries in .crust/, together with npm packaging metadata. crust publish uploads the npm packages; other distribution channels, such as release downloads or Homebrew, use the built binaries directly. The same build is available to scripts as build(). The Build and distribution guide walks through the workflow; this page is the reference.

InstallCopy Anchor Link

npm install -D @crustjs/crust

• Installed through npm, the crust command is a Node launcher for a standalone executable with Bun embedded. That launcher requires Node; a separate Bun installation is not needed. This is a build-tool installation requirement, not a requirement for users running your generated binaries directly.
• Without bun on PATH, arm64 hosts cannot build their own target. The error names the targets you can build; otherwise install Bun.
• @crustjs/crust optionally depends on tsdown and @tsdown/exe, which build Node.js binaries with the node on PATH. Other builds never load them, so an install that skipped them, for example under a Node.js outside tsdown's engines, still builds everything else.
• Deno binaries need deno on PATH; Deno runtime packages (experimental) need deno 2.5.0 or newer there.
• The build() library is a plain JavaScript module, so it needs bun on PATH unless the script runs under Bun. @crustjs/core is a peer dependency so BuildReport is the same type your Extensions see.

npm installation caveatCopy Anchor Link

CommandsCopy Anchor Link

crust build --artifact binary --target bun-linux-x64
# Runtime: bun (default)
# Artifact: binary
# Compiler: bun 1.4.2 (/usr/local/bin/bun)
# Staging 1 distribution target(s) in .../.crust...
#   → linux-x64: .../.crust/linux-x64/bin/my-cli-bun-linux-x64
# ✓ Staged 2 npm package(s) successfully: (excerpt)

crust build validates your CLI and stages it in .crust/. crust publish publishes the staged npm packages, not release archives, Homebrew formulas, or other installer metadata.

crust build optionsCopy Anchor Link

Command names, entry files, runtime, default targets, Bun bundler plugins, extra directories, and external dependencies are not flags: they come from bin and the crust block in package.json.

crust publish optionsCopy Anchor Link

crust publish --dry-run
# Publish order: linux-x64 -> ... -> root
#   → linux-x64: npm publish

crust publish reads .crust/manifest.json and fails with Run crust build before crust publish if there is none. It uses npm, which must be on PATH, because npm supports trusted publishing from CI.

• For each staged package, it checks name@version with npm view and runs npm publish only if that version is missing. Existing versions are skipped and never re-tagged, so rerunning after a failure resumes. --dry-run stays offline.
• Before anything publishes, it verifies the manifest, that package names are unique, and that every package directory resolves inside the staging root.
• When stdin is a TTY, npm inherits the terminal so browser or OTP authentication can complete.
• npm reads publishConfig.access from each staged package.json, copied from your project. Scoped public packages need "publishConfig": { "access": "public" }. See Publishing from CI for credentials.

Programmatic APICopy Anchor Link

build(options?) runs the crust build pipeline and resolves to what it staged. See Programmatic builds for a release-script example.

• build() validates bin, the crust block, and its options with the same errors the CLI prints, selects the compiler (checking engines for binaries, and tsdown's requirements for Node.js binaries, whose targets' Node.js binaries are also downloaded and unpacked then), then wipes .crust/ and stages every package. manifest.json is written last.
• It throws on failure and prints nothing; onLog receives each progress line with its stream.
• BuildReport is @crustjs/core's type, re-exported.
• Overlapping builds for the same real project directory reject before staging, including across processes and symlink aliases. An exclusive .crust.lock directory beside .crust/ is removed on success or failure. If a process is interrupted, remove the leftover lock only after confirming no build is running. Consume staged artifacts before rebuilding; the lock does not protect publishing or other readers.

Build outputCopy Anchor Link

crust build stages its output in .crust/: manifest.json, root/, one <platform>/ per selected target for binaries, and artifacts/ from Extension build hooks. The tree is ready for npm publishing, but npm is optional: distribute <platform>/bin/ with its adjacent data for direct-binary installation. The executable embeds its runtime; only the npm launcher needs Node.js. Runtime packages instead use root/ and require the user's selected runtime.

The build checks that package.json has non-empty name and version before wiping the previous stage, even with --no-validate. See Build for the tree and Custom distribution for release archives and installers.

manifest.json records the build's runtime and artifact. Binary builds also record embeddedRuntimeVersion, the version the selected compiler reported and embedded in every platform binary; runtime packages embed no runtime and omit it. See Binary runtime version.

Staged package.json filesCopy Anchor Link

Staged manifests are generated rather than copied:

¹ Node.js binaries omit engines.node, which constrained the Node.js that built and is embedded in the executables, from platform packages, and from the root unless it carries exports, whose importers need it. Other engines keys are copied.

README.md is copied into the root package and the license file into every package. Platform manifests carry os, cpu, and, on Linux, libc.

To ship a library alongside the CLI:

• exports targets must be ./ paths to staged files: a crust.include file, an Extension artifact, or ./package.json. Nested conditions and null are supported; wildcards, fallback arrays, missing files, and ., .., node_modules, or empty segments are rejected.
• Included files are copied, not transformed. A CommonJS source package needs an included nested package.json such as dist/package.json with {"type":"commonjs"}, or explicit .cjs/.d.cts extensions.
• Peer ranges are published as written: workspace:, catalog:, file:, link:, and portal: ranges are rejected, as are local paths (./native, ../native, /opt/native, ~/native) and local tarballs (native.tgz). peerDependenciesMeta entries must name declared peers.

Supported targetsCopy Anchor Link

Targets apply to binaries. --target overrides crust.targets; without either, all targets of the compiler are built. host selects this machine's OS, architecture, and Linux C library and can be mixed with explicit targets. Runtime packages reject both --target and crust.targets.

Node.js targets use Node.js's own release names. Cross-platform builds download that target's official Node.js archive of the same version; see Node.js binaries for the unpacking tools and macOS signing.

Each platform package contains bin/<command>-<target> (.exe on Windows) per command. The launcher supports only the targets included in the build.

Linux glibc and muslCopy Anchor Link

Plain Linux targets use glibc; Alpine needs Bun's -musl targets. The launcher detects the host C library and selects the matching binary. Deno and Node.js have no musl target.

Commands and entries (bin)Copy Anchor Link

{
  "bin": { "my-cli": "src/cli.ts", "my-cli-admin": "src/admin.ts" }
}

Each bin key is an installed command name and each value is the TypeScript entry compiled for it. Every entry becomes bin/<command>.js in the root package and, for binaries, a <command>-<target> binary in every platform package. A string bin names one command after the unscoped package name; without bin, the build compiles src/cli.ts under that name.

• Entries must be relative paths to existing files inside the project. Containment is checked lexically; symlinks may point elsewhere. Two commands cannot share one entry (compared by real path).
• Command names follow the installed command name rule: letters, digits, ., _, and -, starting with a letter or digit. They cannot differ only by case.
• A validated build requires each entry's root command to be named after its key, such as new Crust("my-cli-admin") for "my-cli-admin": "src/admin.ts". --no-validate skips this check.
• npm link runs the source entry directly, so it needs the runtime's shebang (#!/usr/bin/env bun, #!/usr/bin/env node, or #!/usr/bin/env -S deno run -A). create-crust templates include it. Link .crust/root to exercise the built distribution instead.

package.json configurationCopy Anchor Link

{
  "crust": {
    "runtime": "bun",
    "artifact": "binary",
    "targets": ["bun-linux-x64", "bun-linux-arm64", "bun-darwin-arm64"],
    "bunPlugins": ["@opentui/solid/bun-plugin", "./build/plugin.ts"],
    "include": ["templates"]
  }
}

crust.artifact is required unless every build passes --artifact; the other keys are optional. Unknown keys under crust fail the build, so typos such as bunPlugin are not ignored.

crust.include entries must be existing directories inside the project, cannot be named bin, cannot be inside .crust, and cannot reuse an Extension artifact directory name. Names are compared ignoring letter case (Bin, Assets vs assets) because they alias on case-insensitive file systems. Symlinks are copied dereferenced and must resolve inside the project.

Each crust.external entry must be listed once and be a key of dependencies; a package only in devDependencies, optionalDependencies, or peerDependencies is rejected, as are subpaths and wildcards. Its range must be publishable, by the same rules as peer ranges above. @crustjs/* packages, and npm aliases of them such as npm:@crustjs/utils@0.2.2, cannot be external: core detects a built package through a value the bundler inlines, and an external Crust package would load a second copy of core. An empty list does nothing. These checks run before .crust/ is wiped.

Editor completionCopy Anchor Link

@crustjs/crust ships a JSON schema for this block. It extends the SchemaStore package.json schema, so completion for the standard fields keeps working. create-crust templates set it; crust build never copies $schema into staged packages.

{
  "$schema": "./node_modules/@crustjs/crust/schema/package.json"
}

Extension artifactsCopy Anchor Link

.crust/artifacts/
├── man/<name>.1
├── skills/
└── completions/

Registered Extensions such as man(), skill(), and completion() contribute build hooks. crust build runs those hooks while preparing each entry, writes the files they return, and copies each top-level directory into .crust/root/ and every platform package's bin/. A CLI reads them back with resolveArtifactDir(name).

• Each hook's returned paths are recorded per bin entry under build in .crust/manifest.json. Loose top-level files are recorded but not copied into packages.
• With several bin entries, same-named directories merge, so man/greet.1 and man/admin.1 coexist. A path two entries both write fails the build naming both commands; collisions are compared case-insensitively.
• Upgrade @crustjs/core, @crustjs/crust, and build-hook Extensions together. Reports from an incompatible Core fail preparation with upgrade guidance.
• --no-validate skips all build hooks, so no artifact directories are staged and the manifest has no build field.

Entry modules run during preparation and are not sandboxed; files they write elsewhere are not reported.