JavaScript SDK

Integrate App Config.json into your Node.js or browser applications with a few lines of code. Real-time sync, type-safe access, and zero-config setup.

💡 Note

The JavaScript SDK supports Node.js 14+, Deno, and all modern browsers. We recommend using a package manager for dependency resolution.

Installation

Add the SDK to your project using your preferred package manager:

Terminal

npm install @appconfig/sdk

Quick Start

Initialize the client, fetch your configuration, and start reacting to live updates:

JavaScript

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

// 1. Initialize with your project token
const config = AppConfig.init({
  projectId: "proj_8f3a9c2d",
  environment: "production",
  apiKey: process.env.AC_SECRET_KEY
});

// 2. Fetch initial configuration
const settings = await config.getConfig("app.database");
console.log(settings.host); // "db.appconfig.json"

// 3. Subscribe to real-time changes
config.watch("app.featureFlags", (update) => {
  if (update.enabled) {
    enableBetaFeatures();
  }
});

API Reference

The SDK exposes a clean, Promise-based API designed for both synchronous and reactive workflows.

AppConfig.init(options)

AppConfig.init(options: InitOptions) -> AppConfigInstance

Creates and returns a new configuration client instance bound to your project.

Parameters

projectIdstringYour unique project identifier

environmentstringTarget env (default: "development")

apiKeystringSecret authentication key

getConfig(path?)

async getConfig(path?: string) -> Record

Fetches the current configuration. If a dot-notation path is provided, it returns only that subtree.

Returns

Promise<T>objectResolved configuration data

watch(path, callback)

watch(path: string, callback: (value: any) => void) -> Unsubscribe

Registers a listener for live updates to a specific configuration key. Returns an unsubscribe function.

Parameters

pathstringDot-notation key to watch

callbackfunctionExecuted on every value change

sync()

async sync() -> void

Forces a manual refresh of all cached configuration values from the App Config.json edge network.

Advanced Configuration

Customize network behavior, caching strategies, and retry logic to match your infrastructure needs.

JavaScript

const client = AppConfig.init({
  projectId: "proj_8f3a9c2d",
  apiKey: process.env.AC_SECRET_KEY,
  options: {
    pollingInterval: 30000, // Fallback polling in ms
    useWebSocket: true,    // Enable live sync
    cache: "memory",      // "memory" | "localStorage" | "none"
    retry: {
      attempts: 3,
      backoff: "exponential"
    }
  }
});

TypeScript Support

The SDK ships with comprehensive TypeScript definitions. Pass a custom type to getConfig<T>() for full autocomplete and type safety:

TypeScript

interface DBConfig {
  host: string;
  port: number;
  poolSize: number;
}

const db = await config.getConfig<DBConfig>("database");
// db.host, db.port are fully typed
connect(db.host, db.port);

⚠️ Type Safety Note

While runtime values are validated against your schema in the App Config.json dashboard, TypeScript types are purely compile-time. Ensure your schema definitions match the dashboard configuration.