Pular para conteúdo

njs: Módulos dinâmicos njs do NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_js_module.so;

load_module modules/ngx_stream_js_module.so;

Este documento descreve o nginx-module-njs v0.9.6 lançado em 03 de março de 2026.

Status do Projeto: Ativo – O projeto alcançou um estado estável e utilizável e está sendo desenvolvido ativamente. Suporte da Comunidade

Banner do NGINX JavaScript

NGINX JavaScript

NGINX JavaScript, também conhecido como NJS, é um módulo dinâmico para NGINX que permite a extensão da funcionalidade embutida usando uma sintaxe familiar de JavaScript. A linguagem NJS é um subconjunto do JavaScript, compatível com ES5 (ECMAScript 5.1 Strict Variant) com algumas extensões de ES6 (ECMAScript 6) e versões mais recentes. Veja compatibilidade para mais detalhes.

Como funciona

NGINX JavaScript é fornecido como dois módulos dinâmicos para NGINX (ngx_http_js_module e ngx_stream_js_module) e pode ser adicionado a qualquer instalação suportada do NGINX Open Source ou NGINX Plus sem recompilação.

O módulo NJS permite que administradores do NGINX: - Adicionem controles de acesso e verificações de segurança complexas antes que as solicitações cheguem aos servidores upstream - Manipulem cabeçalhos de resposta - Escrevam manipuladores de conteúdo, filtros e muito mais de forma flexível e assíncrona!

Veja exemplos e nossos vários projetos desenvolvidos com NJS:

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

Estende a funcionalidade do NGINX Plus para se comunicar diretamente com provedores de identidade compatíveis com OIDC, autenticando usuários e autorizando o conteúdo entregue pelo NGINX Plus.

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

Implementação de referência do NGINX Plus como um provedor de serviços para autenticação SAML.

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

Expõe o endpoint de métricas do Prometheus diretamente do NGINX Plus.

[!TIP] NJS também pode ser usado com o servidor de aplicativos NGINX Unit. Saiba mais sobre a API de Controle do NGINX Unit e como definir chamadas de função com NJS.

Baixando e instalando

Siga estas etapas para baixar e instalar os binários Linux pré-compilados do NGINX e do NGINX JavaScript. Você também pode optar por compilar o módulo localmente a partir do código-fonte.

Provisionando o repositório de pacotes do NGINX

Siga este guia para adicionar o repositório de pacotes oficial do NGINX ao seu sistema e instalar o NGINX Open Source. Se você já tem o NGINX Open Source ou NGINX Plus instalado, pule a parte de instalação do NGINX na última etapa.

Começando com o NGINX JavaScript

O uso do NJS envolve habilitar o módulo, adicionar arquivos JavaScript com funções definidas e invocar funções exportadas nos arquivos de configuração do NGINX.

Verifique se o NGINX está em execução

O NGINX JavaScript é um módulo para o NGINX Open Source ou NGINX Plus. Se você ainda não fez isso, siga estas etapas para instalar o NGINX Open Source ou NGINX Plus. Uma vez instalado, certifique-se de que a instância do NGINX está em execução e capaz de responder a solicitações HTTP.

Iniciando o NGINX

Emita o seguinte comando para iniciar o NGINX:

sudo nginx

Verifique se o NGINX está respondendo a solicitações HTTP

curl -I 127.0.0.1

Você deve ver a seguinte resposta: 

HTTP/1.1 200 OK
Server: nginx/1.25.5

Habilitando os módulos JavaScript do NGINX

Uma vez instalado, pelo menos um (ou ambos) os módulos NJS devem ser incluídos no arquivo de configuração do NGINX. Na maioria dos sistemas, o arquivo de configuração do NGINX está localizado em /etc/nginx/nginx.conf por padrão.

Edite o arquivo de configuração do NGINX

sudo vi /etc/nginx/nginx.conf

Habilite o carregamento dinâmico dos módulos NJS

Use a diretiva load_module no contexto de nível superior (“main”) para habilitar um (ou ambos) os módulos.

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

Noções básicas sobre como escrever arquivos de script .js

Os arquivos de script NJS são tipicamente nomeados com a extensão .js e colocados no diretório /etc/nginx/njs/. Eles geralmente são compostos por funções que são então exportadas, tornando-as disponíveis nos arquivos de configuração do NGINX.

Referência de objetos, métodos e propriedades personalizados

O NJS fornece uma coleção de objetos com métodos e propriedades associadas que não fazem parte das definições do ECMAScript. Veja a referência completa para esses objetos e como eles podem ser usados para estender e personalizar ainda mais o NGINX.

Exemplo: Olá Mundo

Aqui está um exemplo básico de "Olá Mundo".

example.js

A função hello neste arquivo retorna um código de status de resposta HTTP 200 OK junto com a string "Hello World!", seguida de uma quebra de linha. A função é então exportada para uso em um arquivo de configuração do NGINX.

Adicione este arquivo ao diretório /etc/nginx/njs:

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

export default {hello}

nginx.conf

Modificamos nossa configuração do NGINX (/etc/nginx/nginx.conf) para importar o arquivo JavaScript e executar a função em circunstâncias específicas.

# Carregar o módulo ngx_http_js_module
load_module modules/ngx_http_js_module.so;

events {}

http {
  # Definir o caminho para nossos arquivos JavaScript njs
  js_path "/etc/nginx/njs/";

  # Importar nosso arquivo JavaScript na variável "main"
  js_import main from http/hello.js;

  server {
    listen 80;

    location / {
      # Executar a função "hello" definida em nosso arquivo JavaScript em todas as solicitações HTTP
      # e responder com o conteúdo de nossa função.
      js_content main.hello;
    }
  }
}

Para uma lista completa de diretivas njs, consulte as páginas de documentação do ngx_http_js_module e ngx_stream_js_module.

[!TIP] Uma versão mais detalhada deste e de outros exemplos pode ser encontrada no repositório oficial njs-examples.

A interface de linha de comando (CLI) do NJS

O NGINX JavaScript é instalado com uma utilidade de interface de linha de comando. A interface pode ser aberta como um shell interativo ou usada para processar sintaxe JavaScript a partir de arquivos pré-definidos ou entrada padrão. Como a utilidade é executada de forma independente, objetos específicos do NGINX, como HTTP e Stream, não estão disponíveis dentro de seu tempo de execução.

Exemplo de uso da CLI interativa

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

Exemplo de uso da CLI não interativa

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

Clonando o repositório do NGINX JavaScript no GitHub

Usando seu método preferido, clone o repositório do NGINX JavaScript em seu diretório de desenvolvimento. Veja Clonando um Repositório do GitHub para ajuda adicional.

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

Configurar e compilar

Execute os seguintes comandos a partir do diretório raiz do seu repositório clonado:

./configure

Compile o NGINX JavaScript: 

make

A utilidade deve agora estar disponível em <NJS_SRC_ROOT_DIR>/build/njs. Veja A Interface de Linha de Comando (CLI) do NJS para informações sobre o uso.

Clonando o repositório do NGINX no GitHub

Clone o repositório do código-fonte do NGINX em um diretório fora do repositório de código-fonte do NJS previamente clonado.

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

Especificações técnicas do NGINX JavaScript

As especificações técnicas para o NJS são idênticas às do NGINX.

Distribuições suportadas

Veja Sistemas Operacionais e Plataformas Testados para uma lista completa de distribuições suportadas.

Ambientes de implantação suportados

  • Contêiner
  • Nuvem pública (AWS, Google Cloud Platform, Microsoft Azure)
  • Máquina virtual

Versões do NGINX suportadas

O NGINX JavaScript é suportado por todas as versões do NGINX Open Source a partir do nginx-1.14 e todas as versões do NGINX Plus a partir do NGINX Plus R15.

Fazendo perguntas, relatando problemas e contribuindo

Incentivamos você a se envolver conosco. Consulte o guia de Contribuição para informações sobre como fazer perguntas, relatar problemas e contribuir com código.

Registro de alterações

Veja nossa página de lançamentos para acompanhar as atualizações.

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-njs.