index.xml

<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">

<article name="nginx JavaScript module"
        link="/en/docs/njs/index.html"
        lang="en"
        rev="38"
        toc="no">

<section id="summary">

<para>
njs is an nginx module that extends the server's functionality through
JavaScript scripting, enabling the creation of custom
server-side logic and <link id="usecases">more</link>.
</para>

<para>
<note>
The built-in
<link doc="engine.xml" id="njs_engine">njs</link> JavaScript engine
is deprecated
since <link doc="changes.xml" id="njs1.0.0">1.0.0</link>;
new configurations should use the
<link doc="engine.xml" id="quickjs_engine">QuickJS</link> engine.
</note>
</para>

</section>


<section id="links">

<para>
<list type="bullet">

<listitem>
<link doc="install.xml"/>
</listitem>

<listitem>
<link doc="changes.xml"/>
</listitem>

<listitem>
<link doc="reference.xml"/>
</listitem>

<listitem>
<link doc="engine.xml"/>
</listitem>

<listitem>
<link doc="native_modules.xml"/>
</listitem>

<listitem>
<link url="https://github.com/nginx/njs-examples/">Examples</link>
</listitem>

<listitem>
<link doc="security.xml"/>
</listitem>

<listitem>
<link doc="compatibility.xml"/>
</listitem>

<listitem>
<link doc="cli.xml"/>
</listitem>

<listitem>
<link doc="preload_objects.xml"/>
</listitem>

<listitem>
<link id="tested_os_and_platforms">Tested OS and platforms</link>
</listitem>

</list>
</para>

<para>
<list type="bullet">

<listitem>
<link doc="../http/ngx_http_js_module.xml">
ngx_http_js_module</link>
</listitem>

<listitem>
<link doc="../stream/ngx_stream_js_module.xml">
ngx_stream_js_module</link>
</listitem>

</list>
</para>

<para>
<list type="bullet">

<listitem>
<link doc="typescript.xml"/>
</listitem>

<listitem>
<link doc="node_modules.xml"/>
</listitem>

</list>
</para>

</section>


<section id="usecases" name="Use cases">

<para>
<list type="bullet">

<listitem>
Complex access control and security checks in njs
before a request reaches an upstream server
</listitem>

<listitem>
Manipulating response headers
</listitem>

<listitem>
Writing flexible asynchronous content handlers and filters
</listitem>

</list>
See <link url="https://github.com/nginx/njs-examples/">examples</link>
for more njs use cases.
</para>

</section>


<section id="example" name="Basic HTTP Example">

<para>
To use njs in nginx:
<list type="bullet">

<listitem>
<para>
<link doc="install.xml">install</link> njs scripting language
</para>
</listitem>

<listitem id="hello_world">
<para>
create an njs script file, for example, <path>http.js</path>.
See <link doc="reference.xml">Reference</link>
for the list of njs properties and methods.
<example>
function hello(r) {
    r.return(200, "Hello world!");
}

export default {hello};
</example>
</para>
</listitem>

<listitem>

<para>
in the <path>nginx.conf</path> file, enable
<link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module
and specify the
<link doc="../http/ngx_http_js_module.xml" id="js_import">js_import</link>
directive
with the <path>http.js</path> script file:
<example>
load_module modules/ngx_http_js_module.so;

events {}

http {
    # since 0.9.1
    js_engine qjs;

    js_import http.js;

    server {
        listen 8000;

        location / {
            js_content http.hello;
        }
    }
}
</example>
</para>
</listitem>

</list>
There is also a standalone <link doc="cli.xml">command line</link> utility
that can be used independently of nginx for njs development and debugging.
</para>

</section>


<section id="tested_os_and_platforms"
        name="Tested OS and platforms">

<para>
<list type="bullet">

<listitem>
FreeBSD / amd64;
</listitem>

<listitem>
Linux / x86, amd64, arm64, ppc64el;
</listitem>

<listitem>
Solaris 11 / amd64;
</listitem>

<listitem>
macOS / x86_64;
</listitem>

</list>
</para>

</section>


<section id="presentation" name="Presentation at nginx.conf 2018">

<para><video id="Jc_L6UffFOs" /></para>

</section>

</article>