# 🐜 MIGA - CLI
> **Bedrock Addon Utility Package Manager**
>
> A fast, zero-dependency CLI that bootstraps, builds, packages and manages
> Minecraft Bedrock Edition add-ons — written in Rust.
[](LICENSE)
<div style="text-align: center">
<img src="assets/miga_banner.png" alt="Miga Banner" height="150">
</div>
---
## 📑 Table of Contents
- [Overview](#-overview)
- [Installation](#-installation)
- [Commands](#-commands)
- [init](#-init)
- [add](#-add)
- [fetch](#-fetch)
- [run](#-run)
- [build](#-build)
- [remove](#-remove)
- [Versioned module storage](#-versioned-module-storage)
- [Project structure](#-project-structure)
- [Environment variables](#-environment-variables)
- [Contributing](#-contributing)
- [License](#-license)
---
## 🔭 Overview
`miga` replaces a full Node.js toolchain for Bedrock add-on development.
It handles:
- 🏗️ **Scaffolding** — creates a complete BP + RP project with typed TypeScript support.
- 📘 **TypeScript types** — downloads `.d.ts` files directly from the npm registry without
requiring `npm` or `node` to be installed.
- 📦 **Registry modules** — fetches community modules from the miga registry and wires
them into your project.
- ⚡ **Compilation** — transpiles and optionally minifies TypeScript using
[oxc](https://oxc.rs/) (native Rust, ~100× faster than `tsc`).
- 📂 **Packaging** — assembles `.mcpack` and `.mcaddon` archives ready for distribution.
- 🔄 **Hot reload** — watches your source files and redeploys to Minecraft's dev pack
folders on every save.
- 🔀 **Version conflict resolution** — when two modules depend on different versions
of the same transitive dependency, miga prompts you to upgrade or keep both.
---
## 📥 Installation
### From source
```bash
git clone https://github.com/HormigaDev/miga.git
cd miga
cargo install --path .
```
### Pre-built binaries
Download the latest release from the
[Releases page](https://github.com/HormigaDev/miga-cli/releases) and place the binary
somewhere on your `PATH`.
---
## 🛠️ Commands
### 🆕 `init`
Scaffold a new Bedrock add-on project interactively.
```bash
miga init [--namespace <ns>] [--name <name>] [--type <type>] [--yes]
```
**Options**
| `--namespace <ns>` | `-N` | Namespace prefix used inside the add-on (e.g. `woc`). |
| `--name <name>` | `-n` | Internal identifier for the add-on (e.g. `ecological-spawns`). |
| `--type <type>` | `-t` | Project type to scaffold (see below). |
| `--yes` | `-y` | Accept all defaults without interactive prompts. |
**Project types**
| Full _(default)_ | `full` | Behavior Pack with scripts + Resource Pack. |
| Behavior | `behavior` | Behavior Pack with scripts only (no Resource Pack). |
| Behavior (scriptless) | `behavior-scriptless` | Data-driven Behavior Pack only (no scripts). |
| Addon (scriptless) | `addon-scriptless` | Behavior Pack + Resource Pack, both without scripts. |
| Resource | `resource` | Resource Pack only. |
Any missing options are asked interactively. Use `-y` to skip all prompts
and use defaults (`namespace=myaddon`, `name=my-addon`, `type=full`).
The command creates a directory named after the add-on containing the
appropriate pack skeleton based on the selected project type.
**Examples**
```bash
miga init # fully interactive
miga init --yes # accept all defaults
miga init -t resource -N textures -n my-rp # resource pack only
miga init -y -t behavior # behavior + scripts, no prompts
```
---
### 📘 `add`
Add a `@minecraft/*` type package from the npm registry.
```bash
miga add <package[@version]> [<package[@version]> ...]
```
**Examples**
```bash
miga add @minecraft/server@2.4.0
miga add @minecraft/server @minecraft/common
```
Types are downloaded to `.miga_modules/` and the package is recorded in
`.miga/miga.json`.
---
### 📦 `fetch`
Install one or more modules from the **miga registry**.
```bash
miga fetch [<module>] [--version <ver>] [--update]
```
**Options**
| `--version` | Install a specific version (e.g. `--version 1.2.0`). |
| `--update` | Update the module (or all modules if no name given) to the latest. |
**Examples**
```bash
miga fetch # install all modules listed in miga.json
miga fetch bimap # install a specific module
miga fetch bimap --version 1.2.0 # install a specific version
miga fetch bimap --update # update a module to latest
miga fetch --update # update all installed modules
```
Modules are downloaded, extracted and registered in `.miga/modules.lock`.
Transitive dependencies are resolved automatically. If a version conflict is
detected (two dependants need different versions of the same module), miga will
prompt you to **upgrade**, **keep both**, or **keep the existing version**.
---
### 🔄 `run`
Watch for source changes and hot-reload the add-on into Minecraft.
```bash
miga run [--no-watch]
```
| `--no-watch` | Compile and deploy once, then exit (no file watcher) |
`miga run` compiles TypeScript on every change and copies the packs to the
paths configured in `.env` (`BEHAVIOR_PACKS_PATH` / `RESOURCE_PACKS_PATH`).
---
### 📦 `build`
Compile, minify and package the add-on for release.
```bash
miga build
```
Outputs:
| `dist/<name>_behavior_pack-v<ver>.mcpack` | Behavior Pack only. |
| `dist/<name>_resource_pack-v<ver>.mcpack` | Resource Pack only. |
| `dist/<name>-v<ver>.mcaddon` | Combined archive (both packs). |
---
### 🗑️ `remove`
Remove installed modules or external type packages.
```bash
miga remove <package> [<package> ...]
miga remove --all
```
| `--all` | Remove all installed modules and externals (asks first) |
Deletes the module/package files and cleans `.miga/modules.lock`,
`.miga/miga.json`, `tsconfig.json` and `behavior/manifest.json` automatically.
---
## 🔀 Versioned module storage
Modules are stored under **`.miga_modules/<name>/v<version>/`**, enabling
multiple versions of the same module to coexist when different dependants
require incompatible versions.
```
.miga_modules/
├── bimap/
│ └── v1.0.0/
│ ├── index.ts
│ └── ...
└── utils/
├── v1.0.0/
│ └── ...
└── v2.0.0/
└── ...
```
During compilation, bare imports are rewritten to their versioned paths
(e.g. `import { ... } from "bimap"` → `./libs/bimap/v1.0.0/index.js`),
so each module always resolves to the exact version it was installed with.
---
## 🗂️ Project structure
After running `miga init`, the project looks like the example below.
The actual directories depend on the chosen project type — for instance,
a `resource` project has no `behavior/` folder, and a `behavior-scriptless`
project has no `scripts/` subdirectory.
```
<addon-name>/
├── behavior/ 📁 Behavior Pack
│ ├── manifest.json
│ ├── pack_icon.png 🎨 Replace with your own icon
│ ├── LICENSE
│ └── scripts/
│ ├── index.ts 🚀 Entry point
│ ├── config/
│ │ └── registry.ts 📋 Central registry / namespace
│ ├── events/
│ │ └── index.ts
│ ├── components/
│ ├── features/
│ └── core/
├── resource/ 📁 Resource Pack
│ ├── manifest.json
│ ├── pack_icon.png
│ ├── LICENSE
│ ├── texts/ 🌍 en_US.lang, es_ES.lang, pt_BR.lang
│ ├── textures/
│ │ ├── blocks/
│ │ ├── items/
│ │ ├── entity/
│ │ └── ui/
│ ├── models/
│ ├── sounds/
│ └── ui/
├── .miga/
│ ├── miga.json 📋 Project manifest (name, version, modules)
│ └── modules.lock 🔒 Installed module lock file
├── .miga_modules/ 📦 Downloaded modules (versioned)
├── .env 🔧 Deploy paths (not committed)
├── .env.template 📄 Template to share with collaborators
├── .gitignore
├── tsconfig.json
├── LICENSE
└── README.md
```
---
## 🔧 Environment variables
Configure `.env` (copy from `.env.template`):
```dotenv
# Absolute path to Minecraft's development_behavior_packs folder
BEHAVIOR_PACKS_PATH=
# Absolute path to Minecraft's development_resource_packs folder
RESOURCE_PACKS_PATH=
# true = inline source maps (debugging only)
SOURCE_MAPS=false
```
On Linux the default paths are auto-detected via `$HOME`. On Windows they point
to `%LOCALAPPDATA%\Packages\Microsoft.MinecraftUWP_*`. If the path is not found,
miga will warn and skip the copy step.
---
## 🤝 Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
---
## 📄 License
`miga` is free software released under the
[GNU General Public License v3.0](LICENSE).