confg-sdk

SDK for confg.dev - Config as a Service.

Git is the source of truth. Configs are synced via GitHub Action on push to main, ensuring full history tracking and no uncommitted changes in production.

Installation

npm install confg-sdk

Quick Start

Runtime Client (Read-Only)

import { Confg } from 'confg-sdk'

const confg = new Confg({
  projectId: 'my-project',
  apiKey: process.env.CONFG_API_KEY, // Optional - only needed for protected configs
})

// Read config
const userSchema = await confg.get('entities/user')

// Read with TypeScript type
const config = await confg.get<{ name: string; version: number }>('settings/app')

// List all configs
const paths = await confg.list()

// Check if config exists
const exists = await confg.exists('entities/user')

CLI (Inspection Only)

# Initialize confg.json for GitHub Action
npx confg init

# List all configs in the project
npx confg list

# Get and display a single config
npx confg get entities/user

Syncing Configs

Configs are synced only via GitHub Action on push to main. This ensures:

• Git remains the single source of truth
• Full history tracking of all changes
• No uncommitted/local changes in production
• Code review before config changes go live

Setup GitHub Action

1. Create your config files in a directory (e.g., ./configs/):

configs/
├── entities/
│   ├── user.json
│   └── company.json
└── settings/
    └── app.json

2. Add the workflow to your repo:

# .github/workflows/sync-configs.yml
name: Sync Configs

on:
  push:
    branches: [main]
    paths:
      - 'configs/**'

jobs:
  sync:
    uses: confg/confg-sdk/.github/workflows/sync.yml@main
    with:
      sync-dir: './configs'
      prune: true  # Optional: delete configs not in repo
    secrets:
      CONFG_API_KEY: ${{ secrets.CONFG_API_KEY }}
      CONFG_PROJECT_ID: ${{ secrets.CONFG_PROJECT_ID }}

3. Add secrets in your repo settings:
   • CONFG_API_KEY - Create a key with write permission in confg.dev dashboard
   • CONFG_PROJECT_ID - Your project slug

API Keys

There are two types of API keys:

| Permission | Use Case | |------------|----------| | write | GitHub Action sync - pushes configs from repo to API | | read | Runtime client - reads protected configs (configs with cnfg:auth: true) |

Create separate keys for each use case in the confg.dev dashboard. The write key should only be stored in GitHub Secrets, never in your codebase.

Configuration

confg.json

Optional file for CLI project context:

{
  "projectId": "my-project",
  "syncDir": "./configs"
}

Environment Variables

• CONFG_PROJECT_ID - Project ID (overrides confg.json)
• CONFG_API_KEY - API key for protected configs
• CONFG_BASE_URL - Custom API URL (default: https://i.confg.dev)

Auth Control

Project-level (cnfg.json in configs root)

{
  "auth": true,
  "secureRoutes": ["secrets/*", "internal/*"]
}

File-level

Add "cnfg:auth": true to any config to require API key for reading:

{
  "cnfg:auth": true,
  "apiKey": "sk-secret..."
}

The cnfg:* fields are automatically stripped from responses.

License

MIT