English | 日本語

scriptup

CLI for Minecraft Bedrock ScriptAPI development.

scriptup helps you keep @minecraft/* modules current, use external libraries in ScriptAPI projects, and scaffold projects and library-ready structures quickly.

Motivation

• Make updating @minecraft/* easier
• Make it easy to use external libraries in ScriptAPI
• Make it easy to create libraries for ScriptAPI

Features

• Scaffold core project files (manifest.json, tsconfig.json, src/main.ts, etc.)
• Initialize the current directory as a ScriptAPI project
• Migrate an existing project to the latest scaffold template
• Build ScriptAPI code with tsdown using manifest.json script entry output
• Optional local library scaffold for creating reusable ScriptAPI packages
• Interactive package manager selection that configures packageManager and mcpack.yml

Requirements

• Node.js 18+
• Minecraft Bedrock environment for addon testing
• One of npm, pnpm, yarn, or bun

Install

Use your preferred package manager and install globally.

npm i -g @nano191225/scriptup

pnpm add -g @nano191225/scriptup

After installation, run via scriptup (or sup).

Quick Start

Update to latest stable ScriptAPI modules

scriptup stable

Create a new project

scriptup new my-pack --open

Build your project

scriptup build

Commands

scriptup stable

Installs module versions matching the latest stable Minecraft version.

scriptup preview

Installs module versions matching the latest preview Minecraft version.

scriptup lts

Installs LTS-like module versions (non-stable, non-preview, non-beta, non-internal when available), with fallback to stable matching versions.

scriptup

Manual version lookup mode.

Example:

scriptup 1.21.60
scriptup 2.0.0-beta

scriptup init

Initialize the current directory as a ScriptAPI project.

Options:

• --lib: Include local library scaffold under package/
• --no-workflow: Do not generate GitHub Actions workflow files
• -i, --interactive: Interactively select a package manager (writes packageManager field and configures mcpack.yml)
• -m, --migrate: Migrate an existing project to the latest scaffold template

What it does:

• Scaffolds core project files (manifest.json, tsconfig.json, src/main.ts, etc.)
• Ensures tsdown.config.ts exists
• Sets package.json scripts:
  • build: scriptup build --release
  • watch: scriptup build --watch
• Installs required dev dependencies

Migration mode (--migrate)

Re-applies the latest scaffold to an existing project while preserving your customizations.

Before scaffolding, existing template files are backed up to .backup/. After scaffolding:

• manifest.json: UUIDs, name, and version are carried over from the old file. Array-format versions ([x, y, z]) are automatically converted to "x.y.z". The generated_with field is refreshed from the new template.
• package.json: name, version, packageManager, and all dependencies and scripts are merged (old values are kept; new template values fill any missing keys).
• Other template files (.gitignore, README.md, etc.): restored verbatim from backup.
• launch.json and tsconfig.json: always overwritten with the latest template.

scriptup new

Create a new ScriptAPI project.

Options:

• -o, --open [command]: Open project after creation (preset: code)
• -p, --preview: Use Minecraft Bedrock Preview behavior packs directory
• -d, --dir : Create under a specific directory
• --lib: Include local library scaffold under package/
• --no-link: Do not create behavior-pack link when --dir is used
• --no-workflow: Do not generate GitHub Actions workflow files
• -i, --interactive: Interactively select a package manager (writes packageManager field and configures mcpack.yml)

Default target directories:

• Windows stable:
  • %APPDATA%/Minecraft Bedrock/Users/Shared/games/com.mojang/development_behavior_packs
• Windows preview:
  • %APPDATA%/Minecraft Bedrock Preview/Users/Shared/games/com.mojang/development_behavior_packs
• Linux (mcpelauncher):
  • ${XDG_DATA_HOME:-~/.local/share}/mcpelauncher/games/com.mojang/development_behavior_packs

scriptup build

Bundle/build current ScriptAPI project using tsdown.

Options:

• -b, --bundle: Force bundled output
• -w, --watch: Watch mode
• -r, --release: Release build (minified, sourcemap off)

Build behavior summary:

• Output target is derived from manifest.json script module entry (for example scripts/main.js)
• Input entry priority:
  • src/main.ts
  • src/index.ts
  • entry in tsdown.config.ts
• Release mode also builds package/**/*.ts into dist/ when package/ exists
• If disallowed external imports remain in output (outside allowed @minecraft/*), scriptup warns with both the likely cause package and remaining dependency names

Typical Workflows

Existing project

scriptup init
scriptup stable
scriptup build

Migrate an existing project to the latest template

scriptup init --migrate --interactive
scriptup stable
scriptup build

New addon project

scriptup new my-addon --open
cd my-addon
scriptup build --watch

New library-ready project

scriptup new @yourname/your-lib --lib --dir . --open

Notes

• scriptup updates versions in manifest.json and installs matching dev dependencies
• Package manager is auto-detected from packageManager field or lockfile
• Alias command sup is also available

License

MIT