Skip to main content

GrainConfig Interface

All available configuration options when creating a Grain client:
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://api.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.
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
authStrategy: 'JWT'

secretKey

Required for SERVER_SIDE authentication. Never expose in client code.
secretKey: process.env.GRAIN_SECRET_KEY

authProvider

Required for JWT authentication. Provides tokens for requests.
authProvider: {
  async getToken() {
    return await auth0.getAccessToken();
  }
}

User Options

userId

Global user ID for all events. Can be changed with setUserId().
userId: 'user_123'

API Options

apiUrl

Custom API endpoint. Defaults to https://api.grainql.com.
apiUrl: 'https://api.grainql.com'
Useful for self-hosted or region-specific deployments.

Batching Options

batchSize

Number of events to accumulate before sending. Default: 50.
batchSize: 100  // Send every 100 events
Larger batches = fewer requests but longer delays.

flushInterval

Milliseconds between automatic flushes. Default: 5000 (5 seconds).
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.
retryAttempts: 5  // Retry up to 5 times

retryDelay

Base delay in milliseconds between retries. Uses exponential backoff. Default: 1000 (1 second).
retryDelay: 2000  // Start with 2s, then 4s, then 8s

Remote Config Options

defaultConfigurations

Default values for configurations. Returns immediately, no API call needed.
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'.
configCacheKey: 'my_app_grain_config'
Useful if running multiple Grain instances.

configRefreshInterval

Milliseconds between automatic config refreshes. Default: 300000 (5 minutes).
configRefreshInterval: 120000  // Refresh every 2 minutes
Set to 0 to disable automatic refreshing.

enableConfigCache

Enable/disable configuration caching. Default: true.
enableConfigCache: false  // Always fetch from API
Disable for testing or when cache causes issues.

Debug Options

debug

Enable console logging for debugging. Default: false.
debug: true
Logs batching, sending, responses, and errors. Disable in production.

Environment-Specific Configs

Adjust config based on environment:
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:
{
  batchSize: 100,  // Larger batches
  flushInterval: 10000,  // Less frequent flushes
  retryAttempts: 5  // More retries
}
Real-time apps:
{
  batchSize: 10,  // Smaller batches
  flushInterval: 1000,  // Frequent flushes
  retryAttempts: 2  // Fail fast
}
Serverless functions:
{
  batchSize: 1,  // No batching
  flushInterval: 0,  // Manual flush only
  retryAttempts: 1  // No retries (short execution time)
}

Next Steps