Getting Started

This walkthrough scaffolds a fresh Bedrock add-on, builds it, hot-reloads it into Minecraft, and packages it as a .mcaddon. It should take about five minutes.

Prerequisites

Node.js 18 or later. Check with node --version. Anything older will not run the scaffolder or the compiler.
A working Minecraft for Windows (Bedrock retail) install if you want to use the deploy command's hot-reload flow. Mac and Linux retail detection is not in 2.0, but the custom deploy path works on every platform.

Scaffold a new project

npx create-mc-bedrock

The scaffolder is interactive and the flow is linear (no source picker). You'll see prompts for:

Project name. Becomes the folder name and the value of name in config.json.
Destination folder. Defaults to ./<project-name>. Press Enter to accept.
Language. TypeScript or JavaScript. Either way the entry point is bundled by esbuild, so pick whichever you prefer.
Install dependencies? Yes/No. If you say yes, the scaffolder runs npm install for you. Either way, manifest UUIDs are freshly generated for this project, with no copy-paste collisions.

You get one opinionated starter wired to @keyyard/bedrock-build, with the create:* generators ready to go. For where this sits next to mct and Regolith, see Bedrock CLI vs mct vs Regolith.

Look at what you got

After the scaffolder finishes, the workspace looks like this:

my-addon/
  config.json
  package.json
  tsconfig.json
  src/
    main.ts                   ← your TypeScript or JavaScript entry point
  packs/
    BP/
      manifest.json           ← UUIDs frozen at scaffold time
      blocks/ entities/ items/ ...
    RP/
      manifest.json
      textures/ models/ ...
  dist/                       ← gitignored; owned by bedrock-build

Full breakdown: Workspace Layout.

Add the folders you need (optional)

Bedrock pack folders have a few footguns (BP/entities/ plural, RP/entity/ singular, etc.). Instead of guessing, run:

npm run folders

You'll get an interactive picker with the canonical layout. Tick the folders you want and they're created under packs/BP/ and packs/RP/. Full reference: folders command.

Generate your first feature

This is the day-2 loop. Instead of hand-wiring an item, its texture entry, and its lang line, run a generator:

npm run create:item

Press Enter through the prompts (every one has a smart default), or pass flags to skip them entirely:

npm run create:weapon -- fire_sword --mode 3d --icon sword

Each create:* command writes every linked file for the feature in one shot: the behavior JSON, the resource JSON (attachable + render controller for 3D), and the texture and lang registration. Generators are safe to re-run, support --dry-run, and emit plain standard packs. Full reference: create generators.

Run your first build

npm run build

The default build is dev mode: sourcemaps inline, no minification, fast. Output lands in dist/packs/BP/ and dist/packs/RP/. Pass --release for a minified, no-sourcemap build. See Dev vs Release builds in the CLI reference.

Hot-reload into Minecraft

npm run deploy:watch

This builds the project, copies the result into Minecraft's development_behavior_packs/ and development_resource_packs/ folders, and then watches for changes. Every save triggers a rebuild and a re-sync. Reload your world in Minecraft to see updates.

⚠️

Windows retail only for v1. The default deploy target searches six known Bedrock install layouts on Windows (modern launcher, Microsoft Store UWP, Education edition, and Preview variants), matching the detection logic in Microsoft's official build tools. Mac and Linux retail detection is a post-2.0 item. If the auto-detect misses your install, set bedrock-cli.deploy.target to "custom" and point bedrock-cli.deploy.customPath at your com.mojang directory. See the config schema and the custom deploy path guide for details.

Package a `.mcaddon`

npm run pack

This runs a release build, then zips dist/packs/BP/ and dist/packs/RP/ into dist/<name>-<version>.mcaddon. The result is a single file you can share, upload, or import by double-clicking on a machine with Minecraft installed.

pack always implies --release. There is no dev-mode pack.

Next steps

Generate features. The create generators are the day-2 loop: create:weapon, create:block, create:entity, and the rest.
Learn the model. Start with Workspace Layout, then Bedrock CLI vs mct vs Regolith to understand where this sits in the ecosystem.
Reference material. The CLI reference and config schema are the two pages you'll bookmark.
Cookbook. Recipes for common tasks land in the Cookbook as they're written.

Introduction Workspace Layout