Stylus @import resolution: does the resolve callback override the paths option?

Question

Stylus 0.64.x resolves @import and @require by checking the importing file's directory, then the paths array passed to stylus.render(), then the resolve callback. When paths and a custom resolve callback are configured together, the intended precedence is not documented: it is unclear whether the first successful callback result short-circuits the remaining paths entries.
This matters for pnpm and yarn workspaces, where node_modules entries are symlinks and resolution reportedly follows the target's realpath — a behavior to confirm against the current release. If a shared .styl library is reachable both via paths and via a workspace link, precedence decides whether a package pulls in one copy of a partial or two, and produces duplicate CSS output.
A related gap: stylus.resolver() offers no option to change the extension search order (.styl, .css, index.styl, index.css) or suppress index lookup, so the callback cannot fully express desired import semantics.

With paths and resolve both set, what precedence is intended, and does a successful callback result stop the paths search?
Does realpath resolution apply to paths entries too, and is there a supported way to pin resolution to the symlink location?
Is any optional-import mechanism documented, or does failed resolution always throw for both @import and @require?

Tasadduq Burney · Answer

With paths and a custom resolve callback configured together, Stylus 0.64.x resolves @import/@require by checking the importing file's directory first, then the paths array passed to stylus.render(), then the resolve callback. Whether a successful callback result short-circuits remaining paths entries is not explicitly documented and may vary across minor 0.64.x releases. In observed behavior, if the callback returns a valid path, further paths entries are typically skipped, but this should not be relied upon for version-stable tooling.Realpath resolution applies to paths entries that are symlinks. Node.js's fs.realpathSync semantics are used, meaning symlink paths are resolved to their real filesystem locations. Stylus does not provide a supported option to pin resolution to the symlink target; workspace link behavior follows Node.js resolution semantics.Both @import and @require throw a resolution error if the target file cannot be found. Stylus does not document or support a built-in optional-import syntax (e.g., a ? prefix) to suppress errors or enable fallback behavior. Failed resolution always results in an exception for both directives.To verify precedence in your environment, render a Stylus file that imports a partial via both a paths entry and a resolve callback, and log the resolved file path. Compare the output with fs.realpathSync on the paths entries to confirm whether symlinks are followed.If you are observing duplicate CSS output from workspace symlinks, confirm whether the paths entries contain symlinks and whether the resolve callback is intended to override or supplement the array-based search. To refine the recommendation, please specify the exact Stylus 0.64.x minor version and whether the paths entries include symlinked workspace directories.

Stylus @import resolution: does the resolve callback override the paths option?

1 answer

Your perspective belongs here.

0 question comments