Quickstart de Node.js

Em poucos minutos o seu serviço em Node vai avaliar feature flags in-process — sem salto de rede por verificação, sem latência no caminho das suas requisições, um polling atendendo toda requisição que o seu processo trata.

Zero dependências em runtime: o bloco dependencies do pacote não existe, e continua assim.

1. Instale

O SDK mora em um repositório público no GitHub — instale-o direto de lá, fixado na release:

npm install github:FortressFlag/FortressFlag_SDK_node#v1.0.0

Se você omitir #v1.0.0, vai acompanhar a branch development em vez disso — útil para testar uma correção, não o que você quer em produção.

O pacote é somente ESM. No Node 22 e posteriores, código CommonJS também consegue carregá-lo com um simples require("@fortressflag/sdk-node").

2. A chave de servidor — um segredo de verdade

Este SDK usa uma chave de servidor (ffs_…), e ela é o oposto das chaves de cliente que os SDKs de mobile e web carregam: ela consegue baixar o seu ruleset completo, regras de segmentação incluídas. Trate-a exatamente como uma senha de banco de dados — uma variável de ambiente ou um gerenciador de segredos, nunca código, nunca um repositório, nunca um log. As duas classes de chave, lado a lado.

3. Inicie o cliente

import { create } from "@fortressflag/sdk-node";

let client;
try {
  client = create({ key: process.env.FF_SERVER_KEY });
} catch (error) {
  // O único lugar em que o SDK lança exceção: uma chave malformada, antes de qualquer coisa ser servida.
  console.error(error);
  process.exit(1);
}

await client.start(AbortSignal.timeout(15_000)); // resolve no primeiro ruleset (ou no prazo)

// ... o seu serviço roda; verificações de flag agora são chamadas de função em memória.

start nunca é rejeitado — se a primeira busca não conseguir chegar a tempo, o cliente continua tentando em segundo plano e quem chama recebe os fallbacks enquanto isso. E o poller nunca mantém o seu processo vivo: quando o seu código termina, o Node sai como de costume.

4. Avalie uma flag

const enabled = client.bool(
  "new-checkout",
  {
    key: "user-42", // a sua chave de contexto estável: um id de usuário, um id de sessão — você escolhe
    tags: { cohort: "beta" },
  },
  false, // o fallback se a flag for desconhecida ou nada tiver sido buscado ainda
);

client.string e client.number funcionam do mesmo jeito. A key de contexto é o que os rollouts percentuais usam para distribuir — passe o mesmo identificador de forma consistente e cada usuário recebe uma coorte estável. É dado seu: o SDK nunca valida, armazena nem registra isso em log.

É isso — o seu serviço está avaliando flags localmente. Uma mudança no painel chega a todo processo em cerca de um minuto.

A avaliação nunca falha

bool, string e number sempre respondem e nunca lançam exceção — um problema com flags nunca pode derrubar o seu serviço. Um processo reiniciado serve os fallbacks do ponto de chamada até a primeira busca chegar (ou defina cachePath na configuração para persistir o último ruleset em um arquivo à sua escolha, e os reinícios retomam dele instantaneamente). Nem uma chave revogada quebra nada: o SDK continua avaliando com o último ruleset que baixou até você entregar uma chave nova.

Para onde ir agora

• Como as flags chegam ao seu app — o server plane, explicado
• Chaves — crie, rotacione e revogue chaves ffs_
• Segmentação — as regras que o seu serviço agora está avaliando