From 20a376af40289bec0a3dbc6fcf27d026e3219672 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Fri, 9 Jun 2023 17:43:22 -0700 Subject: [PATCH] Document the default export deprecation 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.