0
# Storybook CSF Tools
1

2
Storybook CSF Tools is an experimental library that provides programmatic tools to read, analyze, transform, and write Component Story Format (CSF) files using Babel AST parsing. The package enables developers to programmatically manipulate Storybook story files and configuration files for automation, transformation, and testing workflows.
3

4
## Package Information
5

6
- **Package Name**: @storybook/csf-tools
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/csf-tools`
10
- **Status**: Deprecated (redirects to internal Storybook module)
11

12
## Core Imports
13

14
```typescript
15
import { 
16
  CsfFile, 
17
  ConfigFile, 
18
  loadCsf, 
19
  readCsf, 
20
  writeCsf,
21
  getStorySortParameter,
22
  enrichCsf,
23
  babelParse
24
} from "@storybook/csf-tools";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { 
31
  CsfFile, 
32
  ConfigFile, 
33
  loadCsf, 
34
  readCsf, 
35
  writeCsf 
36
} = require("@storybook/csf-tools");
37
```
38

39
## Basic Usage
40

41
```typescript
42
import { loadCsf, formatCsf } from "@storybook/csf-tools";
43

44
// Parse CSF file from code
45
const csfCode = `
46
  export default { title: 'Example/Button' };
47
  export const Primary = { args: { primary: true } };
48
`;
49

50
const csfFile = loadCsf(csfCode, {
51
  fileName: 'Button.stories.ts',
52
  makeTitle: (userTitle) => userTitle || 'Default'
53
}).parse();
54

55
// Access parsed metadata and stories
56
console.log(csfFile.meta.title); // 'Example/Button'
57
console.log(csfFile.stories); // Array of parsed stories
58

59
// Generate code from CSF file
60
const outputCode = formatCsf(csfFile);
61
```
62

63
## Architecture
64

65
Storybook CSF Tools is built around several key components:
66

67
- **CsfFile Class**: Core parser for Component Story Format files with full AST manipulation
68
- **ConfigFile Class**: Parser for Storybook configuration files (.storybook/main.js, etc.)
69
- **Babel Integration**: Uses Babel for AST parsing, traversal, and code generation
70
- **Type System**: Full TypeScript support with comprehensive type definitions
71
- **File I/O Utilities**: Functions for reading/writing files with proper encoding
72
- **Enhancement System**: Tools to enrich CSF files with metadata and source information
73

74
## Capabilities
75

76
### CSF File Processing
77

78
Core functionality for parsing, analyzing, and manipulating Component Story Format files. Essential for automated story generation and transformation workflows.
79

80
```typescript { .api }
81
function loadCsf(code: string, options: CsfOptions): CsfFile;
82
function readCsf(fileName: string, options: CsfOptions): Promise<CsfFile>;
83
function writeCsf(csf: CsfFile, fileName?: string): Promise<void>;
84
```
85

86
[CSF File Processing](./csf-processing.md)
87

88
### Configuration Management
89

90
Parse and manipulate Storybook configuration files including main.js, preview.js, and other config files with support for both ESM and CommonJS formats.
91

92
```typescript { .api }
93
function loadConfig(code: string, fileName?: string): ConfigFile;
94
function readConfig(fileName: string): Promise<ConfigFile>;
95
function writeConfig(config: ConfigFile, fileName?: string): Promise<void>;
96
```
97

98
[Configuration Management](./config-management.md)
99

100
### Story Enhancement
101

102
Add metadata, source code information, and descriptions to CSF files for documentation and development tooling integration.
103

104
```typescript { .api }
105
function enrichCsf(
106
  csf: CsfFile, 
107
  csfSource: CsfFile, 
108
  options?: EnrichCsfOptions
109
): void;
110

111
interface EnrichCsfOptions {
112
  disableSource?: boolean;
113
  disableDescription?: boolean;
114
}
115
```
116

117
[Story Enhancement](./story-enhancement.md)
118

119
### Testing Integration
120

121
Transform CSF files for integration with testing frameworks, particularly Vitest, enabling automated testing of Storybook stories.
122

123
```typescript { .api }
124
function vitestTransform(options: VitestTransformOptions): Promise<string>;
125

126
interface VitestTransformOptions {
127
  code: string;
128
  fileName: string;
129
  configDir: string;
130
  stories: StoriesEntry[];
131
  tagsFilter: TagsFilter;
132
  previewLevelTags?: Tag[];
133
}
134
```
135

136
[Testing Integration](./testing-integration.md)
137

138
## Types
139

140
```typescript { .api }
141
interface CsfOptions {
142
  fileName?: string;
143
  makeTitle: (userTitle: string) => string;
144
  transformInlineMeta?: boolean;
145
}
146

147
interface StaticMeta {
148
  id?: string;
149
  title?: string;
150
  component?: string;
151
  includeStories?: string[] | RegExp;
152
  excludeStories?: string[] | RegExp;
153
  tags?: Tag[];
154
}
155

156
interface StaticStory {
157
  id: string;
158
  name?: string;
159
  localName?: string;
160
  parameters?: any;
161
  tags?: Tag[];
162
  __stats: IndexInputStats;
163
}
164

165
interface PrintResultType {
166
  code: string;
167
  map?: any;
168
  toString(): string;
169
}
170

171
type Tag = string;
172

173
interface IndexInputStats {
174
  loaders?: boolean;
175
  play?: boolean;
176
  render?: boolean;
177
  storyFn?: boolean;
178
  mount?: boolean;
179
  beforeEach?: boolean;
180
  moduleMock?: boolean;
181
  globals?: boolean;
182
  factory?: boolean;
183
  tags?: boolean;
184
}
185
```