Stylus @require deduplication and path resolution reproducibility

Standardizing the Build Integration

To ensure consistent paths, compression, and sourcemap behavior across a team and CI/CD pipeline, you should standardize on the Stylus JavaScript API (stylus.render) rather than the CLI. The API allows for a locked configuration object that eliminates the variance inherent in shell-based execution and environment-specific CLI flags.

Implementation Requirements

To maintain a strict build contract, the following configuration must be pinned in your build script:

• paths: Define an absolute array of lookup directories. This prevents the compiler from relying on the current working directory of the user, which is the primary cause of resolution divergence.
• compress: Set this to a boolean (true or false) explicitly to avoid version-specific defaults.
• sourcemap: Explicitly define the sourcemap object. To ensure reproducibility, use external files rather than inline maps to avoid bloating the CSS and causing checksum mismatches.

@require and Nested Deduplication

Yes, @require guarantees that a file is included only once per compilation, even when referenced through nested imports. If File A requires File B, and File B requires File C, a subsequent @require 'File C' in File A will be ignored by the compiler. This is the primary mechanism for managing shared variables and mixins without duplicating the resulting CSS output.

Project Maintenance and Long-Term Support

Stylus is currently in a maintenance phase. While it remains functional and stable for existing projects, it does not see the same frequency of feature updates or ecosystem growth as modern alternatives like PostCSS or Sass. For long-term planning, teams should treat Stylus as a legacy-stable tool: it is reliable for maintaining current assets, but new architectural shifts should prioritize standards-compliant CSS or more actively maintained preprocessors.

Verification Steps

To verify that your deduplication and path resolution are working as expected, run the following test:

1. Create a _vars.styl file with a unique class (e.g., .dedup-test { color: red; }).
2. Create a _partial.styl that uses @require '_vars'.
3. Create a main entry file that uses @require '_partial' and @require '_vars'.
4. Compile and verify that .dedup-test appears exactly once in the output.

Diagnostic Detail Needed: Are you currently utilizing node_modules for Stylus libraries? If so, the paths configuration must be augmented to include the specific path to the node_modules directory to prevent resolution failures in CI environments where the folder structure may differ from local development.