Last Updated: 1/27/2026

Configuration

Configure the SDK for your environment.

Environment Variables


# .env file
EXAMPLE_API_KEY=sk_live_abc123
EXAMPLE_API_URL=https://api.example.com
EXAMPLE_TIMEOUT=30000
EXAMPLE_DEBUG=false

:::warning Never commit .env files to version control. Add .env to your .gitignore. :::

Configuration Object


import { createClient, type ClientConfig } from '@example/sdk';
 
const config: ClientConfig = {
  // Required
  apiKey: process.env.EXAMPLE_API_KEY!,
 
  // Optional with defaults
  apiUrl: 'https://api.example.com',
  timeout: 30000,
  retries: 3,
  debug: false,
 
  // Advanced options
  hooks: {
    beforeRequest: (req) => {
      console.log(`Requesting: ${req.url}`);
      return req;
    },
    afterResponse: (res) => {
      console.log(`Response: ${res.status}`);
      return res;
    },
  },
};
 
const client = createClient(config);

Configuration Options

Option	Type	Default	Description
`apiKey`	`string`	Required	Your API key
`apiUrl`	`string`	`https://api.example.com`	Base URL
`timeout`	`number`	`30000`	Timeout in ms
`retries`	`number`	`3`	Max retry attempts
`debug`	`boolean`	`false`	Enable logging

:::info All durations are in milliseconds. Use 30000 for 30 seconds. :::

Validation


import { validateConfig, ConfigError } from '@example/sdk';
 
try {
  validateConfig(config);
} catch (error) {
  if (error instanceof ConfigError) {
    console.error('Config errors:', error.issues);
    // [{ path: 'apiKey', message: 'Required' }]
  }
}

:::tip Run validation at startup to catch configuration issues early. :::

Environment-Specific Config


const config: ClientConfig = {
  apiKey: process.env.EXAMPLE_API_KEY!,
 
  // Different URLs per environment
  apiUrl: process.env.NODE_ENV === 'production'
    ? 'https://api.example.com'
    : 'https://sandbox.api.example.com',
 
  // More verbose in development
  debug: process.env.NODE_ENV !== 'production',
};

:::note The sandbox environment has rate limits and test data only. :::