Skip to content

Commit 58f1bfa

Browse files
authored
Document the default export deprecation (#736)
See sass/dart-sass#2008
1 parent a37311c commit 58f1bfa

File tree

2 files changed

+41
-0
lines changed

2 files changed

+41
-0
lines changed

source/documentation/breaking-changes.html.md.erb

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ time-sensitive, so they may be released with new minor version numbers instead.
2323

2424
These breaking changes are coming soon or have recently been released:
2525

26+
* [Loading Sass as a default export in JS is no longer
27+
allowed](breaking-changes/default-export) beginning in Dart Sass 1.63.0.
28+
2629
* [A variable may only have a single `!global` or `!default`
2730
flag](breaking-changes/duplicate-var-flags) beginning in Dart Sass 1.62.0.
2831

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: "Breaking Change: Default Exports"
3+
introduction: >
4+
By default, Node.js allows [CommonJS modules] to be loaded from ECMAScript
5+
modules using the syntax `import sass from 'sass'`. This is now deprecated;
6+
ESM users should use `import * as sass from 'sass'` instead.
7+
8+
[CommonJS modules]: https://nodejs.org/docs/latest/api/modules.html#modules-commonjs-modules
9+
[ECMAScript modules]: https://nodejs.org/api/esm.html#modules-ecmascript-modules
10+
---
11+
12+
Historically, Dart Sass was only available as a CommonJS module. This meant that
13+
anyone using it from a project that used Node.js's native ECMAScript module
14+
support was able to load it as though it provided a [default export]:
15+
16+
[default export]: https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export#using_the_default_export
17+
18+
```js
19+
import sass from 'sass'; // Don't do this anymore
20+
```
21+
22+
This was never intended by the Sass team, and it didn't match the type
23+
declarations provided with the package, but it _did_ work. We have decided to
24+
remove this support in Dart Sass 2.0.0 and require that ECMAScript module users
25+
only use the package's named exports:
26+
27+
```js
28+
import * as sass from 'sass'; // Do this
29+
```
30+
31+
## Transition Period
32+
33+
<% impl_status dart: '1.54.0', libsass: false, ruby: false %>
34+
35+
Until Dart Sass 2.0.0, we will continue to support users loading Sass's default
36+
export. The first time any properties on the default export are accessed, it
37+
will emit a deprecation warning to `console.error()`. To avoid this error, use
38+
`import * as sass form 'sass'` instead.

0 commit comments

Comments
 (0)