@require vs @import for shared Stylus partials in a large component library

Question

We maintain a Stylus-based component library where dozens of modules reference the same variables-and-mixins partial. The build compiles everything into one stylesheet through the Stylus CLI, and I need to pick a single inclusion convention for these shared dependencies.

My understanding is that @import inlines the target file at every reference point, while @require includes it only once per compilation. Since our shared partial emits actual rules (not just variables), repeated @import references would seem to duplicate output and could shift cascade order depending on which module is processed first. On the other hand, a few partials intentionally emit rules that must appear at specific positions in the cascade, where deduplication would break that intent.

Path resolution also matters here: modules live at different directory depths, so relative paths and any configured lookup paths affect what actually gets resolved.

Is @require the correct default for shared partials that emit rules, with @import reserved for deliberate re-emission? Does @require deduplication hold when modules are compiled separately and concatenated afterward, or only within a single compilation unit? And is there a documented way to verify which files were inlined during a given compile?

Tasadduq Burney · Answer

The Direct Resolution
For shared partials in a large component library, @require is the correct default for files containing variables and mixins. However, if a partial emits actual CSS rules that must be included in the final output, @require should be used only if those rules are intended to appear once in the entire stylesheet. If rules must be re-emitted or placed at specific points in the cascade, @import is the necessary choice.

Behavioral Differences
The primary distinction lies in how Stylus handles the compilation lifecycle:

@import: Inlines the target file every time it is called. If ten components @import a shared utility file that contains a CSS rule (e.g., a reset or a base class), that rule will be duplicated ten times in the final CSS output.
  @require: Loads the file once per compilation unit and caches the result. Subsequent @require calls for the same file are ignored. This prevents duplication of CSS rules and reduces bundle size.

Compilation Scope and Concatenation
Deduplication via @require only occurs within a single compilation unit. If your build process compiles dozens of modules into separate .css files and then concatenates them using a shell script or a build tool (like Gulp or Webpack), @require will not prevent duplicates across those separate files. Each separate Stylus CLI call is a new compilation unit with its own cache.

Implementation Strategy
To maintain a clean cascade and avoid bloat in a large library, adopt this split:

Definition Partials (Variables, Mixins, Functions): Use @require. These should ideally emit no CSS rules.
  Global Base Rules: Use @require in a single main entry point to ensure they appear once at the top of the cascade.
  Component-Specific Rules: Use @import or a structured entry file that imports components in a specific order to guarantee cascade predictability.

Verification
To verify which files are being inlined and whether rules are duplicating, use the --print flag (or redirect output to a file) and search for repeated selectors:
stylus main.styl -o output.css
# Search for a known rule from your shared partial
grep ".shared-utility-class" output.css | wc -l
If the count is greater than 1, you are experiencing duplication via @import.

Missing Diagnostic: Are your components compiled as individual files and then concatenated, or are they all imported into one master .styl file before a single CLI execution?

@require vs @import for shared Stylus partials in a large component library

1 answer

The Direct Resolution

Behavioral Differences

Compilation Scope and Concatenation

Implementation Strategy

Verification

Your perspective belongs here.

0 question comments