Less @import Options: Reference vs. Inline for Clean, Duplicate‑Free CSS Builds

Why Import Options Matter

When you share design tokens, mixins, or utility classes across a multi‑page site or a component library, a simple @import can quickly bloat your output. Every entry point that pulls in a shared file will duplicate its CSS unless you tell Less to treat the file as a dependency rather than a stylesheet. The (reference) and (inline) options give you that fine‑grained control.

Reference Imports: Consume, Don’t Emit

A reference import loads the file’s variables, mixins, and any namespaced symbols, but it suppresses normal rule output. Think of it as "include the code for evaluation only." The imported file becomes a dependency that the compiler tracks, but it never contributes a selector to the final CSS.

Typical use‑case: a shared token file that defines colors, spacing, and mixins that are used by many entry points, but you want the base reset or global styles to appear only once in your bundle.

Example

// lib/tokens.less
@brand-primary: #0b5fff;
.reset { margin: 0; }

// main.less
@import (reference) 'lib/tokens.less';
.card { color: @brand-primary; }

Compiling main.less will emit only the .card rule. The .reset class is omitted because it was imported as a reference.

To make .reset available, import tokens.less normally in a single entry point that needs the global styles:

// base.less
@import 'lib/tokens.less'; // normal import, emits the reset

Inline Imports: Preserve Raw CSS

Use (inline) when the file you import is already valid CSS or contains legacy constructs that Less would otherwise try to parse. The compiler injects the file’s content verbatim, bypassing Less’s parser. This is useful for vendor stylesheets or pre‑compiled CSS snippets.

Example

// vendor.css
@keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }

// main.less
@import (inline) 'vendor.css';
.box { animation: spin 2s linear infinite; }

The @keyframes rule appears exactly as written, without any Less transformation.

Trade‑offs & Caveats

• Hidden Side Effects: Reference imports suppress all CSS output, including global classes, keyframes, or @font-face rules. If you need those rules, import the file normally in an entry point that must emit them.
• Build Contract: Switching a normal import to (reference) can silently remove CSS, which might break a page that relied on a rule in the imported file. Treat import options as part of your build contract and verify the output in CI.
• Resolver Variability: The exact behavior of import options can differ between Less 3.x and 4.x, and between raw Less and bundlers like Webpack’s less-loader. Always test your configuration in the target environment.
• Package Imports: Importing from a package (e.g., @import 'pkg/less/tokens.less';) depends on the resolver configuration. For cross‑project sharing, prefer relative imports or a shared node_modules alias.

Practical Checklist

1. Identify shared files that should only provide variables/mixins (use (reference)).
2. Identify shared files that must emit CSS (use normal @import).
3. For vendor or legacy CSS, use (inline) to avoid parsing errors.
4. Run lessc main.less and inspect the output: ensure only the expected selectors appear.
5. Add a CI step that compares the generated CSS hash against a baseline to catch accidental changes.

Conclusion

Less’s (reference) and (inline) import options give you precise control over what gets emitted into your final stylesheet. By treating shared token files as reference imports and reserving normal imports for truly global styles, you keep your bundles lean and avoid duplicate rules. Just remember to audit the output whenever you change an import’s option, and keep your build contract clear across all entry points.