sass
Index
Compile
Options
Logger
Importer
Custom Function
Other
Legacy
Compile
compile
Parameters
path: string
Optional options: Options<"sync">
Returns CompileResult
compile
- Dart Sass
- since 1.45.0
- Node Sass
- ✗
Compatibility:Asynchronously compiles the Sass file at
pathto CSS. Returns a promise that resolves with a CompileResult if it succeeds and rejects with an Exception if it fails.This only allows synchronous or asynchronous Importers and CustomFunctions.
⚠️ Heads up!
When using Dart Sass, compile is almost twice as fast as compileAsync, due to the overhead of making the entire evaluation process asynchronous.
Parameters
path: string
Optional options: Options<"async">
Returns Promise<CompileResult>
compile
- Dart Sass
- since 1.45.0
- Node Sass
- ✗
Compatibility:Synchronously compiles a stylesheet whose contents is
sourceto CSS. If it succeeds it returns a CompileResult, and if it fails it throws an Exception.This only allows synchronous Importers and CustomFunctions.
Parameters
source: string
Optional options: StringOptions<"sync">
Returns CompileResult
compile
- Dart Sass
- since 1.45.0
- Node Sass
- ✗
Compatibility:Asynchronously compiles a stylesheet whose contents is
sourceto CSS. Returns a promise that resolves with a CompileResult if it succeeds and rejects with an Exception if it fails.This only allows synchronous or asynchronous Importers and CustomFunctions.
⚠️ Heads up!
When using Dart Sass, compile is almost twice as fast as compileAsync, due to the overhead of making the entire evaluation process asynchronous.
Parameters
source: string
Optional options: StringOptions<"async">
Returns Promise<CompileResult>
Options
Output
Possible output styles for the compiled CSS:
"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.
String
Options that can be passed to compileString or compileStringAsync.
This is a StringOptionsWithImporter if it has a StringOptionsWithImporter.importer field, and a StringOptionsWithoutImporter otherwise.
Type parameters
sync: "sync" | "async"
This lets the TypeScript checker verify that asynchronous Importers, FileImporters, and CustomFunctions aren't passed to compile or compileString.
Syntax
Syntaxes supported by Sass:
'scss'is the SCSS syntax.'indented'is the indented syntax'css'is plain CSS, which is parsed like SCSS but forbids the use of any special Sass features.
Custom Function
Custom
Type parameters
sync: "sync" | "async"
A
CustomFunction<'sync'>must return synchronously, but in return it can be passed to compile and compileString in addition to compileAsync and compileStringAsync.A
CustomFunction<'async'>may either return synchronously or asynchronously, but it can only be used with compileAsync and compileStringAsync.
Type declaration
A callback that implements a custom Sass function. This can be passed to Options.functions.
const result = sass.compile('style.scss', {
functions: {
"sum($arg1, $arg2)": (args) => {
const value1 = args[0].assertNumber('arg1').value;
const value2 = args[1].assertNumber('arg2')
.convertValueToMatch(arg1, 'arg2', 'arg1');
return new sass.SassNumber(value1 + value2).coerceToMatch(arg1);
}
}
});Parameters
args: Value[]
An array of arguments passed by the function's caller. If the function takes arbitrary arguments, the last element will be a SassArgumentList.
Returns PromiseOr<Value, sync>
The function's result. This may be in the form of a
Promise, but if it is the function may only be passed to compileAsync and compileStringAsync, not compile or compileString.
List
Possible separators used by Sass lists. The special separator null is only used for lists with fewer than two elements, and indicates that the separator has not yet been decided for this list.
sass
Sass's false value.
sass
Sass's null value.
sass
Sass's true value.
Other
Promise
A utility type for choosing between synchronous and asynchronous return values.
This is used as the return value for plugins like CustomFunction, Importer, and FileImporter so that TypeScript enforces that asynchronous plugins are only passed to compileAsync and compileStringAsync, not compile or compileString.
Type parameters
T
sync: "sync" | "async"
If this is
'sync', this can only be aT. If it's'async', this can be either aTor aPromise<T>.
info
Information about the Sass implementation. This always begins with a unique identifier for the Sass implementation, followed by U+0009 TAB, followed by its npm package version. Some implementations include additional information as well, but not in any standardized format.
- For Dart Sass, the implementation name is
dart-sass. - For Node Sass, the implementation name is
node-sass. - For the embedded host, the implementation name is
sass-embedded.
Legacy
Legacy
Type declaration
An asynchronous callback that implements a custom Sass function. This can be passed to LegacySharedOptions.functions, but only for render.
An asynchronous function must return
undefined. Its final argument will always be a callback, which it should call with the result of the function once it's done running.If this throws an error, Sass will treat that as the function failing with that error message.
sass.render({
file: 'style.scss',
functions: {
"sum($arg1, $arg2)": (arg1, arg2, done) => {
if (!(arg1 instanceof sass.types.Number)) {
throw new Error("$arg1: Expected a number");
} else if (!(arg2 instanceof sass.types.Number)) {
throw new Error("$arg2: Expected a number");
}
done(new sass.types.Number(arg1.getValue() + arg2.getValue()));
}
}
}, (result, error) => {
// ...
});Parameters
this: LegacyPluginThis
Rest …args: […LegacyValue[], (result: LegacyValue) => void]
One argument for each argument that's declared in the signature that's passed to LegacySharedOptions.functions. If the signature takes arbitrary arguments, they're passed as a single argument list in the last argument before the callback.
Returns void
Legacy
Type declaration
An asynchronous callback that implements custom Sass loading logic for
@importrules and@userules. This can be passed to LegacySharedOptions.importer for either render or renderSync.An asynchronous importer must return
undefined, and then calldonewith the result of its LegacyImporterResult once it's done running.See LegacySharedOptions.importer for more detailed documentation.
sass.render({
file: "style.scss",
importer: [
function(url, prev, done) {
if (url != "big-headers") done(null);
done({
contents: 'h1 { font-size: 40px; }'
});
}
]
});Parameters
this: LegacyImporterThis
url: string
The
@useor@importrule’s URL as a string, exactly as it appears in the stylesheet.prev: string
A string identifying the stylesheet that contained the
@useor@import. This string’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
@useor@importrule that loaded it. - If the stylesheet came from the data option, it’s the string "stdin".
done: (result: LegacyImporterResult) => void
The callback to call once the importer has finished running.
Parameters
result: LegacyImporterResult
Returns void
Returns void
Legacy
A callback that implements a custom Sass function. For renderSync, this must be a LegacySyncFunction which returns its result directly; for render, it may be either a LegacySyncFunction or a LegacyAsyncFunction which calls a callback with its result.
See LegacySharedOptions.functions for more details.
Type parameters
sync: "sync" | "async"
Legacy
A callback that implements custom Sass loading logic for @import rules and @use rules. For renderSync, this must be a LegacySyncImporter which returns its result directly; for render, it may be either a LegacySyncImporter or a LegacyAsyncImporter which calls a callback with its result.
See LegacySharedOptions.importer for more details.
Type parameters
sync = "sync" | "async"
Legacy
The result of running a LegacyImporter. It must be one of the following types:
An object with the key
contentswhose value is the contents of a stylesheet (in SCSS syntax). This causes Sass to load that stylesheet’s contents.An object with the key
filewhose 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.
Legacy
Options for render and renderSync. This can either be LegacyFileOptions to load a file from disk, or LegacyStringOptions to compile a string of Sass code.
See LegacySharedOptions for options that are shared across both file and string inputs.
Type parameters
sync: "sync" | "async"
Legacy
Type declaration
A synchronous callback that implements a custom Sass function. This can be passed to LegacySharedOptions.functions for either render or renderSync.
If this throws an error, Sass will treat that as the function failing with that error message.
const result = sass.renderSync({
file: 'style.scss',
functions: {
"sum($arg1, $arg2)": (arg1, arg2) => {
if (!(arg1 instanceof sass.types.Number)) {
throw new Error("$arg1: Expected a number");
} else if (!(arg2 instanceof sass.types.Number)) {
throw new Error("$arg2: Expected a number");
}
return new sass.types.Number(arg1.getValue() + arg2.getValue());
}
}
});Parameters
this: LegacyPluginThis
Rest …args: LegacyValue[]
One argument for each argument that's declared in the signature that's passed to LegacySharedOptions.functions. If the signature takes arbitrary arguments, they're passed as a single argument list in the last argument.
Returns LegacyValue
Legacy
Type declaration
A synchronous callback that implements custom Sass loading logic for
@importrules and@userules. This can be passed to LegacySharedOptions.importer for either render or renderSync.See LegacySharedOptions.importer for more detailed documentation.
sass.renderSync({
file: "style.scss",
importer: [
function(url, prev) {
if (url != "big-headers") return null;
return {
contents: 'h1 { font-size: 40px; }'
};
}
]
});Parameters
this: LegacyImporterThis
url: string
The
@useor@importrule’s URL as a string, exactly as it appears in the stylesheet.prev: string
A string identifying the stylesheet that contained the
@useor@import. This string’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
@useor@importrule that loaded it. - If the stylesheet came from the data option, it’s the string "stdin".
Returns LegacyImporterResult
Legacy
A type representing all the possible values that may be passed to or returned from a LegacyFunction.
render
This function asynchronously compiles a Sass file to CSS, and calls
callbackwith a LegacyResult if compilation succeeds or LegacyException if it fails.⚠️ Heads up!
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.
const sass = require('sass'); // or require('node-sass');
sass.render({
file: "style.scss"
}, function(err, result) {
// ...
});Parameters
options: LegacyOptions<"async">
callback: (exception?: LegacyException, result?: LegacyResult) => void
Parameters
Optional exception: LegacyException
Optional result: LegacyResult
Returns void
Returns void
render
This function synchronously compiles a Sass file to CSS. If it succeeds, it returns the result, and if it fails it throws an error.
Parameters
options: LegacyOptions<"sync">
Returns LegacyResult
Synchronously compiles the Sass file at
pathto CSS. If it succeeds it returns a CompileResult, and if it fails it throws an Exception.This only allows synchronous Importers and CustomFunctions.