TypeScript & JavaScript

The @gogreenflags/sdk package targets Node.js and browsers. Use it from TypeScript (recommended) or plain JavaScript; types ship with the package. React helpers are available via gogreenflags/sdk/react.

Installation


npm install @gogreenflags/sdk

Initialization

The @gogreenflags/sdk package uses CommonJS. In TypeScript or CommonJS projects the standard import works directly. For ESM projects ("type": "module" in package.json), use createRequire:


// CommonJS / TypeScript (works out of the box)
const { GoGreenClient } = require('@gogreenflags/sdk');
 
// ESM projects
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const { GoGreenClient } = require('@gogreenflags/sdk');


import { GoGreenClient } from '@gogreenflags/sdk'; // TypeScript with CommonJS moduleResolution
 
const client = new GoGreenClient({
  sdkKey: 'YOUR_SDK_KEY',
  environmentId: 'YOUR_ENV_ID',
  apiBaseUrl: 'https://app.gogreenflags.com',
  streamUrl: 'https://app.gogreenflags.com',
  eventsUrl: 'https://app.gogreenflags.com',
  enableStreaming: true,
  defaultContext: {
    key: 'user-123',
    custom: { plan: 'enterprise' },
  },
});

Configuration Options

Option	Type	Default	Description
`sdkKey`	`string`	required	SDK key from Environment Settings
`environmentId`	`string`	required	Environment ID
`defaultContext`	`EvaluationContext`	required	Default user context
`apiBaseUrl`	`string`	`localhost:8091`	Evaluation API base URL
`streamUrl`	`string`	optional	Streaming service URL
`eventsUrl`	`string`	optional	Events ingestion URL
`enableStreaming`	`boolean`	`false`	Enable real-time SSE updates
`requestTimeout`	`number`	`5000`	HTTP request timeout (ms)
`flushInterval`	`number`	`60000`	Event flush interval (ms)
`offline`	`boolean`	`false`	Offline mode
`bootstrap`	`EvaluationResponse`	`undefined`	Pre-loaded config (skip initial fetch)
`allAttributesPrivate`	`boolean`	`false`	Redact all user attributes
`privateAttributes`	`string[]`	`[]`	Specific attributes to redact
`piiKeyStrategy`	`'hash' \| 'mask' \| 'drop'`	`'hash'`	PII redaction strategy for user key
`piiAttrStrategy`	`'hash' \| 'mask' \| 'drop'`	`'mask'`	PII redaction strategy for attributes
`configRetryMaxAttempts`	`number`	`5`	Max retry attempts for config fetch
`apiBaseUrls`	`string[]`	`undefined`	Multi-region failover URLs
`streamUrls`	`string[]`	`undefined`	Multi-region failover stream URLs

Evaluating Flags


// Simple evaluation
const enabled = client.boolVariation('feature-x', false);
const theme = client.stringVariation('ui-theme', 'light');
const limit = client.numberVariation('rate-limit', 100);
const config = client.jsonVariation('feature-config', {});
 
// Detailed evaluation
const detail = client.boolVariationDetail('feature-x', false);
console.log(detail.value);          // true
console.log(detail.reason);         // "RULE_MATCH"
console.log(detail.variationIndex); // 0
console.log(detail.ruleIndex);      // 1

Tracking Events


// Track custom events for experimentation
client.track('purchase', { revenue: 49.99, currency: 'USD' });

Event Listeners


// Listen for flag changes
client.on('configUpdated', () => {
  console.log('Flags updated!');
});
 
// Listen for errors
client.on('error', (err) => {
  console.error('SDK error:', err);
});

Testing


import { testClient } from '@gogreenflags/sdk';
 
// Create an offline test client
const client = testClient({
  'feature-x': true,
  'ui-theme': 'dark',
  'rate-limit': 50,
});
 
// Use in unit tests — no network calls
const enabled = client.boolVariation('feature-x', false); // returns true

Bootstrap (SSR / Hydration)


// Server: embed config in HTML
const config = await fetchConfig();
res.send(`<script>window.__GOGREEN_BOOTSTRAP__ = ${JSON.stringify(config)}</script>`);
 
// Client: use bootstrap to avoid flash of default values
const client = new GoGreenClient({
  sdkKey: 'YOUR_SDK_KEY',
  environmentId: 'YOUR_ENV_ID',
  defaultContext: { key: 'user-123' },
  bootstrap: window.__GOGREEN_BOOTSTRAP__,
});