Merge remote-tracking branch 'upstream/main' into main

source/documentation/breaking-changes/default-export.liquid

@@ -0,0 +1,40 @@
+---
+title: "Breaking Change: Default Exports"
+introduction: |
+  By default, Node.js allows [CommonJS modules] to be loaded from ECMAScript
+  modules using the syntax `import sass from 'sass'`. This is now deprecated;
+  ESM users should use `import * as sass from 'sass'` instead.
+
+  [CommonJS modules]: https://nodejs.org/docs/latest/api/modules.html#modules-commonjs-modules
+  [ECMAScript modules]: https://nodejs.org/api/esm.html#modules-ecmascript-modules
+---
+
+{% markdown %}
+  Historically, Dart Sass was only available as a CommonJS module. This meant that
+  anyone using it from a project that used Node.js's native ECMAScript module
+  support was able to load it as though it provided a [default export]:
+
+  [default export]: https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export#using_the_default_export
+
+  ```js
+  import sass from 'sass'; // Don't do this anymore
+  ```
+
+  This was never intended by the Sass team, and it didn't match the type
+  declarations provided with the package, but it _did_ work. We have decided to
+  remove this support in Dart Sass 2.0.0 and require that ECMAScript module users
+  only use the package's named exports:
+
+  ```js
+  import * as sass from 'sass'; // Do this
+  ```
+
+  ## Transition Period
+
+  {% compatibility 'dart:"1.54.0"', 'libsass:false', 'ruby:false' %}{% endcompatibility %}
+
+  Until Dart Sass 2.0.0, we will continue to support users loading Sass's default
+  export. The first time any properties on the default export are accessed, it
+  will emit a deprecation warning to `console.error()`. To avoid this error, use
+  `import * as sass form 'sass'` instead.
+{% endmarkdown %}

source/documentation/breaking-changes/index.md

@@ -22,31 +22,35 @@ time-sensitive, so they may be released with new minor version numbers instead.
 
 These breaking changes are coming soon or have recently been released:
 
-- [A variable may only have a single `!global` or `!default`
+* [Loading Sass as a default export in JS is no longer
+  allowed](/documentation/breaking-changes/default-export) beginning in Dart
+  Sass 1.63.0.
+
+* [A variable may only have a single `!global` or `!default`
   flag](/documentation/breaking-changes/duplicate-var-flags) beginning in Dart
   Sass 1.62.0.
 
-- [Selectors with invalid combinators are
+* [Selectors with invalid combinators are
   invalid](/documentation/breaking-changes/bogus-combinators) beginning in Dart
   Sass 1.54.0.
 
-- [`/` is changing from a division operation to a list
+* [`/` is changing from a division operation to a list
   separator](/documentation/breaking-changes/slash-div) beginning in Dart Sass
   1.33.0.
 
-- [Functions are stricter about which units they
+* [Functions are stricter about which units they
   allow](/documentation/breaking-changes/function-units) beginning in Dart Sass
   1.32.0.
 
-- [Parsing the special syntax of `@-moz-document` will be
+* [Parsing the special syntax of `@-moz-document` will be
   invalid](/documentation/breaking-changes/moz-document) beginning in Dart Sass
   1.7.2.
 
-- [Compound selectors could not be
+* [Compound selectors could not be
   extended](/documentation/breaking-changes/extend-compound) in Dart Sass 1.0.0
   and Ruby Sass 4.0.0.
 
-- [The syntax for CSS custom property values
+* [The syntax for CSS custom property values
   changed](/documentation/breaking-changes/css-vars) in Dart Sass 1.0.0, LibSass
   3.5.0, and Ruby Sass 3.5.0.