Exportando e Importando um programa

As modificações de programa implementadas no editor do Node-RED são automaticamente salvas ao se clicar em . Para verificar isto, basta fechar a aba do navegador e abrir outra aba novamente no Node-RED e constatará que seu código está lá.

Porém, pode ser que você deseja executar seu programa em outra instância do Node-RED, ou simplesmente manter um back-up. Nestes casos, é possível exportar seu código em formato JSON.

Para exportar seu programa, vá no menu na parte superior-direita e clique em export, abrindo assim a janela de Export nodes. É possível especificar para salvar apenas um conjunto de nós, de flows, ou todos os flows implementados. É possível escolher duas formas de exportação na parte inferior desta janela: (i) copiar o conteúdo do JSON do programa para a memória de transferência (i.e., Ctrl+C); ou (ii) baixar como um arquivo .json.

Para importar um programa salvo no Node-RED, vá no menu na parte superior-direita e clique em import. Na janela Import nodes que abrir, você pode importar seu programa de duas maneiras: (i) colando o conteúdo do JSON do programa na área designada; (ii) fazendo upload do arquivo .json do seu programa.

Funções customizadas

O Node-RED permite criar funções customizadas em JavaScript através do bloco function. Nele, é possível entrar com uma ou várias mensagens, tratá-las de forma programática e gerar uma mensagem de saída.

Clique 2x sobre o nó function para abrir a janela Edit function node que permite configurar este bloco.

Esta janela possui as opções:

• Name: Permite definir um nome para a função que será exibido como o nome do bloco no flow.
• Setup: permite alterar parâmetros da função, como definir o número de mensagens de saída (outputs), importar módulos javascript externos, etc.
• É possível habilitar (enable) ou desabilitar (disable) a função no botão na parte inferior desta janela. Enquanto em disable, O bloco continuará existindo no flow, porém seus algoritmos não serão executados.

É possível criar três tipos de código que possuem diferentes ciclos de execução:

• On Start: Código executado uma única vez ao se clicar em Deploy ou quando o Node-RED é iniciado. Muito útil para inicializações de variáveis, definir constantes, etc.
• On Message: Código callback da entrada, que é executado toda vez que uma mensagem é injetada no nó. Recebe como parâmetro a variável msg.
• On Stop: Código executado uma única vez quando o nó está sendo removido, quando um nodo Deploy é realizado ou quando o Node-RED é desligado. É muito útil para realizar limpezas de memória, definir valores seguros para saídas, fechar conexão com banco de dados, etc.

Uma vez escrito o código desejado, clique em Done para salvar as alterações. Lembre-se de clicar em Deploy para que as alterações sejam compiladas e executadas.

Acessando a mensagem de entrada

O algoritmo definido em On Message é executado toda vez que uma mensagem é injetada no bloco. Este tipo de execução condicionada a um evento é comumente denominado de callback.

A mensagem injetada no nó é disponibilizada para o código interno na variável msg. Ou seja, a variável denominada msg é reservada e seu conteúdo é o JSON da mensagem que aciononou o callback.

Pode-se então acessar o conteúdo de msg como objetos, ou elementos de um dicionário, utilizando o . (ponto). Por exemplo, veja um algoritmo que salva os valores do tópico e do payload da mensagem injetada no bloco de função em variáveis auxiliares:

let auxTopic = msg.topic;
let auxPayload = msg.payload;

A variável msg pode ser escrita diretamente através de atribuições usando o operador =. Como exemplo, o algoritmo abaixo altera o conteúdo de payload da msg originalmente injetada no bloco.

msg.payload = msg.payload + 1;

Retornos do bloco de função

Há algumas maneiras de fazer com que este bloco de função injete mensagens em sua(s) linha(s) de saída.

Independente do método utilizado, lembre-se sempre que as mensagens nas linhas devem ser obrigatoriamente objetos JSON. Tentar enviar outro tipo de dado gera erros de execução.

Retorno simples

O primeiro método é utilizando o método return que, além de enviar o objeto na saída do bloco de função, causa a interrupção do código em execução.

Por exemplo, veja o código abaixo que testa o conteúdo de payload que chega e retorna um novo JSON em função deste:

if (msg.payload == 1){
    return {"payload": 'O retorno é 1'}
} else if (msg.payload == 2) {
    return {"payload": 'O retorno é 2'}
} else {
    return {"payload": 'O retorno é qualquer outra coisa'}
}

let a = 2; // Esta linha de código nunca seria executada

node.send

Há também uma maneira de injetar objetos na linha de saída do bloco de função sem para a execução de seu código. Para isso, utiliza-se o método node.send().

Veja por exemplo o código abaixo que roda um loop em função do número que chega no payload de entrada e publica a contagem a cada iteração, enviando ao fim uma mensagem de finalização.

let i = 0;
for (let i = 0; i < msg.payload; i++) {
    node.send({"payload": `Contagem atual: ${i}`})
}
return {"payload": "Fim da execução"}

Múltiplas saídas

É possível também configurar diversas saídas em um mesmo bloco de função. Para isto, dê 2x cliques no bloco de função, clique na aba Setup e defina a quantidade de saídas desejadas em Outputs. Ao clicar em Done, você notará que o bloco de função agora possui mais de uma saída.

Agora, o return ou node.send devem receber um array de JSONs de tamanho igual à quantidade de saídas configurada neste bloco. A ordem dos elementos no array é respectiva à ordem de cima para baixo das saídas que aparecem no bloco de função.

Como exemplo, veja um código que envia três JSON na saída do bloco de função:

node.send([
            {"payload": "Eu sairei na primeira saída"},
            { "payload": "Eu sairei na segunda saída" },
            { "payload": "Eu sairei na terceira saída" }
        ]
);

Perceba que não é estritamente necessário enviar objetos em todas as saídas sempre ao mesmo tempo. Para isto, no array de saída, popule somente as saídas que deseja enviar objetos e, para as demais, envie null. Por exemplo:

node.send([
            null,
            { "payload": "Eu serei enviado sozinho na segunda saída"},
            null
        ]
);

Com outro exemplo, o código a seguir recebe um número aleatório do payload de entrada e faz seu roteamento entre uma das duas saídas em função do valor recebido.

if (msg.payload <= 0.5) {
    node.send([msg, null]);
} else {
    node.send([null, msg]);
}

Trabalhando com Timestamps

Um timestamp é uma representação numérica de um instante no tempo. No Node-RED (assim como em JavaScript e na grande maioria dos sistemas computacionais modernos) o timestamp é expresso como o número de milissegundos decorridos desde 1º de janeiro de 1970 às 00:00

Por exemplo, o valor 1778006413 representa exatamente:

terça-feira, 05 de maio de 2026 às 18:40:00 UTC

Essa representação é conveniente para armazenamento, transmissão e cálculos temporais, pois é apenas um número inteiro. A conversão para um formato legível por humanos fica a cargo do código que o processa.

Obtendo o Timestamp atual no Node-RED

O nó inject possui a opção nativa de injetar o timestamp atual. Para isso, configure o campo msg.payload com o tipo timestamp. Ao disparar o nó, msg.payload receberá um valor numérico inteiro similar a 1744574400000.

Dentro de um bloco function, um objeto Date com o momento atual pode ser obtido com:

let data = new Date();

Representações do Timestamp

Um mesmo instante pode ser representado de diversas formas. A tabela abaixo mostra as principais, todas obtidas a partir do objeto Date:

Veja o código abaixo que demonstra todas as representações a partir de um timestamp recebido no payload:

let data = new Date();

msg.payload = {
    timestamp_ms:   data.getTime(),
    iso_utc:        data.toISOString(),
    local_string:   data.toString(),
    data_local:     data.toLocaleDateString('pt-BR', { timeZone: 'America/Sao_Paulo' }),
    hora_local:     data.toLocaleTimeString('pt-BR', { timeZone: 'America/Sao_Paulo' }),
    completo_local: data.toLocaleString('pt-BR',     { timeZone: 'America/Sao_Paulo' })
};

return msg;

Apresentando o Timestamp em formato humano

Para exibir a data em um formato mais descritivo — como "segunda-feira, 14 de abril de 2025" — utilize o método toLocaleDateString() com opções de formatação:

let data = new Date();

msg.payload = data.toLocaleDateString('pt-BR', {
    weekday: 'long',
    day: 'numeric',
    month: 'long',
    year: 'numeric'
});

return msg;

As principais opções de configuração do toLocaleDateString() são:

Para incluir o horário na string, basta adicionar hour, minute e second às opções:

let data = new Date(msg.payload);

msg.payload = data.toLocaleString('pt-BR', {
    weekday: 'long',
    day: 'numeric',
    month: 'long',
    year: 'numeric',
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit'
});
// Exemplo: "segunda-feira, 14 de abril de 2025 às 09:30:00"

return msg;

Acessando e modificando componentes individuais da data

O objeto Date do JavaScript permite ler e escrever cada componente da data separadamente. Os métodos seguem o padrão get<Componente>() para leitura e set<Componente>() para escrita, e operam no fuso horário local do sistema:

Exemplo: lendo componentes individuais

let data = new Date();

msg.payload = {
    ano:            data.getFullYear(),
    mes:            data.getMonth() + 1, // +1 para corrigir a base zero
    dia:            data.getDate(),
    dia_da_semana:  data.getDay(),       // 0 = domingo
    hora:           data.getHours(),
    minuto:         data.getMinutes(),
    segundo:        data.getSeconds()
};

return msg;

Exemplo: alterando somente o dia do mês

let data = new Date();

data.setDate(1); // altera somente o dia para o primeiro do mês

msg.payload = data.getTime(); // retorna o novo timestamp
return msg;

Exemplo: avançando a data em N dias

O objeto Date trata automaticamente os estouro de mês e ano. Portanto, somar dias ao dia atual funciona mesmo ao cruzar o final de um mês:

let diasParaAvancar = 10;
let data = new Date();

data.setDate(data.getDate() + diasParaAvancar);

msg.payload = data.getTime();
return msg;

Trabalhando com fusos horários (GMT/UTC)

O objeto Date armazena o instante em UTC internamente. Os métodos get*() e set*() operam no fuso horário local do servidor onde o Node-RED está sendo executado. Para trabalhar explicitamente em UTC, utilize as variantes com o sufixo UTC:

let data = new Date();

msg.payload = {
    hora_local: data.getHours(),     // hora no fuso local do servidor
    hora_utc:   data.getUTCHours(),  // hora em UTC
    dia_local:  data.getDate(),
    dia_utc:    data.getUTCDate()
};

return msg;

Exemplo: convertendo para outro fuso horário na formatação

Para exibir a data em um fuso específico — por exemplo, o horário de Brasília (America/Sao_Paulo) — passe a opção timeZone ao formatar:

let data = new Date();

msg.payload = data.toLocaleString('pt-BR', {
    timeZone: 'America/Sao_Paulo',
    weekday: 'long',
    day: 'numeric',
    month: 'long',
    year: 'numeric',
    hour: '2-digit',
    minute: '2-digit',
    timeZoneName: 'short'
});
// Exemplo: "segunda-feira, 14 de abril de 2025 às 09:30 GMT-3"

return msg;

Exemplo: calculando o offset UTC do fuso local

let data = new Date();

// getTimezoneOffset() retorna a diferença em MINUTOS (positivo para trás de UTC)
let offsetMinutos = data.getTimezoneOffset();
let offsetHoras   = -(offsetMinutos / 60); // invertido: -3 = GMT-3

msg.payload = `Offset local: UTC${offsetHoras >= 0 ? '+' : ''}${offsetHoras}`;
// Exemplo no horário de Brasília: "Offset local: UTC-3"

return msg;

Realizando cálculos com Timestamps

Como timestamps são apenas números, operações aritméticas funcionam diretamente sobre eles. As constantes abaixo são úteis para conversões:

const MS_POR_SEGUNDO = 1000;
const MS_POR_MINUTO  = 60 * MS_POR_SEGUNDO;    //       60.000 ms
const MS_POR_HORA    = 60 * MS_POR_MINUTO;     //    3.600.000 ms
const MS_POR_DIA     = 24 * MS_POR_HORA;       //   86.400.000 ms

Exemplo: calculando a diferença entre duas datas

let dataInicio = new Date('2025-01-01').getTime();
let dataFim    = new Date().getTime();

let diferencaMs   = dataFim - dataInicio;
let diferencaDias = Math.floor(diferencaMs / (1000 * 60 * 60 * 24));

msg.payload = `Dias desde 01/01/2025: ${diferencaDias}`;
return msg;

Exemplo: verificando se uma data já passou

let dataLimite = new Date('2025-12-31T23:59:59').getTime();
let agora      = Date.now();

if (agora > dataLimite) {
    msg.payload = 'Prazo expirado';
} else {
    let diasRestantes = Math.ceil((dataLimite - agora) / (1000 * 60 * 60 * 24));
    msg.payload = `Faltam ${diasRestantes} dias para o prazo`;
}

return msg;