CLI: bedrock-build

@keyyard/bedrock-build is the compiler for Custom-source workspaces. It bundles TypeScript or JavaScript via esbuild, copies pack assets, deploys to Minecraft, and packages .mcaddon files.

This page is the full CLI reference. For the config file it reads from, see the Config Schema.

Usage

bedrock-build <command> [options]

Commands

Global options

build

bedrock-build build [options]

Behavior. Loads and validates config.json. Bundles the entry file via esbuild (ES2020 ESM, with the @minecraft/server-* packages marked as external) to <out>/packs/BP/scripts/main.js. Copies <packs.behaviorPack>/* to <out>/packs/BP/ (excluding any existing scripts/, to avoid clobbering the bundle), and copies <packs.resourcePack>/* to <out>/packs/RP/. Only writes under <out>/, never modifies sources. Sourcemaps are inline in dev mode and off in release mode. Minification is off in dev mode and on in release mode.

# Dev build, fast iteration
npx bedrock-build build
 
# Production build
npx bedrock-build build --release
 
# Fully clean rebuild
npx bedrock-build build --clean --release

watch

bedrock-build watch [options]

No watch-specific flags in v1.

Behavior. Runs a dev-mode build, then watches the entry file and its imports (via esbuild's watch context), <packs.behaviorPack>/**/* (excluding its scripts/ folder), and <packs.resourcePack>/**/* via chokidar. Source changes trigger an incremental esbuild rebuild. Pack file changes copy the changed file to its dist/ mirror. Changes are debounced 50ms. Each rebuild logs a timestamp and what changed. Ctrl+C exits cleanly with code 0.

Watch mode never minifies and never deploys. For deploy-on-save, use deploy --watch instead.

npx bedrock-build watch

deploy

bedrock-build deploy [options]

Behavior. Runs build (honoring --release), then resolves the deploy target:

• bedrock-cli.deploy.target === "retail": globs %LOCALAPPDATA%\Packages\Microsoft.MinecraftUWP_*\LocalState\games\com.mojang\ on Windows. Exits with code 3 if not found.
• bedrock-cli.deploy.target === "custom": uses bedrock-cli.deploy.customPath directly. Exits with code 3 if the path doesn't exist.

The compiler then removes <comMojang>/development_behavior_packs/<name>/ and <comMojang>/development_resource_packs/<name>/ (clean slate) and copies the freshly built dist/packs/BP/ and dist/packs/RP/ into them. If --watch is set, it stays running and re-deploys on every rebuild.

# Hot reload during development
npx bedrock-build deploy --watch
 
# One-shot release deploy (e.g. for a final playtest)
npx bedrock-build deploy --release

pack

bedrock-build pack [options]

Behavior. Always runs a release build first. There is no --dev-pack. Then creates a zip with two top-level subfolders:

<name>-<version>.mcaddon
  <name>_BP/    ← contents of dist/packs/BP/
  <name>_RP/    ← contents of dist/packs/RP/

Minecraft accepts this layout when the user double-clicks the .mcaddon. Logs the output path and file size on completion. Exits with code 4 on zip failure.

# Default output: dist/my-addon-1.0.0.mcaddon
npx bedrock-build pack
 
# Custom output path
npx bedrock-build pack --output ./releases/my-addon.mcaddon

folders

bedrock-build folders

No flags. Interactive only.

Behavior. Shows two multiselect prompts (Behavior pack, then Resource pack) listing the canonical Bedrock subfolders. Tick the ones you want and the command creates them under <packs.behaviorPack>/ and <packs.resourcePack>/ respectively. Folders that already exist are marked (exists) in the list and are silently skipped if picked again.

The picker is what saves you from having to remember which side uses plural vs. singular: BP/entities/, RP/entity/, RP/textures/entity/, RP/models/entity/. The list also covers everything in between: animation_controllers, attachables, feature_rules, loot_tables, render_controllers, spawn_rules, trading, and the rest.

packs/BP/scripts/ is intentionally not offered because it is owned by the bundler (build writes main.js directly into it).

# From a scaffolded project
npm run folders
 
# Or directly
npx bedrock-build folders

Cancel either prompt (Ctrl+C / Esc) to abort without touching the disk.

Exit codes

Use these in CI to handle specific failure modes. For example, exit code 2 is always a fixable config problem, while exit code 3 means the machine running the deploy doesn't have Minecraft installed in the expected place.

Common invocations

# First-time build to verify the workspace
npx bedrock-build build
 
# Day-to-day: rebuild and hot-reload into Minecraft on every save
npx bedrock-build deploy --watch
 
# Release: produce a shareable .mcaddon
npx bedrock-build pack
 
# CI: clean release build, fail fast on config errors
npx bedrock-build build --clean --release
 
# Override config path (monorepos, multiple add-ons, etc.)
npx bedrock-build build --config ./addons/my-addon/config.json