0
# Rollup Plugin SCSS
1

2
Rollup Plugin SCSS enables seamless processing of SCSS, Sass, and CSS files in Rollup build pipelines. It compiles stylesheets using Sass compilers, supports PostCSS integration for advanced CSS processing, and provides flexible output options including CSS file generation, inline style injection, and callback-based handling.
3

4
## Package Information
5

6
- **Package Name**: rollup-plugin-scss
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev rollup-plugin-scss sass`
10

11
## Core Imports
12

13
```typescript
14
import scss from "rollup-plugin-scss";
15
import type { CSSPluginOptions } from "rollup-plugin-scss";
16
import type { CreateFilter } from "rollup-pluginutils";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const scss = require("rollup-plugin-scss");
23
```
24

25
## Basic Usage
26

27
```typescript
28
// rollup.config.js
29
import scss from "rollup-plugin-scss";
30

31
export default {
32
  input: "input.js",
33
  output: {
34
    file: "output.js",
35
    format: "esm"
36
  },
37
  plugins: [
38
    scss() // Outputs compiled styles to output.css
39
  ]
40
};
41

42
// In your JavaScript entry file
43
import "./styles.scss";
44
```
45

46
## Architecture
47

48
Rollup Plugin SCSS is built around several key components:
49

50
- **Sass Compilation**: Automatically detects and uses `sass` or `node-sass` compilers for SCSS/Sass processing
51
- **Import Resolution**: Custom importer supporting node_modules resolution and webpack-style `~` imports
52
- **PostCSS Integration**: Optional CSS post-processing through configurable processor functions
53
- **Output Modes**: Multiple output strategies (file emission, inline injection, callback handling)
54
- **Watch Integration**: File watching support for development workflows with configurable watch paths
55

56
## Capabilities
57

58
### Plugin Factory Function
59

60
Creates a Rollup plugin instance for processing SCSS, Sass, and CSS files.
61

62
```typescript { .api }
63
/**
64
 * Creates a Rollup plugin for processing SCSS, Sass, and CSS files
65
 * @param options - Configuration options for the plugin (defaults to {})
66
 * @returns Rollup plugin instance
67
 */
68
export default function scss(options: CSSPluginOptions = {}): Plugin;
69
```
70

71
## Configuration Options
72

73
```typescript { .api }
74
export interface CSSPluginOptions {
75
  /** Files to exclude from processing (rollup-pluginutils filter format) */
76
  exclude?: string | string[] | RegExp | RegExp[];
77
  
78
  /** Terminate node process on compilation errors (default: false) */
79
  failOnError?: boolean;
80
  
81
  /** Literal asset filename, bypasses any hash transformations */
82
  fileName?: string;
83
  
84
  /** Files to include in processing (default: ['/**/*.css', '/**/*.scss', '/**/*.sass']) */
85
  include?: string | string[] | RegExp | RegExp[];
86
  
87
  /** Additional paths for Sass @import resolution */
88
  includePaths?: string[];
89
  
90
  /** Insert styles into HTML head tag instead of emitting CSS file */
91
  insert?: boolean;
92
  
93
  /** Asset name for output (default: 'output.css'), Rollup may add hash to filename */
94
  name?: string;
95
  
96
  /** @deprecated Use fileName instead - Output configuration */
97
  output?: string | false | ((css: string, styles: Styles) => void);
98
  
99
  /** Global SCSS prefix prepended to all files (useful for variables/mixins) */
100
  prefix?: string;
101
  
102
  /** CSS post-processor function for custom transformations */
103
  processor?: (
104
    css: string,
105
    map: string,
106
    styles: Styles
107
  ) => CSS | Promise<CSS> | PostCSSProcessor;
108
  
109
  /** Custom Sass compiler instance (auto-detects sass/node-sass if not provided) */
110
  sass?: SassRenderer;
111
  
112
  /** Enable source map generation (default: false) */
113
  sourceMap?: boolean;
114
  
115
  /** Log filename and size of generated CSS files (default: true) */
116
  verbose?: boolean;
117
  
118
  /** Files/folders to monitor in watch mode for rebuilds */
119
  watch?: string | string[];
120
  
121
  /** Sass output style (e.g., 'compressed', 'expanded') */
122
  outputStyle?: string;
123
}
124
```
125

126
## Usage Examples
127

128
### Basic File Output
129

130
```typescript
131
// Output to specific filename
132
scss({
133
  fileName: "bundle.css"
134
})
135

136
// Output with source maps
137
scss({
138
  fileName: "styles.css",
139
  sourceMap: true
140
})
141
```
142

143
### Inline Style Injection
144

145
```typescript
146
// Inject styles into HTML head using built-in insertion function
147
scss({
148
  insert: true
149
})
150

151
// When insert: true is used, the plugin exports a function that
152
// automatically creates and appends style tags to document.head
153
// This is handled automatically by the plugin's insertStyleFn
154
```
155

156
### PostCSS Integration
157

158
```typescript
159
import autoprefixer from "autoprefixer";
160
import postcss from "postcss";
161

162
scss({
163
  processor: () => postcss([autoprefixer()])
164
})
165

166
// Or with custom processing
167
scss({
168
  processor: (css, map) => ({
169
    css: css.replace("/*date*/", `/* ${new Date().toJSON()} */`),
170
    map
171
  })
172
})
173
```
174

175
### Custom Output Handling
176

177
```typescript
178
// Disable CSS output, import as string
179
scss({
180
  output: false
181
})
182

183
// Custom output callback
184
scss({
185
  output: (css, styles) => {
186
    fs.writeFileSync("custom-bundle.css", css);
187
  }
188
})
189
```
190

191
### Development Configuration
192

193
```typescript
194
scss({
195
  includePaths: ["node_modules/", "src/styles/"],
196
  prefix: `@import "./variables.scss";`,
197
  watch: ["src/styles/components", "src/styles/mixins"],
198
  verbose: true
199
})
200
```
201

202
### Sass Compiler Options
203

204
Additional options not explicitly defined in `CSSPluginOptions` are passed through to the underlying Sass compiler. This includes options like:
205

206
```typescript
207
scss({
208
  // Sass-specific options passed through to the compiler
209
  indentedSyntax: true,    // For .sass syntax instead of .scss
210
  precision: 10,           // Decimal precision for numbers
211
  includePaths: ["node_modules/"],
212
  outputStyle: "compressed"
213
})
214
```
215

216
## Type Definitions
217

218
```typescript { .api }
219
/** CSS output as string or object with CSS and source map */
220
type CSS = string | { css: string; map: string };
221

222
/** CSS with source map information */
223
interface MappedCSS {
224
  css: string;
225
  map: string;
226
}
227

228
/** Map of stylesheet IDs to their content */
229
interface Styles {
230
  [id: string]: string;
231
}
232

233
/** PostCSS processor interface for CSS post-processing */
234
interface PostCSSProcessor {
235
  process: (css: string, options?: any) => MappedCSS;
236
}
237

238
/** Sass compiler interface */
239
interface SassRenderer {
240
  renderSync: (options: SassOptions) => SassResult;
241
}
242

243
/** Options for Sass compilation */
244
interface SassOptions {
245
  data: string;
246
}
247

248
/** Result from Sass compilation */
249
interface SassResult {
250
  css: Buffer;
251
  map?: Buffer;
252
}
253

254
/** Return type for custom importer functions */
255
type ImporterReturnType = { file: string } | { contents: string } | Error | null;
256

257
/** Callback function for custom importers */
258
type ImporterDoneCallback = (data: ImporterReturnType) => void;
259

260
/** Filter creation function from rollup-pluginutils */
261
type CreateFilter = (
262
  include?: string | string[] | RegExp | RegExp[],
263
  exclude?: string | string[] | RegExp | RegExp[]
264
) => (id: string) => boolean;
265
```
266

267
## Error Handling
268

269
The plugin provides helpful error messages for common issues:
270

271
- **Invalid CSS**: Shows line and column information for syntax errors
272
- **Missing sass package**: Suggests `npm install --save-dev sass`
273
- **node-sass binding issues**: Suggests `npm rebuild node-sass --force`
274

275
Set `failOnError: true` to terminate the build process on compilation errors instead of continuing with warnings.
276

277
## Import Resolution
278

279
The plugin supports various import patterns:
280

281
- **Relative imports**: `@import "./styles.scss"`
282
- **Node modules**: `@import "bootstrap/scss/bootstrap"`
283
- **Webpack-style imports**: `@import "~bootstrap/scss/bootstrap"`
284
- **Extension resolution**: Automatically resolves `.scss`, `.sass`, and `.css` extensions
285

286
## Internal Utility Functions
287

288
The plugin exposes several utility functions for advanced use cases:
289

290
```typescript { .api }
291
/** Load the appropriate Sass compiler (sass or node-sass) */
292
function loadSassLibrary(): SassRenderer;
293

294
/** Convert string or CSS object to MappedCSS format */
295
function stringToCSS(input: string | CSS): MappedCSS;
296

297
/** Format console output with red color for errors */
298
function red(text: string): string;
299

300
/** Format console output with green color for success/solutions */
301
function green(text: string): string;
302

303
/** Format byte size as human-readable string (B, kB, MB) */
304
function getSize(bytes: number): string;
305

306
/** 
307
 * Style insertion function used when insert: true option is enabled
308
 * Creates a style tag and appends it to document.head
309
 * @param css - CSS string to insert
310
 * @returns CSS string that was inserted
311
 */
312
function insertStyleFn(css: string): string;
313
```