Configuration Options¶

This guide covers all available configuration options for LDK initialization and customization.

Basic Configuration¶

Minimal Setup¶

The simplest way to initialize LDK:

await LDK.initialize(
  baseUrl: 'https://your-strapi-server.com',
);

Complete Configuration¶

Here's a comprehensive example with all available options:

await LDK.initialize(
  // Required
  baseUrl: 'https://your-strapi-server.com',

  // Basic Options
  authToken: 'your-jwt-token', // Optional initial auth token
  enableLogging: true, // Enable HTTP request/response logging
  connectTimeout: Duration(seconds: 30), // Connection timeout
  receiveTimeout: Duration(seconds: 30), // Response timeout

  // V2 Features (all enabled by default)
  enableGraphQL: true, // GraphQL client support
  enableRealtime: true, // WebSocket real-time updates
  enableOfflineStorage: true, // Offline data persistence
  enableIntelligentCache: true, // Multi-strategy caching
  enableEnhancedAuth: true, // Advanced authentication features

  // Cache Configuration
  cacheConfig: {
    'strategies': {
      'posts': {
        'ttl': 300000, // 5 minutes in milliseconds
        'maxSize': 100, // Maximum cached items
        'evictionPolicy': 'lru', // LRU, LFU, FIFO, LIFO
        'refreshOnAccess': true, // Refresh TTL on access
        'backgroundRefresh': true, // Refresh in background
        'autoInvalidate': true, // Auto-invalidate on updates
      },
      'users': {
        'ttl': 600000, // 10 minutes
        'maxSize': 50,
        'evictionPolicy': 'lfu',
      },
    },
  },
);

Configuration Options Reference¶

Core Options¶

Option	Type	Default	Description
`baseUrl`	`String`	Required	Your Strapi server URL
`authToken`	`String?`	`null`	Initial JWT authentication token
`enableLogging`	`bool`	`false`	Enable HTTP request/response logging
`connectTimeout`	`Duration?`	`30s`	Connection timeout duration
`receiveTimeout`	`Duration?`	`30s`	Response receive timeout

V2 Feature Flags¶

Option	Type	Default	Description
`enableGraphQL`	`bool`	`true`	Enable GraphQL client
`enableRealtime`	`bool`	`true`	Enable WebSocket real-time features
`enableOfflineStorage`	`bool`	`true`	Enable offline data persistence
`enableIntelligentCache`	`bool`	`true`	Enable intelligent caching system
`enableEnhancedAuth`	`bool`	`true`	Enable advanced authentication

Cache Configuration¶

The cacheConfig parameter accepts a map with strategy configurations:

cacheConfig: {
  'strategies': {
    'collection-name': {
      'ttl': 300000, // Time to live in milliseconds
      'maxSize': 100, // Maximum number of cached items
      'evictionPolicy': 'lru', // Eviction policy
      'refreshOnAccess': true, // Refresh TTL when accessed
      'backgroundRefresh': false, // Refresh data in background
      'autoInvalidate': true, // Auto-invalidate on mutations
    },
  },
}

Cache Eviction Policies¶

lru (Least Recently Used): Removes least recently accessed items
lfu (Least Frequently Used): Removes least frequently accessed items
fifo (First In, First Out): Removes oldest items first
lifo (Last In, First Out): Removes newest items first

Environment-Specific Configuration¶

Development Configuration¶

await LDK.initialize(
  baseUrl: 'http://localhost:1337', // Local Strapi server
  enableLogging: true, // Enable detailed logging
  connectTimeout: Duration(seconds: 10), // Shorter timeout for dev

  // Enable all features for testing
  enableGraphQL: true,
  enableRealtime: true,
  enableOfflineStorage: true,
  enableIntelligentCache: true,
  enableEnhancedAuth: true,

  // Aggressive caching for development
  cacheConfig: {
    'strategies': {
      'default': {
        'ttl': 60000, // 1 minute for quick testing
        'maxSize': 50,
        'evictionPolicy': 'lru',
      },
    },
  },
);

Production Configuration¶

await LDK.initialize(
  baseUrl: 'https://api.yourapp.com',
  enableLogging: false, // Disable logging in production
  connectTimeout: Duration(seconds: 30),
  receiveTimeout: Duration(seconds: 30),

  // Selective feature enabling based on needs
  enableGraphQL: true,
  enableRealtime: true,
  enableOfflineStorage: true,
  enableIntelligentCache: true,
  enableEnhancedAuth: true,

  // Optimized caching for production
  cacheConfig: {
    'strategies': {
      'posts': {
        'ttl': 900000, // 15 minutes
        'maxSize': 200,
        'evictionPolicy': 'lru',
        'backgroundRefresh': true,
      },
      'users': {
        'ttl': 1800000, // 30 minutes
        'maxSize': 100,
        'evictionPolicy': 'lfu',
      },
      'static-content': {
        'ttl': 3600000, // 1 hour
        'maxSize': 50,
        'evictionPolicy': 'fifo',
      },
    },
  },
);

Testing Configuration¶

await LDK.initialize(
  baseUrl: 'http://localhost:1337',
  enableLogging: false, // Reduce test noise
  connectTimeout: Duration(seconds: 5), // Fast timeouts for tests
  receiveTimeout: Duration(seconds: 5),

  // Disable features that might interfere with tests
  enableRealtime: false, // Avoid WebSocket connections in tests
  enableOfflineStorage: false, // Use in-memory only
  enableIntelligentCache: false, // Predictable behavior
  enableEnhancedAuth: false, // Simpler auth for tests
);

Dynamic Configuration¶

Runtime Configuration Updates¶

You can update certain configurations at runtime:

// Update auth token
LDK.setAuthToken('new-jwt-token');

// Clear auth token
LDK.clearAuthToken();

// Update cache strategies
LDK.instance.cache.setCacheStrategy('posts', CacheStrategy(
  ttl: Duration(minutes: 10),
  maxSize: 150,
  evictionPolicy: EvictionPolicy.lru,
));

Conditional Feature Enabling¶

Enable features based on device capabilities or user preferences:

import 'dart:io';

await LDK.initialize(
  baseUrl: 'https://your-strapi-server.com',

  // Enable real-time only on mobile platforms
  enableRealtime: Platform.isAndroid || Platform.isIOS,

  // Enable offline storage based on storage availability
  enableOfflineStorage: await _hasStoragePermission(),

  // Enable GraphQL for better performance on good connections
  enableGraphQL: await _hasGoodConnection(),
);

Configuration Validation¶

LDK validates your configuration and provides helpful error messages:

try {
  await LDK.initialize(
    baseUrl: '', // Invalid: empty URL
  );
} catch (e) {
  print(e); // LDKConfigurationException: Base URL cannot be empty
}

Common validation errors:

Empty base URL: Provide a valid Strapi server URL
Invalid URL format: Ensure URL includes protocol (http/https)
Conflicting features: Some features require others (e.g., realtime needs GraphQL)

Configuration Best Practices¶

1. Use Environment Variables¶

import 'package:flutter_dotenv/flutter_dotenv.dart';

await dotenv.load();

await LDK.initialize(
  baseUrl: dotenv.env['STRAPI_URL'] ?? 'http://localhost:1337',
  enableLogging: dotenv.env['ENVIRONMENT'] == 'development',
);

2. Feature Detection¶

// Check if features are available before using them
if (LDK.instance.isInitialized) {
  try {
    final graphql = LDK.instance.graphql;
    // GraphQL is available
  } catch (e) {
    // GraphQL not configured, use REST API
  }
}

3. Graceful Degradation¶

// Try advanced features first, fall back to basic ones
try {
  // Try real-time subscription
  final stream = LDK.collection('posts').subscribeToUpdates();
  return StreamBuilder(stream: stream, builder: ...);
} catch (e) {
  // Fall back to polling
  return FutureBuilder(
    future: LDK.collection('posts').get(),
    builder: ...,
  );
}

4. Cache Strategy Selection¶

Choose cache strategies based on data characteristics:

cacheConfig: {
  'strategies': {
    // Frequently accessed, rarely changed
    'categories': {
      'ttl': 3600000, // 1 hour
      'evictionPolicy': 'lfu',
    },

    // Frequently updated
    'posts': {
      'ttl': 300000, // 5 minutes
      'evictionPolicy': 'lru',
      'backgroundRefresh': true,
    },

    // User-specific data
    'user-preferences': {
      'ttl': 1800000, // 30 minutes
      'maxSize': 10, // Small cache
      'evictionPolicy': 'fifo',
    },
  },
}

Troubleshooting Configuration¶

Common Issues¶

1. Connection Timeouts¶

Problem: Requests timing out frequently Solution: Increase timeout values or check network connectivity

await LDK.initialize(
  baseUrl: 'https://your-server.com',
  connectTimeout: Duration(seconds: 60), // Increase timeout
  receiveTimeout: Duration(seconds: 60),
);

2. Memory Issues¶

Problem: App using too much memory Solution: Reduce cache sizes or disable caching for large datasets

cacheConfig: {
  'strategies': {
    'large-collection': {
      'maxSize': 20, // Reduce cache size
      'ttl': 60000, // Shorter TTL
    },
  },
}

3. Feature Conflicts¶

Problem: Features not working as expected Solution: Check feature dependencies

// Real-time requires GraphQL
enableGraphQL: true, // Required for real-time
enableRealtime: true,

// Intelligent cache requires offline storage
enableOfflineStorage: true, // Required for caching
enableIntelligentCache: true,

Debug Configuration¶

Enable debug mode to see configuration details:

await LDK.initialize(
  baseUrl: 'https://your-server.com',
  enableLogging: true, // Shows HTTP requests
);

// Check what features are enabled
print('GraphQL enabled: ${LDK.instance.graphql != null}');
print('Cache enabled: ${LDK.instance.cache != null}');
print('Realtime enabled: ${LDK.instance.realtime != null}');

Next Steps¶

Migration Guide: Upgrade from v1.x to v2.x
Authentication: Configure authentication
Caching Strategies: Deep dive into caching
Performance Optimization: Optimize your configuration

Next: Migration Guide →