CLI: `create-mc-bedrock`

create-mc-bedrock is the scaffolder. It lays down a single opinionated Bedrock add-on workspace, regenerates manifest UUIDs, and optionally installs dependencies. It does this once; the day-2 work of adding features is handled by the create generators on the compiler.

This page is the reference. For where the scaffolder fits next to mct and Regolith, see Bedrock CLI vs mct vs Regolith. For the day-one walkthrough, see Getting Started.

No more source picker. Earlier versions asked you to pick a source (Custom / Microsoft Samples / Community Templates). 3.0 ships one opinionated starter. The flow is linear: name → destination → language → scaffold. Remote-fetch sources are gone.

Usage

npx create-mc-bedrock

That's it. The CLI is interactive. There are no required flags.

Requirements

Node.js 18 or later. The scaffolder uses fs.cp, which lands in Node 18. Check with node --version.
A working npm install. npx ships with npm and runs the scaffolder without a global install.

The interactive prompts

The prompts run in this order. Each one validates inline; mistakes are re-asked rather than failing the whole run.

1. Project name

? Project name:

Becomes the folder name for the new project and the value of name in config.json. It's also propagated into the manifest header.name fields as <name> BP and <name> RP, and is the basis for the derived namespace the generators use.

2. Destination folder

? Destination folder: (./<project-name>)

Where the project lands. Defaults to a subdirectory of the current working directory named after the project. Press Enter to accept.

3. Language

? Language?
  > TypeScript
    JavaScript

Sets the starter entry language. TypeScript opens to src/main.ts; JavaScript opens to src/main.js. Either way the workspace supports both languages at once: the bundled tsconfig.json has allowJs, the typescript dev dependency is included, and esbuild bundles a mixed .ts / .js import graph. The chosen entry is recorded under bedrock-cli.entry in config.json. See entry in the config schema.

4. Auto-install dependencies?

? Install dependencies now? (Y/n)

Picking Yes runs npm install in the new project. Picking No finishes the scaffold and leaves dependency installation to you.

What gets generated

A single opinionated starter, expanded so the generators always have a target folder and a registry file to merge into:

my-addon/
  config.json
  package.json                # includes the create:* npm scripts
  tsconfig.json               # allowJs: doubles as the JS workspace
  .gitignore
  .vscode/extensions.json
  README.md
  src/
    main.ts                   # or main.js if you chose JavaScript
  packs/
    BP/
      manifest.json           # fresh UUIDs, script entry scripts/main.js
      pack_icon.png
      items/ entities/ blocks/ spawn_rules/ recipes/ loot_tables/
    RP/
      manifest.json           # fresh UUIDs, depends on BP
      pack_icon.png
      attachables/ animations/ animation_controllers/ render_controllers/
      entity/                 # client_entity (singular)
      models/entity/
      texts/
        en_US.lang            # seeded: pack.name / pack.description
        languages.json        # ["en_US"]  (required, or .lang is ignored)
      textures/
        item_texture.json     # seeded registry
        terrain_texture.json  # seeded registry
        items/ blocks/ entity/
      blocks.json             # seeded registry
  dist/                       # build output, gitignored

The seeded registry files (item_texture.json, terrain_texture.json, blocks.json, texts/en_US.lang, texts/languages.json) exist so the create generators do a read-merge-write into a valid skeleton instead of branching on create-if-missing. The empty folders carry .gitkeep so they survive git checkout.

languages.json is load-bearing. It ships as ["en_US"]. Without it, Minecraft silently ignores en_US.lang, and every generated display name (especially blocks, entities, and spawn eggs, which have no inline fallback) would do nothing.

If you chose JavaScript at the Language prompt, the starter entry is src/main.js instead of src/main.ts (recorded under bedrock-cli.entry). Everything else, including tsconfig.json and the typescript dep, is identical: you can add .ts files to a JavaScript workspace and .js files to a TypeScript one, and both build.

The create:* scripts

The scaffolded package.json wires the generator family to npm scripts:

"scripts": {
  "folders": "bedrock-build folders",
  "build": "bedrock-build build",
  "watch": "bedrock-build watch",
  "deploy": "bedrock-build deploy",
  "deploy:watch": "bedrock-build deploy --watch",
  "pack": "bedrock-build pack",
  "release": "bedrock-build build --release",
  "create:weapon": "bedrock-build create weapon",
  "create:tool": "bedrock-build create tool",
  "create:armor": "bedrock-build create armor",
  "create:item": "bedrock-build create item",
  "create:entity": "bedrock-build create entity",
  "create:block": "bedrock-build create block"
}

These are the day-2 loop. See the generator reference.

Manifest UUID regeneration

Every scaffold gets a fresh set of UUIDs for both the BP and RP manifests, and the cross-references between them are wired up correctly in one pass:

Each header.uuid is replaced with a new v4 UUID.
Each modules[].uuid is replaced with a new v4 UUID.
BP dependencies[].uuid entries are pointed at the new RP header UUID.
RP dependencies[].uuid entries are pointed at the new BP header UUID.
dependencies[].module_name entries (like @minecraft/server) are left untouched.

See Packs and Manifests for what each field means.

Version pinning at scaffold time

The starter package.json doesn't ship hard-coded version strings. Instead, the scaffolder queries the npm registry for the latest stable version of each of:

@minecraft/server
@minecraft/server-ui
typescript
@keyyard/bedrock-build

It writes the resolved version strings into the generated package.json before handing the project over. Every fresh scaffold is pinned to current latest, with no maintenance burden on the template.

Offline scaffolding. If the registry fetch fails (no network, npm mirror down), the scaffolder falls back to a known-good baseline version for each dependency. The scaffold still succeeds; you'll just get older pins until you npm install an updated version.

Behavior notes

Existing directory: if the destination folder already exists and is non-empty, the scaffolder refuses and asks for a different name. No clobbering.
pack_icon.png: included in both BP and RP. Replace with your own art before shipping.
No namespace key in config.json. The starter ships without one; the compiler derives the namespace from name at load time. Add a namespace under bedrock-cli only if you want a stable, explicit one. See Config schema: namespace.

After scaffolding

cd my-addon
npm install          # if you skipped the prompt
npm run create:item  # add your first feature
npm run deploy:watch # hot reload into Minecraft

CLI: create generators for the create:* family.
Bedrock CLI vs mct vs Regolith for the positioning.
Workspace Layout for the starter tree.
Config schema for what config.json controls.
Packs and Manifests for the manifest fields the scaffolder rewrites.

Custom Deploy Path CLI: create generators

CLI: create-mc-bedrock