Stylus @require duplicate inclusion through path aliases

Direct Answers

Does Stylus resolve symlinks before @require deduplication? Yes. Stylus uses Node.js fs.realpathSync to resolve each import target to its canonical filesystem path. If two import strings (relative, absolute, or symlinked) resolve to the same inode, the file is included only once.

Can the paths option prevent duplicates when the same file is reachable through different forms? The paths option only adds lookup directories; it does not alter the deduplication logic. Deduplication still occurs on the resolved realpath. However, using a single lookup directory consistently can avoid accidentally importing different physical copies of a file (e.g., duplicated packages in nested node_modules).

Is there a documented way to guarantee single inclusion for aliased imports? No explicit configuration exists to toggle deduplication behavior. The guarantee comes from realpath-based comparison, which is the default and only mechanism.

How Deduplication Works

1. Stylus receives an @require path (relative, absolute, or found via paths lookup).
2. It resolves that path to an absolute filesystem path using Node's fs.realpathSync, which follows symlinks.
3. It checks an internal set of already-included realpaths. If the realpath is present, the import is skipped; otherwise the file is read and its realpath added to the set.

This means @require './colors', @require '/abs/path/colors', and @require './link-colors' (where link-colors is a symlink to colors) all map to the same realpath and produce a single inclusion.

Practical Verification

Run these steps in a clean directory to confirm the behavior on your toolchain:

# 1. Create a partial with a visible side effect
echo 'body { color: red }' > colors.styl

# 2. Create a symlink
ln -s colors.styl link-colors.styl

# 3. Entry file requiring both forms
cat > entry.styl <<'EOF'
@require './colors'
@require './link-colors'
EOF

# 4. Compile with Stylus CLI (adds current dir to paths implicitly)
stylus entry.styl -o out.css

# 5. Inspect output — rule should appear exactly once
cat out.css

Repeat with an absolute path @require '/full/path/colors' to confirm cross-form deduplication. Check versions with stylus --version and node --version; the realpath behavior assumes Node.js ≥10.

Caveats

• Windows case-insensitive FS: Paths differing only in case resolve to the same realpath and deduplicate — usually desired, but can surprise cross-platform teams.
• Nested node_modules: If the same package exists in multiple physical locations, each has a distinct realpath and will be included separately. Use a single paths entry pointing to the preferred copy.
• @import vs @require: Only @require deduplicates. A partial that internally uses @import can still emit duplicate CSS.

One Diagnostic Detail

If you are using a non-Node Stylus runtime (e.g., Dart Sass embedded Stylus or a legacy version), run the verification above and report the Stylus and Node versions. The realpath behavior may differ on alternative runtimes.