Migration Guide

Identify Configuration Sources

Run our CLI scanner to automatically discover configuration files, environment variables, and hardcoded values across your codebase.

appconfig scan ./my-project --output audit.json
# Output: Found 142 keys across 8 environments
# Secrets detected: 3 | Hardcoded configs: 11 | Duplicates: 5

Review audit.json to understand dependencies, deprecation warnings, and environment-specific overrides before proceeding.

Define Your Configuration Schema

App Config.json enforces JSON schemas to prevent invalid deployments. Map your legacy keys to our structured format.

Use the dashboard's Schema Builder to generate a validation rule set, or upload your audit.json for auto-mapping.

Install & Initialize

Add the SDK to your application. It runs as a lightweight sidecar process or in-process library depending on your runtime.

npm install @appconfig/json-sdk

import { AppConfig } from '@appconfig/json-sdk';

const config = new AppConfig({
  projectId: 'proj_8x92kd',
  environment: process.env.NODE_ENV || 'development',
  fallback: './local-config.json',
  pollInterval: 5000
});

// Start listening for real-time updates
config.subscribe((key, value) => {
  console.log(`[Config] ${key} updated to ${value}`);
});

Initialize early in your app lifecycle. The SDK caches configurations locally and syncs on boot, ensuring fast cold starts.

Staging Verification

Before touching production, validate your migration in a sandbox environment. Use the CLI diff tool to compare expected vs actual configs.

appconfig diff --env staging
✓ database.connection.host matches
✓ retries.max_attempts matches
⚠ flags.beta_ui has environment override
Run `appconfig validate --strict` to enforce schema compliance.

Run your full integration test suite. The SDK provides a config.snapshot() method to verify runtime state matches dashboard definitions.

Phased Rollout & Rollback

Deploy using our recommended shadow sync pattern:

1. Deploy new code with SDK pointing to appconfig.json but keep legacy configs active as fallback
2. Enable shadowMode: true in SDK config to sync without overriding
3. Monitor logs for sync success rates (>99.5% recommended)
4. Flip shadowMode: false to activate live sync
5. Verify health checks, then decommission legacy config files/secrets

If anomalies are detected, revert by setting SDK_OVERRIDE=true in your deployment manifest. All changes are versioned and reversible within 30 days.