sass

• Add a split($string, $separator, $limit: null) function to sass:string that splits a string into separate substrings based on a separator string.

JavaScript API

• Potentially breaking bug fix: Custom functions in both the modern and legacy API now properly reject signatures with whitespace between the function name and parentheses.

• Custom functions in the legacy API now allow signatures with whitespace before the function name, to match a bug in Node Sass.

Dart API

• Potentially breaking bug fix: Callable.fromSignature() and AsyncCallable.fromSignature() now reject signatures with whitespace between the function name and parentheses.

Embedded Sass

• The embedded compiler now supports version 1.2.0 of the embedded protocol.

Embedded Sass

• Importer results now validate that contents is actually a string and whether sourceMapUrl is an absolute URL.

• Potentially breaking change: To match the CSS spec, SassScript expressions beginning with not or ( are no longer supported at the beginning of parenthesized sections of media queries. For example,

  @media (width >= 500px) and (not (grid))
  

  will now be emitted unchanged, instead of producing

  @media (width >= 500px) and (false)
  

  See the Sass website for details.

• Potentially breaking bug fix: Angle units like rad or turn are now properly converted to equivalent deg values for hsl(), hsla(), adjust-hue(), color.adjust(), and color.change().

  See the Sass website for details.

• Fix indentation for selectors that span multiple lines in a @media query.

• Emit a deprecation warning when passing $alpha values with units to color.adjust() or color.change(). This will be an error in Dart Sass 2.0.0.

  See the Sass website for details.

• Emit a deprecation warning when passing a $weight value with no units or with units other than % to color.mix(). This will be an error in Dart Sass 2.0.0.

  See the Sass website for details.

• Emit a deprecation warning when passing $n values with units to list.nth() or list.set-nth(). This will be an error in Dart Sass 2.0.0.

  See the Sass website for details.

• Improve existing deprecation warnings to wrap /-as-division suggestions in calc() expressions.

• Properly mark the warning for passing numbers with units to random() as a deprecation warning.

• Fix a bug where @extend could behave unpredicatably when used along with meta.load-css() and shared modules that contained no CSS themselves but loaded CSS from other modules.

Dart API

• Emit a deprecation warning when passing a sassIndex with units to Value.sassIndexToListIndex(). This will be an error in Dart Sass 2.0.0.

JS API

• Importer results now validate whether contents is actually a string type.

• Importer result argument errors are now rendered correctly.

• Potentially breaking bug fix: Sass numbers are now universally stored as 64-bit floating-point numbers, rather than sometimes being stored as integers. This will generally make arithmetic with very large numbers more reliable and more consistent across platforms, but it does mean that numbers between nine quadrillion and nine quintillion will no longer be represented with full accuracy when compiling Sass on the Dart VM.

• Potentially breaking bug fix: Sass equality is now properly transitive. Two numbers are now considered equal (after doing unit conversions) if they round to the same 1e-11th. Previously, numbers were considered equal if they were within 1e-11 of one another, which led to some circumstances where $a == $b and $b == $c but $a != $b.

• Potentially breaking bug fix: Various functions in sass:math no longer treat floating-point numbers that are very close (but not identical) to integers as integers. Instead, these functions now follow the floating-point specification exactly. For example, math.pow(0.000000000001, -1) now returns 1000000000000 instead of Infinity.

• Emit a deprecation warning for $a -$b and $a +$b, since these look like they could be unary operations but they're actually parsed as binary operations. Either explicitly write $a - $b or $a (-$b). See https://sass-lang.com/d/strict-unary for more details.

Dart API

• Add an optional argumentName parameter to SassScriptException() to make it easier to throw exceptions associated with particular argument names.

• Most APIs that previously returned num now return double. All APIs continue to accept num, although in Dart 2.0.0 these APIs will be changed to accept only double.

JS API

• Fix a bug in which certain warning spans would not have their properties accessible by the JS API.

• Fix an incorrect span in certain @media query deprecation warnings.

• No user-visible changes.

• Add support for 32-bit ARM releases on Linux.

• Fix a bug where a @media query could be incorrectly omitted from a stylesheet if it had multiple levels of nested @media queries within it and the inner queries were mergeable but the outer query was not.

• Properly consider a ~ c to be a superselector of a ~ b ~ c and a + b + c.

• Properly consider b > c to be a superselector of a > b > c, and similarly for other combinators.

• Properly calculate specificity for selector pseudoclasses.

• Deprecate use of random() when $limit has units to make it explicit that random() currently ignores units. A future version will no longer ignore units.

• Don't throw an error when the same module is @forwarded multiple times through a configured module.

Embedded Sass

• Rather than downloading the embedded compiler for the local platform on install, the sass-embedded npm package now declares optional dependencies on platform-specific embedded compiler packages.

• Improve error messages when passing incorrect units that are also out-of-bounds to various color functions.

• Release a native ARM64 executable for Mac OS.

• No user-visible changes.

• When unifying selectors for @extend and selector.unify(), ensure that :root, :scope, :host, and :host-context only appear at the beginning of complex selectors.

• Deprecate selectors with leading or trailing combinators, or with multiple combinators in a row. If they're included in style rules after nesting is resolved, Sass will now produce a deprecation warning and, in most cases, omit the selector. Leading and trailing combinators can still be freely used for nesting purposes.

  See https://sass-lang.com/d/bogus-combinators for more details.

• Add partial support for new media query syntax from Media Queries Level 4. The only exception are logical operations nested within parentheses, as these were previously interpreted differently as SassScript expressions.

  A parenthesized media condition that begins with not or an opening parenthesis now produces a deprecation warning. In a future release, these will be interpreted as plain CSS instead.

• Deprecate passing non-deg units to color.hwb()'s $hue argument.

• Fix a number of bugs when determining whether selectors with pseudo-elements are superselectors.

• Treat * as a superselector of all selectors.

Dart API

• Add a top-level fakeFromImport() function for testing custom importers that use AsyncImporter.fromImport.

JS API

• Add a charset option that controls whether or not Sass emits a @charset/BOM for non-ASCII stylesheets.

• Fix Sass npm package types for TS 4.7+ Node16 and NodeNext module resolution.

• Add support for calling var() with an empty second argument, such as var(--side, ).

JS API

• Fix a bug where meta.load-css() would sometimes resolve relative URLs incorrectly when called from a mixin using the legacy JS API.

Embedded Sass

• Respect npm's proxy settings when downloading the embedded Sass compiler.

• Fix crash when trailing loud comments (/* ... */) appear twice in a row across two different imports which themselves imported the same file each.

• Preserve location of trailing loud comments (/* ... */) instead of pushing the comment to the next line.

Command Line Interface

• Fix a bug where --watch mode would close immediately in TTY mode. This was caused by our change to close --watch when stdin was closed outside of TTY mode, which has been reverted for now while we work on a fix.

• Add support for arbitrary modifiers at the end of plain CSS imports, in addition to the existing supports() and media queries. Sass now allows any sequence of identifiers of functions after the URL of an import for forwards compatibility with future additions to the CSS spec.

• Fix an issue where source locations tracked through variable references could potentially become incorrect.

• Fix a bug where a loud comment in the source can break the source map when embedding the sources, when using the command-line interface or the legacy JS API.

JS API

• SassNumber.assertUnit() and SassNumber.assertNoUnits() now correctly return the number called on when it passes the assertion.

• Potentially breaking change: Change the order of maps returned by map.deep-merge() to match those returned by map.merge(). All keys that appeared in the first map will now be listed first in the same order they appeared in that map, followed by any new keys added from the second map.

• Improve the string output of some AST nodes in error messages.

Embedded Sass

• The JS embedded host and the embedded compiler will now properly avoid resolving imports relative to the current working directory unless '.' is passed as a load path.

• Fix a bug in the JS embedded host's implementation of the legacy JS API where imports that began with / could crash on Windows.

• @extend now treats :where() the same as :is().

Command Line Interface

• Closing the standard input stream will now cause the --watch command to stop running.

Embedded Sass

• Fix a bug where the JS embedded host crashed when invoking a legacy importer after resolving a relative filesystem import.

• Improve error messages when returning non-Object values from legacy importers.

• Add support for 64-bit ARM releases on Linux.

Embedded Sass

• The embedded compiler now correctly sets the id field for all OutboundMessages.

• Quiet deps mode now silences compiler warnings in mixins and functions that are defined in dependencies even if they're invoked from application stylesheets.

• In expanded mode, Sass will now emit colors using rgb(), rbga(), hsl(), and hsla() function notation if they were defined using the corresponding notation. As per our browser support policy, this change was only done once 95% of browsers were confirmed to support this output format, and so is not considered a breaking change.

  Note that this output format is intended for human readability and not for interoperability with other tools. As always, Sass targets the CSS specification, and any tool that consumes Sass's output should parse all colors that are supported by the CSS spec.

• Fix a bug in which a color written using the four- or eight-digit hex format could be emitted as a hex color rather than a format with higher browser compatibility.

• Calculations are no longer simplified within supports declarations

Embedded Sass

• Fixed a bug where the legacy API could crash when passed an empty importer list.

• Fixed a bug where some plain CSS imports would not be emitted.

JS API

• Fix a bug where inspecting the Sass module in the Node.js console crashed on Node 17.

Embedded Sass

• Fix a bug where source map URLs were incorrectly generated when passing importers to the legacy API.

Embedded Sass

• First stable release the sass-embedded npm package that contains the Node.js Embedded Host.

• First stable release of the sass_embedded pub package that contains the Embedded Dart Sass compiler.

• No user-visible changes.

• No user-visible changes.

• No user-visible changes.

• No user-visible changes.

• No user-visible changes.

• Stop supporting non-LTS Node.js versions.

• Fix a bug in string.insert with certain negative indices.

JS API

• Add support for the sourceMapIncludeSources option in the new JS API.

TypeScript Declarations

• Fix a bug where LegacyPluginThis.options.linefeed was typed to return abbreviations when it actually returned literal linefeed characters.

JS API

• Potentially breaking bug fix: Match the specification of the new JS API by setting LegacyResult.map to undefined rather than null.

TypeScript Declarations

• Add a declaration for the NULL constant.

JS API

TypeScript Declarations

• Add declarations for the TRUE and FALSE constants.

JS API

• Potentially breaking bug fix: Match the specification of the new JS API by passing undefined rather than null to Logger.warn() for an unset span.

TypeScript Declarations

• Add a declaration for the LegacyPluginThis.options.context field.

• Update the definition of LegacyAsyncFunction to include explicit definitions with zero through six arguments before the done parameter. This makes it possible for TypeScript users to pass in callbacks that take a specific number of arguments, rather than having to declare a callback that takes an arbitrary number.

• Add a declaration for types.Error, a legacy API class that can be returned by asynchronous functions to signal asynchronous errors.

• Add a LegacyAsyncFunctionDone type for the done callback that's passed to LegacyAsyncFunction.

JS API

• Potentially breaking bug fix: Change the default value of the separator parameter for new SassArgumentList() to ',' rather than null. This matches the API specification.

• Potentially breaking bug fix: Properly parse custom properties in @supports conditions. Note that this means that SassScript expressions on the right-hand side of custom property @supports queries now need to be interpolated, as per https://sass-lang.com/d/css-vars.

• Potentially breaking bug fix: Fix a bug where inspect() was not properly printing nested, empty, bracketed lists.

JS API

This release includes an entirely new JavaScript API, designed to be more idiomatic, performant, and usable. The old API will continue to be supported until Dart Sass 2.0.0, but it is now considered deprecated and should be avoided for new code.

The new API includes:

• compile() and compileAsync() functions that take Sass file paths and return the result of compiling them to CSS. The async function returns a Promise rather than using a callback-based API.

• compileString() and compileStringAsync() functions that take a string of Sass source and compiles it to CSS. As above, the async function returns a Promise.

• A new importer API that more closely matches the Sass specification's logic for resolving loads. This makes it much easier for Sass to cache information across @import and @use rules, which substantially improves performance for applications that rely heavily on repeated @imports.

• A new custom function API, including much more usable JS representations of Sass value types complete with type-assertion functions, easy map and list lookups, and compatibility with the immutable package. Unlike in the legacy API, function callbacks now take one argument which contains an array of Sass values (rather than taking a separate JS argument for each Sass argument).

For full documentation of this API, please see the Sass website.

This release also adds TypeScript type definitions.

• Suggest calc() as an alternative in /-as-division deprecation messages.

Dart API

• Add SassNumber.convert() and SassNumber.convertValue(). These work like SassNumber.coerce() and SassNumber.coerceValue(), except they don't treat unitless numbers as universally compatible.

• Fix a bug where SassNumber.coerceToMatch() and SassNumber.coerceValueToMatch() wouldn't coerce single-unit numbers to match unitless numbers.

• Fix a bug where calculations with different operators were incorrectly considered equal.

• Properly parse attribute selectors with empty namespaces.

JS API

• Print more detailed JS stack traces. This is mostly useful for the Sass team's own debugging purposes.

JS API

• Fix a bug where the logger option was ignored for the render() function.

• Improve performance.

• Improve the error message when the default namespace of a @use rule is not a valid identifier.

• No user-visible changes.

JS API

• Add support for the logger option. This takes an object that can define warn or debug methods to add custom handling for messages emitted by the Sass compiler. See the JS API docs for details.

• Add a Logger.silent object that can be passed to the logger option to silence all messages from the Sass compiler.

• Fix a bug where Sass variables and function calls in calculations weren't being resolved correctly if there was a parenthesized interpolation elsewhere in the file.

• min() and max() expressions are once again parsed as calculations as long as they contain only syntax that's allowed in calculation expressions. To avoid the backwards-compatibility issues that were present in 1.40.0, they now allow unitless numbers to be mixed with numbers with units just like the global min() and max() functions. Similarly, + and - operations within min() and max() functions allow unitless numbers to be mixed with numbers with units.

• Preserve parentheses around var() functions in calculations, because they could potentially be replaced with sub-expressions that might need to be parenthesized.

• Calculation values can now be combined with strings using the + operator. This was an error in 1.40.0, but this broke stylesheets that were relying on $value + "" expressions to generically convert values to strings. (Note that the Sass team recommends the use of "#{$value}" or inspect($value) for that use-case.)

• The selector.unify() function now correctly returns null when one selector is a :host or :host-context and the other is a selector that's guaranteed to be within the current shadow DOM. The @extend logic has been updated accordingly as well.

• Fix a bug where extra whitespace in min(), max(), clamp(), and calc() expressions could cause bogus parse errors.

• Fix a bug where the right-hand operand of a - in a calculation could incorrectly be stripped of parentheses.

Dart API

• SassCalculation.plus() now allows SassString arguments.

• Potentially breaking bug fix: min() and max() expressions outside of calculations now behave the same way they did in 1.39.2, returning unquoted strings if they contain no Sass-specific features and calling the global min() and max() functions otherwise. Within calculations, they continue to behave how they did in 1.40.0.

  This fixes an unintended breaking change added in 1.40.0, wherein passing a unitless number and a number without units to min() or max() now produces an error. Since this breakage affects a major Sass library, we're temporarily reverting support for min() and max() calculations while we work on designing a longer-term fix.

• Add support for first-class calc() expressions (as well as clamp() and plain-CSS min() and max()). This means:

  • calc() expressions will be parsed more thoroughly, and errors will be highlighted where they weren't before. This may break your stylesheets, but only if they were already producing broken CSS.

  • calc() expressions will be simplified where possible, and may even return numbers if they can be simplified away entirely.

  • calc() expressions that can't be simplified to numbers return a new data type known as "calculations".

  • Sass variables and functions can now be used in calc() expressions.

  • New functions meta.calc-name() and meta.calc-args() can now inspect calculations.

Dart API

• Add a new value type, SassCalculation, that represents calculations.

• Add new CalculationOperation, CalculationOperator, and CalculationInterpolation types to represent types of arguments that may exist as part of a calculation.

• Add a new Value.assertCalculation() method.

• Add a new Number.hasCompatibleUnits() method.

• Fix a bug where configuring with @use ... with would throw an error when that variable was defined in a module that also contained @forward ... with.

• Partial fix for a bug where @at-root does not work properly in nested imports that contain @use rules. If the only @use rules in the nested import are for built-in modules, @at-root should now work properly.