This document contains many fun recipes for cooking with mojo.js.


Essentials every mojo.js developer should know.

Reverse Proxy

A reverse proxy architecture is a deployment technique used in many production environments, where a reverse proxy server is put in front of your application to act as the endpoint accessible by external clients. It can provide a lot of benefits, like terminating SSL connections from the outside, limiting the number of concurrent open sockets towards the mojo.js application, balancing load across multiple instances, or supporting several applications through the same IP/port.

                :                                        :
+--------+      :  +-----------+      +---------------+  :
|        |-------->|           |      |               |  :
| client |      :  |  reverse  |----->|  mojo.js      |  :
|        |<--------|   proxy   |      |  application  |  :
+--------+      :  |           |<-----|               |  :
                :  +-----------+      +---------------+  :
                :                                        :
                .. system boundary (e.g. same host) ......

This setup introduces some problems, though: the application will receive requests from the reverse proxy instead of the original client; the address/hostname where your application lives internally will be different from the one visible from the outside; and if terminating SSL, the reverse proxy exposes services via HTTPS while using HTTP towards the mojo.js application.

As an example, compare a sample request from the client and what the mojo.js application receives:

client                       reverse proxy                mojo.js app
__|__              _______________|______________             ____|____
/     \            /                              \           /         \ --HTTPS--> --HTTP-->

GET /foo/1 HTTP/1.1                |    GET /foo/1 HTTP/1.1
Host:              |    Host:
User-Agent: Firefox                |    User-Agent: ShinyProxy/1.2
...                                |    ...

However, now the client address is no longer available (which might be useful for analytics, or Geo-IP) and URLs generated via ctx.urlFor() will look like this:

instead of something meaningful for the client, like this:

To solve these problems, you can configure your reverse proxy to send the missing data and tell your application about it with the --proxy option.

$ node myapp.js server --proxy


Getting mojo.js applications running on different platforms.

Built-in Web Server

mojo.js contains a very portable Node.js based HTTP and WebSocket server. It can be used for web applications of any size and scales very well.

$ node myapp.js server
Web application available at

It is available to every application through the server command, which has many configuration options and is known to work on every platform Node.js works on.

$ node myapp.js server -h
...List of available options...

Another huge advantage is that it supports TLS and WebSockets out of the box, a self-signed development certificate for testing purposes is built right in, so it just works.

$ node myapp.js server -l
Web application available at


To manage the web server with systemd, you can use a unit configuration file like this.

Description=My mojo.js application

ExecStart=NODE_ENV=production node /home/sri/myapp/myapp.js server -l http://*:8080


And while the default logger will already work pretty well, we also have native support for the journald format. That means if you activate the systemdFormatter you can get proper log level mapping and syntax highlighting for your journal too.

import mojo, {Logger} from '@mojojs/core';

const app = mojo();
app.log.formatter = Logger.systemdFormatter;

app.get('/', ctx => ctx.render({text: 'Hello systemd!'}));


You can even use systemd for socket activation. The socket will be passed to your server as file descriptor 3, so all you have to do is to use a slightly different listen option.

ExecStart=NODE_ENV=production node /home/sri/myapp/myapp.js server -l http://*?fd=3


After reading the Introduction you should already be familiar with nodemon. It is a restarter that starts a new web server process whenever a file in your project changes, and should therefore only be used during development.

$ npm install nodemon

$ npx nodemon myapp.js server
[39248] Web application available at


CGI is supported out of the box and your mojo.js application will automatically detect that it is executed as a CGI script. Its use in production environments is discouraged though, because as a result of how CGI works, it is very slow and many web servers are making it exceptionally hard to configure properly. Additionally, many real-time web features, such as WebSockets, are not available.

ScriptAlias / /home/sri/myapp/index.js/


One of the most popular setups these days is web applications behind an Nginx reverse proxy, which even supports WebSockets in newer versions.

upstream myapp {
server {
  listen 80;
  server_name localhost;
  location / {
    proxy_pass http://myapp;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;


Another good reverse proxy is Apache with mod_proxy, the configuration looks quite similar to the Nginx one above. And if you need WebSocket support, newer versions come with mod_proxy_wstunnel.

<VirtualHost *:80>
  ServerName localhost
  <Proxy *>
    Require all granted
  ProxyRequests Off
  ProxyPreserveHost On
  ProxyPass /echo ws://localhost:8080/echo
  ProxyPass / http://localhost:8080/ keepalive=On
  ProxyPassReverse / http://localhost:8080/
  RequestHeader set X-Forwarded-Proto "http"


mojo.js applications can be deployed on cloud-native environments that use Envoy, such as with this reverse proxy configuration similar to the Apache and Nginx ones above.

  - name: listener_0
      socket_address: { address:, port_value: 80 }
    - filters:
      - name:
          codec_type: auto
          stat_prefix: index_http
            name: local_route
            - name: service
              domains: ["*"]
              - match:
                  prefix: "/"
                  cluster: local_service
          - upgrade_type: websocket
          - name: envoy.filters.http.router
  - name: local_service
    connect_timeout: 0.25s
    type: strict_dns
    lb_policy: round_robin
      cluster_name: local_service
      - lb_endpoints:
        - endpoint:
              socket_address: { address: mojo, port_value: 8080 }

While this configuration works for simple applications, Envoy's typical use case is for implementing proxies of applications as a "service mesh" providing advanced filtering, load balancing, and observability features, such as seen in Istio. For more examples, visit the Envoy documentation.

Real-Time Web

The real-time web is a collection of technologies that include Comet (long polling), EventSource and WebSockets, which allow content to be pushed to consumers with long-lived connections as soon as it is generated, instead of relying on the more traditional pull model. The built-in web server uses non-blocking I/O and is based on an event loop, which provides many very powerful features that allow real-time web applications to scale up to thousands of concurrent client connections.

Backend Web Services

Since the built-in HTTP user-agent is also based on the event loop, it won't block the built-in web server, even for high latency backend web services.

import mojo from '@mojojs/core';

const app = mojo();

app.get('/', async ctx => {
  const res = await'', {query: {q: 'mojolicious'}});
  const data = await res.json();
  await ctx.render({inline: metacpanTemplate}, {hits: data.hits.hits});

const metacpanTemplate = `
<!DOCTYPE html>
  <head><title>MetaCPAN results for "mojolicious"</title></head>
    % for (const hit of hits) {
      <p><%= hit._source.release %></p>
    % }


Thanks to async/await there is no need to use any callbacks.


Fun mojo.js application hacks for all occasions.

Basic Authentication

Basic authentication data will be automatically extracted from the Authorization header.

import mojo from '@mojojs/core';

const app = mojo();

app.get('/', async ctx => {

  // Check for username "Bender" and password "rocks"
  if (ctx.req.userinfo === 'Bender:rocks') return ctx.render({text: 'Hello Bender!'});

  // Require authentication
  ctx.res.set('WWW-Authenticate', 'Basic');
  return ctx.render({text: 'Authentication required!', status: 401});


This can be combined with TLS for a secure authentication mechanism.

$ node myapp.js server -l 'https://*:3000?cert=./server.crt&key=./server.key'

Adding a Configuration File

Adding a configuration file to your application is as easy as adding a file to its home directory and loading the plugin jsonConfigPlugin. The default name for the config file is config.json, and it is possible to have mode specific config files like config.development.json.

$ echo '{"name": "my mojo.js application"}' > config.json

Configuration files themselves are just plain JSON files containing settings that will get merged into app.config, which is also available as ctx.config.

import mojo, {jsonConfigPlugin} from '@mojojs/core';

const app = mojo();

app.get('/', async ctx => {
  await ctx.render({json: {name:}});


Alternatively you can also use configuration files in the YAML format with yamlConfigPlugin.

Adding Plugins to Your Application

To organize your code better and to prevent helpers from cluttering your application, you can use application specific plugins.

$ mkdir plugins
$ touch plugins/my-helpers.js

They work just like normal plugins.

export default function myHelpersPlugin (app) {
  app.addHelper('renderWith.header', async (ctx, ...args) => {
    ctx.res.set('X-Mojo', 'I <3 mojo.js!');
    await ctx.render(...args);

You can have as many application specific plugins as you like, the only difference to normal plugins is that you load them directly from the file.

import mojo from '@mojojs/core';
import myHelpersPlugin from './plugins/my-helpers.js';

const app = mojo();

app.get('/', async ctx => {
  await ctx.renderWith.header({text: 'I ♥ mojo.js!'});


Of course these plugins can contain more than just helpers.

Adding Commands to Your Application

By now you've probably used many of the built-in commands, like get and server, but did you know that you can just add new ones and that they will be picked up automatically by the command line interface if they are placed in a cli directory in your application's home directory?

$ mkdir cli
$ touch cli/spy.js

Every command is async and has full access to the application object app.

export default async function spyCommand(app, args) {
  const subCommand = args[2];
  if (subCommand === 'secrets') {
  } else if (subCommand === 'mode') {

spyCommand.description = 'Spy on application';
spyCommand.usage = `Usage: APPLICATION spy [OPTIONS]

  node index.js spy

  -h, --help   Show this summary of available options

Command line arguments are passed right through and you can parse them with whatever module you prefer.

$ node index.js spy secrets

The options -h and --help are handled automatically for all commands.

Running Code Against Your Application

Ever thought about running a quick one-liner against your mojo.js application to test something? Thanks to the eval command you can do just that, the application object itself can be accessed via app.

$ node index.js eval 'console.log(app.static.publicPaths)'

The verbose option will automatically print the return value or returned data structure to stdout.

$ node index.js eval -v 'app.renderer.viewPaths'


A lot more documentation and examples by many different authors can be found in the mojo.js wiki.


If you have any questions the documentation might not yet answer, don't hesitate to ask in the Forum, on IRC, or Matrix.