From ba172d9df1e97253069dd8d5452583a1c0b42f9e Mon Sep 17 00:00:00 2001
From: Israel-4Ever <nweiz@google.com>
Date: Tue, 13 Jun 2023 15:28:59 -0700
Subject: [PATCH] Document the default export deprecation (#736)

See sass/dart-sass#2008
---
 .../breaking-changes.html.md.erb              |  3 ++
 .../breaking-changes/default-export.md.erb    | 38 +++++++++++++++++++
 2 files changed, 41 insertions(+)
 create mode 100644 source/documentation/breaking-changes/default-export.md.erb

diff --git a/source/documentation/breaking-changes.html.md.erb b/source/documentation/breaking-changes.html.md.erb
index 35f8df346..9c0439e5d 100644
--- a/source/documentation/breaking-changes.html.md.erb
+++ b/source/documentation/breaking-changes.html.md.erb
@@ -23,6 +23,9 @@ time-sensitive, so they may be released with new minor version numbers instead.
 
 These breaking changes are coming soon or have recently been released:
 
+* [Loading Sass as a default export in JS is no longer
+  allowed](breaking-changes/default-export) beginning in Dart Sass 1.63.0.
+
 * [A variable may only have a single `!global` or `!default`
   flag](breaking-changes/duplicate-var-flags) beginning in Dart Sass 1.62.0.
 
diff --git a/source/documentation/breaking-changes/default-export.md.erb b/source/documentation/breaking-changes/default-export.md.erb
new file mode 100644
index 000000000..b0bf3e85d
--- /dev/null
+++ b/source/documentation/breaking-changes/default-export.md.erb
@@ -0,0 +1,38 @@
+---
+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
+---
+
+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
+
+<% impl_status dart: '1.54.0', libsass: false, ruby: false %>
+
+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.