0
# Configuration Options
1

2
Comprehensive configuration options for rollup-plugin-sass, including file filtering, API selection, and Sass compiler settings.
3

4
## Capabilities
5

6
### File Inclusion and Exclusion
7

8
Control which files are processed by the plugin using glob patterns.
9

10
```typescript { .api }
11
interface FileFilterOptions {
12
  /** File globs to include in processing. Default ['**/*.sass', '**/*.scss'] */
13
  include?: string | string[];
14
  /** File globs to exclude from processing. Default 'node_modules/**' */
15
  exclude?: string | string[];
16
}
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import sass from 'rollup-plugin-sass';
23

24
// Include additional CSS files
25
sass({
26
  include: ['**/*.css', '**/*.sass', '**/*.scss'],
27
});
28

29
// Exclude specific directories
30
sass({
31
  exclude: ['node_modules/**', 'test/**/*.scss'],
32
});
33

34
// Multiple patterns
35
sass({
36
  include: ['src/**/*.scss', 'styles/**/*.sass'],
37
  exclude: ['src/vendor/**', 'styles/temp/**'],
38
});
39
```
40

41
### API Mode Selection
42

43
Choose between legacy and modern Sass APIs based on your Sass version and requirements.
44

45
```typescript { .api }
46
interface ApiModeOptions {
47
  /** API mode selection - 'legacy' (default) or 'modern' */
48
  api?: 'legacy' | 'modern';
49
  /** Sass compiler options specific to the selected API */
50
  options?: SassModernOptions | SassLegacyOptions;
51
}
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
// Legacy API (default)
58
sass({
59
  api: 'legacy',
60
  options: {
61
    outputStyle: 'compressed',
62
    includePaths: ['node_modules'],
63
  },
64
});
65

66
// Modern API
67
sass({
68
  api: 'modern',
69
  options: {
70
    style: 'compressed',
71
    loadPaths: ['node_modules'],
72
  },
73
});
74

75
// Modern API with NodePackageImporter for npm packages
76
import * as sass from 'sass';
77

78
sass({
79
  api: 'modern',
80
  options: {
81
    importers: [new sass.NodePackageImporter()],
82
  },
83
});
84
```
85

86
### Sass Runtime Configuration
87

88
Specify custom Sass runtime for compatibility with different Sass implementations.
89

90
```typescript { .api }
91
interface RuntimeOptions {
92
  /** Sass runtime instance - sass, node-sass or other compatible compiler */
93
  runtime?: any;
94
}
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import * as sass from 'sass';
101
import * as nodeSass from 'node-sass';
102

103
// Use Dart Sass (default)
104
sass({
105
  runtime: sass,
106
});
107

108
// Use Node Sass
109
sass({
110
  runtime: nodeSass,
111
});
112
```
113

114
### Output Configuration
115

116
Configure how and where the compiled CSS is output.
117

118
```typescript { .api }
119
interface OutputOptions {
120
  /** 
121
   * Output control:
122
   * - false: no output (default)
123
   * - true: output as .css file alongside JS bundle
124
   * - string: specific file path
125
   * - function: custom output handler
126
   */
127
  output?: boolean | string | RollupPluginSassOutputFn;
128
}
129

130
type RollupPluginSassOutputFn = (
131
  styles: string,
132
  styleNodes: StyleSheetIdAndContent[]
133
) => unknown;
134
```
135

136
**Usage Examples:**
137

138
```typescript
139
// No output (styles embedded in JS)
140
sass({
141
  output: false,
142
});
143

144
// Auto-generate CSS file
145
sass({
146
  output: true, // Creates bundle.css if bundle is bundle.js
147
});
148

149
// Specific output file
150
sass({
151
  output: 'dist/styles.css',
152
});
153

154
// Custom output handler
155
sass({
156
  output(styles, styleNodes) {
157
    console.log(`Generated ${styles.length} characters of CSS`);
158
    writeFileSync('custom-bundle.css', styles);
159
  },
160
});
161
```
162

163
### Style Injection
164

165
Inject compiled CSS directly into the HTML document head.
166

167
```typescript { .api }
168
interface StyleInjectionOptions {
169
  /** Insert compiled CSS into HTML head via utility function */
170
  insert?: boolean;
171
}
172
```
173

174
**Usage Examples:**
175

176
```typescript
177
// Inject styles into document head
178
sass({
179
  insert: true,
180
});
181

182
// Combined with other options
183
sass({
184
  insert: true,
185
  output: false, // Don't create CSS file when injecting
186
});
187
```
188

189
### Data Prepending
190

191
Prepend data (variables, mixins) to all Sass files during compilation.
192

193
```typescript { .api }
194
interface DataOptions {
195
  /** Data to prepend to all Sass files */
196
  data?: string;
197
}
198
```
199

200
**Usage Examples:**
201

202
```typescript
203
// Inject global variables
204
sass({
205
  options: {
206
    data: '$primary-color: #007bff; $font-size: 16px;',
207
  },
208
});
209

210
// Import global mixins and variables
211
sass({
212
  options: {
213
    data: '@import "src/styles/variables"; @import "src/styles/mixins";',
214
  },
215
});
216
```
217

218
## Complete Configuration Example
219

220
```typescript
221
import sass from 'rollup-plugin-sass';
222
import * as dartSass from 'sass';
223

224
export default {
225
  input: 'src/index.js',
226
  output: {
227
    file: 'dist/bundle.js',
228
    format: 'esm',
229
  },
230
  plugins: [
231
    sass({
232
      // File filtering
233
      include: ['src/**/*.scss', 'styles/**/*.sass'],
234
      exclude: ['node_modules/**', 'test/**'],
235
      
236
      // API configuration
237
      api: 'modern',
238
      runtime: dartSass,
239
      
240
      // Output configuration
241
      output: 'dist/styles.css',
242
      insert: false,
243
      
244
      // Sass options
245
      options: {
246
        style: 'compressed',
247
        loadPaths: ['node_modules', 'src/styles'],
248
        data: '@import "variables"; @import "mixins";',
249
      },
250
    }),
251
  ],
252
};
253
```