> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grainql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Options

> Complete reference for all SDK configuration options

## GrainConfig Interface

All available configuration options when creating a Grain client:

```typescript theme={null}
const grain = createGrainAnalytics({
  // Required
  tenantId: 'your-tenant-id',
  
  // Authentication
  authStrategy: 'NONE',  // or 'SERVER_SIDE', 'JWT'
  secretKey: 'your-secret',  // For SERVER_SIDE
  authProvider: { getToken: () => 'token' },  // For JWT
  
  // User Identification
  userId: 'user_123',
  
  // API Configuration
  apiUrl: 'https://clientapis.grainql.com',
  
  // Event Batching
  batchSize: 50,
  flushInterval: 5000,
  
  // Retry Logic
  retryAttempts: 3,
  retryDelay: 1000,
  
  // Remote Config
  defaultConfigurations: {
    hero_text: 'Welcome'
  },
  configCacheKey: 'grain_config',
  configRefreshInterval: 300000,
  enableConfigCache: true,
  
  // Debugging
  debug: false
});
```

## Required Options

### tenantId

Your unique tenant identifier from Grain. Use the alias shown on your dashboard (not the UUID). Get this from [grainql.com/dashboard](https://grainql.com/dashboard).

```typescript theme={null}
tenantId: 'your-tenant-id'
```

## Authentication Options

### authStrategy

Choose your authentication method:

* `'NONE'` - No authentication (default)
* `'SERVER_SIDE'` - Secret key authentication
* `'JWT'` - JSON Web Token authentication

```typescript theme={null}
authStrategy: 'JWT'
```

### secretKey

Required for `SERVER_SIDE` authentication. Never expose in client code.

```typescript theme={null}
secretKey: process.env.GRAIN_SECRET_KEY
```

### authProvider

Required for `JWT` authentication. Provides tokens for requests.

```typescript theme={null}
authProvider: {
  async getToken() {
    return await auth0.getAccessToken();
  }
}
```

## User Options

### userId

Global user ID for all events. Can be changed with `setUserId()`.

```typescript theme={null}
userId: 'user_123'
```

## API Options

### apiUrl

Custom API endpoint. Defaults to `https://clientapis.grainql.com`.

```typescript theme={null}
apiUrl: 'https://clientapis.grainql.com'
```

Useful for self-hosted or region-specific deployments.

## Batching Options

### batchSize

Number of events to accumulate before sending. Default: `50`.

```typescript theme={null}
batchSize: 100  // Send every 100 events
```

Larger batches = fewer requests but longer delays.

### flushInterval

Milliseconds between automatic flushes. Default: `5000` (5 seconds).

```typescript theme={null}
flushInterval: 10000  // Flush every 10 seconds
```

Set to `0` to disable automatic flushing (manual only).

## Retry Options

### retryAttempts

Number of retry attempts for failed requests. Default: `3`.

```typescript theme={null}
retryAttempts: 5  // Retry up to 5 times
```

### retryDelay

Base delay in milliseconds between retries. Uses exponential backoff. Default: `1000` (1 second).

```typescript theme={null}
retryDelay: 2000  // Start with 2s, then 4s, then 8s
```

## Remote Config Options

### defaultConfigurations

Default values for configurations. Returns immediately, no API call needed.

```typescript theme={null}
defaultConfigurations: {
  hero_text: 'Welcome!',
  button_color: 'blue',
  feature_enabled: 'false'
}
```

Always provide defaults for critical configs.

### configCacheKey

Custom key for localStorage cache. Default: `'grain_config'`.

```typescript theme={null}
configCacheKey: 'my_app_grain_config'
```

Useful if running multiple Grain instances.

### configRefreshInterval

Milliseconds between automatic config refreshes. Default: `300000` (5 minutes).

```typescript theme={null}
configRefreshInterval: 120000  // Refresh every 2 minutes
```

Set to `0` to disable automatic refreshing.

### enableConfigCache

Enable/disable configuration caching. Default: `true`.

```typescript theme={null}
enableConfigCache: false  // Always fetch from API
```

Disable for testing or when cache causes issues.

## Debug Options

### debug

Enable console logging for debugging. Default: `false`.

```typescript theme={null}
debug: true
```

Logs batching, sending, responses, and errors. Disable in production.

## Environment-Specific Configs

Adjust config based on environment:

```typescript theme={null}
const config = {
  tenantId: 'your-tenant-id',
  authStrategy: process.env.NODE_ENV === 'production' ? 'JWT' : 'NONE',
  debug: process.env.NODE_ENV === 'development',
  batchSize: process.env.NODE_ENV === 'production' ? 50 : 10,
  flushInterval: process.env.NODE_ENV === 'production' ? 5000 : 1000
};

const grain = createGrainAnalytics(config);
```

## Performance Tuning

**High-traffic apps**:

```typescript theme={null}
{
  batchSize: 100,  // Larger batches
  flushInterval: 10000,  // Less frequent flushes
  retryAttempts: 5  // More retries
}
```

**Real-time apps**:

```typescript theme={null}
{
  batchSize: 10,  // Smaller batches
  flushInterval: 1000,  // Frequent flushes
  retryAttempts: 2  // Fail fast
}
```

**Serverless functions**:

```typescript theme={null}
{
  batchSize: 1,  // No batching
  flushInterval: 0,  // Manual flush only
  retryAttempts: 1  // No retries (short execution time)
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Performance" icon="gauge" href="/advanced/performance">
    Optimize for your use case
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/advanced/error-handling">
    Handle errors gracefully
  </Card>
</CardGroup>