njs #
NGINX JavaScript — embed real JavaScript into request handling (<code>js_set</code>, <code>js_content</code>, <code>js_body_filter</code>, <code>js_periodic</code>, …) for routing, header rewriting, dynamic auth and response transformation. <strong>Built against QuickJS-NG</strong> instead of njs’s native interpreter, so the language surface is full ES2023: real <code>async</code>/<code>await</code>, <code>BigInt</code>, <code>Proxy</code>, ES modules with dynamic <code>import()</code>, modern regex (lookbehind, <code>\p{…}</code>) and a working <code>Intl</code>. You stop hitting “njs doesn’t have that” walls when porting code from Node or MDN.
Source: upstream source
Directives
js_access #
syntax: js_access 1 arg; · context: location, location-if, limit_except
Sets an njs function as a handler in the access phase, using r.return() to deny access or r.decline() to defer to other checkers.
js_body_filter #
syntax: js_body_filter 1 arg; · context: location, location-if, limit_except
Sets an njs function that filters response body data chunks synchronously, optionally modifying content before it is sent.
js_content #
syntax: js_content 1 arg; · context: location, location-if, limit_except
Sets an njs function as the content handler for a location, generating the response.
js_context_reuse #
syntax: js_context_reuse 1 arg (size (k/m/g)); · context: http, server, location
Size in bytes; accepts k / m / g suffixes.
js_context_reuse_max_size #
syntax: js_context_reuse_max_size 1 arg (size (k/m/g)); · context: http, server, location
Size in bytes; accepts k / m / g suffixes.
js_engine #
syntax: js_engine 1 arg; · context: http, server, location
Sets the JavaScript engine (njs, deprecated, or qjs, recommended) used to run njs scripts.
js_fetch_buffer_size #
syntax: js_fetch_buffer_size 1 arg (size (k/m/g)); · context: http, server, location
Size in bytes; accepts k / m / g suffixes.
js_fetch_ciphers #
syntax: js_fetch_ciphers 1 arg (string); · context: http, server, location
Specifies the enabled OpenSSL cipher list for HTTPS requests made with the Fetch API.
js_fetch_keepalive #
syntax: js_fetch_keepalive 1 arg (integer); · context: http, server, location
Integer value.
js_fetch_keepalive_requests #
syntax: js_fetch_keepalive_requests 1 arg (integer); · context: http, server, location
Integer value.
js_fetch_keepalive_time #
syntax: js_fetch_keepalive_time 1 arg (duration in ms); · context: http, server, location
Duration in milliseconds; accepts ms / s / m suffixes.
js_fetch_keepalive_timeout #
syntax: js_fetch_keepalive_timeout 1 arg (duration in ms); · context: http, server, location
Duration in milliseconds; accepts ms / s / m suffixes.
js_fetch_max_response_buffer_size #
syntax: js_fetch_max_response_buffer_size 1 arg (size (k/m/g)); · context: http, server, location
Size in bytes; accepts k / m / g suffixes.
js_fetch_protocols #
syntax: js_fetch_protocols 1+ args (bitmask); · context: http, server, location
Enables the specified TLS protocol versions for HTTPS requests made with the Fetch API.
js_fetch_proxy #
syntax: js_fetch_proxy 1 arg; · context: http, server, location
Configures a forward proxy URL (HTTP scheme only, optional Basic-auth credentials) for the Fetch API.
js_fetch_timeout #
syntax: js_fetch_timeout 1 arg (duration in ms); · context: http, server, location
Duration in milliseconds; accepts ms / s / m suffixes.
js_fetch_trusted_certificate #
syntax: js_fetch_trusted_certificate 1 arg (string); · context: http, server, location
Specifies a PEM file of trusted CA certificates used to verify HTTPS servers accessed via the Fetch API.
js_fetch_verify #
syntax: js_fetch_verify on | off (on/off flag); · context: http, server, location
Enables or disables verification of the HTTPS server certificate for Fetch API requests.
js_fetch_verify_depth #
syntax: js_fetch_verify_depth 1 arg (integer); · context: http, server, location
Integer value.
js_filter #
syntax: js_filter 1 arg (string); · context: stream, stream/server
Stores a single string value.
js_header_filter #
syntax: js_header_filter 1 arg (string); · context: location, location-if, limit_except
Sets an njs function as a response header filter that can synchronously modify header fields.
js_import #
syntax: js_import 1 arg; · context: http, server, location
Imports an njs module, exposing its exported functions as location and variable handlers under a namespace.
js_load_http_native_module #
syntax: js_load_http_native_module 1 arg; · context: main
Loads a native module shared library, main context only, for use in HTTP JavaScript code under the QuickJS engine.
js_load_stream_native_module #
syntax: js_load_stream_native_module 1 arg; · context: main
Loads a native module shared library, main context only, for use in Stream JavaScript code under the QuickJS engine.
js_path #
syntax: js_path 1 arg (list of strings); · context: http, server, location
Sets an additional filesystem path njs uses to resolve imported modules.
js_periodic #
syntax: js_periodic any args; · context: location
Specifies a content handler to run at a regular interval, with optional jitter and worker-process affinity.
js_preload_object #
syntax: js_preload_object 1 arg; · context: http, server, location
Preloads an immutable JSON object at configuration time for access as a global variable in njs code.
js_preread #
syntax: js_preread 1 arg (string); · context: stream, stream/server
Stores a single string value.
js_set #
syntax: js_set 2 args; · context: http, server, location
Sets an njs function that computes the value of the specified variable when it is first referenced in a request.
js_var #
syntax: js_var 1 arg; · context: http, server, location
Declares a writable njs-accessible variable that persists its value across internal redirects.
Example
# Load the ngx_http_js_module module
load_module modules/ngx_http_js_module.so;
events {}
http {
# Set the path to our njs JavaScript files
js_path "/etc/nginx/njs/";
# Import our JavaScript file into the variable "main"
js_import main from http/hello.js;
server {
listen 80;
location / {
# Execute the "hello" function defined in our JavaScript file on all HTTP requests
# and respond with the contents of our function.
js_content main.hello;
}
}
}