0
# Persistent Caching
1
2
Advanced caching functionality using the browser's Cache API for persistent SVG storage across browser sessions. This enables faster loading times and offline support for cached SVG content.
3
4
## Capabilities
5
6
### Cache Provider Setup
7
8
Enables persistent caching by wrapping your application with the cache provider. This activates browser Cache API integration for all InlineSVG components.
9
10
```typescript { .api }
11
/**
12
* Provider component that enables persistent SVG caching using browser Cache API
13
* @param children - React components to wrap with cache context
14
* @param name - Custom cache name (default: 'react-inlinesvg')
15
*/
16
declare const CacheProvider: React.FC<{
17
children: React.ReactNode;
18
name?: string;
19
}>;
20
```
21
22
**Usage Example:**
23
24
```typescript
25
import { createRoot } from "react-dom/client";
26
import CacheProvider from "react-inlinesvg/provider";
27
import App from "./App";
28
29
createRoot(document.getElementById("root")!).render(
30
<CacheProvider name="my-app-svgs">
31
<App />
32
</CacheProvider>
33
);
34
```
35
36
### Cache Store Access
37
38
Direct access to the global cache store for advanced cache management and introspection.
39
40
```typescript { .api }
41
import { cacheStore } from "react-inlinesvg";
42
43
/**
44
* Global cache store instance with both in-memory and persistent storage
45
*/
46
interface CacheStore {
47
/** Cache initialization status - false until Cache API is ready */
48
readonly isReady: boolean;
49
50
/**
51
* Register callback for cache ready state
52
* @param callback - Function to call when cache is ready
53
*/
54
onReady(callback: () => void): void;
55
56
/**
57
* Retrieve SVG content from cache or fetch if not cached
58
* @param url - SVG URL to retrieve
59
* @param fetchOptions - Optional fetch configuration
60
* @returns Promise resolving to SVG content string
61
*/
62
get(url: string, fetchOptions?: RequestInit): Promise<string>;
63
64
/**
65
* Store SVG content in cache
66
* @param url - URL key for the cached content
67
* @param data - Storage item with content and status
68
*/
69
set(url: string, data: StorageItem): void;
70
71
/**
72
* Check if URL is cached and successfully loaded
73
* @param url - URL to check
74
* @returns True if URL is cached with 'loaded' status
75
*/
76
isCached(url: string): boolean;
77
78
/**
79
* Get all cached URLs
80
* @returns Array of cached URL strings
81
*/
82
keys(): string[];
83
84
/**
85
* Get all cache entries as key-value pairs
86
* @returns Array of objects with URL keys and StorageItem values
87
*/
88
data(): Array<Record<string, StorageItem>>;
89
90
/**
91
* Remove specific URL from cache (both memory and persistent)
92
* @param url - URL to remove from cache
93
*/
94
delete(url: string): Promise<void>;
95
96
/**
97
* Clear all cached content (both memory and persistent)
98
*/
99
clear(): Promise<void>;
100
}
101
102
interface StorageItem {
103
/** SVG content as string */
104
content: string;
105
/** Current loading/processing status */
106
status: Status;
107
}
108
109
type Status = 'idle' | 'loading' | 'loaded' | 'failed' | 'ready' | 'unsupported';
110
```
111
112
**Usage Examples:**
113
114
```typescript
115
import { cacheStore } from "react-inlinesvg";
116
117
// Wait for cache to be ready
118
cacheStore.onReady(() => {
119
console.log("Cache is ready");
120
});
121
122
// Check if URL is cached
123
if (cacheStore.isCached("https://example.com/icon.svg")) {
124
console.log("Icon is already cached");
125
}
126
127
// Get cache statistics
128
console.log(`Cached URLs: ${cacheStore.keys().length}`);
129
console.log("Cache data:", cacheStore.data());
130
131
// Clear cache on user logout
132
async function clearUserSession() {
133
await cacheStore.clear();
134
console.log("Cache cleared");
135
}
136
137
// Remove specific cached item
138
async function removeCachedIcon(url: string) {
139
await cacheStore.delete(url);
140
console.log(`Removed ${url} from cache`);
141
}
142
```
143
144
### Global Window Configuration
145
146
Browser environment configuration for cache behavior, set via window globals before components initialize. These globals are automatically detected when using CacheProvider.
147
148
```typescript { .api }
149
/**
150
* Global window interface extensions for cache configuration
151
*/
152
declare global {
153
interface Window {
154
/** Custom cache name for browser Cache API storage */
155
REACT_INLINESVG_CACHE_NAME?: string;
156
/** Enable persistent caching using browser Cache API */
157
REACT_INLINESVG_PERSISTENT_CACHE?: boolean;
158
}
159
}
160
```
161
162
**Configuration Example:**
163
164
```typescript
165
// Configure before importing react-inlinesvg
166
if (typeof window !== 'undefined') {
167
window.REACT_INLINESVG_CACHE_NAME = 'my-custom-cache';
168
window.REACT_INLINESVG_PERSISTENT_CACHE = true;
169
}
170
171
import InlineSVG from "react-inlinesvg";
172
```
173
174
## Caching Behavior
175
176
### Automatic Caching
177
178
By default, all SVG requests are cached in memory when `cacheRequests={true}` (default). This provides immediate performance benefits for repeated SVG usage within a session.
179
180
### Persistent Storage
181
182
When `CacheProvider` is used or `REACT_INLINESVG_PERSISTENT_CACHE` is enabled:
183
184
1. **Cache API Detection**: Checks for browser Cache API support
185
2. **Cache Opening**: Opens named cache storage
186
3. **Request Interception**: Intercepts SVG fetch requests
187
4. **Storage**: Stores successful responses in both memory and persistent cache
188
5. **Retrieval**: Serves from persistent cache on subsequent visits
189
190
### Cache Limitations
191
192
- **Browser Support**: Requires browsers with Cache API support (modern browsers)
193
- **Storage Quotas**: Subject to browser storage limitations
194
- **HTTPS Requirement**: Cache API typically requires HTTPS in production
195
- **Cache Eviction**: Browsers may evict cached content under storage pressure
196
197
### Cache Strategy
198
199
1. **Check Memory**: First checks in-memory cache for immediate access
200
2. **Check Persistent**: Falls back to persistent cache if memory miss
201
3. **Network Fetch**: Fetches from network if not in any cache
202
4. **Dual Storage**: Stores successful fetches in both memory and persistent cache
203
5. **Error Handling**: Gracefully falls back to memory-only if persistent cache fails