$ show webpack/stylus-loader
This is a webpack loader that compiles Stylus (.styl) files into CSS. It acts as a bridge between the webpack build system and the Stylus CSS preprocessor, handling import resolution (including glob patterns, node_modules, webpack aliases, and tilde imports), source maps, custom Stylus options, and URL rewriting. The architecture follows the standard webpack loader pattern: it receives the source code, parses options via a JSON schema, renders Stylus using an implementation (defaulting to the `stylus` package), and outputs either the compiled CSS along with source map and dependency list. It supports dual ESM/CJS builds and is compatible with webpack 5 and optionally Rspack. The primary entry point is `src/index.js`, which exports the loader function. Core utilities live in `src/utils.js`, which includes a custom Stylus evaluator that overrides import resolution to delegate to webpack's resolver, utility functions for normalizing options and source maps, and a dependency collector that traverses the Stylus AST to report all imports to webpack's build graph. The loader integrates deeply with webpack's module resolution (aliases, `resolve.byDependency`, custom conditions) and supports advanced Stylus features like CSS module exports, `@import` and `@require`, `@block`, and the `url()` resolver. Externally, it depends on the `stylus` npm package as the core preprocessor, and on webpack's loader API. It is actively maintained, with recent major version bumps aligning with Node.js runtime requirements (v9.0.0 requires Node >=22.11.0). The codebase is well-tested with a comprehensive test suite covering numerous edge cases in import resolution, error handling, and option combinations. While the loader itself is webpack-specific, several internal patterns (custom evaluator, dependency resolution, URL handling) demonstrate non-obvious craftsmanship and could inform similar integrations for other CSS preprocessors.
The LLM identified 1 files worth highlighting for reuse:
This module contains the core extensions to Stylus that enable webpack-aware import resolution and dependency tracking. The `createEvaluator` function returns a subclass of Stylus's Evaluator that overrides `visitImport` to resolve imports via webpack's resolver (supporting file, glob, and alias resolution) instead of Stylus's default filesystem-based resolution. This pattern is reusable for any CSS preprocessor loader that needs to integrate with webpack's module system. The module also exports `getStylusImplementation` (handles custom `stylus` package detection and version checks), `getStylusOptions` (normalizes options including `define`, `import`, `use`), `normalizeSourceMap` (transforms source map formats for webpack compatibility), `resolveFilename` (wrapper for webpack's resolver), and `urlResolver` (modifies Stylus's `url()` handling to preserve relative paths). These utilities are self-contained (only depend on `path`, `util`, and internal Stylus APIs) and could be extracted for use in other build tool integrations or standalone preprocessing scripts.