Interface SassOptions

Paths in which to look for stylesheets loaded by rules like @use and @import.

A load path loadPath is equivalent to the following FileImporter:

{
  findFileUrl(url) {
    // Load paths only support relative URLs.
    if (/^[a-z]+:/i.test(url)) return null;
    return new URL(url, pathToFileURL(loadPath));
  }
}
Copy

If this is true, the compiler will exclusively use ASCII characters in its error and warning messages. Otherwise, it may use non-ASCII Unicode characters as well.

Default Value

false

If this is true, the compiler will use ANSI color escape codes in its error and warning messages. If it's false, it won't use these. If it's undefined, the compiler will determine whether or not to use colors depending on whether the user is using an interactive terminal.

An object to use to handle warnings and/or debug messages from Sass.

By default, Sass emits warnings and debug messages to standard error, but if Logger.warn or Logger.debug is set, this will invoke them instead.

The special value Logger.silent can be used to easily silence all messages.

If this option is set to true, Sass won’t print warnings that are caused by dependencies. A “dependency” is defined as any file that’s loaded through loadPaths or importers. Stylesheets that are imported relative to the entrypoint are not considered dependencies.

This is useful for silencing deprecation warnings that you can’t fix on your own. However, please also notify your dependencies of the deprecations so that they can get fixed as soon as possible!

Heads up! If compileString or compileStringAsync is called without StringOptionsWithoutImporter.url, all stylesheets it loads will be considered dependencies. Since it doesn’t have a path of its own, everything it loads is coming from a load path rather than a relative import.

Default Value

false

By default, Dart Sass will print only five instances of the same deprecation warning per compilation to avoid deluging users in console noise. If you set verbose to true, it will instead print every deprecation warning it encounters.

Default Value

false

should Autoprefixer add prefixes.

If relying upon the fs.Stats object that may get passed with add, addDir, and change events, set this to true to ensure it is provided even in cases where it wasn't already available from the underlying watch events.

true if useFsEvents and usePolling are false). Automatically filters out artifacts that occur when using editors that use "atomic writes" instead of writing directly to the source file. If a file is re-added within 100 ms of being deleted, Chokidar emits a change event rather than unlink then add. If the default of 100 ms does not work well for you, you can override it by setting atomic to a custom value, in milliseconds.

can be set to an object in order to adjust timing params:

Interval of file system polling for binary files. ([see list of binary extensions](https://gi thub.com/sindresorhus/binary-extensions/blob/master/binary-extensions.json))

The browser(s) to open Default: default

Register callbacks via a regular option - this can be used to get access the Browsersync instance in situations where you cannot provide a callback via the normal API (for example, in a Gruntfile)

This 'ready' callback can be used to access the Browsersync instance

should Autoprefixer use Visual Cascade, if CSS is uncompressed

¯_(ツ)_/¯ Best guess, when ghostMode (or SocketIO?) is setup the events listed here will be emitted and able to hook into.

Send file-change events to the browser Default: true

Add HTTP access control (CORS) headers to assets served by Browsersync. Default: false Note: Requires at least version 2.16.0.

Current working directory

If set, limits how many levels of subdirectories will be traversed.

If set to true then the strings passed to .watch() and .add() are treated as literal path names, even if they look like globs. Default: false.

environment for Browserslist

¯_(ツ)_/¯

Browsersync can watch your files as you work. Changes you make will either be injected into the page (CSS & images) or will cause all browsers to do a full-page refresh. See anymatch for more information on glob patterns. Default: false

should Autoprefixer add prefixes for flexbox properties

When false, only the symlinks themselves will be watched for changes instead of following the link references and bubbling events through the link's path.

Clicks, Scrolls & Form inputs on any device will be mirrored to all others. clicks - Default: true scroll - Default: true forms - Default: true

should Autoprefixer add IE 10-11 prefixes for Grid Layout properties

Override host detection if you know the correct IP to use

Override http module to allow using 3rd party server modules (such as http2).

Enable https for localhost development. Note: This may not be needed for proxy option as it will try to infer from your target url. Note: If privacy error is encountered please see HttpsOptions below, setting those will resolve. Note: Requires at least version 1.3.0.

Patterns for any watchers to ignore. Anything provided here will end up inside 'watchOptions.ignored'.

If set to false then add/addDir events are also emitted for matching paths while instantiating the watching as chokidar discovers these file paths (before the ready event).

Indicates whether to watch files that don't have read permissions if possible. If watching fails due to EPERM or EACCES with this set to true, the errors will be suppressed silently.

do not raise error on unknown browser version in Browserslist config.

(anymatch-compatible definition) Defines files/paths to be ignored. The whole relative or absolute path is tested, not just filename. If a function with two arguments is provided, it gets called twice per path - once with a single argument (the path), second time with two arguments (the path and the fs.Stats object of that path).

Whether to inject changes (rather than a page refresh) Default: true

¯_(ツ)_/¯

Interval of file system polling.

Specify a host to listen on. Use this if you want to prevent binding to all interfaces.

Note: When you specify this option, it overrides the 'host' option

Support environments where dynamic hostnames are not required (ie: electron).

Whether or not to log connections Default: false

Whether or not to log information about changed files Default: false

Can be either "info", "debug", "warn", or "silent" Default: info

Change the console logging prefix. Useful if you're creating your own project based on Browsersync Default: BS Note: Requires at least version 1.5.1.

Log the snippet to the console when you're in snippet mode (no proxy/server) Default: true Note: Requires at least version 1.5.2.

Functions or actual plugins used as middleware.

Whether to minify the client script Default: true

The small pop-over notifications in the browser are not always needed/wanted. Default: true

Some features of Browsersync (such as xip & tunnel) require an internet connection, but if you're working offline, you can reduce start-up time by setting this option to false

Default: true Decide which URL to open automatically when Browsersync starts. Defaults to "local" if none set. Can be true, local, external, ui, ui-external, tunnel or false

list of queries for target browsers. Try to not use it. The best practice is to use .browserslistrc config or browserslist key in package.json to share target browsers with Babel, ESLint and Stylelint

Indicates whether the process should continue to run as long as files are being watched. If set to false when using fsevents to watch, no more events will be emitted after ready, even if the process continues to run.

User provided plugins Default: [] Note: Requires at least version 2.6.0.

Use a specific port (instead of the one auto-detected by Browsersync) Default: 3000

Proxy an EXISTING vhost. Browsersync will wrap your vhost with a proxy URL to view your site. Passing only a URL as a string equates to passing only target property of ProxyOptions type. target - Default: undefined ws - Default: undefined middleware - Default: undefined reqHeaders - Default: undefined proxyRes - Default: undefined (http.ServerResponse if expecting single parameter) proxyReq - Default: undefined

Restrict the frequency in which browser:reload events can be emitted to connected clients Default: 0 Note: Requires at least version 2.6.0.

Time, in milliseconds, to wait before instructing the browser to reload/inject following a file change event Default: 0

Reload each browser when Browsersync is restarted. Default: false

Emit only the first event during sequential time windows of a specified duration. Note: Requires at least version 2.13.0.

should Autoprefixer [remove outdated] prefixes

Add additional HTML rewriting rules. Default: false Note: Requires at least version 2.4.0.

Configure the script domain

Default: [] Note: Requires at least version 2.9.0. Sync the scroll position of any element on the page - where any scrolled element will cause all others to match scroll position. This is helpful when a breakpoint alters which element is actually scrolling

Sync the scroll position of any element on the page. Add any amount of CSS selectors Default: [] Note: Requires at least version 2.9.0.

scrollProportionally: false // Sync viewports to TOP position Default: true

Decide which technique should be used to restore scroll position following a reload. Can be window.name or cookie Default: 'window.name'

How often to send scroll events Default: 0

Add additional directories from which static files should be served. Should only be used in proxy or snippet mode. Default: [] Note: Requires at least version 2.8.0.

Options that are passed to the serve-static middleware when you use the string[] syntax: eg: serveStatic: ['./app']. Please see serve-static for details.

Use the built-in static server for basic HTML/JS/CSS websites. Default: false

Serve an index.html file for all non-asset routes. Useful when using client-routers.

You can control how the snippet is injected onto each page via a custom regex + function. You can also provide patterns for certain urls that should be ignored from the snippet injection. Note: Requires at least version 2.0.0.

Configure the Socket.IO path and namespace & domain to avoid collisions. path - Default: "/browser-sync/socket.io" clientPath - Default: "/browser-sync" namespace - Default: "/browser-sync" domain - Default: undefined port - Default: undefined clients.heartbeatTimeout - Default: 5000 Note: Requires at least version 1.6.2.

The initial path to load

custom usage statistics for > 10% in my stats browsers query

should Autoprefixer add prefixes for

Supports

parameters.

¯_(ツ)_/¯

Append timestamps to injected files Default: true

Tunnel the Browsersync server through a random Public URL Default: null

Browsersync includes a user-interface that is accessed via a separate port. The UI allows to controls all devices, push sync updates and much more.

port - Default: 3001 weinre.port - Default: 8080 Note: Requires at least version 2.0.0.

Whether to use the fsevents watching interface if available. When set to true explicitly and fsevents is available this supercedes the usePolling setting. When set to false on OS X, usePolling: true becomes the default.

Whether to use fs.watchFile (backed by polling), or fs.watch. If polling leads to high CPU utilization, consider setting this to false. It is typically necessary to set this to true to successfully watch files over a network, and it may be necessary to successfully watch files in other non-standard situations. Setting to true explicitly on OS X overrides the useFsEvents default.

Watch files automatically.

Specify which file events to respond to. Available events: add, change, unlink, addDir, unlinkDir

File watching options that get passed along to Chokidar. Check their docs for available options Default: undefined Note: Requires at least version 2.6.0.

Requires an internet connection - useful for services such as Typekit as it allows you to configure domains such as *.xip.io in your kit settings Default: false

If true, the compiler may prepend @charset "UTF-8"; or U+FEFF (byte-order marker) if it outputs non-ASCII CSS.

If false, the compiler never emits these byte sequences. This is ideal when concatenating or embedding in HTML <style> tags. (The output will still be UTF-8.)

Default Value

true

Compatibility

dart: "1.54.0", node: false

Whether or not Sass should generate a source map. If it does, the source map will be available as CompileResult.sourceMap.

Heads up! Sass doesn't automatically add a sourceMappingURL comment to the generated CSS. It's up to callers to do that, since callers have full knowledge of where the CSS and the source map will exist in relation to one another and how they'll be served to the browser.

Default Value

false

Whether Sass should include the sources in the generated source map.

This option has no effect if sourceMap is false.

Default Value

false

The OutputStyle of the compiled CSS.

Example

const source = `
h1 {
  font-size: 40px;
  code {
    font-face: Roboto Mono;
  }
}`;

let result = sass.compileString(source, {style: "expanded"});
console.log(result.css.toString());
// h1 {
//   font-size: 40px;
// }
// h1 code {
//   font-face: Roboto Mono;
// }

result = sass.compileString(source, {style: "compressed"})
console.log(result.css.toString());
// h1{font-size:40px}h1 code{font-face:Roboto Mono}
Copy

Additional built-in Sass functions that are available in all stylesheets. This option takes an object whose keys are Sass function signatures like you'd write for the @function rule and whose values are CustomFunctions.

Functions are passed JavaScript representations of Sass value types, and must return the same.

When writing custom functions, it's important to make them as user-friendly and as close to the standards set by Sass's core functions as possible. Some good guidelines to follow include:

• Use Value.assert* methods, like Value.assertString, to cast untyped Value objects to more specific types. For values that were passed directly as arguments, pass in the argument name as well. This ensures that the user gets good error messages when they pass in the wrong type to your function.

• Individual classes may have more specific assert* methods, like SassNumber.assertInt, which should be used when possible.

• In Sass, every value counts as a list. Rather than trying to detect the SassList type, you should use Value.asList to treat all values as lists.

• When manipulating values like lists, strings, and numbers that have metadata (comma versus space separated, bracketed versus unbracketed, quoted versus unquoted, units), the output metadata should match the input metadata.

• When in doubt, lists should default to comma-separated, strings should default to quoted, and numbers should default to unitless.

• In Sass, lists and strings use one-based indexing and use negative indices to index from the end of value. Functions should follow these conventions. Value.sassIndexToListIndex and SassString.sassIndexToStringIndex can be used to do this automatically.

• String indexes in Sass refer to Unicode code points while JavaScript string indices refer to UTF-16 code units. For example, the character U+1F60A SMILING FACE WITH SMILING EYES is a single Unicode code point but is represented in UTF-16 as two code units (0xD83D and 0xDE0A). So in JavaScript, "a😊b".charCodeAt(1) returns 0xD83D, whereas in Sass str-slice("a😊b", 1, 1) returns "😊". Functions should follow Sass's convention. SassString.sassIndexToStringIndex can be used to do this automatically, and the SassString.sassLength getter can be used to access a string's length in code points.

Example

sass.compileString(`
h1 {
  font-size: pow(2, 5) * 1px;
}`, {
  functions: {
    // Note: in real code, you should use `math.pow()` from the built-in
    // `sass:math` module.
    'pow($base, $exponent)': function(args) {
      const base = args[0].assertNumber('base').assertNoUnits('base');
      const exponent =
          args[1].assertNumber('exponent').assertNoUnits('exponent');

      return new sass.SassNumber(Math.pow(base.value, exponent.value));
    }
  }
});
Copy

Custom importers that control how Sass resolves loads from rules like @use and @import.

Loads are resolved by trying, in order:

• The importer that was used to load the current stylesheet, with the loaded URL resolved relative to the current stylesheet's canonical URL.

• Each Importer or FileImporter in importers, in order.

• Each load path in loadPaths, in order.

If none of these return a Sass file, the load fails and Sass throws an error.