MAGE tutorial — 02. Debugging a MAGE server

Photo by Markus Spiske on Unsplash

Welcome to the second part of First steps with MAGE series tutorial! In the previous tutorial, we saw how to setup a basic MAGE server to store players data. In this tutorial, we will learn how to debug this server.

At first, debugging a MAGE server could be difficult. You have to use a client SDK or if you want to make a manual request you need to follow the MAGE specific request format. Also, sometimes you want to inspect the variables of your application.

That’s why mage-console has been created. It’s a REPL interface which lets you introspect your MAGE application. You can directly call your modules methods, display variables value, etc…

Setting up mage-console

First, you need to install mage-console from npm.

npm install --save-dev mage-console

We also modify our package.json to make our npm command develop use mage-console:

Now, start your server as usual:

npm run develop

Note that mage-console only works if your MAGE server is configured in single worker and single cluster mode.

Using mage-console

When starting a server using mage-console, you get a prompt which allows you to print all the variables of the global scope. However, the only variable that will interest us is the mage variable, exposed to the REPL by mage-console.

Try to print mage:

mage

You can also call modules commands. Before doing so, we need to create a State object.

let state = new mage.core.State()

Then, call the command players.create:

mage.players.create(state, 'foo')

However, this command will not really create our user. When you use a State object in a user command, it stacks all the operations you made and sends the transaction only on the user command completion.

For more information on State transaction management, please refer to the documentation.

As we are not in a user command, we need to send manually the transaction with:

state.distribute(() => {})

Then, you can use Archivist to get the user (remember, we hardcoded the playerId to 1):

state.archivist.get('player', {playerId: 1}, console.log)

Now, you can play with mage-console, try to display mage objects values, etc…

Here are some interesting commands and variables you could inspect:

• mage.core.archivist.getTopics()
• mage.core.archivist.getPersistentVaults()
• mage.core.logger.emergency(‘This is an emergency’)
• mage.listModules() and mage.core.modules
• And also our module mage.players

Other features

Besides allowing you to inspect variables, mage-console has also:

• auto-completion
• history navigation
• server restart on file changes

By default, mage-console will watch lib and config folders to restart the server on file changes. If needed, you can configure new directories and files to be watched.

If we want our server to restart when we modify our package.json, we could add this config in config/default.yaml:

Every time you will save your package.json, the server will restart.

You can also debug your application in Docker, Google Chrome, Visual Studio Code, but we won’t cover this in this tutorial. For more information, please refer to the repository.

Conclusion

mage-console is a very convenient way to inspect your application. As seen in the previous tutorial or as you will see in the next tutorials, you don’t need to make manual curl requests to debug your user commands. Just use mage-console!

See you in the next tutorial to discover how to validate data with mage-validator.