New JS API entrypoint

• Proposal
• Tests
• Documentation
• Dart Sass
• Node Host

---

Something @Awjin and I have discussed one on one but hasn’t been captured on the issue tracker yet is the idea of creating new entrypoint functions for the JS API as part of the redesign of the custom importer and function APIs (#2509 and #2510). While we could potentially support new imports and functions in the existing render()/renderSync() entrypoints, there are a number of reasons why it might be better to have an entirely new entrypoint. (I’ll tentatively call this entrypoint compile() to match the Dart Sass API.)

• As we improve various aspects of the API, it makes it totally clear to users which aspects are new and supported (those used by compile()) and which are old and deprecated (those used by render()). Users won’t be able to accidentally mix and match and then get broken when support for the deprecated versions is dropped.

• We don’t have to deal with tricky questions about how aspects of the old API interact with the new one. For example, we won’t have to deal with users passing both old-style and new-style importers to the same render() call, and we won’t have to figure out which source map options take precedence in which situations.

• The names render() and renderSync() imply that the synchronous version is “less default”, when in fact for Dart Sass the synchronous version is actually much more efficient. In the new API, we can call the entrypoints compile() and compileAsync() instead.

• We can have compileAsync() return a promise rather than using the old-style error/value callback without making it a breaking change.

• Cross-compilation state of the sort described in #2745 won’t work well with the old importer API, since it doesn’t have a strong notion of “canonical URLs” that can be stable over time. By putting the new APIs in a new entrypoint, we’ll be able to expose a version of that entrypoint on a state-preserving Compiler class without having to figure out how to handle old-style importers.

[nex3]

Supporting module-ized custom functions is an interesting question, although one I think we shouldn’t block this feature on. I think a better solution than building it into the functions argument might be making it part of the importer API, since that already has well-defined behavior for locating and resolving URLs. That would also open the door for distributing function plugins on npm and having them automatically loaded by an importer.

[nex3]

We don’t expect to release it until 2024 or so, very possibly later. There’s a small chance we’ll want to release it sooner in order to enable /-as-separator by default, but in that case we’ll only remove those deprecated features we believe to be either in low global use or highly detrimental to the ecosystem.