Skip to content

Commit

Permalink
Document the default export deprecation (#736)
Browse files Browse the repository at this point in the history
  • Loading branch information
nex3 authored Jun 13, 2023
1 parent a37311c commit 58f1bfa
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 0 deletions.
3 changes: 3 additions & 0 deletions source/documentation/breaking-changes.html.md.erb
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
38 changes: 38 additions & 0 deletions source/documentation/breaking-changes/default-export.md.erb
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit 58f1bfa

Please sign in to comment.