Upgrading sass 0.5 to 1
Breaking0.5.0 → 1.107.1Breaking80Platform3Deprecated49New218Changed144Fixed218Other98
BreakingUpgrade verdict
79 breaking changes and 3 platform requirement changes.
In plain terms
- Color channel values are no longer rounded to whole numbers, so colors that used to look identical may now differ slightly.
- The embedded Sass API no longer provides the RgbColor, HslColor and HwbColor value types.
- The CalculationValue.interpolation field is deprecated and will be removed in a future version.
- Potentially breaking bug fix: The importer used to load a given file is no longer used to load absolute URLs that appear in that file.
Must act Top 5 of 128 that need code or config changes
Node.js requirement changed in 1.100.0: * → >=20.19.0.
Adds @parcel/watcher ^2.4.1, chokidar ^5.0.0, immutable ^5.1.5, source-map-js >=0.6.2 <2.0.0.
Installs 22 packages in all (was 0).
Also installs @parcel/watcher-android-arm64, @parcel/watcher-darwin-arm64, @parcel/watcher-darwin-x64, @parcel/watcher-freebsd-x64, @parcel/watcher-linux-arm-glibc, @parcel/watcher-linux-arm-musl, @parcel/watcher-linux-arm64-glibc, @parcel/watcher-linux-arm64-musl, @parcel/watcher-linux-x64-glibc, @parcel/watcher-linux-x64-musl, @parcel/watcher-win32-arm64, @parcel/watcher-win32-x64, detect-libc, is-extglob, is-glob and 3 more.
What you must change
Breaking79
Sass no longer rounds RGB channels to the nearest integer, so rgb(0 0 1) no longer equals rgb(0 0 0.6).
Removes the RgbColor, HslColor and HwbColor SassScript values from Embedded Sass.
RgbColorHslColorHwbColorThe CalculationValue.interpolation field is deprecated and will be removed in a future version.
CalculationValue.interpolationCalculationValue.stringPotentially breaking bug fix: The importer used to load a given file is no longer used to load absolute URLs that appear in that file.
Breaking change: Drop support for the additional CSS calculations defined in CSS Values and Units 4. Custom Sass functions whose names overlapped with these new CSS functions were being parsed as…
Potentially breaking change: Drop support for End-of-Life Node.js 12.
Remove sourcemap comments from Sass sources.
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.
notPotentially 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.
sass:mathmath.pow(0.000000000001, -1)InfinityCalculations are no longer simplified within supports declarations.
Potentially breaking bug fix: Change the default value of the separator parameter for new SassArgumentList() to ',' rather than null.
separatornullPotentially breaking bug fix: Null values in @use and @forward configurations no longer override the !default variable, matching the behavior of the equivalent code using @import.
@use@forwarddefault@importDrop support for Chokidar 2.x.
Rename SassNumber.valueInUnits() to SassNumber.coerceValue().
SassNumber.valueInUnits()SassNumber.coerceValue()Rename SassNumber.coerceValueToUnit(), a shorthand for SassNumber.coerceValue() that takes a single numerator unit.
SassNumber.coerceValueToUnit()SassNumber.coerceValue()Potentially breaking bug fix: An empty map returned by map-remove() is now treated as identical to the literal value (), rather than being treated as though it had a comma separator.
map-remove()The adjust-color() function no longer throws an error when a large $alpha value is combined with HSL adjustments.
adjust-color()$alphaThe zip() function no longer deadlocks if passed no arguments.
zip()Remove the source map comment from the compiled JS.
Remove the deprecated render() function.
render()Import URLs passed to importers are no longer normalized.
"./foo.scss""foo.scss"Remove a non-sh-compatible idiom from the standalone shell script.
shDrop support for the reference combinator.
Normalizes CSS escape codes for 0, surrogates, and out-of-range code points to U+FFFD in expression contexts, except a lone
\0.Throws an error for mixins and functions whose rest parameters duplicate normal parameter names.
Fixes cases where a CSS escape code at the start of an identifier changed parsing behavior versus the literal character.
Serializes units ambiguous with a numeric exponent as an escape code instead of a literal
e.Stops parsing escaped
E or e as an exponent in @keyframes percentage selectors.@keyframesProperly normalizes underscores written as CSS escape codes in variable, mixin, and function names.
Colors now convert NaN, negative zero, and infinity or negative infinity for polar-hue channels to 0 per the CSS spec.
Colors now preserve analogous sets of missing channels during conversions per the CSS spec, changing some conversion results.
color.to-space()The Node package importer now resolves import-only variants of Sass files declared in package.json exports, sass, and style fields.
exportssassstylepackage.json@importParses
@function rules whose names begin with -- as unknown at-rules to support the plain CSS @function rule, with result parsed as raw CSS.@functionresultMakes
@mixin rules whose names begin with -- errors, since no browser currently supports CSS mixins.@mixinEmits declarations, childless at-rules, and comments in source order even when interleaved with nested rules, obsoleting the mixed-decls deprecation.
mixed-declsFully reserves the function name
type() for the plain CSS function, so @function type definitions error and calls parse as special function strings.type()@functionmeta.inspect() and systems using it now emit numbers at full available precision instead of rounding to 1e-10 as CSS serialization does.
meta.inspect()@debugThrows an error when passing a function or mixin object from one compilation to another.
Fixes plain CSS files with a top-level nesting selector
& loaded via meta.load-css() or @import to emit CSS nesting instead of combining with the parent selector.meta.load-css()@import&Selectors with unmatched brackets now always produce a parser error.
Adding text after an explicit
*/ in the indented syntax is now an error instead of silently generating invalid CSS.math.unit() now wraps multiple denominator units in parentheses, e.g. px/(em*em) instead of px/em*em.
math.unit()Passing a percentage to the $alpha parameter of color.change(), color.adjust(), change-color(), and adjust-color() now interprets it as a percentage instead of ignoring the unit.
color.change()color.adjust()change-color()adjust-color()$alphaPassing large positive or negative values to color.adjust() can now push a color's channels outside its gamut.
color.adjust()Fixes
// in places like unknown at-rule values being kept in CSS output; it is now parsed as a silent comment and omitted.Throws errors for misplaced statements in keyframe blocks.
As a consequence of the change in calculation parsing described above, calculation functions containing interpolation are now parsed more strictly than before.
Print better calc()-based suggestions for /-as-division expression that contain calculation-incompatible constructs like unary minus.
calc()Emit a unitless hue when serializing hsl() colors.
hsl()degPotentially breaking bug fix: Custom functions in both the modern and legacy API now properly reject signatures with whitespace between the function name and parentheses.
Potentially breaking bug fix: Callable.fromSignature() and AsyncCallable.fromSignature() now reject signatures with whitespace between the function name and parentheses.
Callable.fromSignature()AsyncCallable.fromSignature()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().
radturndeghsl()hsla()adjust-hue()Potentially breaking bug fix: Sass numbers are now universally stored as 64-bit floating-point numbers, rather than sometimes being stored as integers.
Potentially breaking bug fix: Sass equality is now properly [transitive].
1e-11Potentially breaking change: Change the order of maps returned by map.deep-merge() to match those returned by map.merge().
map.deep-merge()map.merge()In expanded mode, Sass will now emit colors using rgb(), rbga(), hsl(), and hsla() function notation if they were defined using the corresponding notation.
rgb()rbga()hsl()hsla()Potentially breaking bug fix: Match the specification of the new JS API by setting LegacyResult.map to undefined rather than null.
LegacyResult.mapundefinednullPotentially breaking bug fix: Match the specification of the new JS API by passing undefined rather than null to Logger.warn() for an unset span.
undefinednullLogger.warn()spanPotentially breaking bug fix: Properly parse custom properties in @supports conditions.
@supportsPotentially breaking bug fix: Fix a bug where inspect() was not properly printing nested, empty, bracketed lists.
inspect()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…
min()max()Potentially breaking bug fix: SassException has been marked as @sealed to formally indicate that it's not intended to be extended outside of the sass package.
SassException@sealedsassPotentially breaking bug fix: Properly throw an error for Unicode ranges that have too many ?s after hexadecimal digits, such as U+12345??
U+12345??Potentially breaking bug fix: Fixed a bug where certain local variable declarations nested within multiple @if statements would incorrectly override a global variable.
@ifglobalPotentially breaking bug fix: Fix a bug where imports of root-relative URLs (those that begin with /) in @import rules would be passed to both Dart and JS importers as file: URLs.
@importfile:Potentially breaking bug fix: The heuristics around when potentially slash-separated numbers are converted to slash-free numbers—for example, when 1/2 will be printed as 0.5 rather than 1/2—have…
Potentially breaking bug fix: When using @for with numbers that have units, the iteration variable now matches the unit of the initial number.
@forPotentially breaking bug fix: meta.load-css() now correctly uses the name $url for its first argument, rather than $module.
meta.load-css()$url$modulePotentially breaking bug fix: selector.nest() now throws an error if the first arguments contains the parent selector &.
selector.nest()Potentially breaking bug fix: @use rules whose URLs' basenames begin with now correctly exclude that from the rules' namespaces.
@use_Potentially breaking bug fix: character sequences consisting of two or more hyphens followed by a number (such as --123), or two or more hyphens on their own (such as --), are now parsed as…
Potentially breaking bug fix: The keywords() function now converts underscore-separated argument names to hyphen-separated names.
keywords()Potentially breaking bug fix: The argument name for the saturate() function is now $amount, to match the name in LibSass and originally in Ruby Sass.
saturate()$amountPotentially breaking bug fix: The invert() function now properly returns #808080 when passed $weight: 50%.
invert()$weightPotentially breaking bug fix: The str-insert() function now properly inserts at the end of the string if the $index is -1.
str-insert()$indexExplicitly require that importers' canonicalize() methods be able to take paths relative to their outputs as valid inputs.
canonicalize()AsyncImporter.canonicalize() and Importer.canonicalize() must now return absolute URLs.
AsyncImporter.canonicalize()Importer.canonicalize()Tokens such as #abcd that are now interpreted as hex colors with alpha channels, rather than unquoted ID strings.
#abcdPotentially breaking bug fix: SassNumber.asSlash, SassNumber.withSlash(), and SassNumber.withoutSlash() have been marked as @internal.
SassNumber.asSlashSassNumber.withSlash()SassNumber.withoutSlash()@internalsassPlatform3
Increases the minimum Dart SDK to 3.6.0.
Adds linux-riscv64, linux-musl-riscv64, and android-riscv64 support for the sass-embedded npm package.
The NPM release of 1.59.0 dropped support for Node 12 without actually indicating so in its pubspec.
Deprecations to plan for
Deprecated46
Passing a version number beyond the current Dart Sass version to Options.fatalDeprecations is now deprecated.
Options.fatalDeprecationsDeprecation.forVersionDeprecates writing two compound selectors adjacent without whitespace, such as
[class]a, which was always a CSS error.Deprecates user-defined functions named EXPRESSION, URL, ELEMENT, -...-ELEMENT and case variants, which conflict with special-syntax CSS functions.
EXPRESSIONURLELEMENTDeprecates calls to functions starting with - and ending in -expression or -url whose parsing will lose special handling in a future release.
Deprecates calls to functions whose names begin with - and end with -progid:...
Deprecates the old Sass if() syntax in favor of the new CSS syntax.
if()sass()Deprecates configuring private variables via
@use ... with, @forward ... with, and meta.load-css(..., $with: ...).@use@forwardmeta.load-css()Passing a rest argument ($arg...) before a positional or named argument in a function or mixin call is now deprecated.
$arg...Deprecates passing a relative URL to
compileString() and related functions.compileString()Deprecates user-defined functions named
type() to make room for the new CSS type() function.type()Deprecates
@import and global built-in functions that are available within built-in modules.@importDeprecates color.red(), .green(), .blue(), .hue(), .saturation(), .lightness(), .whiteness(), and .blackness() and their globals in favor of color.channel().
color.red()color.green()color.blue()color.hue()color.saturation()color.lightness()color.whiteness()color.blackness()Deprecates global adjust-hue(), saturate(), desaturate(), lighten(), darken(), transparentize(), fade-out(), opacify(), and fade-in() in favor of color.adjust() or color.scale().
adjust-hue()saturate()desaturate()lighten()darken()transparentize()fade-out()opacify()Deprecates SassColor.red, .green, .blue, .hue, .saturation, .lightness, .whiteness, and .blackness in favor of SassColor.channel().
SassColor.redSassColor.greenSassColor.blueSassColor.hueSassColor.saturationSassColor.lightnessSassColor.whitenessSassColor.blacknessDeprecates SassColor.changeRgb(), .changeHsl(), and .changeHwb() in favor of SassColor.changeChannels().
SassColor.changeRgb()SassColor.changeHsl()SassColor.changeHwb()SassColor.changeChannels()Emits warnings when the legacy JS API is used; silence with legacy-js-api in silenceDeprecations.
legacy-js-apisilenceDeprecationsDeprecates the meta.feature-exists function under the deprecation name feature-exists.
meta.feature-existsDeprecates declarations that appear after nested rules because Sass's historical semantics differ from CSS semantics.
Deprecates
Deprecation.duplicateVariableFlags and replaces it with Deprecation.duplicateVarFlags for consistency with duplicate-var-flags.Deprecation.duplicateVariableFlagsDeprecation.duplicateVarFlagsduplicate-var-flagsDeprecates mixins and functions whose names begin with
-- for forwards-compatibility with the in-progress CSS functions and mixins spec.css-function-mixinDeprecate Deprecation.calcInterp since it was never actually emitted as a deprecation.
Deprecation.calcInterpInterpolations in calculation functions that aren't used in a position that could also have a normal calculation value are now deprecated.
calc(1px #{"+ 2px"})calc(1px + #{"2px"})calc-interpDeprecate explicitly passing the % unit to the global abs() function.
abs()abs-percentRe-enable support for import sass from 'sass' when loading the package from an ESM module in Node.js.
Deprecate the use of multiple !global or !default flags on the same variable.
globaldefaultduplicate-var-flagsThe compile methods now take in fatalDeprecations and futureDeprecations parameters, which work similarly to the CLI flags.
compilefatalDeprecationsfutureDeprecationsEmit a deprecation warning when passing $alpha values with units to color.adjust() or color.change().
$alphacolor.adjust()color.change()Emit a deprecation warning when passing a $weight value with no units or with units other than % to color.mix().
$weightcolor.mix()Emit a deprecation warning when passing $n values with units to list.nth() or list.set-nth().
$nlist.nth()list.set-nth()Properly mark the warning for passing numbers with units to random() as a deprecation warning.
random()Emit a deprecation warning when passing a sassIndex with units to Value.sassIndexToListIndex().
sassIndexValue.sassIndexToListIndex()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.
Deprecate use of random() when $limit has units to make it explicit that random() currently ignores units.
random()$limitDeprecate selectors with leading or trailing combinators, or with multiple combinators in a row.
Deprecate passing non-deg units to color.hwb()'s $hue argument.
degcolor.hwb()$hueSuggest calc() as an alternative in /-as-division deprecation messages.
calc()Cap deprecation warnings at 5 per feature by default.
Deprecate the use of / for division.
math.div()Print the actual number that was received in unit deprecation warnings for color functions.
Deprecate passing numbers with units other than deg as the hue to hsl(), hsla(), adjust-hue(), color.adjust(), and color.change().
deghsl()hsla()adjust-hue()color.adjust()color.change()Properly mark some warnings emitted by sass:color functions as deprecation warnings.
sass:colorDeprecate !global variable assignments to variables that aren't yet defined.
globalnullDeprecated the indented parameter to compileString() and compileStringAsync().
indentedcompileString()compileStringAsync()Deprecated the indented parameter to new ImporterResult() and the ImporterResult.indented getter in favor of syntax.
indentedImporterResult.indentedsyntaxEmit deprecation warnings for tokens such as #abcd that are ambiguous between ID strings and hex colors with alpha channels.
#abcdThe standalone executable distributed on GitHub is now named sass rather than dart-sass.
sassdart-sass