CSS 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 CSS 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 the CSS file, found within url(id) from cwd:

1. if id begins with /

   1. cwd is the filesystem root

2. resolve as a file using cwd/id as file

3. otherwise, resolve as a directory using cwd/id as dir

4. otherwise, if id does not begin with /, ./, or ../

   1. resolve as a module using cwd and id

5. otherwise, throw "CSS Module not found"

2.1. Resolve as a File

1. resolve file as the file

2. otherwise, resolve file.css as the file

2.2. Resolve as a Directory

1. resolve the JSON contents of dir/package.json as pkg

   1. if pkg has an exports.css.import field

      1. resolve dir/pkg.exports.css.import as the file

   2. if pkg has an exports.css.default field

      1. resolve dir/pkg.exports.css.default as the file

   3. if pkg has an exports.css field

      1. resolve dir/pkg.exports.css as the file

   4. if pkg has a style field

      1. resolve dir/pkg.style as the file

   5. otherwise, resolve dir/index.css as the file

2.3. Resolve as a Module

1. for each dir in the node modules directory using cwd:

   1. resolve as a file using dir/id as file

   2. otherwise, resolve as a directory using dir/id as dir

2.4. Node Modules Directory

1. segments is cwd split by /

2. count is the length of segments

3. dirs is an empty list

4. while count is greater than 0:

   1. if segments[count] is not node_modules

      1. push a new item to dirs as the /-joined segments[0 - count] and node_modules

   2. count is count minus 1

5. return dirs

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.