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

The JavaScript importer API shared by Dart Sass and Node Sass needs an overhaul. The current API has a number of issues:

• It doesn't respect URL semantics. In particular, it doesn't provide any guarantee that @import "./bar" within a stylesheet with URL foo means the same thing as @import "foo/bar", even when resolved by the same importer.

• It doesn't have a notion of resolving an imported URL to an absolute URL—for example, an npm-aware importer might resolve ~foo to file:///home/nex3/app/node_modules/foo/_index.scss. This makes canonicalization of imported stylesheets impossible, and means that importers are fundamentally less expressive than built-in filesystem imports. It also means that the URLs reported in source maps and other APIs are unlikely to be resolvable.

• It doesn't support the indented syntax.

• Its notion of "redirecting" to a file import has some strange corner cases—for example, a relative path redirect can be resolved relative to the file that contains the import, relative to the working directory, or relative to an import path.

• It doesn't seem to do much error checking for invalid responses.

• It uses the string "stdin" to refer to files passed by data, even when they don't come from standard input. This could potentially conflict with a real file named "stdin".

• The this context includes a bunch of undocumented information without a clear use-case.

We should design a new API that addresses these issues and makes it easy to write importers that work similarly to native filesystem imports. I strongly favor writing the API in such a way that filesystem imports themselves can be modeled as an importer.