Methods required to implement a stylesheet importer.

Importers resolve @import, @use, and @forward rules in stylesheets. The methods are called back by the compiler during compilation. You don’t need this to include the contents of a filesystem directory: see instead ImportResolver.loadPath(_:).

You could use this to present network resources or dynamically constructed content.

An import has two steps: canonicalization and loading.

Importer.canonicalize(...) is always called first with whatever URL text the user has written in their rule. The routine interprets that and returns a canonical URL that is absolute with a scheme.

The compiler most likely implements a cache based on canonical URLs. If the compiler does not have a stylesheet cached for the canonical URL then it calls Importer.load(...) with that URL to get at the content.

File extension rules

Sass itself handles imports from the filesystem using various filename conventions. Users of your importer mostly likely expect the same behavior if the URLs you are importing resemble filenames with extensions and directories.

From the Sass embedded protocol documentation:

The importer should look for stylesheets by adding the prefix _ to the URL’s basename, and by adding the extensions .sass and .scss if the URL doesn’t already have one of those extensions. For example, given the URL “foo/bar/baz” the importer should look for:

1. foo/bar/baz.sass
2. foo/bar/baz.scss
3. foo/bar/_baz.sass
4. foo/bar/_baz.scss

Given the URL “foo/bar/baz.scss” the importer should look for:

1. foo/bar/baz.scss
2. foo/bar/_baz.scss

If the importer finds a stylesheet at more than one of these URLs then it must throw an error indicating that the import is ambiguous.

If none of the possible paths are valid then the importer should perform the same resolution on the URL followed by /index. In the example above, it should additionally look for:

1. foo/bar/baz/_index.sass
2. foo/bar/baz/index.sass
3. foo/bar/baz/_index.scss
4. foo/bar/baz/index.scss

If more than one of these implicit index resources exist then the importer must throw an error indicating that the import is ambiguous.

The results of loading a stylesheet through an importer.

Methods required to implement a filesystem-redirecting stylesheet importer.

Use this to map imports to a filesystem location, letting the Sass compiler deal with index directories, file extensions, and actually loading the stylesheet.

How the Sass compiler should resolve @import, @use, and @forward rules.