Guía rápida de Node.js

En unos minutos tu servicio en Node evaluará feature flags en el propio proceso — sin salto de red por comprobación, sin latencia en tu ruta de petición, un solo sondeo sirviendo a cada petición que atiende tu proceso.

Cero dependencias en tiempo de ejecución: el bloque dependencies del paquete no existe, y así se queda.

1. Instala

El SDK vive en un repositorio público en GitHub — instálalo directamente desde ahí, fijado a la versión publicada:

npm install github:FortressFlag/FortressFlag_SDK_node#v1.0.0

Si omites #v1.0.0, seguirás la rama development en su lugar — útil para probar una corrección, no lo que quieres en producción.

El paquete es solo ESM. En Node 22 y posteriores, el código CommonJS también puede cargarlo con un simple require("@fortressflag/sdk-node").

2. La clave de servidor — un secreto de verdad

Este SDK usa una clave de servidor (ffs_…), y es lo contrario de las claves de cliente que llevan los SDK móviles y web: puede descargar tu ruleset completo, reglas de targeting incluidas. Trátala exactamente como una contraseña de base de datos — una variable de entorno o un gestor de secretos, nunca código, nunca un repositorio, nunca un log. Las dos clases de claves, lado a lado.

3. Arranca el cliente

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

let client;
try {
  client = create({ key: process.env.FF_SERVER_KEY });
} catch (error) {
  // El único sitio en el que el SDK lanza una excepción: una clave mal formada, antes de que nada se sirva.
  console.error(error);
  process.exit(1);
}

await client.start(AbortSignal.timeout(15_000)); // se resuelve con el primer ruleset (o al vencer el plazo)

// ... tu servicio se ejecuta; las comprobaciones de flags son ahora llamadas a funciones en memoria.

start nunca se rechaza — si la primera descarga no puede llegar a tiempo, el cliente sigue intentándolo en segundo plano y quienes te llaman reciben sus respaldos mientras tanto. Y el sondeador nunca mantiene vivo tu proceso: cuando tu código termina, Node sale como siempre.

4. Evalúa un flag

const enabled = client.bool(
  "new-checkout",
  {
    key: "user-42", // tu clave de contexto estable: un id de usuario, un id de sesión — tú eliges
    tags: { cohort: "beta" },
  },
  false, // el respaldo si el flag es desconocido o nunca se descargó nada
);

client.string y client.number funcionan igual. La key del contexto es sobre lo que reparten los rollouts porcentuales — pasa el mismo identificador de forma consistente y cada usuario obtiene una cohorte estable. Son tus datos: el SDK nunca los valida, almacena ni registra.

Eso es todo — tu servicio está evaluando flags localmente. Un cambio en el panel llega a cada proceso en aproximadamente un minuto.

La evaluación nunca falla

bool, string y number siempre responden y nunca lanzan excepciones — un problema con los flags nunca debe tumbar tu servicio. Un proceso reiniciado sirve tus respaldos del punto de llamada hasta que llega su primera descarga (o pon cachePath en la configuración para persistir el último ruleset en un archivo que elijas, y los reinicios se reanudan desde él al instante). Ni siquiera una clave revocada rompe nada: el SDK sigue evaluando con el último ruleset que descargó hasta que le des una clave nueva.

¿Por dónde seguir?

• Cómo llegan los flags a tu app — el plano de servidor, explicado
• Claves — emite, rota y revoca claves ffs_
• Targeting — las reglas que tu servicio está evaluando ahora