0
# @storybook/core-common
1

2
@storybook/core-common is a deprecated compatibility shim package that provides framework-agnostic API utilities for Storybook. It serves as a bridge for legacy code that relied on the `@storybook/core-common` package name while the underlying implementation has been consolidated into the main Storybook package. All functionality is re-exported from `storybook/internal/common`.
3

4
## Package Information
5

6
- **Package Name**: @storybook/core-common
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @storybook/core-common`
10
- **Peer Dependencies**: `storybook ^8.2.0 || ^8.3.0-0 || ^8.4.0-0 || ^8.5.0-0 || ^8.6.0-0`
11

12
## Core Imports
13

14
```typescript
15
import { loadMainConfig, getStorybookInfo, cache } from "@storybook/core-common";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { loadMainConfig, getStorybookInfo, cache } = require("@storybook/core-common");
22
```
23

24
Import specific utilities:
25

26
```typescript
27
import { 
28
  normalizeStories, 
29
  FileSystemCache, 
30
  createFileSystemCache 
31
} from "@storybook/core-common";
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { 
38
  loadMainConfig, 
39
  getStorybookInfo, 
40
  normalizeStories,
41
  cache 
42
} from "@storybook/core-common";
43

44
// Load Storybook configuration
45
const mainConfig = await loadMainConfig({ 
46
  configDir: '.storybook' 
47
});
48

49
// Get project information
50
const projectInfo = await getStorybookInfo(
51
  packageJson, 
52
  '.storybook'
53
);
54

55
// Normalize story entries
56
const stories = normalizeStories([
57
  './src/**/*.stories.@(js|jsx|ts|tsx)'
58
], { configDir: '.storybook' });
59

60
// Use file system cache
61
const cachedData = await cache.get('my-key');
62
await cache.set('my-key', { some: 'data' });
63
```
64

65
## Architecture
66

67
@storybook/core-common is organized around several key functional areas:
68

69
- **Configuration Management**: Loading, validating, and processing Storybook configurations
70
- **Preset System**: Managing preset configurations and addon resolution  
71
- **File System Caching**: High-performance caching with TTL and namespace support
72
- **Story Processing**: Normalizing story entries and generating story metadata
73
- **Environment Handling**: Processing environment variables and CLI options
74
- **Package Management**: Interfacing with npm/yarn/pnpm for dependency operations
75
- **Utility Functions**: Path handling, template generation, logging, and development workflow support
76

77
## Capabilities
78

79
### Configuration Management
80

81
Core utilities for loading, validating, and processing Storybook configuration files. Essential for any tool that needs to understand Storybook project structure.
82

83
```typescript { .api }
84
function loadMainConfig(options: { 
85
  configDir: string; 
86
  noCache?: boolean; 
87
}): Promise<StorybookConfigRaw>;
88

89
function getStorybookInfo(
90
  packageJson: PackageJson, 
91
  configDir?: string
92
): Promise<CoreCommon_StorybookInfo>;
93

94
function validateFrameworkName(frameworkName: string): void;
95
```
96

97
[Configuration Management](./configuration.md)
98

99
### Preset System
100

101
Powerful preset loading and application system for managing Storybook addons and framework configurations. Supports both functional and declarative preset definitions.
102

103
```typescript { .api }
104
function getPresets(
105
  presets: PresetConfig[], 
106
  storybookOptions: InterPresetOptions
107
): Promise<Presets>;
108

109
function loadAllPresets(options: {
110
  corePresets: PresetConfig[];
111
  overridePresets: PresetConfig[];
112
  isCritical?: boolean;
113
}): Promise<Presets>;
114

115
interface Presets {
116
  apply<T>(extension: string, config?: T, args?: unknown): Promise<T>;
117
}
118
```
119

120
[Preset System](./presets.md)
121

122
### File System Caching
123

124
High-performance file system caching with namespace support, TTL, and both sync/async operations. Built for development workflow optimization.
125

126
```typescript { .api }
127
class FileSystemCache {
128
  constructor(options?: {
129
    ns?: string;
130
    prefix?: string; 
131
    hash_alg?: string;
132
    basePath?: string;
133
    ttl?: number;
134
  });
135
  
136
  get<T>(key: string): Promise<T | undefined>;
137
  getSync<T>(key: string): T | undefined;
138
  set<T>(key: string, value: T): Promise<void>;
139
  setSync<T>(key: string, value: T): void;
140
}
141

142
function createFileSystemCache(options?: object): FileSystemCache;
143

144
declare const cache: FileSystemCache;
145
```
146

147
[File System Caching](./caching.md)
148

149
### Story Processing
150

151
Story entry normalization and metadata generation for Storybook's story indexing system. Handles glob patterns, directory mapping, and story ID generation.
152

153
```typescript { .api }
154
function normalizeStories(
155
  entries: StoriesEntry[], 
156
  options: NormalizeOptions
157
): NormalizedStoriesEntry[];
158

159
function getStoryId(
160
  data: StoryIdData, 
161
  options: GetStoryIdOptions
162
): string;
163

164
function getStoryTitle(options: {
165
  specifier: { title?: string; component?: string };
166
  filepath: string;
167
  normalizedPath: string;
168
}): string;
169
```
170

171
[Story Processing](./story-processing.md)
172

173
### Environment & CLI Utilities
174

175
Environment variable processing, temporary file management, and CLI utility functions for Storybook development tools.
176

177
```typescript { .api }
178
function loadEnvs(options?: { production?: boolean }): Record<string, string>;
179

180
function temporaryDirectory(options?: { prefix?: string }): Promise<string>;
181

182
function temporaryFile(options?: { 
183
  name?: string; 
184
  extension?: string; 
185
}): Promise<string>;
186

187
function parseList(str: string): string[];
188
```
189

190
[Environment & CLI Utilities](./environment-cli.md)
191

192
### Package Management
193

194
JavaScript package manager abstraction layer supporting npm, yarn, and pnpm. Provides unified interface for dependency management operations.
195

196
```typescript { .api }
197
abstract class JsPackageManager {
198
  abstract getInstallArgs(): string[];
199
  abstract getRunCommand(): string;
200
  abstract getRunArgs(): string[];
201
  abstract getAddArgs(installAsDevDependencies: boolean): string[];
202
  abstract type: 'npm' | 'yarn1' | 'yarn2' | 'pnpm';
203
}
204

205
class JsPackageManagerFactory {
206
  static getPackageManager(options?: { 
207
    force?: 'npm' | 'yarn1' | 'yarn2' | 'pnpm' 
208
  }): JsPackageManager;
209
}
210
```
211

212
[Package Management](./package-management.md)
213

214
### Text Processing & Formatting
215

216
Template interpolation, code formatting, and logging utilities for development tools and code generation.
217

218
```typescript { .api }
219
function interpolate(template: string, bindings: Record<string, any>): string;
220

221
function formatFileContent(filePath: string, content: string): Promise<string>;
222

223
function commandLog(message: string): {
224
  success: (message: string) => void;
225
  error: (message: string) => void;
226
};
227
```
228

229
[Text Processing & Formatting](./text-processing.md)
230

231
## Core Types
232

233
```typescript { .api }
234
interface StorybookConfig {
235
  stories: PresetValue<StoriesEntry[]>;
236
  addons?: Preset[];
237
  framework?: Preset;
238
  core?: PresetValue<CoreConfig>;
239
  typescript?: PresetValue<TypescriptOptions>;
240
  features?: PresetValue<Record<string, boolean>>;
241
}
242

243
interface Options extends LoadOptions, CLIOptions, BuilderOptions {
244
  presets: Presets;
245
  build?: TestBuildConfig;
246
}
247

248
interface CoreCommon_StorybookInfo {
249
  version: string;
250
  framework: string;
251
  frameworkPackage: string;
252
  renderer: string;
253
  rendererPackage: string;
254
  configDir?: string;
255
  mainConfig?: string;
256
  previewConfig?: string;
257
  managerConfig?: string;
258
}
259

260
type PresetConfig = string | {
261
  name: string;
262
  options?: unknown;
263
};
264

265
interface StoriesEntry {
266
  directory: string;
267
  files: string;
268
  titlePrefix?: string;
269
}
270

271
type PackageJson = {
272
  name?: string;
273
  version?: string;
274
  dependencies?: Record<string, string>;
275
  devDependencies?: Record<string, string>;
276
  [key: string]: any;
277
};
278
```