|
| 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