Using TypeScript

TypeScript is a commonly chosen alternative to JavaScript when working with Minecraft’s Script API. When working with the Script API, it’s a good idea to initialize the Allay project with npm or other package managers. This guide will use npm as the package manager.

First, initialize the project for npm:

npm init

Then edit the generated package.json to look similar to the following:

{
  "name": "myproject",
  "version": "0.1.0",
  "license": "MIT",
  "scripts": {
    "build": "tsc --outDir $ALLAY_PREBUILD"
  },
  "dependencies": {
    "@minecraft/server": "^1.13.0",
    "@minecraft/server-ui": "^1.3.0",
    "typescript": "next"
  }
}

We also create a tsconfig.json required to transpile our TypeScript files correctly:

{
  "compilerOptions": {
    "rootDir": "./src",
    "module": "ES2020",
    "moduleResolution": "Node",
    "target": "es6",
    "sourceMap": false
  },
  "include": ["src/**/*"]
}

This is the bare minimum TypeScript configuration required. You can further configure the file to your preferences.

We won’t use the npm CLI directly to run the build script like you usually would do. Instead, we invoke the build script by using an Allay plugin:

# ...

[[plugin]]
name = "transpile typescript"
run = "npm"
args = ["run", "build"]

This is neccessary as the package.json makes use of the environment variable ALLAY_PREBUILD which is only available when run by Allay.

The built add-on will still contain TypeScript files alongside the generated JavaScript files. Because we don’t need these files, we can use a plugin that removes the TypeScript files from the build.

# ...

[[plugin]]
name = "exclude typescript files"
run = "plugins/exclude.rb"
with = "ruby"
options = { patterns = ["**/*.ts"] }

You can find this plugin here.