From 59934a3d5c4b0ee9b136442046f391e7981ea1ef Mon Sep 17 00:00:00 2001
From: Jonas da Silva <phoenixr41414141@gmail.com>
Date: Wed, 16 Oct 2024 19:30:57 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=8D=B1=20Add=20TypeScript=20guide?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 manual/src/SUMMARY.md          |  1 +
 manual/src/using-typescript.md | 83 ++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 manual/src/using-typescript.md

diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
index ab07e52..1ad90d1 100644
--- a/manual/src/SUMMARY.md
+++ b/manual/src/SUMMARY.md
@@ -12,6 +12,7 @@
 
 - [Plugins](./plugins.md)
 - [Managing UUIDs]()
+- [Using TypeScript](./using-typescript.md)
 - [Publishing your Work]()
 
 # Ports
diff --git a/manual/src/using-typescript.md b/manual/src/using-typescript.md
new file mode 100644
index 0000000..49632b7
--- /dev/null
+++ b/manual/src/using-typescript.md
@@ -0,0 +1,83 @@
+# 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]:
+
+```console
+npm init
+```
+
+Then edit the generated `package.json` to look similar to the following:
+
+```json,filepath=package.json
+{
+  "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:
+
+```json,filepath=tsconfig.json
+{
+  "compilerOptions": {
+    "rootDir": "./src",
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "target": "ES2016",
+    "noImplicitAny": true,
+    "removeComments": true,
+    "preserveConstEnums": true,
+    "sourceMap": false
+  },
+  "include": ["src/**/*"]
+}
+```
+
+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:
+
+```toml,filepath=allay.toml
+# ...
+
+[[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.
+
+```toml
+# ...
+
+[[plugin]]
+name = "exclude typescript files"
+run = "plugins/exclude.rb"
+with = "ruby"
+options = { patterns = ["**/*.ts"] }
+```
+
+You can find this plugin [here](https://github.com/allay-mc/plugins/tree/master/plugins/exclude).
+
+[npm]: https://www.npmjs.com/
+[Script API]: https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/?view=minecraft-bedrock-stable
+[TypeScript]: https://www.typescriptlang.org/