Tggl Client SDK

Common errors

• TypeError: client.isActive is not a function

  cause Attempting to call the `isActive` method, which was removed in `tggl-client` v2.0.0.
  fix Update your code to use the `get` method with a default boolean value instead, e.g., `client.get('feature-name', false)`.

• Argument of type 'undefined' is not assignable to parameter of type 'string | boolean | number | null | Record<string, any>'

  cause Calling the `get` method without providing a required default value as the second argument (for client-side) or third argument (for server-side with context). This became mandatory in `tggl-client` v2.0.0.
  fix Provide a default value for the flag, e.g., `client.get('feature-name', true)` or `localClient.get(context, 'feature-name', 'default_value')`.

• ERR_REQUIRE_ESM

  cause Attempting to import `tggl-client` using CommonJS `require()` syntax in an environment configured for ESM, or when the package's primary entry point is ESM-only.
  fix Use ESM `import` statements (e.g., `import { TgglClient } from 'tggl-client';`) and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`). If running in Node.js, ensure your environment supports ESM.

• Error: Tggl client is not ready after Xms

  cause The `waitReady()` method timed out, indicating an issue with fetching flags from the Tggl API (e.g., incorrect API key, network issues, or service unavailability).
  fix Verify your `apiKey` is correct and has the necessary permissions. Check network connectivity to `tggl.io` (or your configured `baseUrl`). Review Tggl's status page or logs for potential service outages or errors. Ensure firewalls are not blocking access.

Warnings

• breaking Version 2.0.0 introduced significant breaking changes: the `isActive` method was removed entirely, and the `get` method now requires a default value as a mandatory argument. This change enforces best practices, preventing code from relying on a flag's existence and instead promoting graceful fallbacks.
  Fix: Replace any calls to `client.isActive('flag-name')` with `client.get('flag-name', false)` or similar, and ensure all `client.get('flag-name')` calls are updated to `client.get('flag-name', defaultValue)`.
• breaking Version 3.0.0 was a complete rewrite, focusing on reliability and fault tolerance. While the core API (`get` method) remained largely consistent with v2, internal mechanisms changed (e.g., `ky` for HTTP requests), and API simplifications might affect advanced usage patterns or custom integrations. The SDK now requires Node.js >=20.0.0.
  Fix: Review the v3 release notes and documentation for any changes to client configuration or behavior. Ensure your Node.js environment meets the `>=20.0.0` requirement. Verify all peer dependencies are correctly installed if using built-in storages.
• gotcha It's crucial to distinguish between `TgglClient` (for client-side environments like browsers or React Native) and `TgglLocalClient` (for server-side Node.js applications). Using the wrong client type can lead to incorrect flag evaluations, performance issues, or security vulnerabilities (e.g., exposing server API keys on the client).
  Fix: Always use `TgglClient` with a client API key in frontend applications and `TgglLocalClient` with a server API key in backend applications. `TgglLocalClient` also requires a storage mechanism (e.g., `StaticStorage`, `PostgresStorage`, `RedisStorage`).
• gotcha The `waitReady()` method is asynchronous and must be awaited before attempting to retrieve flag values. If `get()` is called before the client is ready, it may return default values prematurely or encounter errors, as flags might not have been fetched yet.
  Fix: Always `await client.waitReady()` immediately after client initialization to ensure that the initial set of flags has been loaded before any `get()` calls are made. This is essential for reliable flag evaluation.

Install

• npm install tggl-client npm
• yarn add tggl-client yarn
• pnpm add tggl-client pnpm

Imports

• TgglClient
  wrong:

  import TgglClient from 'tggl-client'

  correct:

  import { TgglClient } from 'tggl-client'

  Used for client-side applications (browsers, React Native) requiring a client API key. It is a named export.
• TgglLocalClient
  wrong:

  const { TgglLocalClient } = require('tggl-client')

  correct:

  import { TgglLocalClient } from 'tggl-client'

  Used for server-side Node.js applications. While CJS might work in some setups, ESM import is the modern and recommended approach, especially with Node.js >=20. It is a named export.
• StaticStorage

  import { StaticStorage } from 'tggl-client'

  Used for server-side clients to provide a basic, in-memory storage solution for flags. Other storage options like PostgresStorage and RedisStorage are also named exports.

Quickstart

This quickstart demonstrates the initialization and usage of both TgglClient (for client-side) and TgglLocalClient (for server-side) to evaluate feature flags with different contexts and built-in storage options.

import { TgglClient, TgglLocalClient, StaticStorage } from 'tggl-client';

async function runFeatureFlagExample() {
  // It's highly recommended to use environment variables for API keys in production
  const clientApiKey = process.env.TGGL_CLIENT_API_KEY ?? 'TGGL_CLIENT_KEY_XXX';
  const serverApiKey = process.env.TGGL_SERVER_API_KEY ?? 'TGGL_SERVER_KEY_YYY';

  // --- Client-side usage example (e.g., browser, React Native) ---
  console.log("\n--- Initializing TgglClient (Client-side) ---");
  const client = new TgglClient({
    apiKey: clientApiKey,
    initialContext: { userId: 'browser-user-123', plan: 'free' },
  });

  try {
    await client.waitReady(); // Wait for initial flags to be fetched
    if (client.get('enable-dark-mode', false)) {
      console.log('Client: Dark mode is ENABLED for this user!');
    } else {
      console.log('Client: Dark mode is DISABLED or not found, using default.');
    }

    const welcomeMessage = client.get('welcome-banner-text', 'Hello there!');
    console.log(`Client: Welcome message: "${welcomeMessage}"`);

  } catch (error) {
    console.error("Error with TgglClient initialization or flag evaluation:", error);
  }

  // --- Server-side usage example (e.g., Node.js backend) ---
  console.log("\n--- Initializing TgglLocalClient (Server-side) ---");
  // For production, consider PostgresStorage or RedisStorage with proper configuration
  const storage = new StaticStorage(); 
  const localClient = new TgglLocalClient({
    apiKey: serverApiKey,
    storage, // Pass the storage instance
    refreshInterval: 60000, // Refresh flags from Tggl API every minute
  });

  try {
    await localClient.waitReady(); // Wait for initial flags to be fetched

    const serverContext = { userId: 'server-user-456', environment: 'production' };
    if (localClient.get(serverContext, 'new-api-endpoint', false)) {
      console.log('Server: Using new API endpoint for this context!');
    } else {
      console.log('Server: Using old API endpoint.');
    }

    const featureVariant = localClient.get({ userId: 'another-user-789' }, 'feature-x-variant', 'control');
    console.log(`Server: 'feature-x-variant' for 'another-user-789' is: ${featureVariant}`);

  } catch (error) {
    console.error("Error with TgglLocalClient initialization or flag evaluation:", error);
  } finally {
    // Important: Stop background processes for local client when done (e.g., on server shutdown)
    localClient.stopReporting?.(); 
    localClient.stopRefreshing?.();
  }
}

runFeatureFlagExample();