Unlock Nginx with nginScript: Embed JavaScript Directly in Your Config

Last year Nginx released nginScript , a JavaScript execution environment built on Nginx that lets you extend the server’s capabilities directly from the configuration file.

Nginx is already powerful, but its built‑in directives and third‑party modules sometimes fall short, and writing C modules has a high learning curve. nginScript offers a lighter, more convenient way to add custom logic.

nginScript consists of two parts:

A custom, lightweight JavaScript VM.

A configuration syntax that allows embedding JavaScript snippets in nginx.conf.

Example: Variable Declaration with js_set

http {
    ...
    js_set $msg "
        var m = 'Hello ';
        m += 'world!';
        m;
    ";
    ...
    server {
        ...
        location /hello {
            add_header Content-Type text/plain;
            return 200 $msg;
        }
        ...
    }
}

After reloading Nginx, accessing /hello returns the string "Hello world!".

Example: Executing Code with js_run

location /run {
    js_run "
        var res;
        res = $r.response;
        res.contentType = 'text/plain';
        res.status = 200;
        res.sendHeader();
        res.send('test run');
        res.finish();
    ";
}

Visiting /run returns the plain‑text response "test run".

Example: Accessing Request Parameters

http {
    ...
    js_set $summary "
        var a, s, h;
        s = 'JS summary

';
        s += 'Method: ' + $r.method + '
';
        s += 'HTTP version: ' + $r.httpVersion + '
';
        s += 'Host: ' + $r.headers.host + '
';
        s += 'Remote Address: ' + $r.remoteAddress + '
';
        s += 'URI: ' + $r.uri + '
';
        s += 'Headers:
';
        for (h in $r.headers) { s += '  header "' + h + '" is "' + $r.headers[h] + '
'; }
        s += 'Args:
';
        for (a in $r.args) { s += '  arg "' + a + '" is "' + $r.args[a] + '
'; }
        s;
    ";
    ...
    server {
        ...
        location /summary {
            add_header Content-Type text/plain;
            return 200 $summary;
        }
        ...
    }
    ...
}

This configuration creates a /summary endpoint that returns a detailed list of request method, HTTP version, host, remote address, URI, headers, and query arguments.

Installation

$ mkdir -p ~/nginScript
$ cd ~/nginScript
$ wget http://nginx.org/download/nginx-1.9.5.tar.gz
$ git clone https://github.com/nginScript/nginScript --depth=1
$ tar xfvz nginx-1.9.5.tar.gz
$ cd nginx-1.9.5
$ ./configure --add-module=../nginScript/nginx --prefix=$HOME/nginScript/nginx
$ make
$ make install

After building and installing, reload Nginx with nginx -s reload to apply the new configuration.