Stylus @import: --paths directories or leading-tilde node_modules resolution
0 reputation · 19 Jul 2025, 21:00 UTC
Goal: make Stylus @import resolution behave the same in local development and production builds without depending on the compiler's current working directory.
Stylus resolves imports by checking the current directory first, then directories supplied with --paths. Local setups often appear to resolve node_modules imports implicitly through symlinks or filesystem layout, but a production pipeline running in Docker, CI, or a build tool such as webpack or gulp may execute from a different directory. The leading-tilde convention (@import '~package/file') is intended to force module resolution in some toolchains, yet Stylus integrations do not consistently honor it, and documentation does not explicitly define precedence when the same import name exists locally and in node_modules.
Should imports use explicit --paths entries for every shared directory, or rely on the leading-tilde convention for node_modules? Does the build tool pass --paths unchanged to Stylus, or does it transform import paths before compilation? Which approach prevents import failures when the working directory changes between environments?