docs
Guides
Packaging .mcaddon

Packaging a .mcaddon

A .mcaddon is the distribution format for a Bedrock add-on. It's a zip file with two subfolders (one BP, one RP), renamed so Minecraft recognizes it as installable. Double-click on a machine with Minecraft and both packs install in one step.

npm run pack produces one of these in a single command. This guide covers the output, the version bump workflow, and where to distribute the result.

Run the command

npm run pack

Output lands at dist/<name>-<version>.mcaddon, where <name> and <version> come from bedrock.config.json. To override the path, run the underlying binary with --output:

npx bedrock-build pack --output ./somewhere-else.mcaddon

What's inside

A .mcaddon is just a zip with a specific internal layout:

my-addon-1.0.0.mcaddon       (zip file)
  my-addon_BP/               (contents of dist/packs/BP/)
    manifest.json
    scripts/main.js
    blocks/ entities/ items/ ...
  my-addon_RP/               (contents of dist/packs/RP/)
    manifest.json
    textures/ models/ ...

Two top-level subfolders, named <name>_BP and <name>_RP. Minecraft recognizes this two-pack layout and installs both halves together when the user double-clicks the file.

Release mode is mandatory

pack always runs npm run release (build --release) first. There is no dev-mode .mcaddon. The reason: a shipped pack should be minified, with no inline sourcemaps, set up with NODE_ENV=production. Smaller file, faster cold start, no debug payload exposed to end users.

If you want to share a build for testing without packaging, use npm run deploy to push it into a friend's com.mojang directly, or zip dist/packs/ by hand. See Dev vs Release builds for why the two modes exist.

Version bump workflow

Before packing, bump the version in three places so they stay in sync:

  1. bedrock.config.json: the version field. This controls the .mcaddon filename.
  2. packs/BP/manifest.json: header.version (array form, e.g. [1, 1, 0]). This is what Minecraft reads to detect updates.
  3. packs/RP/manifest.json: same as above. Keep BP and RP version numbers aligned so updates stay coherent.

A quick mental checklist when releasing:

# 1. Update versions in bedrock.config.json + both manifest.json files.
 
# 2. Verify everything still builds clean.
npm run release -- --clean
 
# 3. Pack.
npm run pack
 
# 4. Look at dist/<name>-<version>.mcaddon. That's your release artifact.
⚠️

Don't ship a dev build. Dev builds carry inline sourcemaps, which roughly double the bundle size and reveal more of the source map than end users need. pack enforces release mode for this reason. If you ever zip dist/packs/ by hand, make sure the last build that ran was a release build.

Where to distribute

Once you have a .mcaddon, the file is yours to ship. Common destinations:

  • Minecraft Marketplace for paid distribution. Requires acceptance into the Minecraft Partner Program (opens in a new tab) and goes through Microsoft's submission and review process.
  • CurseForge (opens in a new tab) for free distribution with stats, comments, and a familiar mod-hosting workflow.
  • MCPEDL (opens in a new tab) for free distribution to the Bedrock community at large.
  • GitHub Releases for open-source projects. Attach the .mcaddon to a tagged release alongside your changelog.
  • Discord servers, Twitter, your own site, friends. It's just a file. Anywhere you can share a file, you can share a .mcaddon.

Related

Hot Reload SetupDev vs Release Builds