# Host a Node.js WebSocket game server: what to prepare

> Our servers run Node.js 24, but they never install packages, so your project has to be packed on your own computer first. One command does that. This guide covers it, the setting for a WebSocket that is not at the root path, and the cases that cannot work. It is built and tested locally; no Node game has run on our servers yet.

*NetCraftGames (NCG) by Charging Bull Software. Last updated: 2026-10-03. Canonical page: https://netcraftgames.com/guides/node-websocket-server/*

## The short answer

Open a terminal in your project folder and run `ncg pack . --node --install`, then `ncg check .ncg/build` and `ncg submit`. The first command builds a folder with your code, the packages built for Linux and a small start script, and packs it into the archive we upload. It installs nothing unless you give it `--install`, and it never changes your own `node_modules`.

## What the host provides

- **Node.js 24, the long-term-support line.** One exact version is installed on every server and checked against the official signed release before it is used. When we move to a newer line, this guide changes the same day.
- **No npm and no package install.** Everything your server needs at run time must be in the archive. That is why the packages are built for Linux x64 (glibc) on your computer, whatever your computer runs.
- **A start script named `server`.** `ncg pack` writes it. It starts your file with `node` and a memory ceiling that fits the profile you chose. Your manifest's command is that script, because a command must be a file inside your archive.
- **Ubuntu 24.04.** Anything you build for Linux yourself must not need a newer glibc than 2.39.

If you would rather use a different Node version, you can put your own Linux x64 `node` in the archive and start it from your own script. The check then judges that program instead.

## Steps

1. **Make the server listen on all addresses.** Bind `0.0.0.0`, read the port from the environment with a default, and never bind `127.0.0.1` only.
2. **Add a health page and a join check.** A small route such as `/health` that answers `ok`, and one that proves a player could join. The [Node prompt](https://netcraftgames.com/can-you-host-my-game/prompts/node-ws-hosting-basics/) makes your AI add both.
3. **Handle SIGTERM.** Save and exit within the grace time when the host asks you to stop.
4. **Run `ncg init .`.** It reads the project and writes `ncg.json`, marking what it could not find.
5. **Run `ncg pack . --node --install`.** The exact command it runs is printed first. It needs npm 10.3 or newer and a `package-lock.json`. No package install script runs. If the lockfile points at git, a web address, a folder or a link instead of the npm registry, `ncg` stops before npm starts and says which package; replace it with a registry version (or use `--bundle`).
6. **Run `ncg check .ncg/build`.** This is what the service would say about your upload, before anything leaves your computer.

## If your WebSocket is not at the root path

By default the gateway connects to `ws://<your server>:<port>/`. If your server only accepts upgrades at `/ws`, write that in `ncg.json`:

```json
"wsPath": "/ws"
```

The path is fixed by you when you release. Nothing a player sends (path, query or headers) becomes part of the address the gateway connects to, so a player cannot reach another path on your server or on anyone else's. A path uses letters, digits and `. _ ~ - /`, up to 128 characters, with an optional fixed query of up to eight `key=value` pairs.

## socket.io

socket.io works only in WebSocket-only mode. In the browser, connect to the gateway address with `transports: ['websocket']` and `addTrailingSlash: false` (socket.io-client 4.6 or newer), and put the fixed query in the manifest:

```json
"wsPath": "/socket.io/?EIO=4&transport=websocket"
```

Long polling does not pass through the gateway, and neither does the client `query` option. Send tokens in the `auth` option instead. The [socket.io prompt](https://netcraftgames.com/can-you-host-my-game/prompts/node-socketio/) makes your AI change exactly that.

## What does not work

- **Colyseus.** It starts with plain web requests for matchmaking before the WebSocket. We say so before you upload, and the [check](https://netcraftgames.com/can-you-host-my-game/) says so before you start.
- **Packages for the wrong system.** A package with a native add-on built for Windows, macOS, ARM or Alpine is refused with the package named. `ncg pack --install` asks for Linux x64 builds only.
- **uWebSockets.js for a different Node.** Its add-ons are built per Node version. Use the build for Node 24, or the `ws` library.
- **Install scripts.** They never run on our servers. If your game needs one, move that work into the build.
- **TypeScript as the start file.** Compile it first and point `ncg pack` at the output with `--entry`.
- **A source folder.** Uploading a project with `package.json` and no start script is held with the command to run.

## Mistakes that waste the most time

| Mistake | What you see | Fix |
| --- | --- | --- |
| Packed on Windows without `--install` | A Windows add-on in `node_modules` is refused | Pack with `--install`, which builds for Linux |
| `engines.node` says 20 only | Node version not supported | Allow 24 in `engines`, for example `>=20` |
| Server binds `127.0.0.1` | The health check never passes | Bind `0.0.0.0` |
| WebSocket only at `/ws`, no `wsPath` | The check holds the build | Add `wsPath` to the manifest |
| Port in the code differs from the manifest | Timeout at start | Use the same number in both |

## Frequently asked questions


### Do I need to ship my own Node.js binary?

No. The servers have Node.js 24. You only ship your own if you need a different version, and then you start it from your own script.

### Does NetCraftGames run npm install for me?

No. Nothing on our servers installs packages. The command `ncg pack . --node --install` does it on your computer and puts the Linux packages in the archive.

### Can I use TypeScript?

Yes, compile it to JavaScript first. The start script runs a JavaScript file, and a TypeScript entry is refused with that advice.

### Is there a Node.js game running on NetCraftGames today?

Not yet. The preparation, the checks and the gateway path setting are built and tested locally with real libraries, but no Node game has run on our servers, and nothing here is certified.

## Sources

- [Node.js: previous releases (Node 24 long-term support line)](https://nodejs.org/en/about/previous-releases), accessed 2026-10-05
- [MDN: WebSockets API](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API), accessed 2026-10-03

## Related pages

- [Hosting a browser WebSocket (WSS) game server](https://netcraftgames.com/engines/browser-websocket/): Host an existing authoritative browser game server on NetCraftGames: a Node 24, Python 3.12 or Linux x64 WebSocket server behind a wss gateway.
- [Host a Python WebSocket game server: what to prepare](https://netcraftgames.com/guides/python-websocket-server/): Get a Python 3.12 WebSocket game server ready for NetCraftGames: the command that vendors Linux wheels, the WebSocket path setting and what does not work.
- [What a connection config file must contain](https://netcraftgames.com/guides/connection-config-file-contents/): What a deployment manifest and a player connection config must contain for a hosted multiplayer server, with a real example and the rules that cause rejections.