Bedrock Script API Custom Components 2026

Minecraft Bedrock Script API Custom Components (2026)

Use Minecraft Bedrock custom components with @minecraft/server in 2026: item JSON, component registration, manifest dependencies, testing, and debugging.

18 min read
Updated May 2026
Advanced
2026 accuracy note This guide was built from current official documentation checked on May 2026. For preview APIs, always re-check the linked official docs before shipping a public download.

Why custom components matter in 2026

Custom components are now the cleanest way to connect JSON-defined blocks or items with targeted script behavior. Instead of running broad scripts and checking every item manually, you attach a namespaced component to the item or block that needs the behavior.

For 2026 content, this is stronger SEO and stronger engineering: players search for working right-click items, edible items, custom crops, gadgets, and scripted mechanics. The tutorial should show a real pattern, not a vague addon overview.

Recommended pack structure

Use a Behavior Pack for JSON and scripts, and a Resource Pack only when the item needs icons, textures, models, sounds, or animations.

A script-based addon should keep `scripts/main.js` or compiled `scripts/main.js` in the Behavior Pack, with item files under `items/` and your manifest at the pack root.

Example
my_addon_BP/manifest.json
my_addon_BP/items/glow_berry_wand.json
my_addon_BP/scripts/main.js
my_addon_RP/textures/item_texture.json
my_addon_RP/textures/items/glow_berry_wand.png

Manifest dependency

Your Behavior Pack manifest must declare a script module and a dependency on `@minecraft/server`. Keep the exact module version aligned with the stable or preview API you are targeting, and do not copy old 2023 examples blindly.

Example
"modules": [{ "type": "script", "language": "javascript", "entry": "scripts/main.js" }]
"dependencies": [{ "module_name": "@minecraft/server", "version": "2.0.0" }]

Attach the component in JSON

Attach your own namespaced component inside the item's `components` object, next to native components. The namespace is important because it avoids conflicts with vanilla and other creators.

Example
"minecraft:icon": "glow_berry_wand"
"icedfox:cast_glow_burst": {}

Register the component

Register custom item components during startup. Keep the registration name identical to the component name in the item JSON. If the names do not match exactly, the item may import but the behavior will never fire.

For an item that runs behavior when consumed, register the custom component in `system.beforeEvents.startup` and handle the event exposed by the component API.

Example
import { system } from "@minecraft/server";
system.beforeEvents.startup.subscribe((event) => {
  event.itemComponentRegistry.registerCustomComponent("icedfox:cast_glow_burst", {
    onUse(eventData) {
      eventData.source.runCommand("particle minecraft:totem_particle ~ ~1 ~");
    }
  });
});

Debug checklist

If the item appears but does nothing, check the manifest dependency, the script entry path, the component namespace, and the Content Log. If the script never loads, simplify to one console message first, then add the component behavior back.

When a tutorial is meant to rank in 2026, include the failure states. Users rarely search for perfect examples; they search because something is broken.

Official sources checked

These are the official or primary references used to keep this tutorial current: