Stylus @import: --paths directories or leading-tilde node_modules resolution

Question

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?

Tasadduq Burney · Answer

Answer first
Use explicit absolute --paths entries for every shared directory and do not rely on leading-tilde @import '~package/file' for Stylus core. Leading tilde is not a Stylus core feature. Make all paths absolute and fixed to the project root so resolution is identical regardless of the compiler's current working directory.
Do not rely on implicit node_modules resolution. If you need tilde imports, you must confirm the exact build-tool integration strips the tilde and resolves it to node_modules before Stylus runs. Otherwise imports will fail when cwd changes.
Confirmed facts

Stylus core resolves @import relative to the importing file's directory, then searches the directories listed in the paths option.
Paths entries that are relative are interpreted against process.cwd() at render time. A different cwd in Docker, CI, webpack or gulp changes the meaning of a relative path entry.
Stylus core does not treat a leading tilde as special. @import '~package/file' is resolved literally unless a build-tool integration rewrites it before compilation.
Precedence is not formally specified for same-name collisions. In practice local file resolution is checked first, then paths entries in order. Earlier entries win over later ones.

Likely explanation for local vs production differences
Local setups often appear to resolve node_modules implicitly because of symlinks, a co-located node_modules, or the build tool rewriting imports before Stylus sees them. In production the cwd is different, relative --paths entries point elsewhere, and the tilde rewrite may be absent, so the same import fails.
Steps for this case

Identify the Stylus integration used in both environments: CLI, stylus Node API, webpack stylus-loader, gulp-stylus, etc.
Convert all --paths entries to absolute paths resolved from a fixed project root, e.g. path.resolve(projectRoot, 'src/styles') and path.resolve(projectRoot, 'node_modules'). Never pass a relative path entry.
Keep the same absolute paths array in local and production builds. Do not depend on process.cwd().
If you currently use @import '~package/file', test whether the integration strips the tilde. If it does not, replace with an explicit path via --paths or rewrite imports to @import 'package/file' with node_modules in paths.
Verify resolution with a test import from a subdirectory while running the compiler with cwd outside the project. It should succeed only via the absolute paths entries.

Verification

Render a test file that imports a file from a shared directory and from node_modules using the production cwd. Confirm success with absolute paths only.
Assert all paths entries are absolute and identical in local and production configs.
If tilde imports are required, run a minimal build in the actual tool and confirm the tilde is stripped and resolved from node_modules before Stylus compiles.

Missing diagnostic detail that changes the recommendation: which exact Stylus integration and version is used in webpack/gulp/CLI in both local and production? Tilde support and whether --paths is passed unchanged depends entirely on that integration.

Stylus @import: --paths directories or leading-tilde node_modules resolution

1 answer

Answer first

Confirmed facts

Likely explanation for local vs production differences

Steps for this case

Verification

Your perspective belongs here.

0 question comments