Interface FileImporter<sync>

A special type of importer that redirects all loads to existing files on disk. Although this is less powerful than a full Importer, it automatically takes care of Sass features like resolving partials and file extensions and of loading the file from disk.

Like all importers, this implements custom Sass loading logic for @use rules and @import rules. It can be passed to Options.importers or StringOptionsWithImporter.importer.

example
const {fileURLToPath} = require('url');

sass.compile('style.scss', {
  importers: [{
    // An importer that redirects relative URLs starting with "~" to
    // `node_modules`.
    findFileUrl(url) {
      if (!url.startsWith('~')) return null;
      return new URL(url.substring(1), pathToFileURL('node_modules'));
    }
  }]
});

Type parameters

Hierarchy

  • FileImporter

Index

Methods

Methods

findFileUrl

  • findFileUrl(url: string, options: { fromImport: boolean }): PromiseOr<null | URL, sync>

  • A callback that's called to partially resolve a load (such as @use or @import) to a file on disk.

    Unlike an Importer, the compiler will automatically handle relative loads for a FileImporter. See Options.importers for more details on the way loads are resolved.

    throws

    any - If this importer recognizes url but determines that it's invalid, it may throw an exception that will be wrapped by Sass. If the exception object has a message property, it will be used as the wrapped exception's message; otherwise, the exception object's toString() will be used. This means it's safe for importers to throw plain strings.

    Parameters

    • url: string

      The loaded URL. Since this might be relative, it's represented as a string rather than a [[URL]] object.

    • options: { fromImport: boolean }
      • fromImport: boolean

        Whether this is being invoked because of a Sass @import rule, as opposed to a @use or @forward rule.

        This should only be used for determining whether or not to load import-only files.

    Returns PromiseOr<null | URL, sync>

    An absolute file: URL if this importer recognizes the url. This may be only partially resolved: the compiler will automatically look for partials, index files, and file extensions based on the returned URL. An importer may also return a fully resolved URL if it so chooses.

    If this importer doesn't recognize the URL, it should return null instead to allow other importers or load paths to handle it.

    This may also return a Promise, but if it does the importer may only be passed to compileAsync and compileStringAsync, not compile or compileString.