Quickstart Node.js

In pochi minuti il tuo servizio Node valuterà i feature flag in-process — nessun salto di rete per controllo, nessuna latenza nel percorso delle tue richieste, un solo poll che serve ogni richiesta gestita dal tuo processo.

Zero dipendenze a runtime: il blocco dependencies del pacchetto non esiste, e resta così.

1. Installa

L’SDK vive in un repository pubblico su GitHub — installalo direttamente da lì, fissato alla release:

npm install github:FortressFlag/FortressFlag_SDK_node#v1.0.0

Se ometti #v1.0.0, seguirai invece il branch development — comodo per provare un fix, non quello che vuoi in produzione.

Il pacchetto è solo ESM. Su Node 22 e successivi, anche il codice CommonJS può caricarlo con un semplice require("@fortressflag/sdk-node").

2. La chiave server — un segreto vero e proprio

Questo SDK usa una chiave server (ffs_…), ed è l’opposto delle chiavi client che gli SDK mobile e web portano con sé: può scaricare il tuo ruleset completo, regole di targeting incluse. Trattala esattamente come la password di un database — una variabile d’ambiente o un secret manager, mai il codice, mai un repository, mai un log. Le due classi di chiavi, fianco a fianco.

3. Avvia il client

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

let client;
try {
  client = create({ key: process.env.FF_SERVER_KEY });
} catch (error) {
  // L'unico punto in cui l'SDK lancia un'eccezione: una chiave malformata, prima che qualsiasi cosa venga servita.
  console.error(error);
  process.exit(1);
}

await client.start(AbortSignal.timeout(15_000)); // si risolve al primo ruleset (o alla scadenza)

// ... il tuo servizio gira; i controlli dei flag ora sono chiamate di funzione in memoria.

start non viene mai rifiutata — se il primo fetch non riesce ad arrivare in tempo, il client continua a riprovare in background e nel frattempo i tuoi chiamanti ricevono i loro fallback. E il poller non tiene mai in vita il tuo processo: quando il tuo codice finisce, Node esce come al solito.

4. Valuta un flag

const enabled = client.bool(
  "new-checkout",
  {
    key: "user-42", // la tua chiave di contesto stabile: un id utente, un id sessione — scegli tu
    tags: { cohort: "beta" },
  },
  false, // il fallback se il flag è sconosciuto o non è mai stato scaricato nulla
);

client.string e client.number funzionano allo stesso modo. La key del contesto è ciò su cui i rollout percentuali fanno il bucketing — passa lo stesso identificatore in modo coerente e ogni utente riceve una coorte stabile. Sono dati tuoi: l’SDK non li valida, memorizza o registra mai.

Fatto — il tuo servizio sta valutando i flag in locale. Una modifica nella dashboard raggiunge ogni processo entro circa un minuto.

La valutazione non fallisce mai

bool, string e number rispondono sempre e non lanciano mai eccezioni — un problema con i flag non deve mai buttare giù il tuo servizio. Un processo riavviato serve i fallback dei tuoi punti di chiamata finché non arriva il primo fetch (oppure imposta cachePath nella configurazione per persistere l’ultimo ruleset in un file a tua scelta, e i riavvii riprendono da lì all’istante). Nemmeno una chiave revocata rompe qualcosa: l’SDK continua a valutare con l’ultimo ruleset scaricato finché non gli consegni una nuova chiave.

Prossimi passi

• Come i flag raggiungono la tua app — il piano server, spiegato
• Chiavi — genera, ruota e revoca le chiavi ffs_
• Targeting — le regole che il tuo servizio sta ora valutando