0
# Caching System
1

2
Intelligent caching system for manager builds and configurations to improve build performance by avoiding unnecessary rebuilds when configuration and files haven't changed.
3

4
## Capabilities
5

6
### Manager Cache Usage
7

8
Checks if a cached manager build can be reused based on configuration and file modification times.
9

10
```typescript { .api }
11
/**
12
 * Check if cached manager build can be reused
13
 * @param cacheKey - Unique key identifying the cache entry
14
 * @param options - Storybook configuration options with cache provider
15
 * @param managerConfig - Current webpack configuration for comparison
16
 * @returns Promise resolving to true if cache can be used, false otherwise
17
 */
18
function useManagerCache(
19
  cacheKey: string,
20
  options: Options,
21
  managerConfig: Configuration
22
): Promise<boolean>;
23

24
interface Options {
25
  /** Cache provider for storing/retrieving cached data */
26
  cache: CacheProvider;
27
  /** Path to Storybook configuration directory */
28
  configDir: string;
29
  /** Other Storybook options */
30
  [key: string]: any;
31
}
32

33
interface CacheProvider {
34
  /** Retrieve cached value by key */
35
  get(key: string): Promise<string>;
36
  /** Store value with key */
37
  set(key: string, value: string): Promise<void>;
38
  /** Check if cache entry exists */
39
  fileExists(key: string): boolean;
40
  /** Remove cache entry */
41
  remove(key: string): Promise<void>;
42
}
43
```
44

45
**Usage Examples:**
46

47
```typescript
48
import { useManagerCache } from "@storybook/manager-webpack5/utils/manager-cache";
49

50
const cacheKey = `managerConfig-webpack5@${storybookVersion}`;
51
const canUseCache = await useManagerCache(cacheKey, options, webpackConfig);
52

53
if (canUseCache) {
54
  console.log('Using cached manager build');
55
  // Skip build process
56
} else {
57
  console.log('Cache miss, rebuilding manager');
58
  // Proceed with build
59
}
60
```
61

62
### Cache Invalidation Logic
63

64
The cache system checks several factors to determine if a cached build is valid:
65

66
1. **Configuration Comparison**: Compares current webpack configuration with cached configuration using JSON serialization
67
2. **File Modification Times**: Checks modification times of all files in the config directory
68
3. **Ignored Files**: Automatically ignores certain files that don't affect the manager build:
69
   - `main.(m)js|ts` - Already handled separately
70
   - `preview.(m)js|ts` - Only affects preview, not manager
71
   - `preview-head.html` - Only affects preview, not manager
72

73
### Clear Manager Cache
74

75
Removes cached manager build data when cache invalidation is needed.
76

77
```typescript { .api }
78
/**
79
 * Remove cached manager build data
80
 * @param cacheKey - Unique key identifying the cache entry to remove
81
 * @param options - Storybook configuration options with cache provider
82
 * @returns Promise resolving to true if cache was cleared, false if no cache existed
83
 */
84
function clearManagerCache(cacheKey: string, options: Options): Promise<boolean>;
85
```
86

87
**Usage Examples:**
88

89
```typescript
90
import { clearManagerCache } from "@storybook/manager-webpack5/utils/manager-cache";
91

92
// Clear cache when configuration changes significantly
93
const wasCleared = await clearManagerCache(cacheKey, options);
94

95
if (wasCleared) {
96
  console.log('Cleared cached manager configuration');
97
} else {
98
  console.log('No cached configuration to clear');
99
}
100
```
101

102
### Cache Key Generation
103

104
Cache keys are typically generated using a combination of:
105

106
- Manager configuration type (e.g., "managerConfig")
107
- Webpack version identifier
108
- Storybook version number
109

110
**Example:**
111

112
```typescript
113
const packageFile = await findUp('package.json', { cwd: __dirname });
114
const { version: storybookVersion } = await fs.readJSON(packageFile);
115
const cacheKey = `managerConfig-webpack5@${storybookVersion}`;
116
```
117

118
## Cache Storage Format
119

120
The cache stores data in the following format:
121

122
```
123
{timestamp}_{serialized_config}
124
```
125

126
Where:
127
- `timestamp`: ISO timestamp of when the cache was created
128
- `serialized_config`: JSON-serialized webpack configuration (excluding the cache property)
129

130
## Performance Benefits
131

132
The caching system provides significant performance improvements:
133

134
- **Configuration Reuse**: Avoids webpack configuration generation when nothing has changed
135
- **Build Skipping**: Can skip entire build process when using prebuilt manager or cached builds
136
- **Selective Invalidation**: Only rebuilds when relevant files have actually changed
137
- **Version Awareness**: Automatically invalidates cache when Storybook version changes
138

139
## Integration with Other Systems
140

141
The caching system integrates with:
142

143
- **Prebuilt Manager**: Works alongside prebuilt manager detection to choose the fastest option
144
- **Development Server**: Supports cache during development for faster startup
145
- **CI/CD**: Enables faster builds in continuous integration environments
146
- **File Watching**: Coordinates with file watchers to invalidate cache when files change