Deprecate @import and global builtins

[jathak]

See sass/sass#3898.
See sass/sass-spec#2004.

[skip sass-embedded]

[nex3]

Looks like we might need to disable the future deprecation tests temporarily until we have a future deprecation we can actually test. I think the embedded protocol tests also need to be updated to avoid @import.

[jathak]

Yeah, there are a lot of tests in js-api-spec that need to be updated. Working on them now

[ntkme]

The current situation is:

1. Almost none of the most popular sass frameworks have adopted @use, because they still want to support both libsass and dart-sass as of today. This means we (the whole sass community, including bootstrap etc.) will be flooded by frustrated users again, and this time probably way more than what we recently got from mixed-decls depreciation as @import is still used everywhere. What’s more problematic is that switching to @use is a major breaking change for frameworks as it drops support of libsass, and many developers are simply not ready yet. For example, bootstrap plans to drop libsass and switches to @use in 6.0.0 major release, but they far from ready. This isn’t something like mixed-decls they can hot-fix in 5.3.4 patch release, so the impact of the warnings can be wildly spread and long-lasted.
2. Webpack has new API support, but still default to legacy API, and Vite only has legacy API support. This would lead to difficulties for end users to silence massive amount of warnings coming from dependencies or even transitive dependencies. Even worse, some web bundlers use custom importers (including pkg importer) to resolve dependency imports rather use the load path, meaning quietDeps option would not work and the users will be forced to use a custom logger to suppress the warnings.

Given the frustrating community adoption of @use and deprecation API, we may want to consider:

1. Officially mark libsass and all language bindings for it as end-of-life at the same time as we officially deprecate @import, in order to incentivize sass framework maintainers to drop the use of @import and move to @use faster.
2. Release this (the deprecation) as 2.0.0 instead of 1.78.0, and later remove the support of @import (and other things originally planned for 2.0.0) in 3.0.0. This is to reduce unnecessary noises from end users who don’t have an easy way to suppress the warnings for dependencies that they may not have full control. Of course, this has the downside at the same time that less users will get these notice (e.g. sass version locked to 1.x). However, the developers of sass frameworks like bootstrap who are actively testing latest sass release will get the deprecation and probably speed up towards a major release. In my opinion, this is probably the a good balance to not annoy to way too many users.

[nex3]

I'll discuss these points with the team. It's definitely a lot to ask of users to migrate without consistent access to deprecation-silencing capabilities. To some degree I think it's just clear that frameworks will not proactively migrate without a sufficient volume of user complaints pushing them to, but I think at least for the modern API migration the recent declaration-order deprecation may have lit enough of a fire to get the ball rolling.

I specifically don't want to tie the @import deprecation to a major version release, because breaking releases are always some amount of pain to upgrade through and I don't want to add an additional massive hindrance directly on top of that. I'd rather delay the @import deprecation until after 2.0.0 so that we can get more people onto that release cycle less painfully.

I agree that it may be time to end-of-life Node Sass, at least. LibSass has received commits and even a release in the past year, so I'm more hesitant to declare that end-of-life, but Node Sass hasn't been touched at all since May 2023. I've filed sass/node-sass#3424 and emailed the maintainers. If I don't hear back in a couple weeks and after a few pings, I'll look into doing it without their involvement.

One major open question I'm interested in: are there widely-used frameworks other than Vite that still don't support the modern JS API? Or is it the only one?

[ntkme]

One major open question I'm interested in: are there widely-used frameworks other than Vite that still don't support the modern JS API? Or is it the only one?

I just did a small research. Webpack seems to be the only one supporting new API, yet it still default to legacy API.

I wasn't able to find anything that supports new API, all of the below are Legacy API only:

• https://www.npmjs.com/package/parcel
• https://www.npmjs.com/package/esbuild-sass-plugin
• https://www.npmjs.com/package/@jgoz/esbuild-plugin-sass
• https://www.npmjs.com/package/next
• https://www.npmjs.com/package/gulp-sass

The problem here is that we now called it the legacy API, but never really had a deprecation process for it, nor throwing any warning to end users. So there is almost zero motivation for developers to support the new API, because legacy API gives them interchangeable compatibility between node-sass (libsass) and dart-sass, where switching to new API is additional work and a breaking change for them.

[ntkme]

It seems if we don't want to delay this too much, a reasonable solution is to port deprecation options to the legacy API?

[nex3]

I had hoped that we wouldn't need to actually print warnings for the legacy API, since we're able to mark it as deprecated in the TSDoc, but apparently that's not sufficient. It's probably worth producing an official deprecation message.

I agree that adding deprecation-control options to the legacy API is the most expedient path forward in the short term. I'm going to reach out to some major frameworks as well to sound them out on the timeline for deprecating @import.

[nex3]

• I've filed Use the modern Sass API parcel-bundler/parcel#9857
• It looks like esbuild-sass-plugin is using the modern API
• @jgoz/esbuild-plugin-sass has next to no users so I don't care too much about it
• If I'm reading correctly, Next.js forwards Sass options to sass-loader and so should be configurable to use the modern API although it doesn't by default
• render() and renderSync() are deprecated for the sass package dlmanning/gulp-sass#867 was already filed

[ntkme]

If I'm reading correctly, Next.js forwards Sass options to sass-loader and so should be configurable to use the modern API although it doesn't by default

This actually does not work, because in webpack the config looks like this: https://webpack.js.org/loaders/sass-loader/#api

            options: {
              api: "modern",
              sassOptions: {
                // Your sass options
              },
            },

That the choice of api is passed outside of sassOptions. next.js does not take nor pass the api option to sass-loader so users are just forced to use the default, which is legacy.

[ntkme]

On a related note, shall we also mark sassc-ruby as end-of-life? The repo has not been updated for 4 years. There are tons of open issues and PRs. Recently, I even discovered a hidden 10x performance regression for sassc-ruby due to an unannounced change in Ruby 2.7: https://bugs.ruby-lang.org/issues/20604

As for migration paths: we have sass-embedded gem for most of the users, as well as sassc-embedded gem that emulates sassc-ruby for complex legacy use cases like sprockets. I have it summarized here: https://github.com/sass-contrib/sassc-embedded-shim-ruby?tab=readme-ov-file#which-sass-implementation-should-i-use-for-my-ruby-project. So far the only gap in migrating to dart-sass is that the embedded compiler currently does not have support for BSD or minor CPU architectures. This can be potentially mitigated by implementing sass --embedded in pure JS mode, but that's for another discussion.

In my opinion, it might be the right time to mark sassc-ruby as end-of-life, but I cannot even figure out who are the maintainers we should contact.

@nex3 What do you think?

[nex3]

I agree. I think @bolandrm is the maintainer of record. Ryan, what are your thoughts here?

[ntkme]

The link reference does not match

[jathak]

Fixed. Good catch!

[nex3]

Style nit: only split strings at newlines or just before you'd hit the 80 char limit.

[ntkme]

@bolandrm We're planning to deprecate @import in favor of @use, which libsass does not support. This is a significant change. To prepare for it, we have already marked node-sass as EOL to encourage frameworks and end users to migrate, and we want to mark sassc-ruby as EOL for the same reason. I can draft a final PR to update the README to provide guidance on migration path for users. What do you think?

[nex3]

@ntkme If you don't hear back soon, @ me on that PR and I'll merge it.