Config Schema

config.json is the single configuration file for @keyyard/bedrock-build. It lives at the project root and is read by every subcommand.

It follows the Bedrock-OSS Project Config Standard (opens in a new tab) so the same file can be shared with other ecosystem tools (bridge, Regolith, Lantern). Compiler-specific settings live under a bedrock-cli namespace key.

Filename: bedrock-build looks for config.json first, then falls back to the legacy bedrock.config.json. New projects scaffolded by create-mc-bedrock ship config.json. See Legacy configs if you have an older project.

Shape

interface ProjectConfig {
  /** Project type marker from the standard. */
  type: "minecraftBedrock";
 
  /** Project name, used for the .mcaddon filename and manifest header.name */
  name: string;
 
  /** Optional list of author names. */
  authors?: string[];
 
  /** Minecraft version this project targets, e.g. "1.21.0". Hint only. */
  targetVersion?: string;
 
  /** Pack source directories (relative to the config file). */
  packs: {
    behaviorPack: string;  // default: "packs/BP"
    resourcePack: string;  // default: "packs/RP"
  };
 
  /** Compiler settings for bedrock-build. */
  "bedrock-cli": {
    /** Project version for the .mcaddon filename. Falls back to package.json. */
    version?: string;
 
    /** Identifier namespace for the create generators. Derived from name when omitted. */
    namespace?: string;
 
    /** TS or JS entry, relative to the config file. */
    entry?: string;  // default: probes "src/main.ts" then "src/main.js"
 
    /** Build output directory. */
    out?: string;  // default: "dist"
 
    /** Deploy configuration. */
    deploy?: {
      target: "retail" | "custom";  // default: "retail"
      customPath: string | null;     // required when target === "custom"
    };
  };
}

Field reference

`type`

Type: "minecraftBedrock"

The project-type marker from the standard. Lets shared tooling recognize the file as a Bedrock project config.

"type": "minecraftBedrock"

`name`

Type: string
Required: yes

Project name. Used as the filename stem for .mcaddon output (<name>-<version>.mcaddon) and the directory name inside the zip (<name>_BP/, <name>_RP/). A sensible value to mirror in your manifest.json header.name, though the compiler does not enforce that.

"name": "my-addon"

`authors`

Type: string[]
Required: no

Optional list of author names from the standard. Not consumed by the compiler.

"authors": ["you"]

`targetVersion`

Type: string
Required: no

The Minecraft version the project targets, e.g. "1.21.0". Used as a hint only. The compiler does not enforce or verify it. (This replaces the legacy minecraft.serverVersion field, which is still read for older configs.)

"targetVersion": "1.21.0"

`packs`

Type: { behaviorPack: string; resourcePack: string }
Required: no (defaults applied)
Default: { "behaviorPack": "packs/BP", "resourcePack": "packs/RP" }

Source paths to the behavior and resource pack folders, relative to the config file. Both directories must exist at build time and must each contain a manifest.json.

"packs": {
  "behaviorPack": "packs/BP",
  "resourcePack": "packs/RP"
}

`bedrock-cli.version`

Type: string
Required: no
Constraint: must be a valid semver (opens in a new tab) string.

Project version, used in the .mcaddon filename. If omitted, bedrock-build falls back to the version in your package.json, then to "0.0.0". Validation fails with exit code 2 if the resolved value isn't valid semver.

"bedrock-cli": { "version": "1.0.0" }

`bedrock-cli.namespace`

Type: string
Required: no
Default: derived from name

The identifier namespace the create generators use to build identifiers like <namespace>:<feature>. Optional and backward-compatible. New starters ship without it.

When omitted (or when present but malformed), the compiler derives a legal namespace from name: lowercased, non-alphanumeric runs collapsed to _, leading / trailing underscores trimmed, and a leading digit prefixed with ns_. So name: "My Addon" derives my_addon.

"bedrock-cli": { "namespace": "my_addon" }

Non-fatal at load time. An absent or malformed namespace never breaks build, watch, or deploy: the compiler warns and falls back to the derived value. A namespace is only hard-validated at generate time, inside create, where a bad value can't break a previously working project. Set an explicit namespace when you want stable, predictable identifiers across machines.

`bedrock-cli.entry`

Type: string
Required: no
Default: probes "src/main.ts", then "src/main.js"

Path to the script entry file, relative to the config file. TypeScript or JavaScript: esbuild bundles both. Everything entry imports is pulled into a single bundle written to <out>/packs/BP/scripts/main.js. If omitted, bedrock-build uses src/main.ts when present, otherwise src/main.js.

"bedrock-cli": { "entry": "src/main.ts" }

`bedrock-cli.out`

Type: string
Required: no
Default: "dist"

Output directory, relative to the config file. The compiler owns this path: build --clean removes it, and all build output is written under it. Should be in .gitignore. See Workspace Layout.

"bedrock-cli": { "out": "dist" }

`bedrock-cli.deploy.target`

Type: "retail" | "custom"
Required: no
Default: "retail"

How the deploy command finds Minecraft.

"retail": auto-detects the install across every known Bedrock layout in priority order: the modern Minecraft Bedrock launcher, Bedrock Preview, Microsoft Store (UWP), and Education editions. Windows-only.
"custom": uses deploy.customPath as the com.mojang directory. Works on any platform.

`bedrock-cli.deploy.customPath`

Type: string | null
Required: only when deploy.target === "custom"
Default: null

Absolute or project-relative path to a com.mojang directory. Required (and a non-empty string) when deploy.target is "custom". Ignored when deploy.target is "retail".

"bedrock-cli": {
  "deploy": {
    "target": "custom",
    "customPath": "C:\\Users\\me\\AppData\\Local\\Packages\\Microsoft.MinecraftUWP_8wekyb3d8bbwe\\LocalState\\games\\com.mojang"
  }
}

Validation rules

The compiler validates the config on every command. Failures exit with code 2.

name is present and a non-empty string.
The resolved version is a valid semver string.
The behavior and resource pack directories exist on disk at build time.
Each pack directory contains a manifest.json.
entry resolves to a file that exists at build time.
If deploy.target === "custom", deploy.customPath is a non-empty string. If deploy.target === "retail", customPath is ignored.

If a non-required field is omitted, the default is applied silently.

Only name is strictly required. Every other field has a default or a fallback (version comes from package.json; entry is auto-probed). A config with just type, name, and packs is enough.

Complete example

{
  "type": "minecraftBedrock",
  "name": "my-addon",
  "authors": ["you"],
  "targetVersion": "1.21.0",
  "packs": {
    "behaviorPack": "packs/BP",
    "resourcePack": "packs/RP"
  },
  "bedrock-cli": {
    "version": "1.0.0",
    "entry": "src/main.ts",
    "out": "dist",
    "deploy": {
      "target": "retail",
      "customPath": null
    }
  }
}

A minimal config relying on defaults:

{
  "type": "minecraftBedrock",
  "name": "my-addon",
  "packs": {
    "behaviorPack": "packs/BP",
    "resourcePack": "packs/RP"
  }
}

Legacy configs

Projects scaffolded before the standard adoption use a flat bedrock.config.json:

{
  "name": "my-addon",
  "version": "1.0.0",
  "packs": { "bp": "packs/BP", "rp": "packs/RP" },
  "entry": "src/main.ts",
  "out": "dist",
  "deploy": { "target": "retail", "customPath": null },
  "minecraft": { "serverVersion": "1.19.0" }
}

These still work, unchanged. bedrock-build reads the legacy shape (packs.bp/packs.rp, top-level version/entry/out/deploy, minecraft.serverVersion) and normalizes it internally. To migrate, rename the file to config.json and move the compiler fields under a bedrock-cli key. When both shapes are present in one file, the standard fields win.

CLI: bedrock-build Overview