njs: Modules dynamiques NGINX njs

Installation

Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

RedHat Enterprise Linux 7, 8, 9 et 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 et Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 et Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-njs

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-njs

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_js_module.so;

load_module modules/ngx_stream_js_module.so;

Ce document décrit nginx-module-njs v0.9.6 publié le 3 mars 2026.

Bannière NGINX JavaScript

NGINX JavaScript

NGINX JavaScript, également connu sous le nom de NJS, est un module dynamique pour NGINX qui permet d'étendre les fonctionnalités intégrées en utilisant une syntaxe JavaScript familière. Le langage NJS est un sous-ensemble de JavaScript, conforme à ES5 (ECMAScript 5.1 Strict Variant) avec quelques extensions ES6 (ECMAScript 6) et plus récentes. Consultez la section compatibilité pour plus de détails.

Comment ça fonctionne

NGINX JavaScript est fourni sous forme de deux modules dynamiques pour NGINX (ngx_http_js_module et ngx_stream_js_module) et peut être ajouté à toute installation prise en charge de NGINX Open Source ou NGINX Plus sans recompilation.

Le module NJS permet aux administrateurs NGINX de : - Ajouter des contrôles d'accès et de sécurité complexes avant que les requêtes n'atteignent les serveurs en amont - Manipuler les en-têtes de réponse - Écrire des gestionnaires de contenu, des filtres, et plus encore, flexibles et asynchrones !

Consultez les exemples et nos divers projets développés avec NJS :

https://github.com/nginxinc/nginx-openid-connect

Étend les fonctionnalités de NGINX Plus pour communiquer directement avec des fournisseurs d'identité compatibles OIDC, authentifiant les utilisateurs et autorisant le contenu livré par NGINX Plus.

https://github.com/nginxinc/nginx-saml

Implémentation de référence de NGINX Plus en tant que fournisseur de services pour l'authentification SAML.

https://github.com/nginxinc/njs-prometheus-module

Expose le point de terminaison des métriques Prometheus directement depuis NGINX Plus.

[!TIP] NJS peut également être utilisé avec le serveur d'applications NGINX Unit. En savoir plus sur l'API de contrôle de NGINX Unit et comment définir des appels de fonction avec NJS.

Téléchargement et installation

Suivez ces étapes pour télécharger et installer les binaires Linux précompilés de NGINX et NGINX JavaScript. Vous pouvez également choisir de compiler le module localement à partir du code source.

Provisionnement du dépôt de paquets NGINX

Suivez ce guide pour ajouter le dépôt de paquets officiel de NGINX à votre système et installer NGINX Open Source. Si vous avez déjà NGINX Open Source ou NGINX Plus installé, passez la partie installation de NGINX dans la dernière étape.

Commencer avec NGINX JavaScript

L'utilisation de NJS implique d'activer le module, d'ajouter des fichiers JavaScript avec des fonctions définies et d'invoquer des fonctions exportées dans les fichiers de configuration NGINX.

Vérifiez que NGINX fonctionne

NGINX JavaScript est un module pour NGINX Open Source ou NGINX Plus. Si vous ne l'avez pas encore fait, suivez ces étapes pour installer NGINX Open Source ou NGINX Plus. Une fois installé, assurez-vous que l'instance NGINX fonctionne et est capable de répondre aux requêtes HTTP.

Démarrer NGINX

Émettez la commande suivante pour démarrer NGINX :

sudo nginx

Vérifiez que NGINX répond aux requêtes HTTP

curl -I 127.0.0.1

Vous devriez voir la réponse suivante :

HTTP/1.1 200 OK
Server: nginx/1.25.5

Activer les modules NGINX JavaScript

Une fois installé, l'un ou l'autre (ou les deux) module(s) NJS doit être inclus dans le fichier de configuration NGINX. Sur la plupart des systèmes, le fichier de configuration NGINX se trouve par défaut à /etc/nginx/nginx.conf.

Modifier le fichier de configuration NGINX

sudo vi /etc/nginx/nginx.conf

Activer le chargement dynamique des modules NJS

Utilisez la directive load_module dans le contexte de niveau supérieur ("principal") pour activer l'un ou l'autre (ou les deux) module(s).

load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so;

Notions de base sur l'écriture de fichiers de script .js

Les fichiers de script NJS sont généralement nommés avec une extension .js et placés dans le répertoire /etc/nginx/njs/. Ils se composent généralement de fonctions qui sont ensuite exportées, les rendant disponibles dans les fichiers de configuration NGINX.

Référence des objets, méthodes et propriétés personnalisés

NJS fournit une collection d'objets avec des méthodes et des propriétés associées qui ne font pas partie des définitions ECMAScript. Consultez la référence complète de ces objets et comment ils peuvent être utilisés pour étendre et personnaliser davantage NGINX.

Exemple : Bonjour le monde

Voici un exemple de base "Bonjour le monde".

example.js

La fonction hello dans ce fichier renvoie un code de réponse HTTP 200 OK accompagné de la chaîne "Hello World!", suivie d'un saut de ligne. La fonction est ensuite exportée pour être utilisée dans un fichier de configuration NGINX.

Ajoutez ce fichier au répertoire /etc/nginx/njs :

function hello(r) {
  r.return(200, "Hello world!\n");
}

export default {hello}

nginx.conf

Nous modifions notre configuration NGINX (/etc/nginx/nginx.conf) pour importer le fichier JavaScript et exécuter la fonction dans des circonstances spécifiques.

# Charger le module ngx_http_js_module
load_module modules/ngx_http_js_module.so;

events {}

http {
  # Définir le chemin vers nos fichiers JavaScript njs
  js_path "/etc/nginx/njs/";

  # Importer notre fichier JavaScript dans la variable "main"
  js_import main from http/hello.js;

  server {
    listen 80;

    location / {
      # Exécuter la fonction "hello" définie dans notre fichier JavaScript pour toutes les requêtes HTTP
      # et répondre avec le contenu de notre fonction.
      js_content main.hello;
    }
  }
}

Pour une liste complète des directives njs, consultez les pages de documentation des modules ngx_http_js_module et ngx_stream_js_module.

[!TIP] Une version plus détaillée de cet exemple et d'autres peut être trouvée dans le dépôt officiel njs-examples.

L'interface de ligne de commande NJS (CLI)

NGINX JavaScript s'installe avec un utilitaire d'interface de ligne de commande. L'interface peut être ouverte comme un shell interactif ou utilisée pour traiter la syntaxe JavaScript à partir de fichiers prédéfinis ou d'une entrée standard. Comme l'utilitaire fonctionne indépendamment, les objets spécifiques à NGINX tels que HTTP et Stream ne sont pas disponibles dans son environnement d'exécution.

Exemple d'utilisation de la CLI interactive

$ njs
>> globalThis
global {
  njs: njs {
    version: '0.8.4'
  },
  global: [Circular],
  process: process {
    argv: ['/usr/bin/njs'],
    env: {
      PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
      HOSTNAME: 'f777c149d4f8',
      TERM: 'xterm',
      NGINX_VERSION: '1.25.5',
      NJS_VERSION: '0.8.4',
      PKG_RELEASE: '1~buster',
      HOME: '/root'
    }
  },
  console: {
    log: [Function: native],
    dump: [Function: native],
    time: [Function: native],
    timeEnd: [Function: native]
  },
  print: [Function: native]
}
>>

Exemple d'utilisation de la CLI non interactive

$ echo "2**3" | njs -q
8

Clonage du dépôt GitHub de NGINX JavaScript

Utilisez votre méthode préférée pour cloner le dépôt NGINX JavaScript dans votre répertoire de développement. Consultez Clonage d'un dépôt GitHub pour obtenir de l'aide supplémentaire.

https://github.com/nginx/njs.git

Configurer et construire

Exécutez les commandes suivantes depuis le répertoire racine de votre dépôt cloné :

./configure

Construisez NGINX JavaScript :

make

L'utilitaire devrait maintenant être disponible à <NJS_SRC_ROOT_DIR>/build/njs. Consultez L'interface de ligne de commande NJS (CLI) pour des informations sur l'utilisation.

Clonage du dépôt GitHub de NGINX

Clonez le dépôt de code source NGINX dans un répertoire en dehors du dépôt source NJS cloné précédemment.

https://github.com/nginx/nginx.git

Spécifications techniques de NGINX JavaScript

Les spécifications techniques pour NJS sont identiques à celles de NGINX.

Distributions prises en charge

Consultez Systèmes d'exploitation et plateformes testés pour une liste complète des distributions prises en charge.

Environnements de déploiement pris en charge

Conteneur
Cloud public (AWS, Google Cloud Platform, Microsoft Azure)
Machine virtuelle

Versions NGINX prises en charge

NGINX JavaScript est pris en charge par toutes les versions NGINX Open Source à partir de nginx-1.14 et toutes les versions NGINX Plus à partir de NGINX Plus R15.

Poser des questions, signaler des problèmes et contribuer

Nous vous encourageons à interagir avec nous. Veuillez consulter le guide Contributing pour des informations sur la façon de poser des questions, de signaler des problèmes et de contribuer du code.

Journal des modifications

Consultez notre page de publication pour suivre les mises à jour.

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-njs.