Choosing Between Less @import (reference) and @import (inline) for Lean CSS Output

Decision: Choose @import (reference) or @import (inline) in Less

When building a stylesheet with Less you often split helpers, variables, and component rules into separate files. The way you import those files influences the final CSS size and whether unused rules appear in the output. This guide helps you decide which import mode to use based on your goals for output size, specificity safety, and modularity.

Constraints and goals

• Minimize generated CSS while keeping every rule that is actually needed.
• Preserve correct selector specificity; avoid accidentally duplicating rules.
• Allow modular imports of helper files (mixins, variables) without runtime overhead.
• Ensure that side‑effect rules such as @keyframes or @font‑face are not unintentionally dropped.

Comparison of the two import modes

Import mode	What it does	Typical output CSS size	When it is appropriate
@import (reference) "file.less"	Imports only symbols (variables, mixins, definitions) that are referenced in the importing file. Rules from the imported file are emitted only if they are used.	Smallest – only the rules that are actually referenced appear.	When you need shared helpers but want to keep the final CSS lean.
@import (inline) "file.less"	Copies the entire content of the imported file into the current file and emits all its rules, regardless of whether they are referenced.	Larger – includes every rule from the imported file.	When you want the imported file's rules to always be present, e.g., legacy CSS, @keyframes, @font‑face, or when using Less as a passthrough.

Trade‑offs

Using @import (reference) reduces file size and prevents duplicate rules, but it relies on the importing file to actually reference each selector you want to keep. If a rule is intended to appear as a side‑effect (for example an animation defined with @keyframes) and nothing in the importing file references it, the rule will be omitted. @import (inline) guarantees that all rules from the imported file are present, which eliminates the risk of missing side‑effects, but it can bloat the output and cause specificity conflicts if the same rules are imported multiple times from different places.

Concrete implementation example

1. Create a helper file helpers.less that contains a mixin and a standalone rule:

// helpers.less
.border-radius(@r) {
  -webkit-border-radius: @r;
  border-radius: @r;
}
.btn {
  color: #fff;
  background: #007bff;
}


Create a main Less file that imports the helpers with the reference flag and uses the mixin:

// main.less
@import (reference) "helpers.less";
.button {
  .border-radius(4px);
}


Compile the Less file to CSS. Run the command in a terminal where you have the Less compiler installed (typically lessc). No special permissions are required beyond read access to the source files and write access to the output directory.

lessc main.less > main.css


Inspect the generated CSS. You should see only the .button rule with the border‑radius properties; the standalone .btn rule should be absent because it was never referenced.

If you instead change the import line to @import (inline) "helpers.less" and repeat the compile step, the output CSS will contain both the .button rule and the .btn rule, demonstrating the size difference.
Validation and practical checks

Verify the Less compiler version supports the feature: run lessc --version and ensure it is 3.x or later (the reference flag was introduced in Less 2.0, but stable behavior is present in 3.x).
To double‑check that no unintended rules are missing, open the generated CSS in a browser and confirm that any expected styles (for example, a .btn button) appear only when you explicitly use them or when you switch to inline import.
For a more detailed view, generate a source map: lessc -s main.less > main.css and examine the map; rules from helpers.less that are not referenced will not appear in the mapping.
As a safety check, compute the file size of the output with wc -c main.css and compare it between the reference and inline variants; the reference version should be noticeably smaller when the imported file contains unused rules.

Limitations
The reference import mode does not affect runtime behavior; it only influences what the compiler emits. If you rely on a rule being present in the CSS file for JavaScript to query (e.g., reading a stylesheet rule via document.styleSheets), you must ensure the rule is either referenced or use inline import. Additionally, because the compiler decides emission based on static analysis, dynamic class names constructed at runtime will not be recognized as references, potentially causing those rules to be omitted.
Decision checklist

Do you need side‑effect rules (@keyframes, @font‑face) that are not referenced? → use inline.
Are you primarily importing mixins and variables? → reference is safe.
Will the same helper be imported in multiple places? → reference prevents duplicate output; inline may cause duplication unless you guard with @import (once) or similar.
Is build time a concern? → both flags have negligible compile‑time cost; the main impact is output size.

Summary
Choose @import (reference) when you want to import helpers, variables, or mixins without bloating the CSS output, provided every rule you need is actually referenced in the importing file. Choose @import (inline) when you need to guarantee that all rules from an imported file appear in the final CSS, such as for legacy stylesheets, animations, or font faces that are not directly referenced.