Harnessing the Power and Convenience of JavaScript for Each Request with the NGINX JavaScript Module<\/p>\n
\n<\/p>\n
table.nginx-blog, table.nginx-blog th, table.nginx-blog td {
\n border: 2px solid black;
\n border-collapse: collapse;
\n }
\n table.nginx-blog {
\n width: 100%;
\n }
\n table.nginx-blog th {
\n background-color: #d3d3d3;
\n align: left;
\n padding-left: 5px;
\n padding-right: 5px;
\n padding-bottom: 2px;
\n padding-top: 2px;
\n line-height: 120%;
\n }
\n table.nginx-blog td {
\n padding-left: 5px;
\n padding-right: 5px;
\n padding-bottom: 2px;
\n padding-top: 5px;
\n line-height: 120%;
\n }
\n table.nginx-blog td.center {
\n text-align: center;
\n padding-bottom: 2px;
\n padding-top: 5px;
\n line-height: 120%;
\n }<\/p>\n
Editor<\/strong> – The blog post titled “Introduction to the NGINX JavaScript Module” redirects here. The post has been updated to use the NGINX JavaScript Module directives and features supported as of April 2021.<\/em><\/p>\n The NGINX JavaScript module (njs) became generally available as a stable module in NGINX Open Source 1.11.10 and NGINX Plus R12<\/a><\/span>. [The module was originally called nginScript, and that name appears in some older posts.]<\/em> We have been working steadily on NGINX JavaScript since its launch in September 2015<\/a>, adding the features and language support included in the stable module.<\/p>\n NGINX JavaScript is a unique JavaScript implementation for NGINX and NGINX Plus, designed specifically for server‑side use cases and per‑request processing. It extends NGINX configuration syntax with JavaScript code in order to implement sophisticated configuration solutions.<\/p>\n The use cases are extensive, especially as the NGINX JavaScript module is available for both HTTP and TCP\/UDP protocols. Sample use cases for NGINX JavaScript include:<\/p>\n Before discussing NGINX JavaScript in more detail, let\u2019s first address two common misconceptions.<\/p>\n The NGINX community has created several programmatic extensions over the years. At the time of writing, Lua is the most popular of these; it’s available as a module for NGINX<\/a> and a supported, prebuilt third‑party dynamic module<\/a> for NGINX Plus. The Lua module and add‑on libraries provide deep integration with the NGINX core and a rich set of functionality, including a driver for Redis.<\/p>\n Lua is a powerful scripting language. It, however, remains fairly niche in terms of adoption and is not typically found in the \u201cskillset toolbox\u201d of the frontend developer or DevOps engineer.<\/p>\n NGINX JavaScript does not seek to replace Lua and it will be some time before NGINX JavaScript has a comparable level of functionality. The goal of NGINX JavaScript is to provide programmatic configuration solutions to the widest possible community by using a popular programming language.<\/p>\n NGINX JavaScript does not aim to turn NGINX or NGINX Plus into an application server. In simple terms, the use cases for NGINX JavaScript are akin to middleware, as the execution of JavaScript code happens between the client and the content. Technically speaking, while Node.js shares two things with the combination of NGINX JavaScript and NGINX or NGINX Plus – an event‑driven architecture<\/a> and the JavaScript programming language – the similarities end there.<\/p>\n Node.js uses the Google V8 JavaScript engine, whereas NGINX JavaScript is a bespoke implementation of the ECMAScript standards, designed specifically for NGINX and NGINX Plus. Node.js has a persistent JavaScript virtual machine (VM) in memory and performs routine garbage collection for memory management, whereas NGINX JavaScript initializes a new JavaScript VM and the necessary memory for each request and frees the memory when the request is completed.<\/p>\n As mentioned above, NGINX JavaScript is a bespoke implementation of the JavaScript language. All other existing JavaScript runtime engines are designed to be executed within a web browser. The nature of client‑side code execution is different from server‑side code execution in many ways \u2013 from the availability of system resources to the possible number of concurrent runtimes.<\/p>\n We decided to implement our own JavaScript runtime in order to meet the requirements of server‑side code execution and fit elegantly with NGINX\u2019s request‑processing architecture. Our design principles for NGINX JavaScript are these:<\/p>\n Runtime environment lives and dies with the request<\/strong><\/p>\n The NGINX JavaScript module uses single‑threaded bytecode execution, designed for quick initialization and disposal. The runtime environment is initialized per request. Startup is extremely quick, because there is no complex state or helpers to initialize. Memory is accumulated in pools during execution and released at completion by freeing the pools. This memory management scheme eliminates the need to track and free individual objects or to use a garbage collector.<\/p>\n<\/li>\n Non‑blocking code execution<\/strong><\/p>\n NGINX and NGINX Plus\u2019 event‑driven model schedules the execution of individual NGINX JavaScript runtime environments. When an NGINX JavaScript rule performs a blocking operation (such as reading network data or issuing an external subrequest), NGINX and NGINX Plus transparently suspend execution of the associated NGINX JavaScript VM and reschedule it when the event completes. This means that you can write rules in a simple, linear fashion and NGINX and NGINX Plus schedule them without internal blocking.<\/p>\n<\/li>\n Implement only the language support that we need<\/strong><\/p>\n The specifications for JavaScript are defined by the ECMAScript<\/a> standards. NGINX JavaScript follows ECMAScript 5.1<\/a> with some ECMAScript 6<\/a> for mathematical functions. Implementing our own JavaScript runtime gives us the freedom to prioritize language support for server‑side use cases and ignore what we don\u2019t need. We maintain a list of the currently supported language elements<\/a>.<\/p>\n<\/li>\n Close integration with request‑processing phases<\/strong><\/p>\n NGINX and NGINX Plus process requests in distinct phases. Configuration directives typically operate at a specific phase and native NGINX modules often take advantage of the ability to inspect or modify a request at a particular phase. NGINX JavaScript exposes some of the processing phases through configuration directives to give control over when the JavaScript code is executed. This integration with the configuration syntax promises the power and flexibility of native NGINX modules with the simplicity of JavaScript code.<\/p>\n The table below indicates which processing phases are accessible via NGINX JavaScript at the time of writing, and the configuration directives that provide it.<\/p>\n\n
NGINX JavaScript Is Not Lua<\/h2>\n
NGINX JavaScript Is Not Node.js<\/h2>\n
JavaScript as a Server-Side Language<\/h2>\n
\n