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. You'll see prompts for:

Source. Pick one of three starting points:
- Custom: the new default. A bedrock.config.json workspace wired up to @keyyard/bedrock-build. Pick this unless you have a reason not to.
- Microsoft Samples: the official samples from microsoft/minecraft-scripting-samples (opens in a new tab). Good for following an MS tutorial verbatim.
- Community Templates: specialized starters from keyyard/custom-mc-scripting-templates (opens in a new tab).
More detail on the trade-offs: Which source?.
Project name. Becomes the folder name and the value of name in bedrock.config.json.
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.

Look at what you got

After the scaffolder finishes, the workspace looks like this (Custom source):

my-addon/
  bedrock.config.json
  package.json
  tsconfig.json
  src/
    main.ts                   ← your TypeScript 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.

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 deploy.target to "custom" and point 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

Learn the model. Start with Workspace Layout, then Which source? to understand 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