Sass Import Resolve

1. Introduction

The purpose of this document is to specify an algorithm for resolving the location of external style sheets included by the @import rule in Sass tooling. It is written for developers and implementors looking for formal guidance, and should match existing implementions.

1.1. The @import rule

The @import rule allows users to import style rules from other style sheets. If an @import rule refers to a valid stylesheet, user agents must treat the contents of the stylesheet as if they were written in place of the @import rule, with two exceptions:

• If a feature *explicitly* defines that it only applies to a particular stylesheet, and not any imported ones (such as the @namespace rule), then it doesn’t apply to the imported stylesheet.
• If a feature relies on the relative position of two or more constructs in a stylesheet (such as the requirement that an @else rule follow another conditional group rule, or the requirement that @charset must not have any other content preceding it), it only applies between constructs in the same stylesheet.

Any @import rules must precede all other at-rules and style rules in a style sheet (besides @charset, which must be the first thing in the style sheet if it exists), or else the @import rule is invalid.

2. Resolve Algorithm

When @import is called, the following high-level algorithm is used to resolve the location of a file within url(id) from cwd:

1. if id begins with /

   1. cwd is the filesystem root

2. file is cwd/id

3. base is base path of file

4. dir is directory path of file

5. if base ends with .sass, .scss, or .css

   1. test whether file exists

   2. if base does not start with _

      1. test whether dir/_base exists

6. otherwise

   1. test whether dir/base.scss exists

   2. test whether dir/base.sass exists

   3. test whether dir/base.css exists

   4. if base does not start with _

      1. test whether dir/_base.scss exists

      2. test whether dir/_base.sass exists

      3. test whether dir/_base.css exists

7. if the length of existing files is 1

   1. return the existing file

8. otherwise, if the length of existing files is greater than 1

   1. throw "It’s not clear which file to import"

9. otherwise, if base does not end with .css

   1. throw "File to import not found or unreadable"

3. Implementations

Parcelify is a tool to add css to your npm modules consumed with browserify. It includes the Resolve Algorithm internally.

PostCSS Import is a PostCSS plugin to transform @import rules by inlining content. It includes the Resolve Algorithm internally, but diverges from the load_as_directory algorithm by using the style field and then the main field if possible.

rework-npm is a tool to import CSS styles from NPM modules using rework. It includes the Resolve Algorithm internally, but diverges by supporting glob notation.