flying-squid: a Minecraft server you can script from JavaScript

What flying-squid is and what the feature list omits

flying-squid creates Minecraft servers with a high level JavaScript API. It is a server implementation written in Node.js, published to npm as flying-squid, with a homepage under the PrismarineJS documentation site.

The most useful thing to do with this project is to read its feature list closely, because it is short and it tells you the boundary of the project. The documented features are: support for Minecraft 1.8 through 1.21, players can see the world, players see each other in game and in the tab list, digging, placing blocks, player movement, world generation, Anvil loading, and multi world.

That is the list. There is no mention of mobs, redstone, crafting, hunger, weather, villagers, the nether, the end, hunger or experience, or world persistence beyond loading Anvil format. This is not a vanilla replacement and it does not pretend to be one. It is a server that renders a world and lets players move around in it and modify blocks, built on a protocol library so that the interesting engineering is the server framework rather than the game.

The users are therefore developers building a custom Minecraft experience, a test harness, a teaching environment, or a proxy in front of a real server, and the specific pull is that everything is JavaScript. A server plugin is an npm package, a world generator is an npm package, and the server configuration is an object literal in your own code.

The repository is part of the PrismarineJS ecosystem, and the credits name the author of flying-squid, the person who helped with the protocols, a major contributor, and the PrismarineJS team for creating prismarine-chunk and node-minecraft-protocol.

Running from source and the config directory

The build and run path is two commands, and the project asks you to configure the server first:

npm install
node app.js

The configuration is expected in config/settings.json, and the recommendation is to set it up before you run or build the server, since the server reads its settings from there.

There is also a global install route, documented as installing flying-squid globally with sudo npm install -g flying-squid and then running it with the flying-squid command. The package manifest declares app.js as the bin entry, which is how that command exists at all.

The project uses yargs for argument parsing, and the container entrypoint shows the flags the binary understands, since it launches the server with a configuration directory:

ENTRYPOINT [ "node", "app.js", "-c", "/config" ]

So the -c option points at a directory of configuration, and in the container that directory is the mounted /config path.

The test setup is also worth noting if you plan to contribute. The scripts run the linter with standard before the test suite, and the test command itself is mocha with a spec reporter, a 30 second timeout, two retries and an exit flag. The dev dependencies include mocha, expect, mineflayer and minecraft-wrap, which means the test suite drives a real client against the server rather than only calling internal functions.

Docker and the compose file for a repeatable server

Docker is presented as the way to get a higher level of isolation, compatibility and consistency, and the quick start is one command:

docker run -p 25565:25565 prismarinejs/flying-squid

Port 25565 is the standard Minecraft port, and the image publishes it as a volume mapping so a normal client can connect.

To supply your own configuration and a container name, mount the config directory and name it:

docker run -p 25565:25565 -v $(pwd)/config:/config --name my-flying-squid prismarinejs/flying-squid

The compose file in the documentation is the third form, and it is a good one to copy:

version: '3.8'

services:
  flying-squid:
    image: prismarinejs/flying-squid
    volumes:
       - ${PWD}/config:/config
    ports:
      - "25565:25565"
volumes:
  flying-squid:

You launch it with:

docker-compose -f path/to/docker-compose.yaml up

The compose file in the repository itself is the build variant, using build: . instead of a published image, and it declares the same volume and port mapping.

For the fully local path, the documentation gives a build and a run:

docker build -t local-flying-squid .
docker run -p 25565:25565 local-flying-squid

The Dockerfile behind that is minimal. It starts from node:16-slim, sets the working directory to /app, disables npm bin links with npm config set bin-links false, installs the package, copies the rest of the source in, and sets the entrypoint to node app.js with the -c /config flag.

Swapping the world generator and adding plugins

World generation is modular, and the default module is called diamond-square.

Three options are documented. The node-voxel-worldgen module is a voxel world generator written in Rust, compatible with flying-squid, and it allows basic Minecraft like generation including caves. The diamond-square module is a diamond square Minecraft generation. The third is superflat, a superflat world generator with configurable blocks and biome.

The installation mechanism is deliberately trivial: to install a world generation, you npm install it and then change the generation option in settings.json. There is no registry and no plugin loader to configure for this case.

Plugins are a separate category, and the documented ones show what the plugin API is for. flying-squid-irc is a bridge between an IRC channel and the Minecraft server, and is currently used between the project's test server and its Gitter room through the Gitter IRC bridge. flying-squid-schematic provides /listSchemas and /loadSchema commands, so a schema can be added through a simple HTTP API and then loaded into the world from inside the game. flying-squid-essentials is a plugin intended eventually to be like the Essentials plugin for Bukkit and Spigot, providing the basic commands a server should have. squidcord is a bridge between a Discord channel and the server. authme is an authentication plugin for servers running with online-mode=false.

You can add server plugins and player plugins in your own package, following the guidance in the project's contribute document, and the repository has an examples/ directory with a basic.js file, plus an examples page on the documentation site.

Using flying-squid as a library

flying-squid is also a server library, and the configuration object is the API. A minimal server looks like this, with a few of the documented options left out so the shape stays readable:

const mcServer = require('flying-squid')

mcServer.createMCServer({
  'motd': 'A Minecraft Server \nRunning flying-squid',
  'port': 25565,
  'max-players': 10,
  'online-mode': true,
  'difficulty': 1,
  'worldFolder': 'world',
  'generation': {
    'name': 'diamond_square',
    'options': {
      'worldHeight': 80
    }
  },
})

The rest of the options in the documented example cover the kick timeout, a plugins object, modpe, the view distance, the player list text with a header and a footer, everybody-op, max-entities, and the protocol version, which is set to 1.18 in that example.

Two of these are worth calling out for operational reasons. The version field selects which protocol the server speaks, and the list of supported versions in the feature list runs from 1.8 to 1.21, so a client on a version outside that range will not connect. And online-mode controls whether the server authenticates players against the official session servers, which the authme plugin exists to work around for servers set to online-mode=false.

Because the configuration is a plain object passed to a function, the server can be created from your own code, in a test, or in a process that manages several servers, rather than only from a config file.

Where flying-squid is the wrong tool

The first limit is the game itself. If you want players to survive, fight, farm, trade with villagers or complete the game, this server does not implement that, and the feature list is explicit about where it stops. Running a public server for players who expect the vanilla game on flying-squid will disappoint them quickly.

The second is version churn. The server speaks many protocol versions, and the protocol implementations come from a separate library that the project credits the PrismarineJS team for creating, along with prismarine-chunk. When Mojang changes a protocol, the server inherits that work rather than controlling it, and the version matrix in the configuration is where you find out whether a given client works.

The third is that the world is a directory of Anvil format files, and the project lists Anvil loading as a feature. There is no documented generator for terrain beyond the three modules above, and no documented story about how worlds are created from scratch other than through a generator module.

The fourth is operational maturity. The release history shows 1.10.0 and 1.11.0 on the same day in January 2025, and 1.12.0 on 2026-04-01. The last push was on 2026-10-06, so the tree is current, but a 1.12 line is not a mature release train.

Compare that with the Java server ecosystem, where a server such as Spigot or Paper implements the full game and takes plugins as Java jars with a well known API, and where the client protocol is handled by the same server codebase. The difference in approach is that flying-squid inverts the usual relationship: the game logic is thin and the JavaScript programming model is the point, so a Java server gives you a complete game and a Java extension model, while flying-squid gives you a JavaScript extension model and only the part of the game listed in its features.

Licence, dependencies and the cost of an upgrade

flying-squid is released under the MIT licence, which the package manifest confirms with a licence field of MIT and a LICENSE file at the repository root. The MIT terms allow use, modification and redistribution including inside a closed source product, provided the copyright notice and licence text are kept with copies. Read the LICENSE file yourself for the exact text, and keep the notice in your distribution.

The dependency list is where the real design decision shows. The server is built on minecraft-protocol for the wire protocol, prismarine-chunk for chunk handling, prismarine-entity, prismarine-item, prismarine-nbt, prismarine-provider-anvil for world loading, prismarine-registry, prismarine-windows and prismarine-world. Around those sit utility packages, moment for time handling, yargs for the command line, exit-hook, long, flatmap, range, random-seed, colors and change-case.

That is a lot of packages, and the diamond-square world generator is a direct dependency too, which is a hint about how the generator option is wired. Upgrading is therefore a matter of tracking the PrismarineJS package releases rather than one project, and the pinned versions in package.json are where you would look first.

The manifest also declares an engines field requiring node >=8, while the Dockerfile is built on node:16-slim. Those two numbers do not match, and the Docker image is the one with a defined runtime, so that is the environment to reason about. The package version in the manifest is 1.12.0, and the repository has a TODO.md file at the root, which is a reasonable place to look for what the maintainers consider unfinished.

Editorial conclusion

flying-squid fits a developer who wants a Minecraft server they can configure and extend from JavaScript rather than from configuration files and Java plugins, and who is happy with the feature set the project actually implements. It does not fit a server operator who needs a full survival game with redstone, mobs, farming and the rest of the vanilla feature list, because the documented features stop at world generation, digging, placing and movement. Before adopting it, read the version field in the configuration against the clients you expect to connect, try the Docker image on a throwaway port first, and check the MIT licence terms in the LICENSE file, which are short and permissive enough to read in a minute.

Frequently asked questions

Official sources

1. License: MIT
2. PrismarineJS/flying-squid on GitHub
3. Project website
4. README
5. Releases