0
# Storybook Preset for Create React App
1

2
The @storybook/preset-create-react-app package provides a Storybook preset that enables seamless integration with Create React App (CRA) projects. It automatically configures Webpack and Babel settings to match the host CRA application's build configuration, ensuring consistent behavior between the main app and Storybook environment.
3

4
## Package Information
5

6
- **Package Name**: @storybook/preset-create-react-app
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -D @storybook/preset-create-react-app`
10

11
## Core Imports
12

13
This preset is typically configured in Storybook's main configuration file and does not export user-facing functions for direct import. The preset works automatically when added to your Storybook configuration.
14

15
**Note**: This preset does not export functions for direct use. It works as a Storybook addon/preset that modifies webpack configuration automatically.
16

17
## Basic Usage
18

19
The simplest way to use this preset is by adding it to your Storybook configuration:
20

21
```javascript
22
// .storybook/main.js
23
module.exports = {
24
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
25
  addons: [
26
    '@storybook/preset-create-react-app',
27
    '@storybook/addon-essentials',
28
  ],
29
};
30
```
31

32
For advanced customization with options:
33

34
```javascript
35
// .storybook/main.js
36
module.exports = {
37
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
38
  addons: [
39
    {
40
      name: '@storybook/preset-create-react-app',
41
      options: {
42
        scriptsPackageName: '@my/react-scripts',
43
        craOverrides: {
44
          fileLoaderExcludes: ['pdf'],
45
        },
46
      },
47
    },
48
    '@storybook/addon-essentials',
49
  ],
50
};
51
```
52

53
## Capabilities
54

55
### Core Configuration
56

57
The preset provides core Storybook configuration that disables default webpack settings to allow full CRA integration. This is handled internally by the preset.
58

59
```typescript { .api }
60
/**
61
 * Internal core configuration - automatically applied by the preset
62
 * Disables Storybook's default webpack configuration to prevent conflicts with CRA
63
 */
64
interface CoreConfiguration {
65
  disableWebpackDefaults: true;
66
}
67
```
68

69
### Webpack Configuration
70

71
The preset automatically merges CRA and Storybook webpack configurations. This processing is handled internally by the preset when it's loaded.
72

73
```typescript { .api }
74
/**
75
 * Internal webpack configuration processing - automatically applied by the preset
76
 * Merges CRA's webpack configuration with Storybook's configuration
77
 */
78
interface WebpackProcessing {
79
  // Automatically processes and merges:
80
  // - JavaScript/TypeScript compilation rules
81
  // - CSS processing rules
82
  // - Asset handling rules
83
  // - Plugin merging with conflict resolution
84
  // - Module resolution paths
85
}
86
```
87

88
### Plugin Options Configuration
89

90
Configuration interface for customizing the preset behavior.
91

92
```typescript { .api }
93
// Plugin configuration options interface
94
interface PluginOptions {
95
  configDir: string;
96
  packageJson?: { version?: string };
97
  presets: {
98
    apply: (key: string) => Promise<any>;
99
  };
100
  presetsList?: Array<string | { name: string }>;
101
  
102
  /**
103
   * Optionally set the package name of a react-scripts fork. In most cases, the package is located
104
   * automatically by this preset.
105
   */
106
  scriptsPackageName?: string;
107

108
  /** Overrides for Create React App's Webpack configuration. */
109
  craOverrides?: {
110
    fileLoaderExcludes?: string[];
111
  };
112

113
  typescriptOptions?: {
114
    reactDocgen: 'react-docgen-typescript' | 'react-docgen' | false;
115
    reactDocgenTypescriptOptions: RDTSPluginOptions;
116
  };
117
}
118

119
// Type definitions for react-docgen-typescript plugin options
120
interface RDTSPluginOptions {
121
  [key: string]: any;
122
}
123
```
124

125
### Internal Processing
126

127
The preset includes several internal capabilities that work automatically:
128

129
- **Preset Compatibility Checking**: Automatically validates compatibility with other presets and warns about potential conflicts
130
- **CRA Configuration Processing**: Intelligently processes Create React App's webpack configuration for Storybook compatibility
131
- **Plugin Merging**: Merges webpack plugins while avoiding duplicates and handling special cases like React Refresh
132
- **Module Path Resolution**: Extracts module resolution paths from TypeScript/JavaScript config files (tsconfig.json/jsconfig.json)
133
- **React Scripts Detection**: Automatically locates react-scripts package installation path, including support for custom forks
134

135
## Configuration Examples
136

137
### Basic Storybook Integration
138

139
```javascript
140
// .storybook/main.js
141
module.exports = {
142
  addons: ['@storybook/preset-create-react-app'],
143
};
144
```
145

146
### With Complete Addon Configuration
147

148
```javascript
149
// .storybook/main.js
150
module.exports = {
151
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
152
  addons: [
153
    '@storybook/preset-create-react-app',
154
    '@storybook/addon-essentials',
155
    '@storybook/addon-interactions',
156
    '@storybook/addon-links',
157
  ],
158
  framework: {
159
    name: '@storybook/react-webpack5',
160
    options: {},
161
  },
162
};
163
```
164

165
### Custom react-scripts Package
166

167
```javascript
168
// .storybook/main.js - For projects using forked react-scripts
169
module.exports = {
170
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
171
  addons: [
172
    {
173
      name: '@storybook/preset-create-react-app',
174
      options: {
175
        scriptsPackageName: '@my/react-scripts', // Custom react-scripts fork
176
      },
177
    },
178
    '@storybook/addon-essentials',
179
  ],
180
  framework: {
181
    name: '@storybook/react-webpack5',
182
    options: {},
183
  },
184
};
185
```
186

187
### File Loader Overrides
188

189
```javascript
190
// .storybook/main.js - Exclude additional file types from asset processing
191
module.exports = {
192
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
193
  addons: [
194
    {
195
      name: '@storybook/preset-create-react-app',
196
      options: {
197
        craOverrides: {
198
          fileLoaderExcludes: ['pdf', 'doc', 'docx', 'zip'], // Additional exclusions
199
        },
200
      },
201
    },
202
    '@storybook/addon-essentials',
203
  ],
204
  framework: {
205
    name: '@storybook/react-webpack5',
206
    options: {},
207
  },
208
};
209
```
210

211
### Complete Configuration with TypeScript Options
212

213
```javascript
214
// .storybook/main.js - Full configuration example
215
module.exports = {
216
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
217
  addons: [
218
    {
219
      name: '@storybook/preset-create-react-app',
220
      options: {
221
        scriptsPackageName: 'react-scripts', // Can be customized for forks
222
        craOverrides: {
223
          fileLoaderExcludes: ['pdf', 'doc'], // Additional file exclusions
224
        },
225
        typescriptOptions: {
226
          reactDocgen: 'react-docgen-typescript',
227
          reactDocgenTypescriptOptions: {
228
            shouldExtractLiteralValuesFromEnum: true,
229
            propFilter: (prop) => {
230
              if (prop.parent) {
231
                return !prop.parent.fileName.includes('node_modules');
232
              }
233
              return true;
234
            },
235
          },
236
        },
237
      },
238
    },
239
    '@storybook/addon-essentials',
240
    '@storybook/addon-interactions',
241
  ],
242
  framework: {
243
    name: '@storybook/react-webpack5',
244
    options: {},
245
  },
246
  typescript: {
247
    check: false,
248
    checkOptions: {},
249
    reactDocgen: 'react-docgen-typescript',
250
    reactDocgenTypescriptOptions: {
251
      shouldExtractLiteralValuesFromEnum: true,
252
      propFilter: (prop) => {
253
        if (prop.parent) {
254
          return !prop.parent.fileName.includes('node_modules');
255
        }
256
        return true;
257
      },
258
    },
259
  },
260
};
261
```
262

263
## Error Handling
264

265
The preset includes built-in error handling for common scenarios:
266

267
- **Missing react-scripts**: Logs error and returns unmodified webpack config
268
- **Invalid scriptsPackageName**: Logs warning and falls back to automatic detection  
269
- **Missing CRA webpack rules**: Returns empty rules array safely
270
- **File system access errors**: Handles missing config files gracefully
271
- **Plugin conflicts**: Automatically detects and resolves webpack plugin conflicts
272
- **Babel configuration merging**: Safely merges CRA and Storybook Babel configurations
273

274
## Compatibility
275

276
- **Create React App**: Version 5.0.0 and later (supports react-scripts forks)
277
- **Storybook**: Compatible with Storybook 5.3.0+ (optimized behavior for 6.0+)
278
- **React**: Compatible with React 16.8+ and React 18
279
- **TypeScript**: Full TypeScript support with automatic detection
280
- **Node.js**: Supports Node.js 16+ with both CommonJS and ES modules
281
- **Platforms**: Cross-platform support including Windows, macOS, and Linux
282
- **Package Managers**: Works with npm, yarn, and pnpm