Server Framework TypeScript Setup #

The game server embeds a JavaScript Virtual Machine (VM) which can be used to load and run custom logic which is specific to your game project. This is in addition to Lua and Go as supported programming languages to write your server code.

It’s useful to implement game code you would not want to run on the client or trust the client to provide unchecked inputs on. You can think of this feature of Nakama as similar to what is sometimes called Lambda or Cloud Functions in other systems. A good use case is if you wanted to grant the user a reward each day that they play the game.

TypeScript is a fantastic superset of the JavaScript language. It allows you to write your code with types which helps to reduce bugs and unexpected runtime behavior of code. Nakama’s support for JavaScript has been built to directly consider the use of TypeScript for your code and is the recommended way to develop your JavaScript code.

You can learn more about how to write your JavaScript code in TypeScript in the official documentation.

Prerequisites #

You will need to have these tools installed to work with TypeScript for your project:

• Node v14 (active LTS) or greater.
• Basic UNIX tools or knowledge on the Windows equivalents.

The TypeScript compiler and other dependencies will be fetched with NPM.

Initialize the project #

These steps will set up a workspace to write all your project code to be run by the game server.

Define the folder name that will be the workspace for the project. In this case we’ll use “ts-project”.

1
2

mkdir -p ts-project/{src,build}
cd ts-project

Use NPM to set up the Node dependencies in the project. Install the TypeScript compiler.

1
2

npm init -y
npm install --save-dev typescript

Use the TypeScript compiler installed to the project to set up the compiler options.

1

npx tsc --init

You’ll now have a “tsconfig.json” file which describes the available options that are run on the TypeScript compiler. When you’ve trimmed the commented out entries and updated it a minimal file will look something like:

1
2
3
4
5
6
7
8
9

{
  "compilerOptions": {
    "target": "es5",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Add this configuration option to the "compilerOptions" block:

1

"outFile": "./build/index.js",

Add the Nakama runtime types as a dependency to the project and configure the compiler to find the types.

1

npm i 'https://github.com/heroiclabs/nakama-common'

Add this configuration option to the "compilerOptions" block of the “tsconfig.json” file:

1
2
3

"typeRoots": [
  "./node_modules"
],

This completes the setup and your project should look similar to this layout:

1
2
3
4
5
6
7
8
9

.
├── build
├── node_modules
│   ├── nakama-runtime
│   └── typescript
├── package-lock.json
├── package.json
├── src
└── tsconfig.json

Develop code #

We’ll write some simple code and compile it to JavaScript so it can be run by the game server.

All code must start execution from a function that the game server looks for in the global scope at startup. This function must be called "InitModule" and is how you register RPCs, before/after hooks, and other event functions managed by the server.

The code below is a simple Hello World example which uses the "Logger" to write a message. Name the source file “main.ts” inside the “src” folder. You can write it in your favourite editor or IDE.

1
2
3
4

let InitModule: nkruntime.InitModule =
        function(ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
    logger.info("Hello World!");
}

We can now add the file to the compiler options and run the TypeScript compiler.

1
2
3
4
5
6
7
8

{
  "files": [
    "./src/main.ts"
  ],
  "compilerOptions": {
    // ... etc
  }
}

To compile the codebase:

1

npx tsc

Returning errors #

When writing your own custom runtime code, you should ensure that any errors that occur when processing a request are passed back to the client appropriately. This means that the error returned to the client should contain a clear and informative error message as well as an appropriate HTTP status code.

Internally the Nakama runtime uses gRPC error codes and converts them to the appropriate HTTP status codes when returning the error to the client. The following table shows the mapping between gRPC code and HTTP code.

The Nakama TypeScript runtime defines the error codes in the nkruntime.Codes enum. You can use these to define your own custom nkruntime.Error objects. The following are some examples of errors you might wish to define in your module.

1
2
3
4
5
6
7
8
9

const errBadInput: nkruntime.Error = {
  message: 'input contained invalid data',
  code: nkruntime.Codes.INVALID_ARGUMENT
};

const errGuildAlreadyExists: nkruntime.Error = {
  message: 'guild name is in use',
  code: nkruntime.Codes.ALREADY_EXISTS
};

Below shows an example of how you would return appropriate errors both in an RPC call as well as in a Before Hook.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

const createGuildRpc: nkruntime.RpcFunction = (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, payload: string): string | void  => {
  // ... check if a guild already exists and set value of `alreadyExists` accordingly
  const alreadyExists = true;

  if (alreadyExists) {
    throw errGuildAlreadyExists;
  }

  return JSON.stringify({ success: true });
};

const beforeAuthenticateCustom: nkruntime.BeforeHookFunction<nkruntime.AuthenticateCustomRequest> = (ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, data: nkruntime.AuthenticateCustomRequest): void | nkruntime.AuthenticateCustomRequest => {
  // Only match custom Id in the format "cid-000000"
  const pattern = new RegExp('^cid-([0-9]{6})$');

  if (!pattern.test(data.account.id)) {
    throw errBadInput;
  }

  return data;
}

Restrictions #

Compatibility #

The JavaScript runtime is powered by the goja VM which currently supports the JavaScript ES5 spec.

The JavaScript runtime has access to the standard library functions included in the ES5 spec. You cannot call Lua functions from the Go runtime, or Go functions from the Lua runtime.

Global state #

The JavaScript runtime code is executed in instanced contexts. You cannot use global variables as a way to store state in memory or communicate with other JS processes or function calls.

Sandboxing #

The JavaScript runtime code is fully sandboxed and cannot access the filesystem, input/output devices, or spawn OS threads or processes. This allows the server to guarantee that JS modules cannot cause fatal errors - the runtime code cannot trigger unexpected client disconnects or affect the main server process.

Running the project #

With Docker #

The easiest way to run your server locally is with Docker.

To do this, create a file called Dockerfile.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

FROM node:alpine AS node-builder

WORKDIR /backend

COPY package*.json .
RUN npm install

COPY tsconfig.json .
COPY main.ts .
RUN npx tsc

FROM heroiclabs/nakama:3.11.0

COPY --from=node-builder /backend/build/*.js /nakama/data/modules/build/
COPY local.yml .

Next create a docker-compose.yml file. For more information see the Install Nakama with Docker Compose documentation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

version: '3'
services:
  postgres:
    command: postgres -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all
    environment:
      - POSTGRES_DB=nakama
      - POSTGRES_PASSWORD=localdb
    expose:
      - "8080"
      - "5432"
    image: postgres:12.2-alpine
    ports:
      - "5432:5432"
      - "8080:8080"
    volumes:
      - data:/var/lib/postgresql/data

  nakama:
    build: .
    depends_on:
      - postgres
    entrypoint:
      - "/bin/sh"
      - "-ecx"
      - >
        /nakama/nakama migrate up --database.address postgres:localdb@postgres:5432/nakama &&
        exec /nakama/nakama --config /nakama/data/local.yml --database.address postgres:localdb@postgres:5432/nakama        
    expose:
      - "7349"
      - "7350"
      - "7351"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7350/"]
      interval: 10s
      timeout: 5s
      retries: 5
    links:
      - "postgres:db"
    ports:
      - "7349:7349"
      - "7350:7350"
      - "7351:7351"
    restart: unless-stopped

volumes:
  data:

Now run the server with the command:

1

docker compose up

Without Docker #

Install a Nakama binary stack for Linux, Windows, or macOS. When this is complete you can run the game server and have it load your code:

1

nakama --logger.level DEBUG --runtime.js_entrypoint "build/index.js"

Remember you need to build the build/index.js file by running npx tsc from the Terminal before you can execute the above command.

Confirming the server is running #

The server logs will show this output or similar which shows that the code we wrote above was loaded and executed at startup.

1

{"level":"info","ts":"...","msg":"Hello World!","caller":"server/runtime_javascript_logger.go:54"}

Bundling with Rollup #

The setup above relies solely on the TypeScript compiler. This helps to keep the toolchain and workflow simple, but limits your ability to bundle your TypeScript code with additional node modules.

Rollup is one of the options available to bundle node modules that don’t depend on the Node.js runtime to run within Nakama.

Configuring Rollup #

When configuring your TypeScript project to use Rollup there are a few additional steps and alterations you will need to make to your project if you have followed the steps above.

The first thing you will need to do is install some additional dependencies that will allow you to run Rollup to build your server runtime code. These include Babel, Rollup, several of their respective plugins/presets and tslib.

To do this, run the following command in the Terminal, which will install the dependencies and add them to your package.json file as development dependencies:

1

npm i -D @babel/core @babel/plugin-external-helpers @babel/preset-env @rollup/plugin-babel @rollup/plugin-commonjs @rollup/plugin-json @rollup/plugin-node-resolve @rollup/plugin-typescript rollup tslib

With Rollup installed as a dev dependency of your project, you now need to modify the build script in package.json to run the rollup -c command instead of the tsc command. You should also add a type-check script that will allow you to verify your TypeScript compiles without actually emitting a build file.

package.json

1
2
3
4
5
6
7
8

{
  ...
  "scripts": {
    "build": "rollup -c",
    "type-check": "tsc --noEmit"
  },
  ...
}

Next, you must add the following rollup.config.js file to your project.

rollup.config.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

import resolve from '@rollup/plugin-node-resolve';
import commonJS from '@rollup/plugin-commonjs';
import json from '@rollup/plugin-json';
import babel from '@rollup/plugin-babel';
import typescript from '@rollup/plugin-typescript';
import pkg from './package.json';

const extensions = ['.mjs', '.js', '.ts', '.json'];

export default {
  input: './src/main.ts',
  external: ['nakama-runtime'],
  plugins: [
    // Allows node_modules resolution
    resolve({ extensions }),

    // Compile TypeScript
    typescript(),

    json(),

    // Resolve CommonJS modules
    commonJS({ extensions }),

    // Transpile to ES5
    babel({
      extensions,
      babelHelpers: 'bundled',
    }),
  ],
  output: {
    file: 'build/index.js',
  },
};

Followed by adding a babel.config.json file to your project.

babel.config.json

1
2
3
4
5
6

{
  "presets": [
    "@babel/env"
  ],
  "plugins": []
}

There are also changes to the tsconfig.json file that must be made. Using Rollup simplifies the build process and means you no longer have to manually update the tsconfig.json file every time you add a new *.ts file to your project. Replace the contents of your existing tsconfig.json file with the example below.

tsconfig.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "compilerOptions": {
    "noImplicitReturns": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "noUnusedLocals": true,
    "removeComments": true,
    "target": "es5",
    "module": "ESNext",
    "strict": false,
  },
  "files": [
    "./node_modules/nakama-runtime/index.d.ts",
  ],
  "include": [
    "src/**/*",
  ],
  "exclude": [
    "node_modules",
    "build"
  ]
}

Next, you need to include a line at the bottom of your main.ts file that references the InitModule function. This is to ensure that Rollup does not omit it from the build.

main.ts

1
2
3
4
5
6

function InitModule(ctx: nkruntime.Context, logger: nkruntime.Logger, nk: nkruntime.Nakama, initializer: nkruntime.Initializer) {
  logger.info('TypeScript module loaded.');
}

// Reference InitModule to avoid it getting removed on build
!InitModule && InitModule.bind(null);

You will also need to create a configuration for nakama called local.yml. The runtime.js_entrypoint setting indicates to nakama to read the built javascript code.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

console:
  max_message_size_bytes: 409600
logger:
  level: "DEBUG"
runtime:
  js_entrypoint: "build/index.js"
session:
  token_expiry_sec: 7200 # 2 hours
socket:
  max_message_size_bytes: 4096 # reserved buffer
  max_request_size_bytes: 131072

Finally, you need to make a slight alteration to your Dockerfile to ensure you copy across the rollup.config.js and babel.config.json files. You must also change the RUN command to run your updated build command rather than using the TypeScript compiler directly. Replace the contents of your Dockerfile with the example below.

Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

FROM node:alpine AS node-builder

WORKDIR /backend

COPY package*.json .
RUN npm install

COPY . .
RUN npm run build

FROM heroiclabs/nakama:3.11.0

COPY --from=node-builder /backend/build/*.js /nakama/data/modules/build/
COPY local.yml /nakama/data/

Building your module locally #

Ensure you have all dependencies installed:

1

npm i

Perform a type check to ensure your TypeScript will compile successfully:

1

npm run type-check

Build your project:

1

npm run build

Running your module with Docker #

To run Nakama with your custom server runtime code, run:

1

docker compose up

If you have made changes to your module and want to re-run it, you can run:

1

docker compose up --build nakama

This will ensure the image is rebuilt with your latest changes.

Next steps #

Have a look at the Nakama project template which covers the following Nakama features:

• Authoritative multiplayer match handler
• In-App Notifications
• Storage
• RPCs
• User Wallets