Alternative MAGE development console, with REPL interface.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.eslintrc.yml Save REPL when files are changed Jul 21, 2017
.npmrc Save REPL when files are changed Jul 21, 2017
package.json Multiple fixes and prettification of errors Dec 6, 2017
screen.gif Save REPL when files are changed Jul 21, 2017


Alternative MAGE development console, with REPL interface.

screen capture


  • Activates debugging (--debug for Node.js < 8.0.0, --inspect otherwise)
  • REPL interface which lets you introspect your MAGE application
  • Watches your './lib' folder and automatically reloads the worker on file changes
  • Works for both JavaScript and TypeScript projects


MAGE Version

This module is compatible with MAGE >= 1.0.0. Note that if you have upgraded an older MAGE application to MAGE 1.0.0, you will need to make sure that your ./lib/index.js follows the new initialisation pattern.

Application configuration

mage-console will only work when your application is configured in cluster mode to start a single process:

### Make sure `config/development.yml is configured as such
  cluster: 1


In your MAGE project:

npm install --save mage-console

Then, in your project's package.json, update the develop script job from npm run mage to mage-console:

    "scripts": {
        "develop": "mage-console"

If your project is a TypeScript project, set the value to ts-mage-console instead:

    "scripts": {
        "develop": "ts-mage-console"

Then simply run npm run develop like you would normally do.


You may configure mage-console by adding configuration entries into your MAGE configuration. See MAGE's documentation for more details.


    # Where to put the socket file for the console.
    # Default: [project-dir]/node_modules/mage-console/mage-console.sock
    sockfile: /tmp/mage-console.sock

    # Watch additional files; we will always watch `./config' and './lib',
    # but you may want to watch additional folders as well.
      - /tmp/file
      - ./www



The following ports are used automatically for debugging:

  • TypeScript: 9229 (inspect protocol, using --inspect flags);
  • Node 8.0 and up: 9229 (inspect protocol, using --inspect flags);
  • Node less than 8.0: 5858 (legacy protocol, using --debug flags);

The debugging interface is activated on workers: this means that when you will save code, the worker will be restarted, and your debugging session will be terminated.

Remote debugging (docker)

While debugging is activated by default, debugging is attached to localhost; if you develop in a Docker container, this means you won't be able to connect remotely to the debugging port.

To solve this issue, you can set the DEBUG_HOST environment variable, as follow:

DEBUG_HOST="" npm run develop

This will instruct mage-console to have the worker bind the debugging interface on all available interfaces instead of only on localhost.

Visual Studio Code configuration

The default debugging port selection is made to match the behaviour of VSCode. However, if you are using TypeScript, you will need to specifically mention that you are using the new inspect protocol:


  "version": "0.2.0",
  "configurations": [{
    "name": "Attach to MAGE instance",
    "type": "node",
    "request": "attach",
    "sourceMaps": true,
    "outDir": "${workspaceRoot}/dist",
    "protocol": "inspector",
    "internalConsoleOptions": "neverOpen"