-
Notifications
You must be signed in to change notification settings - Fork 222
/
js-api.html.md.erb
1307 lines (957 loc) · 35 KB
/
js-api.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: JavaScript API
table_of_contents: true
introduction: >
Both major Sass implementations support the same JavaScript API. [Dart
Sass](/dart-sass) is distributed as the pure-Javascript [`sass`
package](https://www.npmjs.com/package/sass), and [LibSass](/libsass) is
distributed as a native extension in the [`node-sass`
package](https://www.npmjs.com/package/node-sass).
---
## Usage
The Sass module provides two functions with similar APIs.
### `renderSync()`
This function synchronously compiles a Sass file to CSS. If it succeeds, it
returns the [result][], and if it fails it throws an [error][]. It takes an
[options object][], which must have either the [`file` option][] or the
[`data` option][] set.
[result]: #result-object
[error]: #error-object
[options object]: #options
[`file` option]: #file
[`data` option]: #data
```js
var sass = require('sass'); // or require('node-sass');
var result = sass.renderSync({file: "style.scss"});
// ...
```
### `render()`
<% impl_status dart: true, node: '3.0.0' %>
This function asynchronously compiles a Sass file to CSS, and calls a standard
Node callback with the [result][] or an [error][] when the rendering is
complete. It takes an [options object][], which must have either the
[`file` option][] or the [`data` option][] set.
<% heads_up do %>
When using Dart Sass, **[`renderSync()`][] is almost twice as fast as
`render()`** by default, due to the overhead of making the entire evaluation
process asynchronous. To avoid this performance hit, you can pass the
[`fiber` option][] to `render()`.
[`renderSync()`]: #rendersync
[`fiber` option]: #fiber
<% end %>
```js
var sass = require('sass'); // or require('node-sass');
sass.render({
file: "style.scss"
}, function(err, result) {
// ...
});
```
### `info`
<% impl_status dart: true, node: '2.0.0' %>
The `info` property contains a string that includes tab-separated information
about the Sass implementation. For Dart Sass, this is the version of Dart Sass
and the version of the [dart2js][] compiler used to compile it to JavaScript;
for LibSass, it's the version of LibSass and the version of [Node Sass][] that
wraps it.
[dart2js]: https://webdev.dartlang.org/tools/dart2js
[Node Sass]: https://www.npmjs.com/package/node-sass
```js
console.log(sass.info);
// dart-sass <%= impl_version(:dart) %> (Sass Compiler) [Dart]
// dart2js 2.0.0 (Dart Compiler) [Dart]
```
### Result Object
When [`renderSync()`][] or [`render()`][] succeed, they provide a result object
that contains information about the compilation. This object has the following
properties:
[`renderSync()`]: #rendersync
[`render()`]: #render
#### `result.css`
The compiled CSS, as a [Buffer][]. This can be converted to a string by calling
[`Buffer.toString()`][].
[Buffer]: https://nodejs.org/api/buffer.html
[`Buffer.toString()`]: https://nodejs.org/api/buffer.html#buffer_buf_tostring_encoding_start_end
```js
var result = sass.renderSync({file: "style.scss"});
console.log(result.css.toString());
```
#### `result.map`
The source map that maps the compiled CSS to the source files from which it was
generated, as a [Buffer][]. This can be converted to a string by calling
[`Buffer.toString()`][].
This is `null` or `undefined` unless either
* the [`sourceMap` option][] is a string; or
* the `sourceMap` option is `true` *and* the [`outFile` option][] is set.
The source map uses absolute [`file:` URLs][] to link to the Sass source files,
except if the source file comes from the [`data` option][] in which case it
lists its URL as `stdin`.
[`sourceMap` option]: #sourcemap
[`outFile` option]: #outfile
[`file:` URLs]: https://en.wikipedia.org/wiki/File_URI_scheme
```js
var result = sass.renderSync({
file: "style.scss",
sourceMap: true,
outFile: "style.css"
})
console.log(result.map.toString());
```
#### `result.stats.includedFiles`
An array of the absolute paths of all Sass files loaded during compilation. If a
stylesheet was loaded from an [importer][] that returned the stylesheet's
contents, the raw string of the `@use` or `@import` that loaded that stylesheet
is included in this array.
[importer]: #importer
#### `result.stats.entry`
The absolute path of the input file passed as the [`file` option], or `"data"`
if the [`data` option] was passed instead.
#### `result.stats.start`
The number of milliseconds between 1 January 1970 at 00:00:00 UTC and the time
at which Sass compilation began.
#### `result.stats.end`
The number of milliseconds between 1 January 1970 at 00:00:00 UTC and the time
at which Sass compilation ended.
#### `result.stats.duration`
The number of milliseconds it took to compile the Sass file. This is always
equal to [`result.stats.start`][] minus [`result.stats.end`][].
[`result.stats.start`]: #result-stats-start
[`result.stats.end`]: #result-stats-end
### Error Object
When [`renderSync()`][] or [`render()`][] fail, they provide an
[`Error` object][] that contains information about the compilation. This object
has the following properties, in addition to the standard `Error` properties:
[`Error` object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
#### `error.formatted`
A string representation of the error. In [Node Sass][], this is more detailed
than [`error.toString()`][] or [`error.message`][]. In [Dart Sass][], it
provides the same information.
[Dart Sass]: /dart-sass
[`error.toString()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/toString
[`error.message`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/message
#### `error.file`
The stylesheet where the error occurred. If the error occurred in a stylesheet
loaded from disk, this is the absolute path of that stylesheet. If the error
occurred in a stylesheet that was loaded from an [importer][] which returned the
stylesheet's contents, this is the raw string of the `@use` or `@import` that
loaded that stylesheet. If it occurred in the contents of the [`data` option][],
this is the string `"stdin"`.
#### `error.line`
The line in [`error.file`][] on which the error occurred.
[`error.file`]: #error-file
#### `error.column`
The column of [`error.line`][] in [`error.file`][] on which the error occurred.
[`error.line`]: #error-line
#### `error.status`
The [exit status][] that should be used if this error causes the enclosing
program to exit.
[exit status]: https://en.wikipedia.org/wiki/Exit_status
## Options
### Input
These options control how Sass loads it input files.
#### `file`
<% impl_status dart: '1.11.0', node: :partial, feature: "Plain CSS Files" do %>
Node Sass and older versions of Dart Sass support loading files with the
extension `.css`, but contrary to the specification they're treated as SCSS
files rather than being parsed as CSS. This behavior has been deprecated in
Node Sass, and an update is in the works to load them as plain CSS instead.
All versions of Node Sass and Dart Sass otherwise support the `file` option as
described below.
<% end %>
This string option is the path to the file for Sass to load and compile. If the
file's extension is `.scss`, it will be parsed as [SCSS][]; if it's `.sass`, it
will be parsed as the [indented syntax][]; and if it's `.css`, it will be parsed
as [plain CSS][]. If it has no extension, it will be parsed as SCSS.
[SCSS]: syntax#scss
[indented syntax]: syntax#the-indented-syntax
[plain CSS]: at-rules/import#importing-css
If the `file` option and the [`data` option][] are both passed, the `file`
option is used as the path of the stylesheet for error reporting, but the `data`
option is used as the contents of the stylesheet. In this case, the `file`
option's extension is *not* used to determine the syntax of the stylesheet.
```js
sass.renderSync({file: "style.scss"});
```
#### `data`
This string option provides the contents of the stylesheet to compile. Unless
the [`file` option][] is passed as well, the stylesheet's URL is set to
`"stdin"`.
By default, this stylesheet is parsed as [SCSS][]. This can be controlled using
the [`indentedSyntax` option][].
[`indentedSyntax` option]: #indentedsyntax
```js
sass.renderSync({
data: `
h1 {
font-size: 40px;
}`
});
```
### `indentedSyntax`
This flag controls whether the [`data` option][] is parsed as the [indented
syntax][] or not. It defaults to `false`. It has no effect on stylesheets loaded
using the [`file` option][].
```js
sass.renderSync({
data: `
h1
font-size: 40px`,
indentedSyntax: true
});
```
### `includePaths`
<% impl_status dart: '1.15.0', node: '3.9.0', feature: "SASS_PATH" do %>
Earlier versions of Dart Sass and Node Sass didn't support the `SASS_PATH`
environment variable.
<% end %>
This array of strings option provides [load paths][] for Sass to look for
imports. Earlier load paths will take precedence over later ones.
[load paths]: at-rules/import#load-paths
```js
sass.renderSync({
file: "style.scss",
includePaths: ["node_modules/bootstrap/dist/css"]
});
```
Load paths are also loaded from the `SASS_PATH` [environment variable][], if
it's set. This variable should be a list of paths separated by `;` (on Windows)
or `:` (on other operating systems). Load paths from the `includePaths` option
take precedence over load paths from `SASS_PATH`.
[environment variable]: https://en.wikipedia.org/wiki/Environment_variable
```shellsession
$ SASS_PATH=node_modules/bootstrap/dist/css sass style.scss style.css
```
### Output
These options control how Sass produces output files.
#### `outputStyle`
This string option controls the output style of the resulting CSS. There are
four possible output styles:
* `"expanded"` (the default for Dart Sass) writes each selector and declaration
on its own line.
* `"compressed"` removes as many extra characters as possible, and writes the
entire stylesheet on a single line.
* `"nested"` (the default for Node Sass, not supported by Dart Sass) indents CSS
rules to match the nesting of the Sass source.
* `compact` (not supported by Dart Sass) puts each CSS rule on its own single
line.
```js
var source = `
h1 {
font-size: 40px;
code {
font-face: Roboto Mono;
}
}`;
var result = sass.renderSync({
data: source,
outputStyle: "expanded"
});
console.log(result.css.toString());
// h1 {
// font-size: 40px;
// }
// h1 code {
// font-face: Roboto Mono;
// }
result = sass.renderSync({
data: source,
outputStyle: "compressed"
});
console.log(result.css.toString());
// h1{font-size:40px}h1 code{font-face:Roboto Mono}
result = sass.renderSync({
data: source,
outputStyle: "nested"
});
console.log(result.css.toString());
// h1 {
// font-size: 40px; }
// h1 code {
// font-face: Roboto Mono; }
result = sass.renderSync({
data: source,
outputStyle: "compact"
});
console.log(result.css.toString());
// h1 { font-size: 40px; }
// h1 code { font-face: Roboto Mono; }
```
#### `precision`
<% impl_status dart: false, node: true do %>
For performance reasons, Dart Sass doesn't allow its precision to be
customized. It always supports 10 digits of numeric precision.
<% end %>
This integer option determines the [precision][] that will be used when
generating CSS that includes numbers. It defaults to 5 for Node Sass.
[precision]: values/numbers#precision
```js
var result = sass.renderSync({
data: `
h1 {
font-size: (100px / 3);
}`,
precision: 20
});
console.log(result.css.toString());
// h1 {
// font-size: 33.333333333333336px; }
```
#### `indentType`
<% impl_status dart: true, node: '3.0.0' %>
This string option determines whether the generated CSS should use spaces (with
the value `"space"`) or tabs (with the value `"tab"`) for indentation. It
defaults to `"space"`.
```js
var result = sass.renderSync({
file: "style.scss",
indentType: "tab",
indentWidth: 1
});
result.css.toString();
// "h1 {\n\tfont-size: 40px;\n}\n"
```
#### `indentWidth`
<% impl_status dart: true, node: '3.0.0' %>
This integer option controls how many spaces or tabs (depending on the
[`indentType` option][]) should be used per indentation level in the generated
CSS. It defaults to 2, and must be between 0 and 10 (inclusive).
[`indentType` option]: #indenttype
```js
var result = sass.renderSync({
file: "style.scss",
indentWidth: 4
});
console.log(result.css.toString());
// h1 {
// font-size: 40px;
// }
```
#### `linefeed`
<% impl_status dart: true, node: '3.0.0' %>
This string option controls what character sequence is used at the end of each
line in the generated CSS. It can have the following values:
* `lf` (the default) uses U+000A LINE FEED.
* `lfcr` uses U+000A LINE FEED followed by U+000D CARRIAGE RETURN.
* `cr` (the default) uses U+000D CARRIAGE RETURN.
* `crlf` uses U+000D CARRIAGE RETURN followed by U+000A LINE FEED.
```js
var result = sass.renderSync({
file: "style.scss",
linefeed: "crlf"
});
console.log(result.css.toString());
// "h1 {\r\n font-size: 40px;\r\n}\r\n"
```
#### `sourceComments`
<% impl_status dart: false, node: true do %>
This option isn't supported by Dart Sass, because source maps are recommended
as the best way of determining where a style rule is defined.
<% end %>
This flag causes Sass to emit comments for every style rule that indicate where
each style rule was defined in the source stylesheet. It defaults to `false`.
```js
var result = sass.renderSync({
file: "style.scss",
sourceComments: true
});
console.log(result.css.toString());
// /* line 1, style.scss */
// h1 {
// font-size: 40px;
// }
```
### Source Maps
<%= partial 'documentation/snippets/source-maps' %>
The Sass JS API makes source maps available using the [`result.map` field][].
[`result.map` field]: #result-map
#### `sourceMap`
This flag controls whether source maps are generated.
If this option is a string, it's the path that the source map is expected to be
written to, which is used to link to the source map from the generated CSS and
to link *from* the source map to the Sass source files. Note that if the
`sourceMap` option is a string and the [`outFile` option][] isn't passed, Sass
assumes that the CSS will be written to the same directory as the [`file`
option][] if it's passed.
If this option is `true`, the path is assumed to be the `outFile` option with
`.map` added to the end. If it's `true` and the `outFile` option isn't passed,
it has no effect.
```js
var result = sass.renderSync({
file: "style.scss",
sourceMap: "out.map"
})
console.log(result.css.toString());
// h1 {
// font-size: 40px;
// }
// /*# sourceMappingURL=out.map */
result = sass.renderSync({
file: "style.scss",
sourceMap: true,
outFile: "out.css"
})
console.log(result.css.toString());
// h1 {
// font-size: 40px;
// }
// /*# sourceMappingURL=out.css.map */
```
#### `outFile`
This string option is the location that Sass expects the generated CSS to be
saved to. It's used to determine the URL used to link from the generated CSS to
the source map, and *from* the source map to the Sass source files.
<% heads_up do %>
Despite the name, Sass does *not* write the CSS output to this file. The
caller must do that themselves.
<% end %>
```js
result = sass.renderSync({
file: "style.scss",
sourceMap: true,
outFile: "out.css"
})
console.log(result.css.toString());
// h1 {
// font-size: 40px;
// }
// /*# sourceMappingURL=out.css.map */
```
#### `omitSourceMapUrl`
This flag causes Sass not to link from the generated CSS to the source map.
```js
var result = sass.renderSync({
file: "style.scss",
sourceMap: "out.map",
omitSourceMapUrl: true
})
console.log(result.css.toString());
// h1 {
// font-size: 40px;
// }
```
#### `sourceMapContents`
This flag tells Sass to embed the entire contents of the Sass files that
contributed to the generated CSS in the source map. This may produce very large
source maps, but it guarantees that the source will be available on any computer
no matter how the CSS is served.
```js
sass.renderSync({
file: "style.scss",
sourceMap: "out.map",
sourceMapContents: true
})
```
#### `sourceMapEmbed`
This flag tells Sass to embed the contents of the source map file in the
generated CSS, rather than creating a separate file and linking to it from the
CSS.
```js
sass.renderSync({
file: "style.scss",
sourceMap: "out.map",
sourceMapEmbed: true
})
```
#### `sourceMapRoot`
This string option is prepended to all the links from the source map to the Sass
source files.
### Plugins
These options use JavaScript callbacks to expand the functionality of Sass
compilation.
#### `fiber`
When using Dart Sass, **`renderSync()` is more than twice as fast as
`render()`**, due to the overhead of asynchronous callbacks. To avoid this
performance hit, `render()` can use the [`fibers`][fibers] package to call
asynchronous importers from the synchronous code path. To enable this, pass the
`Fiber` class to the `fiber` option:
[fibers]: https://www.npmjs.com/package/fibers
```js
var sass = require("sass");
var Fiber = require("fibers");
sass.render({
file: "input.scss",
importer: function(url, prev, done) {
// ...
},
fiber: Fiber
}, function(err, result) {
// ...
});
```
This option is allowed, but will have no effect, when using Node Sass or when
using the `renderSync()` function.
#### `functions`
This option defines additional built-in Sass functions that are available in all
stylesheets. It's an object whose keys are Sass function signatures and whose
values are JavaScript functions. Each function should take the same arguments as
its signature. If the signature takes [arbitrary arguments][], the JavaScript
function should take a single argument.
[arbitrary arguments]: at-rules/function#taking-arbitrary-arguments
Functions are passed JavaScript representations of [Sass value types][], and
must return the same. All functions can return synchronously, but functions
passed to the asynchronous [`render()` function][] can also take an additional
callback to which they can asynchronously pass the result of the function when
it's complete.
[Sass value types]: #value-types
[`render()` function]: #render
If a function synchronously throws an error, that error is reported to the
caller of the function and stylesheet compilation fails. There's currently no
way to asynchronously report an error.
<% heads_up do %>
When writing custom functions, it's important to ensure that all the arguments
are the types you expect. Otherwise, users' stylesheets could crash in
hard-to-debug ways or, worse, compile to meaningless CSS.
<% end %>
```js
sass.render({
data: `
h1 {
font-size: pow(2, 5) * 1px;
}`,
functions: {
// This function uses the synchronous API, and can be passed to either
// renderSync() or render().
'pow($base, $exponent)': function(base, exponent) {
if (!(base instanceof sass.types.Number)) {
throw "$base: Expected a number.";
} else if (base.getUnit()) {
throw "$base: Expected a unitless number.";
}
if (!(exponent instanceof sass.types.Number)) {
throw "$exponent: Expected a number.";
} else if (exponent.getUnit()) {
throw "$exponent: Expected a unitless number.";
}
return new sass.types.Number(
Math.pow(base.getValue(), exponent.getValue()));
},
// This function uses the asynchronous API, and can only be passed to
// render().
'sqrt($number)': function(number, done) {
if (!(number instanceof sass.types.Number)) {
throw "$number: Expected a number.";
} else if (number.getUnit()) {
throw "$number: Expected a unitless number.";
}
done(new sass.types.Number(Math.sqrt(number.getValue())));
}
}
}, function(err, result) {
console.log(result.css.toString());
// h1 {
// font-size: 32px;
// }
});
```
#### `importer`
<% impl_status dart: true, node: '3.0.0' do %>
Versions of Node Sass before 3.0.0 don't support arrays of importers,
nor do they support importers that return `Error` objects.
Versions of Node Sass before 2.0.0 don't support the `importer` option at all.
<% end %>
<% impl_status dart: '1.20.2', node: false, feature: "Import order" do %>
Versions of Dart Sass before 1.20.2 preferred resolving imports using load
paths ([includePaths](#includepaths)) before resolving them using custom
importers.
All versions of Node Sass currently pass imports to importers before loading
them relative to the file in which the `@import` appears. This behavior is
considered incorrect and should not be relied on because it violates the
principle of *locality*, which says that it should be possible to reason about
a stylesheet without knowing everything about how the entire system is set up.
If a user tries to import a stylesheet relative to another stylesheet, that
import should *always* work. It shouldn't be possible for some configuration
somewhere else to break it.
<% end %>
This option defines one or more additional handlers for loading files when a
[`@use` rule] or an [`@import` rule][] is encountered. It can either be a single
JavaScript function, or an array of functions. These functions are always passed
two arguments:
[`@use` rule]: at-rules/use
[`@import` rule]: at-rules/import
1. The `@use` or `@import` rule's URL as a string, exactly as it appears in the
stylesheet.
2. A string identifying for the stylesheet that contained the `@use` or
`@import`. This identifier's format depends on how that stylesheet was
loaded:
* If the stylesheet was loaded from the filesystem, it's the absolute path of
its file.
* If the stylesheet was loaded from an importer that returned its contents,
it's the URL of the `@use` or `@import` rule that loaded it.
* If the stylesheet came from the [`data` option][], it's the string
`"stdin"`.
Importers must return one of the following types:
* An object with the key `contents` whose value is the contents of a stylesheet
(in SCSS syntax). This causes Sass to load that stylesheet's contents.
* An object with the key `file` whose value is a path on disk. This causes Sass
to load that file as though it had been imported directly.
* `null`, which indicates that it doesn't recognize the URL and another importer
should be tried instead.
* An [`Error` object][], indicating that importing failed.
All importers can return synchronously, but importers passed to the asynchronous
[`render()` function][] can also take an additional callback to which they can
asynchronously pass the result of the import once it's complete.
Imports are resolved by trying, in order:
* Loading a file relative to the file in which the `@use` or `@import` appeared.
* Each custom importer.
* Loading a file relative to the current working directory.
* Each load path in [includePaths](#includepaths)
* Each load path specified in the `SASS_PATH` environment variable, which
should be semicolon-separated on Windows and colon-separated elsewhere.
<% impl_status dart: '1.33.0', node: false, feature: "this.fromImport" %>
An importer can determine whether it's being called from an `@import` rule by
checking `this.fromImport`. This should *only* be used for determining whether
or not to load [import-only files].
[import-only files]: https://sass-lang.com/documentation/at-rules/import#import-only-files
```js
sass.render({
file: "style.scss",
importer: [
// This importer uses the synchronous API, and can be passed to either
// renderSync() or render().
function(url, prev) {
// This generates a stylesheet from scratch for `@use "big-headers"`.
if (url != "big-headers") return null;
return {
contents: `
h1 {
font-size: 40px;
}`
};
},
// This importer uses the asynchronous API, and can only be passed to
// render().
function(url, prev, done) {
// Convert `@use "foo/bar"` to "node_modules/foo/sass/bar".
var components = url.split('/');
var innerPath = components.slice(1).join('/');
done({
file: `node_modules/${components.first}/sass/${innerPath}`
});
}
]
}, function(err, result) {
// ...
});
```
## Value Types
In order to support [custom functions][], Sass provides access to JavaScript
wrappers for its various [value types][]. These are all provided under the
`types` namespace in the main Sass module.
[custom functions]: #functions
[value types]: values
<% heads_up do %>
All value types support methods that modify the value objects. Users are
strongly discouraged from using these methods (except for the [`Map` type][]
and [`List` type][] where they're necessary to create new values), because
they don't match the general principle that Sass values are immutable. Users
should construct new objects rather than modifying existing ones.
[`Map` type]: #types-map
[`List` type]: #types-list
<% end %>
### `types.Number`
This class represents a [Sass number][].
[Sass number]: values/numbers
#### `new types.Number(value[, unit = ''])`
Creates a new Sass number with the given numeric value and string unit.
[Complex units][] are parsed from the unit string: numerator units are separated
from denominators by a `/`. Multiple numerator and/or denominator units may be
separated by `*`.
[Complex units]: values/numbers#units
```js
new sass.types.Number(0.5); // == 0.5
new sass.types.Number(10, "px"); // == 10px
new sass.types.Number(10, "px*px"); // == 10px * 1px
new sass.types.Number(10, "px/s"); // == 10px / 1s
new sass.types.Number(10, "px*px/s*s"); // == 10px * 1px / 1s / 1s
```
#### `number.getValue()`
Returns the value of the number, ignoring units.
<% heads_up do %>
This means that `96px` and `1in` will return different values, even though
they represent the same length.
<% end %>
```js
var number = new sass.types.Number(10, "px");
console.log(number.getValue()); // 10
```
#### `number.getUnit()`
Returns the units of the number as a string. Complex units are returned in the
same format that [the constructor][new Number] accepts them.
[new Number]: #new-types-number-value-unit
```js
// number is `10px`.
console.log(number.getUnit()); // "px"
// number is `10px / 1s`.
console.log(number.getUnit()); // "px/s"
```
#### `number.setValue(value)`
Sets the value of the number, independent of its units.
#### `number.setUnit(unit)`
Sets the units of the number, independent of its numeric value. Complex units
are specified in the same format as for [the constructor][new Number].
### `types.String`
This class represents a [Sass string][].
[Sass string]: values/strings
<% heads_up do %>
This API currently provides no way of distinguishing between a [quoted][] and
[unquoted][] string.
[quoted]: values/strings#quoted
[unquoted]: values/strings#unquoted
<% end %>
#### `new types.String(value)`
Creates a new unquoted Sass string with the given value.
<% heads_up do %>
This API currently provides no way of creating a [quoted][] string.
[quoted]: values/strings#quoted
<% end %>
```js
new sass.types.String("Arial"); // == Arial
```
#### `string.getValue()`
Returns the contents of the string. If the string contains escapes, those
escapes are included literally if it's [unquoted][], while the values of the
escapes are included if it's [quoted][].
[unquoted]: values/strings#unquoted
[quoted]: values/strings#quoted
```js
// string is `Arial`.
string.getValue(); // "Arial"
// string is `"Helvetica Neue"`.
string.getValue(); // "Helvetica Neue"
// string is `\1F46D`.
string.getValue(); // "\\1F46D"
// string is `"\1F46D"`.
string.getValue(); // "👭"
```
#### `string.setValue(value)`
Sets the contents of the string.
<% heads_up do %>
Even if the string was originally quoted, this will cause it to become
unquoted.
<% end %>
### `types.Color`
This class represents a [Sass color][].
[Sass color]: values/colors
#### `new types.Color(red, green, blue[, alpha = 1])`
Creates a new Sass color with the given red, green, blue, and alpha channels.
The red, green, and blue channels must be integers between 0 and 255
(inclusive), and alpha must be between 0 and 1 (inclusive).
```js
new sass.types.Color(107, 113, 127); // #6b717f
new sass.types.Color(0, 0, 0, 0); // rgba(0, 0, 0, 0)
```
#### `new types.Color(argb)`
Creates a new Sass color with alpha, red, green, and blue channels taken from
respective two-byte chunks of a hexidecimal number.
```js
new sass.types.Color(0xff6b717f); // #6b717f
new sass.types.Color(0x00000000); // rgba(0, 0, 0, 0)
```