Saltar a contenido

njs: Módulos dinámicos njs de NGINX

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

  • RedHat Enterprise Linux 7, 8, 9 y 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 y Amazon Linux 2023
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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_js_module.so;

load_module modules/ngx_stream_js_module.so;

Este documento describe nginx-module-njs v0.9.6 lanzado el 03 de marzo de 2026.

Estado del Proyecto: Activo – El proyecto ha alcanzado un estado estable y utilizable y está siendo desarrollado activamente. Soporte Comunitario

Banner de NGINX JavaScript

NGINX JavaScript

NGINX JavaScript, también conocido como NJS, es un módulo dinámico para NGINX que permite extender la funcionalidad incorporada utilizando una sintaxis de JavaScript familiar. El lenguaje NJS es un subconjunto de JavaScript, compatible con ES5 (ECMAScript 5.1 Variante Estricta) con algunas extensiones de ES6 (ECMAScript 6) y versiones más recientes. Consulta compatibilidad para más detalles.

Cómo funciona

NGINX JavaScript se proporciona como dos módulos dinámicos para NGINX (ngx_http_js_module y ngx_stream_js_module) y puede ser añadido a cualquier instalación soportada de NGINX Open Source o NGINX Plus sin necesidad de recompilación.

El módulo NJS permite a los administradores de NGINX: - Añadir controles de acceso y verificaciones de seguridad complejas antes de que las solicitudes lleguen a los servidores upstream - Manipular encabezados de respuesta - Escribir controladores de contenido, filtros y más, de manera flexible y asíncrona.

Consulta ejemplos y nuestros diversos proyectos desarrollados con NJS:

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

Extiende la funcionalidad de NGINX Plus para comunicarse directamente con Proveedores de Identidad compatibles con OIDC, autenticando usuarios y autorizando contenido entregado por NGINX Plus.

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

Implementación de referencia de NGINX Plus como proveedor de servicios para autenticación SAML.

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

Expone el endpoint de métricas de Prometheus directamente desde NGINX Plus.

[!TIP] NJS también puede ser utilizado con el servidor de aplicaciones NGINX Unit. Aprende más sobre la API de Control de NGINX Unit y cómo definir llamadas a funciones con NJS.

Descargando e instalando

Sigue estos pasos para descargar e instalar los binarios de NGINX y NGINX JavaScript precompilados para Linux. También puedes optar por compilar el módulo localmente desde el código fuente.

Provisión del repositorio de paquetes de NGINX

Sigue esta guía para añadir el repositorio oficial de paquetes de NGINX a tu sistema e instalar NGINX Open Source. Si ya tienes NGINX Open Source o NGINX Plus instalado, omite la parte de instalación de NGINX en el último paso.

Comenzando con NGINX JavaScript

El uso de NJS implica habilitar el módulo, añadir archivos de JavaScript con funciones definidas y invocar funciones exportadas en los archivos de configuración de NGINX.

Verificar que NGINX esté en funcionamiento

NGINX JavaScript es un módulo para NGINX Open Source o NGINX Plus. Si no lo has hecho ya, sigue estos pasos para instalar NGINX Open Source o NGINX Plus. Una vez instalado, asegúrate de que la instancia de NGINX esté en funcionamiento y pueda responder a solicitudes HTTP.

Iniciar NGINX

Emite el siguiente comando para iniciar NGINX:

sudo nginx

Verificar que NGINX esté respondiendo a solicitudes HTTP

curl -I 127.0.0.1

Deberías ver la siguiente respuesta: 

HTTP/1.1 200 OK
Server: nginx/1.25.5

Habilitando los módulos de NGINX JavaScript

Una vez instalado, uno (o ambos) de los módulos NJS debe ser incluido en el archivo de configuración de NGINX. En la mayoría de los sistemas, el archivo de configuración de NGINX se encuentra en /etc/nginx/nginx.conf por defecto.

Editar el archivo de configuración de NGINX

sudo vi /etc/nginx/nginx.conf

Habilitar la carga dinámica de módulos NJS

Usa la directiva load_module en el contexto de nivel superior (“principal”) para habilitar uno (o ambos) módulos.

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

Conceptos básicos de escritura de archivos de script .js

Los archivos de script NJS suelen tener una extensión .js y se colocan en el directorio /etc/nginx/njs/. Generalmente están compuestos por funciones que luego son exportadas, haciéndolas disponibles en los archivos de configuración de NGINX.

Referencia de objetos, métodos y propiedades personalizadas

NJS proporciona una colección de objetos con métodos y propiedades asociadas que no son parte de las definiciones de ECMAScript. Consulta la referencia completa de estos objetos y cómo pueden ser utilizados para extender y personalizar aún más NGINX.

Ejemplo: Hola Mundo

Aquí hay un ejemplo básico de "Hola Mundo".

example.js

La función hello en este archivo devuelve un código de estado de respuesta HTTP 200 OK junto con la cadena "Hello World!", seguida de un salto de línea. La función es luego exportada para su uso en un archivo de configuración de NGINX.

Añade este archivo al directorio /etc/nginx/njs:

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

export default {hello}

nginx.conf

Modificamos nuestra configuración de NGINX (/etc/nginx/nginx.conf) para importar el archivo de JavaScript y ejecutar la función bajo circunstancias específicas.

# Cargar el módulo ngx_http_js_module
load_module modules/ngx_http_js_module.so;

events {}

http {
  # Establecer la ruta a nuestros archivos de JavaScript njs
  js_path "/etc/nginx/njs/";

  # Importar nuestro archivo de JavaScript en la variable "main"
  js_import main from http/hello.js;

  server {
    listen 80;

    location / {
      # Ejecutar la función "hello" definida en nuestro archivo de JavaScript en todas las solicitudes HTTP
      # y responder con el contenido de nuestra función.
      js_content main.hello;
    }
  }
}

Para una lista completa de las directivas njs, consulta las páginas de documentación de ngx_http_js_module y ngx_stream_js_module.

[!TIP] Una versión más detallada de este y otros ejemplos se puede encontrar en el repositorio oficial de njs-examples.

La interfaz de línea de comandos (CLI) de NJS

NGINX JavaScript se instala con una utilidad de interfaz de línea de comandos. La interfaz puede abrirse como un shell interactivo o utilizarse para procesar sintaxis de JavaScript desde archivos predefinidos o entrada estándar. Dado que la utilidad se ejecuta de forma independiente, los objetos específicos de NGINX como HTTP y Stream no están disponibles dentro de su tiempo de ejecución.

Ejemplo de uso de la CLI interactiva

$ 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]
}
>>

Ejemplo de uso de la CLI no interactiva

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

Clonando el repositorio de NGINX JavaScript en GitHub

Usando tu método preferido, clona el repositorio de NGINX JavaScript en tu directorio de desarrollo. Consulta Clonando un Repositorio de GitHub para ayuda adicional.

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

Configurar y construir

Ejecuta los siguientes comandos desde el directorio raíz de tu repositorio clonado:

./configure

Construir NGINX JavaScript: 

make

La utilidad debería estar ahora disponible en <NJS_SRC_ROOT_DIR>/build/njs. Consulta La Interfaz de Línea de Comandos (CLI) de NJS para información sobre su uso.

Clonando el repositorio de NGINX en GitHub

Clona el repositorio del código fuente de NGINX en un directorio fuera del repositorio de código fuente de NJS previamente clonado.

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

Especificaciones técnicas de NGINX JavaScript

Las especificaciones técnicas para NJS son idénticas a las de NGINX.

Distribuciones soportadas

Consulta Sistemas Operativos y Plataformas Probadas para una lista completa de distribuciones soportadas.

Entornos de despliegue soportados

  • Contenedor
  • Nube pública (AWS, Google Cloud Platform, Microsoft Azure)
  • Máquina virtual

Versiones de NGINX soportadas

NGINX JavaScript es soportado por todas las versiones de NGINX Open Source a partir de nginx-1.14 y todas las versiones de NGINX Plus a partir de NGINX Plus R15.

Haciendo preguntas, reportando problemas y contribuyendo

Te animamos a interactuar con nosotros. Consulta la guía de Contribución para información sobre cómo hacer preguntas, reportar problemas y contribuir con código.

Registro de cambios

Consulta nuestra página de lanzamientos para mantenerte al tanto de las actualizaciones.

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-njs.