0
# Storybook SCSS Preset
1

2
Storybook SCSS Preset provides one-line SCSS configuration for Storybook. It automatically configures webpack loaders (style-loader, css-loader, and sass-loader) to handle .scss and .sass files, enabling developers to quickly add SCSS support to their Storybook setup without manually configuring webpack.
3

4
## Package Information
5

6
- **Package Name**: @storybook/preset-scss
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -D @storybook/preset-scss css-loader sass-loader style-loader`
10

11
## Core Imports
12

13
```javascript
14
// Import the preset module (for programmatic usage)
15
const { webpack } = require('@storybook/preset-scss');
16
```
17

18
TypeScript:
19

20
```typescript
21
import type { PresetScss } from '@storybook/preset-scss';
22
// For programmatic usage:
23
// const presetScss: PresetScss = require('@storybook/preset-scss');
24
```
25

26
Note: Typically used as a Storybook addon/preset and imported automatically by Storybook.
27

28
## Basic Usage
29

30
Add the preset to your `.storybook/main.js`:
31

32
```javascript
33
module.exports = {
34
  addons: ['@storybook/preset-scss'],
35
};
36
```
37

38
With configuration options:
39

40
```javascript
41
module.exports = {
42
  addons: [
43
    {
44
      name: '@storybook/preset-scss',
45
      options: {
46
        cssLoaderOptions: {
47
          modules: true,
48
          localIdentName: '[name]__[local]--[hash:base64:5]',
49
        },
50
        sassLoaderOptions: {
51
          implementation: require('sass'),
52
        }
53
      }
54
    }
55
  ]
56
};
57
```
58

59
## Capabilities
60

61
### Webpack Configuration
62

63
Configures webpack to handle SCSS/SASS files with the necessary loaders.
64

65
```javascript { .api }
66
/**
67
 * Webpack configuration function that adds SCSS support to Storybook
68
 * @param webpackConfig - Existing webpack configuration object (optional, defaults to {})
69
 * @param options - Configuration options for the preset (optional, defaults to {})
70
 * @returns Modified webpack configuration with SCSS support
71
 */
72
function webpack(webpackConfig = {}, options = {}) {
73
  // Returns webpack config with SCSS rule added
74
  // Internally uses wrapLoader() to conditionally apply loaders
75
  // Test pattern: /\.s[ca]ss$/
76
  // Loader chain: style-loader -> css-loader -> sass-loader
77
}
78
```
79

80
**Usage:**
81

82
```javascript
83
// Called automatically by Storybook when preset is registered
84
// No direct usage required - configuration happens through Storybook's addon system
85

86
// For programmatic usage:
87
const { webpack } = require('@storybook/preset-scss');
88
const modifiedConfig = webpack(existingWebpackConfig, {
89
  cssLoaderOptions: { modules: true },
90
  sassLoaderOptions: { implementation: require('sass') }
91
});
92
```
93

94
**Loader Behavior:**
95

96
The preset internally uses a `wrapLoader` function that conditionally applies loaders:
97
- If a loader option is `false`, that loader is skipped entirely
98
- If a loader option is an object, it's passed as options to that loader
99
- If a loader option is undefined, the loader is applied with no options
100

101
**File Pattern:**
102

103
The preset adds a webpack rule that matches files with the pattern `/\.s[ca]ss$/`, which includes:
104
- `.scss` files (Sass with SCSS syntax)
105
- `.sass` files (Sass with indented syntax)
106

107
## Types
108

109
```typescript { .api }
110
// From webpack types
111
interface Configuration {
112
  module?: {
113
    rules?: any[];
114
  };
115
  [key: string]: any;
116
}
117

118
interface RuleSetCondition {
119
  exclude?: RegExp | string;
120
  include?: RegExp | string;
121
  [key: string]: any;
122
}
123

124
interface Options {
125
  /** Options for style-loader or false to disable */
126
  styleLoaderOptions?: object | false;
127
  /** Options for css-loader or false to disable */
128
  cssLoaderOptions?: object | false;
129
  /** Options for sass-loader or false to disable */
130
  sassLoaderOptions?: object | false;
131
  /** Additional webpack rule conditions */
132
  rule?: RuleSetCondition;
133
}
134

135
interface PresetScss {
136
  webpack: (config?: Configuration, options?: Options) => Configuration;
137
}
138
```
139

140
## Configuration Options
141

142
### Style Loader Options
143

144
Configure style-loader behavior or disable it entirely.
145

146
```javascript
147
{
148
  styleLoaderOptions: {
149
    // Standard style-loader options
150
    // See: https://webpack.js.org/loaders/style-loader/
151
  }
152
  // Or disable:
153
  // styleLoaderOptions: false
154
}
155
```
156

157
### CSS Loader Options
158

159
Configure css-loader for features like CSS modules.
160

161
```javascript
162
{
163
  cssLoaderOptions: {
164
    modules: true,
165
    localIdentName: '[name]__[local]--[hash:base64:5]',
166
    // Other css-loader options
167
    // See: https://webpack.js.org/loaders/css-loader/
168
  }
169
  // Or disable:
170
  // cssLoaderOptions: false
171
}
172
```
173

174
### SASS Loader Options
175

176
Configure sass-loader with custom implementation or other options.
177

178
```javascript
179
{
180
  sassLoaderOptions: {
181
    implementation: require('sass'), // Use Dart Sass instead of Node Sass
182
    // Other sass-loader options
183
    // See: https://webpack.js.org/loaders/sass-loader/
184
  }
185
  // Or disable:
186
  // sassLoaderOptions: false
187
}
188
```
189

190
### Rule Configuration
191

192
Add additional webpack rule conditions.
193

194
```javascript
195
{
196
  rule: {
197
    exclude: /node_modules/,
198
    // Other webpack rule conditions
199
  }
200
}
201
```
202

203
## Dependencies
204

205
This preset requires the following peer dependencies to be installed:
206

207
- `css-loader` - Resolves CSS imports and processes CSS
208
- `sass-loader` - Compiles SCSS/SASS to CSS
209
- `style-loader` - Injects CSS into the DOM
210

211
The preset automatically resolves these loaders using `require.resolve()` and applies them in the correct order: style-loader → css-loader → sass-loader.