0
# Stencil Sass Plugin
1

2
The @stencil/sass plugin enables seamless Sass/SCSS preprocessing for Stencil components. It provides a pure JavaScript implementation using sass-embedded for compiling Sass files within Stencil projects, offering features like automatic component directory inclusion in import paths, global Sass injection capabilities for variables and mixins, comprehensive warning controls, and full integration with Stencil's plugin architecture.
3

4
## Package Information
5

6
- **Package Name**: @stencil/sass
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @stencil/sass --save-dev`
10
- **Peer Dependency**: `@stencil/core` (>=2.0.0 || >=3.0.0-beta.0 || >= 4.0.0-beta.0 || >= 4.0.0) - Required for plugin integration
11

12
## Core Imports
13

14
```typescript
15
import { sass } from "@stencil/sass";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { sass } = require("@stencil/sass");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { Config } from "@stencil/core";
28
import { sass } from "@stencil/sass";
29

30
export const config: Config = {
31
  plugins: [
32
    sass({
33
      // Basic configuration
34
      outputStyle: 'compressed',
35
      sourceMap: true,
36
      includePaths: ['src/styles'],
37
      
38
      // Stencil-specific: inject global Sass files
39
      injectGlobalPaths: ['src/styles/variables.scss', 'src/styles/mixins.scss']
40
    })
41
  ]
42
};
43
```
44

45
## Capabilities
46

47
### Plugin Creation
48

49
Creates and configures the Stencil Sass plugin for processing .scss and .sass files.
50

51
```typescript { .api }
52
/**
53
 * Creates and configures the Stencil Sass plugin
54
 * @param opts - Optional configuration options for the plugin
55
 * @returns Configured Stencil plugin with transform method
56
 */
57
function sass(opts?: PluginOptions): Plugin;
58
```
59

60
The plugin automatically:
61
- Processes files with `.scss` and `.sass` extensions (case insensitive)
62
- Converts Sass/SCSS to CSS during Stencil's build process
63
- Handles dependency tracking for proper rebuilding
64
- Provides comprehensive error handling with diagnostic reporting
65
- Supports source map generation
66
- Integrates with Stencil's file system abstraction
67

68
**Usage Examples:**
69

70
```typescript
71
// Minimal configuration
72
sass()
73

74
// Basic configuration with output options
75
sass({
76
  outputStyle: 'compressed',
77
  sourceMap: true
78
})
79

80
// Advanced configuration with global injection
81
sass({
82
  includePaths: ['src/styles', 'node_modules'],
83
  injectGlobalPaths: [
84
    'src/styles/variables.scss',
85
    'src/styles/mixins.scss'
86
  ],
87
  outputStyle: 'expanded',
88
  sourceMap: true,
89
  quietDeps: true
90
})
91
```
92

93
## Configuration Options
94

95
```typescript { .api }
96
interface PluginOptions {
97
  /** Path to a file to compile */
98
  file?: string;
99
  
100
  /** A string to pass to compile (use with includePaths for @import support) */
101
  data?: string;
102
  
103
  /** Custom importer functions for handling @import directives */
104
  importer?: Importer | Importer[];
105
  
106
  /** Custom functions that may be invoked by Sass files */
107
  functions?: { [key: string]: (...args: any[]) => any };
108
  
109
  /** Paths for @import resolution */
110
  includePaths?: string[];
111
  
112
  /** Global Sass files to inject (Stencil-specific feature) */
113
  injectGlobalPaths?: string[];
114
  
115
  /** Enable Sass indented syntax for parsing */
116
  indentedSyntax?: boolean;
117
  
118
  /** Indentation character type */
119
  indentType?: 'space' | 'tab';
120
  
121
  /** Number of spaces/tabs for indentation */
122
  indentWidth?: number;
123
  
124
  /** Line break sequence */
125
  linefeed?: 'cr' | 'crlf' | 'lf' | 'lfcr';
126
  
127
  /** Disable source map URL inclusion in output */
128
  omitSourceMapUrl?: boolean;
129
  
130
  /** Output file location for source maps */
131
  outFile?: string;
132
  
133
  /** CSS output format */
134
  outputStyle?: 'compressed' | 'expanded';
135
  
136
  /** Suppress dependency warnings */
137
  quietDeps?: boolean;
138
  
139
  /** Silence specific deprecation warnings */
140
  silenceDeprecations?: DeprecationOrId[];
141
  
142
  /** Enable source map generation */
143
  sourceMap?: boolean | string;
144
  
145
  /** Include contents in source map */
146
  sourceMapContents?: boolean;
147
  
148
  /** Embed source map as data URI */
149
  sourceMapEmbed?: boolean;
150
  
151
  /** Source map root value */
152
  sourceMapRoot?: string;
153
}
154
```
155

156
### Custom Importers
157

158
Support for custom importer functions to extend Sass import handling.
159

160
```typescript { .api }
161
/**
162
 * Function type for custom Sass importers
163
 * @param url - The URL/path being imported
164
 * @param prev - The stylesheet that contained the @import
165
 * @param done - Callback to return the import result
166
 * @returns Import result or void (for async handling via callback)
167
 */
168
type Importer = (
169
  url: string,
170
  prev: string,
171
  done: (data: ImporterReturnType) => void
172
) => ImporterReturnType | void;
173

174
/**
175
 * Return type for importer functions
176
 */
177
type ImporterReturnType = 
178
  | { file: string }      // Return file path to load
179
  | { contents: string }  // Return contents directly
180
  | Error                 // Return error
181
  | null;                 // Unable to handle this import
182
```
183

184
**Usage Example:**
185

186
```typescript
187
sass({
188
  importer: [
189
    // Custom importer for special prefixes
190
    (url, prev, done) => {
191
      if (url.startsWith('theme:')) {
192
        const themePath = `src/themes/${url.substring(6)}.scss`;
193
        done({ file: themePath });
194
        return;
195
      }
196
      done(null); // Let default importer handle it
197
    }
198
  ]
199
})
200
```
201

202
## Key Features
203

204
### Global Sass Injection
205

206
The `injectGlobalPaths` option automatically injects Sass files at the beginning of each processed file:
207

208
```typescript
209
sass({
210
  injectGlobalPaths: [
211
    'src/styles/variables.scss',
212
    'src/styles/mixins.scss'
213
  ]
214
})
215
```
216

217
This makes variables and mixins available in all component stylesheets without manual imports.
218

219
### Node Modules Support
220

221
The plugin automatically handles tilde (~) imports for resolving modules from node_modules:
222

223
```scss
224
// Import from node_modules
225
@import '~bootstrap/scss/variables';
226
@import '~@angular/material/theming';
227
```
228

229
### File Extension Support
230

231
- `.scss` - Sass SCSS syntax (default)
232
- `.sass` - Sass indented syntax (automatically detected)
233

234
### Error Handling
235

236
Comprehensive error reporting with:
237
- Line and column numbers
238
- File path information
239
- Context lines around errors
240
- Integration with Stencil's diagnostic system
241

242
### Source Maps
243

244
Full source map support for debugging:
245
- Inline source maps
246
- External source map files
247
- Source content inclusion
248
- Custom source map root paths
249

250
## Advanced Configuration Examples
251

252
### Development Configuration
253

254
Optimized for debugging and development workflow:
255

256
```typescript
257
sass({
258
  // Expanded output for easier CSS debugging
259
  outputStyle: 'expanded',
260
  
261
  // Enable source maps with full content for debugging
262
  sourceMap: true,
263
  sourceMapContents: true,
264
  
265
  // Include both project styles and node_modules for imports
266
  includePaths: ['src/styles', 'node_modules'],
267
  
268
  // Inject development-specific variables
269
  injectGlobalPaths: ['src/styles/dev-variables.scss']
270
})
271
```
272

273
### Production Configuration
274

275
Optimized for bundle size and performance:
276

277
```typescript
278
sass({
279
  // Compressed output for smaller CSS bundles
280
  outputStyle: 'compressed',
281
  
282
  // Disable source maps in production
283
  sourceMap: false,
284
  
285
  // Suppress dependency warnings to reduce noise
286
  quietDeps: true,
287
  
288
  // Silence legacy API deprecation warnings
289
  silenceDeprecations: ['legacy-js-api'],
290
  
291
  // Only include necessary paths
292
  includePaths: ['src/styles'],
293
  
294
  // Inject only production variables and mixins
295
  injectGlobalPaths: ['src/styles/variables.scss', 'src/styles/mixins.scss']
296
})
297
```
298

299
### Custom Functions Configuration
300

301
```typescript
302
sass({
303
  functions: {
304
    'get-theme-color($name)': (name: any) => {
305
      const colors = {
306
        primary: '#007bff',
307
        secondary: '#6c757d'
308
      };
309
      return colors[name.getValue()] || '#000000';
310
    }
311
  }
312
})
313
```
314

315
## Types
316

317
```typescript { .api }
318
/**
319
 * Stencil plugin interface (re-exported from @stencil/core)
320
 */
321
interface Plugin {
322
  name: string;
323
  pluginType: string;
324
  transform?: (sourceText: string, fileName: string, context: PluginCtx) => Promise<PluginTransformResults>;
325
}
326

327
/**
328
 * Plugin transformation results
329
 */
330
interface PluginTransformResults {
331
  id: string;
332
  code?: string;
333
  dependencies?: string[];
334
}
335

336
/**
337
 * Plugin context provided by Stencil
338
 */
339
interface PluginCtx {
340
  config: Config;
341
  fs: FileSystem;
342
  sys: System;
343
  diagnostics: Diagnostic[];
344
}
345

346
/**
347
 * Deprecation identifier type from sass-embedded
348
 */
349
type DeprecationOrId = string | { id: string };
350
```
351

352
Note: The plugin re-exports all types from `@stencil/core/internal`, making them available for TypeScript users who need to work with the plugin API directly.