How to build a Minecraft plugin with JavaScript

CustomRealms is a completely open-source JavaScript framework for building Minecraft plugins

3 min readNov 11, 2021

CustomRealms is back

Building a Minecraft server plugin today requires Java, and a Java API called Bukkit. This is a robust API that has enabled tons of amazing Minecraft experiences, but it’s not ideal for beginner programmers. It’s also not ideal for more advanced programmers who want to build plugins very quickly.

For years, we’ve wanted to build Minecraft plugins using JavaScript. Our code would be easier to write, so we could iterate on our plugin ideas much faster. Plus, we find JavaScript more enjoyable to write than Java.

Last year, we launched CustomRealms, an online code editor that made it possible to build Minecraft plugins using JavaScript completely in the browser. It worked great, and was generally loved by the community, but one question repeatedly came up: How do I export my plugin to a JAR file?

We should be able to run CustomRealms plugins written in JavaScript and Bukkit plugins written in Java side-by-side on the same server.

This was a legitimate question, as the world today is full of Bukkit plugins and servers. Writing a plugin in JavaScript shouldn’t make our server incompatible with all the great Bukkit plugins we depend on. We should be able to run CustomRealms plugins and Bukkit plugins side-by-side.

CustomRealms goes open source

Today, CustomRealms is launching as a fully open-source framework for writing Minecraft plugins in JavaScript, then exporting the plugin to a JAR file compatible with any Bukkit server (Spigot, Paper, Craftbukkit, etc.)

All of our code is available on GitHub at github.com/customrealms

Setting up your first plugin

First, you need to have NodeJS / NPM installed on your machine. If you haven’t already, install it from the NodeJS website: https://nodejs.org/en/download/

Next, you’ll need to open a terminal window and install the CustomRealms CLI using this command:

npm install -g @customrealms/cli

This will install the crx command on your system, which is CustomRealms’ tool for creating and compiling JavaScript plugins.

Now, we need to create a new folder for your project. We’ll run the following three commands to create a folder, and initialize our CustomRealms project.

mkdir my-plugin
cd my-plugin
crx init

Now, you should have a project folder that looks like this:

The default CustomRealms project structure after **crx init**

The entrypoint for your plugin is the src/main.ts file. This is a TypeScript / JavaScript file that you can edit to develop your plugin.

By default, the src/main.ts file comes with some example code, which should look something like this:

This example shows a plugin that does two things:

Listens for players in the chat, and sends them a message whenever they say something
Handles the /title {message}... command, and displays a title on the player’s screen whenever the player uses that command.

Building a simple command

Building commands is extremely easy using the CustomRealms framework. For example, here’s how we would build a /gmc command to give the player creative mode:

Now, players can type the /gmc command on your Minecraft server to put themselves into creative mode.

Your plugin can have as many commands as you want. We can extend it to also include a /gms command for survival mode:

A slightly more interesting command

Here’s an example of a somewhat cooler command. When players type the /strike command, lightning will strike down in the direction they are looking.

One more fun command

And finally, here’s the /smite {player}command, which strikes down lightning on any player, specified by the person running the command.

Compiling your plugin into a JAR file

When you’re ready to create a JAR file to test out your plugin on a Minecraft server, it’s easy:

npm run build:jar

If your code compiles successfully, your JAR file will be put into the dist folder within your project.

We’re really excited to launch this project. This is only the first release, so many improvements are still in the works.

We need your help! If you’d like to get involved with the open source project, please join us:

GitHub: https://github.com/customrealms

Discord: https://discord.gg/uHkJ8V5