JavaScript & Node.js SDK

Official client library for integrating App Config.json into your JavaScript and Node.js applications. Supports synchronous initialization, real-time updates, environment-aware fallbacks, and full TypeScript definitions.

Installation

Install the SDK via npm, yarn, or pnpm:

terminal

npm install @appconfig/sdk
# or
yarn add @appconfig/sdk
# or
pnpm add @appconfig/sdk

For browser environments via CDN:

html

<script src="https://cdn.appconfig.json/sdk/v3/appconfig.min.js"></script>

Quick Start

Initialize the client with your project ID and environment. Configuration is fetched automatically on import.

javascript

import { AppConfig } from "@appconfig/sdk";

// Initialize (async)
const config = await AppConfig.init({
  projectId: "proj_9x2k1m",
  environment: process.env.NODE_ENV || "development",
  token: process.env.APP_CONFIG_TOKEN
});

// Access values
const dbHost = config.get("database.host");
const featureFlags = config.get("features.beta_ui", false); // fallback

Node.js Runtime

Optimized for server-side applications with built-in clustering support, graceful degradation, and automatic restart detection.

javascript // server.js

import express from "express";
import { AppConfig } from "@appconfig/sdk";

const app = express();
const config = await AppConfig.init({ /* ... */});

// Listen for hot-reloads without downtime
config.on("change", (key, newVal, oldVal) => {
  console.log(`Config updated: ${key} → ${newVal}`);
  // Apply changes dynamically
  if (key === "rate_limit") {
    expressRateLimiter.setOptions({ max: newVal });
  }
});

app.listen(config.get("server.port", 3000));

Browser / Frontend Usage

Lightweight bundle (~8KB gzipped). Designed for SPAs, feature flags, and UI personalization.

javascript // app.js

import { AppConfig } from "@appconfig/sdk/browser";

const config = await AppConfig.init({
  projectId: "proj_9x2k1m",
  environment: "production",
  syncInterval: 30000, // poll every 30s
  useLocalStorage: true
});

// React-friendly usage
function FeatureToggle() {
  const isBetaEnabled = config.get("features.beta_ui", false);
  return isBetaEnabled ? <NewDashboard /> : <ClassicDashboard />;
}

Configuration Options

Customize the SDK behavior using the initialization options:

Option	Type	Default	Description
projectId	string	Required	Your unique project identifier from the dashboard
environment	string	"production"	Target environment (dev, staging, production, custom)
token	string	""	API token for server-side auth. Optional for browser
syncInterval	number	60000	Polling interval in milliseconds (set to 0 for manual only)
useLocalStorage	boolean	false	Cache config in localStorage for offline resilience
fetchTimeout	number	5000	Maximum time to wait for config fetch before fallback

Environment Variables

For security, never hardcode tokens. Use environment variables or secret managers:

.env

APP_CONFIG_PROJECT_ID=proj_9x2k1m
APP_CONFIG_TOKEN=ac_live_x8K2...pQ9
APP_CONFIG_ENV=production

Event Handlers

The SDK emits events for configuration lifecycle management:

javascript

config.on("ready", () => console.log("Config loaded"));
config.on("change", (key, newVal, oldVal) => { /* ... */ });
config.on("error", (err) => console.error("Sync failed", err));
config.on("fallback", (key, defaultValue) => {
  console.warn(`Using fallback for ${key}`);
});

// Remove listeners when cleaning up
config.off("change", handlerFn);

Caching Strategy

By default, the SDK uses an in-memory cache. Enable useLocalStorage for frontend apps to survive hard refreshes. Cache headers are automatically handled by the SDK based on your environment's TTL settings.

Troubleshooting

401 Unauthorized: Verify your APP_CONFIG_TOKEN matches the environment.
Empty values on startup: Check network connectivity and fetchTimeout. Use fallback values during init.
Changes not reflecting: Ensure syncInterval is not set to 0, or call config.refresh() manually.
SSR Hydration mismatch: Initialize SDK on the server, pass config to client via state or data attributes.