Importers

An importer decides what @use "…" and @import "…" actually load. jsass 6 follows the dart-sass model, which splits the job in two:

1. canonicalize(url, context) turns whatever the stylesheet wrote into a canonical URI, or returns null to say "not mine, ask the next one".
2. load(canonicalUrl) returns the stylesheet contents for a URI that this importer canonicalized.

The split is what makes caching and deduplication possible: two stylesheets that canonicalize to the same URI are the same module and are loaded once.

A minimal importer

Serve SCSS from a Map

public final class MapBackedImporter implements Importer {

  private static final String SCHEME = "virtual";
  private final Map<String, String> modules;

  public MapBackedImporter(Map<String, String> modules) {
    this.modules = Map.copyOf(modules);
  }

  @Override
  public @Nullable URI canonicalize(String url, CanonicalizeContext context) {
    String name = url.startsWith(SCHEME + ":") ? url.substring(SCHEME.length() + 1) : url;
    return modules.containsKey(name) ? URI.create(SCHEME + ":" + name) : null;
  }

  @Override
  public @Nullable ImporterResult load(URI canonicalUrl) {
    if (!SCHEME.equals(canonicalUrl.getScheme())) {
      return null;
    }
    String contents = modules.get(canonicalUrl.getSchemeSpecificPart());
    return contents == null ? null : DefaultImporterResult.builder()
        .contents(contents)
        .syntax(Syntax.SCSS)
        .build();
  }
}

Register it

var options = StringOptions.builder()
    .url(URI.create("virtual:root.scss"))
    .importers(List.of(new MapBackedImporter(Map.of("theme", "$brand: red;"))))
    .build();

Use it

@use "virtual:theme" as t;

.logo { color: t.$brand; }

CanonicalizeContext tells you why you are being asked: isFromImport() distinguishes a legacy @import from a @use, and getContainingUrl() is the stylesheet the request came from — the hook for relative resolution.

An ImporterResult carries the contents, the syntax (SCSS by default) and an optional sourceMapUrl. Build one with ImporterResult.builder() or DefaultImporterResult.builder().

Resolution order

For a single compile, dart-sass asks in this order:

1. the importer set with importer(…), which also owns relative loads from the entry stylesheet,
2. each importer from importers(…), in list order,
3. the loadPaths, which jsass appends as one last built-in importer.

The first importer returning a non-null canonical URL wins. Returning null is the normal way to decline.

Load paths

loadPaths is the plain-filesystem case, and jsass implements it in Java rather than delegating to dart-sass — dart-sass's own file lookup needs an API that only exists in the Node runtime, so doing it ourselves keeps load paths working on V8 too.

A URL that escapes a load path through .. makes that load path decline, and the next one is tried. Multiple load paths are the norm and one tainted entry should not abort the compile.

WebJars

jsass.webjar-importer resolves imports against WebJars on the classpath, which is how you pull Bootstrap or Foundation into a build without checking their sources in:

var locator = new WebJarAssetLocator();

var options = StringOptions.builder()
    .url(URI.create("webjar:style.scss"))
    .importer(WebjarImporter.builder()
        .locator(locator)
        .allowedWebjars(Set.of("bootstrap"))
        .build())
    .build();

@import "bootstrap/scss/bootstrap";

Using the locator in your own code means org.webjars:webjars-locator-core has to be on the compile classpath; jsass only brings it transitively at runtime scope. Sharing one WebJarAssetLocator between the importer and the V8 module resolver saves scanning the classpath twice.

Builder property	Default	Purpose
allowedWebjars	empty	artifact names this importer may serve, case-insensitive
allowClasspathScan	false	true allows any WebJar on the classpath
locator	new WebJarAssetLocator()	reuse one instance across importer and resolver
classLoader	the importer's own	container setups with an isolated classpath
charset	UTF-8	encoding of the stylesheet sources

The allowlist is empty by default

An importer with no allowedWebjars resolves nothing. That is deliberate: without it, any WebJar that happens to be on the classpath — including one pulled in transitively — could be reached from a stylesheet. Name the artifacts you mean, or set allowClasspathScan(true) if you accept the wider surface.

Failure modes

Situation	What happens
Importer declines	canonicalize returns null, the next importer is asked
Artifact not in allowedWebjars	declines, so another importer still gets its turn
URL contains .. / . segments, or an opaque webjar: URI has no path	SassPathTraversalException — unchecked, aborts the compile
One import matches several stylesheets	AmbiguousImportException naming every candidate
Your importer throws anything else	wrapped as SassImporterExecutionException, reported as a Sass error at the import site

SassPathTraversalException is unchecked because the SPI signature has no throws clause for it. It carries getRequestedPath() and getAllowedRoot() for logging.