Caching

The SDK implements a multi-layer caching strategy to provide optimal performance and offline-first experiences.

Cache Architecture

Components are cached in three layers:

Layer	Speed	Persistence	Description
Memory	<1ms	Until app restart	In-memory Map for instant access
AsyncStorage	~10ms	Survives restarts	Persistent storage with optional TTL
Network	~200ms	Fresh from server	API fetch when cache is empty/expired

Cache Flow

Request Component ↓ In Memory? ───Yes───► Return instantly │ No ↓ In AsyncStorage? ───Yes───► Load to memory → Return │ No ↓ Fetch from API ───Success───► Save to both caches → Return │ Fail ↓ Show error / fallback

Cache Configuration

TSX

initDPage({
  projectId: 'my-project',
  apiToken: 'xxx',
  cache: {
    enabled: true,        // Enable caching (default: true)
    ttl: 3600000,         // 1 hour TTL (default: 0 = no expiry)
    namespace: '@dpage:', // Key prefix (default: '@dpage:')
  },
});

Cache Management

Clear Cache

TSX

import { clearCache } from '@dpage-ai/react-native-dpage';

// Clear all cached components
await clearCache();

// Clear specific component
await clearCache({ name: 'ProductCard' });

// Clear by project
await clearCache({ projectId: 'my-project' });

// Clear specific component in specific project
await clearCache({ name: 'ProductCard', projectId: 'my-project' });

Get Cache Statistics

TSX

import { getCacheStats } from '@dpage-ai/react-native-dpage';

const stats = await getCacheStats();
console.log(`Cached: ${stats.count} components`);
console.log('Keys:', stats.keys);

// Filter by project
const projectStats = await getCacheStats('my-project');

Preloading

Preload components at app startup for instant display when needed:

App.tsx

import { preloadComponents, preloadComponent } from '@dpage-ai/react-native-dpage';

// In your app initialization
async function bootstrap() {
  // Preload multiple components
  const result = await preloadComponents([
    'ProductCard',
    'UserProfile',
    'CheckoutForm',
  ]);
  
  console.log(`Loaded: ${result.loaded}, Failed: ${result.failed}`);
}

// Or preload a single component
await preloadComponent('PromoBanner');

Pro Tip

Preload critical components during app startup to ensure instant display when users navigate to them.

Force Refresh

Bypass cache and fetch fresh content from the API:

TSX

import { refreshComponent } from '@dpage-ai/react-native-dpage';

// Force refresh a component
await refreshComponent('ProductCard');

// With specific project
await refreshComponent('ProductCard', 'my-project');

Offline Support

Once components are cached, they work completely offline:

Offline Ready

Components loaded from cache work without network connectivity. Use preloadComponents to cache critical components before users go offline.

Cache TTL (Time-to-Live)

Configure cache expiration to automatically fetch fresh content:

TSX

// Set 5 minute TTL
initDPage({
  cache: {
    ttl: 1000 * 60 * 5, // 5 minutes
  },
});

// Set 1 hour TTL
initDPage({
  cache: {
    ttl: 1000 * 60 * 60, // 1 hour
  },
});

// No expiry (default)
initDPage({
  cache: {
    ttl: 0, // Never expires
  },
});

Best Practices

✅

Preload critical components

Call preloadComponents at app startup for components users will see immediately.

✅

Set appropriate TTL

Configure TTL based on how frequently your content changes.

✅

Use namespace for multi-app

If multiple apps share AsyncStorage, use different namespaces.

✅

Clear cache on logout

If components contain user-specific content, clear cache on logout.

Debugging Cache

Enable debug logging to see cache operations:

TSX

initDPage({
  logLevel: 'debug', // Shows cache hits, misses, writes
});

// Console output:
// [DynamicComponentCache] Cache hit: ProductCard
// [DynamicComponentCache] Cache miss: NewComponent
// [DynamicComponentCache] Cache write: NewComponent