Setting Up Your First TypeScript Script

October 4, 2026 // Scripting Resources

EDITOR’S NOTE: This guide is an amalgamation of two posts, one by Frazazel and one by Sweaty Bill. Using the dark magicks of reading comprehension and guile, I have stitched them together into one guide. We will try to keep this a bit more updated than some of the older guides! – Scotch

Let’s say you’ve read the JS Overview and decided TypeScript is the way to go for your new script. You’re staring blankly at an empty folder, wondering what’s next. Good news! This guide is what you need to figure that out. While this guide was originally written for Windows users, we’ve tried to add some cross-OS notes when things differ.

Before we start, one encouraging notion: the TypeScript ecosystem exists well outside of KoL scripting. Nearly everything mentioned in this guide is used by millions of developers worldwide (possibly including Mr. Worldwide), so virtually any error you hit along the way is eminently Googleable. Searching for “install vscode windows” or pasting an error message will usually get you an answer in the first link or two. (Well, it did before AI overviews started messing with Google results. But you probably can still find it if you’re crafty.)

What You’ll Need

The full list of what we’ll be installing:

Visual Studio Code (VSCode), a code editor. Some schoolmarms may wax philosophical about how VSCode isn’t technically an IDE; they’re probably right, but the important thing is that it’s just much better than Notepad.
Node.js, the program that the entire JavaScript ecosystem is built on. It also comes with npm, the Node Package Manager.
Yarn, the package manager most Loathers projects actually use.
Git, the version control system used by nearly every KoL script.
A few VSCode extensions, which improve VSCode’s functionality for TypeScript development.

Installing Your Tools

1Install VSCode

Download the installer for Visual Studio Code. Run the installer and leave the default options checked. (If you’re on Mac, download the Mac version.)

2Install Node.js

Download and install Node.js. If you’re given a choice of versions, pick the LTS (long-term support) version; the latest release can (occasionally) be too cutting-edge for some tools.

If you expect to be juggling several projects that need different versions of Node, you can instead install Node Version Manager (nvm), to manage separate node versions. The process slightly differs by operating system:

For Windows users, you can install nvm-windows and use it to install Node with nvm install lts followed by nvm use lts. Microsoft has a good walkthrough of this approach. This is entirely optional; the regular installer works just fine, and will be sufficient for most users.
For Mac and Linux users, you can use nvm instead. While macOS users may actually be fine just doing something simple like the regular installer from nodejs.org outside of the nvm universe, Linux users will benefit a bit more from nvm management as base distro packages can be a few versions old.

3Install Git

Git differs a bit depending on operating systems as well.

For Windows users, download and install Git for Windows. The installer asks a lot of questions, and you can leave most at their defaults. However, when it asks for your default editor, choose Visual Studio Code, since you’ve just installed it. (The default, Vim, is notoriously confusing for newcomers.)
For Mac users, you can install Git by running git --version in the terminal (which spawns an installation prompt that will install Xcode command line tools, including Git), or brew install git if you already have Homebrew installed.
For Linux users, you can install Git via your package manager, with a command like sudo apt install git or the distro’s equivalent. (That works for Debian-based distributions, while others may use yum, pacman, or dnf instead of apt.)

Once Git is installed, run the following in your terminal, using your name and email associated with your GitHub account:

git config --global init.defaultBranch main
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

4Install VSCode Extensions

Open VSCode and install the following extensions:

ESLint, which flags errors and questionable code as you write it.
If you plan on contributing to other people’s scripts, the GitHub Pull Requests extension is also handy.

You may see older guides recommend the Prettier extension as well; it is no longer recommended. Just run yarn run format before you commit.

⚠️ If a command in any of the following steps gives you an error like “not recognized as an internal or external command” or “command not found”, close and reopen VSCode entirely. Newly installed programs often aren’t visible to terminals already open when you installed them. ⚠️

Creating Your Script

5Open a Terminal in Your Projects Folder

First, pick where you want your scripting projects to live. (As an example, one may have a Documents/GitHub/ folder.) Open the folder in VSCode via File > Open Folder, and then open VSCode’s built-in terminal with Ctrl+` .

6Install Yarn

In your terminal, run the following two commands to install yarn:

npm install -g corepack
corepack enable

corepack enable may not print anything, which is fine; no news is good news. You only need to do this once per computer, not once per script. (If you are on Mac or Linux, and did not use the nvm route discussed earlier, you may need to use a sudo command to install corepack.)

7Create Your Script

In your terminal, run:

yarn create kolmafia-script scriptname

Answer its questions, and choose to install libram. Choose to install grimoire if you want to use it for adventuring tasks or for its argument handling. It will then install a whole bunch of stuff and configure it with great defaults. It should add most of the packages you need, and it will also create a git repository for you. Don’t be alarmed by the very large node_modules folder it creates; that’s where all of those packages live, and it’s supposed to be there.

8Move Into Your New Script Folder

In your terminal, change directory into the folder it just created:

cd scriptname

Building & Running Your Script

9Write Some Code

Open src/main.ts in VSCode. (We recommend opening the containing folder of your script with “File > Open Folder” and selecting that file through the left-hand sidebar). Write some TypeScript code to do something, and save it.

10Build Your Script

In your terminal, run:

yarn run build

After a few seconds, it will create a .js script in a new dist/scripts/scriptname/ folder.

11Link Your Script to KoLmafia

For this step, we need to place a symlink in your KoLmafia folder so that you don’t need to copy the script over to mafia every time you build it. The default location of your mafia folder varies by OS, which will lightly vary the installation command needed:

For Windows, your folder will be wherever the .jar file you use to start mafia lived. You will need to find that path and pass it to a new install command, which should look like yarn run install-mafia "C:\Users\YourName\Documents\KoLmafia", replacing the path to wherever you are currently storing your mafia files.
For Mac, assuming you have not moved your data folder away from default, you just need to run yarn run install-mafia. (In case you’re curious, the Mac default location is ~/Library/Application Support/KoLmafia.) If you’ve moved it, pass the path like the Windows example.
For Linux, assuming you have not moved your data folder away from default, you just need to run yarn run install-mafia. (In case you’re curious, the Linux default location is ~/.kolmafia.) If you’ve moved it, pass the path like the Windows example.

12Run It!

Open KoLmafia, type scriptname into the GCLI, and watch it do its thing.

Continuing Development

Once everything is set up, your day-to-day loop looks like this:

In VSCode, write or edit your code and save.
In your terminal, run yarn run build. The symlink we set up in Step 11 allows KoLmafia to see the newly generated script. (Consider enabling rebuild-on-save with yarn run watch – this means you don’t need to run build all the time, which can be nice for your development flow.)
Open KoLmafia and rerun your script!

Working on an Existing Script Instead

The tools you installed in Steps 1 through 6 are also everything you need to work on someone else’s TypeScript script, like garbage-collector. Rather than creating a new script, you’ll fork the project on GitHub, clone your fork, and install its dependencies:

git clone https://github.com/your-username/garbage-collector.git
cd garbage-collector
yarn install
yarn run build

If the build finishes without errors, everything is working. Our guide on how to submit a pull request covers forking, branching, and getting your changes back into the original project in much more detail.

Further Considerations

There are a number of things this guide doesn’t address, but that you should probably know about:

Actually developing your script will require a different guide. This one just gets your environment set up.
You should use git for version control. It’s not hard, and it saves a lot of headaches. Consider GitHub Desktop for git with a GUI and easy GitHub integration instead of command-line git.
If you said yes to the GitHub files in Step 7 (which you should’ve!), your repo already includes a workflow that builds your script into a release branch every time you push to main. Players can then install it with git checkout yourname/scriptname release; we recommend putting that in your README.md for ease of use.
Upgrading packages for the latest KoLmafia, libram, etc. is occasionally required for new KoL content.
Configuring package.json, rollup, TypeScript, and ESLint via their saved configuration files is sometimes a thing you should do, but that’s too much for this guide. Just know that these configuration files are there, and you can change them!

Article contributed by Frazazel & Sweaty Bill