0
# Rollup Plugin Sass
1

2
Rollup Plugin Sass is a Rollup plugin that enables processing and bundling of Sass/SCSS files during the build process. It provides comprehensive configuration options including output control (write to file, callback function, or inject into HTML head), CSS processing pipeline support through custom processor functions, CSS modules generation capabilities, and flexible Sass compiler runtime selection.
3

4
## Package Information
5

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

11
## Core Imports
12

13
ES Module syntax (requires esModuleInterop in tsconfig.json):
14

15
```typescript
16
import sass from 'rollup-plugin-sass';
17
```
18

19
CommonJS syntax (actual export pattern):
20

21
```javascript
22
const sass = require('rollup-plugin-sass');
23
```
24

25
## Basic Usage
26

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

31
export default {
32
  input: 'index.js',
33
  output: {
34
    file: 'bundle.js',
35
    format: 'cjs',
36
  },
37
  plugins: [sass()],
38
};
39
```
40

41
## Architecture
42

43
The plugin is built around several key components:
44

45
- **Plugin Factory Function**: Main export that creates and returns a Rollup plugin instance
46
- **Dual API Support**: Supports both legacy and modern Sass APIs for maximum compatibility
47
- **Processing Pipeline**: Transforms Sass/SCSS files through compilation, optional processing, and output generation
48
- **File Resolution**: Handles node_modules imports using custom importers for both API modes
49
- **Output Management**: Flexible output system supporting file writing, callbacks, and style injection
50

51
## Capabilities
52

53
### Basic Plugin Configuration
54

55
Core plugin setup with essential options for Sass file processing and output control.
56

57
```typescript { .api }
58
/**
59
 * Main plugin factory function that creates a Rollup plugin for Sass processing
60
 * @param options - Configuration options for the plugin
61
 * @returns Rollup plugin object with transform and bundle generation hooks
62
 */
63
function plugin(options?: RollupPluginSassOptions): RollupPlugin;
64
export = plugin;
65

66
type RollupPluginSassOptions = 
67
  | RollupPluginSassWithModernOptions
68
  | RollupPluginSassWithLegacyOptions;
69

70
interface RollupPluginSassSharedOptions {
71
  /** File globs to exclude from processing. Default 'node_modules/**' */
72
  exclude?: string | string[];
73
  /** File globs to include in processing. Default ['**/*.sass', '**/*.scss'] */
74
  include?: string | string[];
75
  /** Controls whether to insert generated styles into HTML head */
76
  insert?: boolean;
77
  /** Custom CSS processor function */
78
  processor?: RollupPluginSassProcessorFn;
79
  /** Output control - false (default), true, string path, or callback function */
80
  output?: boolean | string | RollupPluginSassOutputFn;
81
  /** Sass runtime instance - sass, node-sass or other */
82
  runtime?: any;
83
}
84

85
type RollupPluginSassWithModernOptions = RollupPluginSassSharedOptions & {
86
  api: 'modern';
87
  options?: RollupPluginSassModernOptions;
88
};
89

90
type RollupPluginSassWithLegacyOptions = RollupPluginSassSharedOptions & {
91
  api?: 'legacy';
92
  options?: RollupPluginSassLegacyOptions;
93
};
94
```
95

96
[Configuration Options](./configuration.md)
97

98
### CSS Processing and Output
99

100
Advanced features for CSS processing, modules generation, and flexible output handling through custom processors and output functions.
101

102
```typescript { .api }
103
type RollupPluginSassProcessorFn<T = RollupPluginSassProcessorFnOutput> = 
104
  (styles: string, id: string) => Promise<T> | T;
105

106
type RollupPluginSassProcessorFnOutput = 
107
  | string
108
  | {
109
      css: string;
110
      cssModules?: Record<string, string>;
111
      [key: string]: unknown;
112
    };
113

114
type RollupPluginSassOutputFn = (
115
  styles: string,
116
  styleNodes: StyleSheetIdAndContent[]
117
) => unknown;
118

119
interface StyleSheetIdAndContent {
120
  id?: string;
121
  content?: string;
122
}
123
```
124

125
### Style Injection
126

127
Inject compiled CSS directly into the HTML document head using the built-in style injection utility.
128

129
```typescript { .api }
130
/**
131
 * Client-side utility function for injecting styles into document head
132
 * This function is automatically included when using insert: true option
133
 * @param css - CSS string to inject into document head
134
 * @returns The injected CSS string or undefined if no CSS or not in browser
135
 */
136
function insertStyle(css: string | undefined): string | undefined;
137
```
138

139
[Advanced Features](./advanced-features.md)
140

141
## Types
142

143
```typescript { .api }
144
import type {
145
  LegacyOptions,
146
  Options as SassOptions,
147
  FileImporter,
148
  LegacyImporter,
149
  CompileResult,
150
  LegacyResult
151
} from 'sass';
152

153
type RollupPluginSassModernOptions = Omit<
154
  SassOptions<'async'>,
155
  'sourceMap' // sourcemaps are handled by rollup  
156
> & {
157
  /** Data to prepend to Sass files */
158
  data?: string;
159
};
160

161
type RollupPluginSassLegacyOptions = Omit<
162
  LegacyOptions<'async'>,
163
  'data' // data is assembled and always passed via plugin transform
164
> & {
165
  /** Data to prepend to Sass files */
166
  data?: string;
167
};
168
```