{"id":13671233,"url":"https://github.com/webpack-contrib/stylus-loader","last_synced_at":"2025-05-13T19:11:37.417Z","repository":{"id":11622335,"uuid":"14120839","full_name":"webpack-contrib/stylus-loader","owner":"webpack-contrib","description":":art: A stylus loader for webpack.","archived":false,"fork":false,"pushed_at":"2025-01-21T17:25:04.000Z","size":3026,"stargazers_count":498,"open_issues_count":1,"forks_count":98,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-05-05T22:40:31.638Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webpack-contrib.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"webpack"}},"created_at":"2013-11-04T19:12:51.000Z","updated_at":"2025-01-21T17:25:09.000Z","dependencies_parsed_at":"2024-07-10T19:53:24.175Z","dependency_job_id":"d7612e0e-c233-4246-a622-43d7f7734594","html_url":"https://github.com/webpack-contrib/stylus-loader","commit_stats":{"total_commits":358,"total_committers":48,"mean_commits":7.458333333333333,"dds":0.7932960893854748,"last_synced_commit":"55e0a20dd4ce4cbd86be964682a5f3b7353d4113"},"previous_names":["shama/stylus-loader"],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fstylus-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fstylus-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fstylus-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webpack-contrib%2Fstylus-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webpack-contrib","download_url":"https://codeload.github.com/webpack-contrib/stylus-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253507177,"owners_count":21919162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T09:01:03.640Z","updated_at":"2025-05-13T19:11:37.402Z","avatar_url":"https://github.com/webpack-contrib.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/webpack/webpack\"\u003e\n    \u003cimg width=\"200\" height=\"200\" src=\"https://webpack.js.org/assets/icon-square-big.svg\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n[![npm][npm]][npm-url]\n[![node][node]][node-url]\n[![tests][tests]][tests-url]\n[![cover][cover]][cover-url]\n[![discussion][discussion]][discussion-url]\n[![size][size]][size-url]\n\n# stylus-loader\n\nA Stylus loader for webpack. Compiles Styl to CSS.\n\n## Getting Started\n\nTo begin, you'll need to install `stylus` and `stylus-loader`:\n\n```console\nnpm install stylus stylus-loader --save-dev\n```\n\nor\n\n```console\nyarn add -D stylus stylus-loader\n```\n\nor\n\n```console\npnpm add -D stylus stylus-loader\n```\n\nThen add the loader to your `webpack` config. For example:\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl$/,\n        loader: \"stylus-loader\", // compiles Styl to CSS\n      },\n    ],\n  },\n};\n```\n\nAnd run `webpack` via your preferred method.\n\n## Options\n\n- **[`stylusOptions`](#stylusOptions)**\n- **[`sourceMap`](#sourcemap)**\n- **[`webpackImporter`](#webpackimporter)**\n- **[`additionalData`](#additionalData)**\n- **[`implementation`](#implementation)**\n\n### `stylusOptions`\n\nType:\n\n```ts\ntype stylusOptions =\n  | {\n      use: Array\u003cstring | Function\u003e;\n      include: Array\u003cstring\u003e;\n      import: Array\u003cstring\u003e;\n      define: Array;\n      includeCSS: false;\n      resolveURL: boolean | Object;\n      lineNumbers: boolean;\n      hoistAtrules: boolean;\n      compress: boolean;\n    }\n  | (loaderContext: LoaderContext) =\u003e Array\u003cstring\u003e;\n```\n\nDefault: `{}`\n\nYou can pass any Stylus specific options to the `stylus-loader` through the `stylusOptions` property in the [loader options](https://webpack.js.org/configuration/module/#ruleoptions--rulequery)\nSee the [Stylus documentation](https://stylus-lang.com/docs/js.html).\nOptions in dash-case should use camelCase.\n\n#### `object`\n\nUse an object to pass options through to Stylus.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl$/,\n        use: [\n          {\n            loader: \"style-loader\",\n          },\n          {\n            loader: \"css-loader\",\n          },\n          {\n            loader: \"stylus-loader\",\n            options: {\n              stylusOptions: {\n                /**\n                 * Specify Stylus plugins to use. Plugins may be passed as\n                 * strings instead of importing them in your Webpack config.\n                 *\n                 * @type {(string|Function)[]}\n                 * @default []\n                 */\n                use: [\"nib\"],\n\n                /**\n                 * Add path(s) to the import lookup paths.\n                 *\n                 * @type {string[]}\n                 * @default []\n                 */\n                include: [path.join(__dirname, \"src/styl/config\")],\n\n                /**\n                 * Import the specified Stylus files/paths.\n                 *\n                 * @type {string[]}\n                 * @default []\n                 */\n                import: [\"nib\", path.join(__dirname, \"src/styl/mixins\")],\n\n                /**\n                 * Define Stylus variables or functions.\n                 *\n                 * @type {Array|Object}\n                 * @default {}\n                 */\n                // Array is the recommended syntax: [key, value, raw]\n                define: [\n                  [\"$development\", process.env.NODE_ENV === \"development\"],\n                  [\"rawVar\", 42, true],\n                ],\n                // Object is deprecated syntax (there is no possibility to specify \"raw')\n                // define: {\n                //   $development: process.env.NODE_ENV === 'development',\n                //   rawVar: 42,\n                // },\n\n                /**\n                 * Include regular CSS on @import.\n                 *\n                 * @type {boolean}\n                 * @default false\n                 */\n                includeCSS: false,\n\n                /**\n                 * Resolve relative url()'s inside imported files.\n                 *\n                 * @see https://stylus-lang.com/docs/js.html#stylusresolveroptions\n                 *\n                 * @type {boolean|Object}\n                 * @default { nocheck: true }\n                 */\n                resolveURL: true,\n                // resolveURL: { nocheck: true },\n\n                /**\n                 * Emits comments in the generated CSS indicating the corresponding Stylus line.\n                 *\n                 * @see https://stylus-lang.com/docs/executable.html\n                 *\n                 * @type {boolean}\n                 * @default false\n                 */\n                lineNumbers: true,\n\n                /**\n                 * Move @import and @charset to the top.\n                 *\n                 * @see https://stylus-lang.com/docs/executable.html\n                 *\n                 * @type {boolean}\n                 * @default false\n                 */\n                hoistAtrules: true,\n\n                /**\n                 * Compress CSS output.\n                 * In the \"production\" mode is `true` by default\n                 *\n                 * @see https://stylus-lang.com/docs/executable.html\n                 *\n                 * @type {boolean}\n                 * @default false\n                 */\n                compress: true,\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n#### `function`\n\nAllows setting the options passed through to Stylus based off of the loader context.\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl/,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"stylus-loader\",\n            options: {\n              stylusOptions: (loaderContext) =\u003e {\n                // More information about available properties https://webpack.js.org/api/loaders/\n                const { resourcePath, rootContext } = loaderContext;\n                const relativePath = path.relative(rootContext, resourcePath);\n\n                if (relativePath === \"styles/foo.styl\") {\n                  return {\n                    paths: [\"absolute/path/c\", \"absolute/path/d\"],\n                  };\n                }\n\n                return {\n                  paths: [\"absolute/path/a\", \"absolute/path/b\"],\n                };\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `sourceMap`\n\nType:\n\n```ts\ntype sourceMap = boolean;\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl$/i,\n        use: [\n          \"style-loader\",\n          {\n            loader: \"css-loader\",\n            options: {\n              sourceMap: true,\n            },\n          },\n          {\n            loader: \"stylus-loader\",\n            options: {\n              sourceMap: true,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `webpackImporter`\n\nType:\n\n```ts\ntype webpackImporter = boolean;\n```\n\nDefault: `true`\n\nEnables/Disables the default Webpack importer.\n\nThis can improve performance in some cases.\nUse it with caution because aliases and `@import` at-rules starting with `~` will not work.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"stylus-loader\",\n            options: {\n              webpackImporter: false,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `additionalData`\n\nType:\n\n```ts\ntype additionalData =\n  | string\n  | (\n      content: string | Buffer,\n      loaderContext: LoaderContext,\n      meta: any\n    ) =\u003e string;\n```\n\nDefault: `undefined`\n\nPrepends `Stylus` code before the actual entry file.\nIn this case, the `stylus-loader` will not override the source but just **prepend** the entry's content.\n\nThis is especially useful when some of your Stylus variables depend on the environment:\n\n\u003e [!NOTE]\n\u003e\n\u003e Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this, like multiple Stylus entry files.\n\n#### `string`\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl/,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"stylus-loader\",\n            options: {\n              additionalData: `@env: ${process.env.NODE_ENV};`,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n#### `function`\n\n##### Sync\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl/,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"stylus-loader\",\n            options: {\n              additionalData: (content, loaderContext) =\u003e {\n                // More information about available properties https://webpack.js.org/api/loaders/\n                const { resourcePath, rootContext } = loaderContext;\n                const relativePath = path.relative(rootContext, resourcePath);\n\n                if (relativePath === \"styles/foo.styl\") {\n                  return \"value = 100px\" + content;\n                }\n\n                return \"value 200px\" + content;\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n##### Async\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl/,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"stylus-loader\",\n            options: {\n              additionalData: async (content, loaderContext) =\u003e {\n                // More information about available properties https://webpack.js.org/api/loaders/\n                const { resourcePath, rootContext } = loaderContext;\n                const relativePath = path.relative(rootContext, resourcePath);\n\n                if (relativePath === \"styles/foo.styl\") {\n                  return \"value = 100px\" + content;\n                }\n\n                return \"value 200px\" + content;\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### `implementation`\n\nType:\n\n```ts\ntype implementation = Function | string;\n```\n\nThe special `implementation` option determines which implementation of Stylus to use. Overrides the locally installed `peerDependency` version of `stylus`.\n\n#### `function`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"stylus-loader\",\n            options: {\n              implementation: require(\"stylus\"),\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n#### `string`\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl/i,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"stylus-loader\",\n            options: {\n              implementation: require.resolve(\"stylus\"),\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n## Examples\n\n### Normal usage\n\nChain the `stylus-loader` with the [`css-loader`](https://github.com/webpack-contrib/css-loader) and the [`style-loader`](https://github.com/webpack-contrib/style-loader) to immediately apply all styles to the DOM.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl$/,\n        use: [\n          {\n            loader: \"style-loader\", // creates style nodes from JS strings\n          },\n          {\n            loader: \"css-loader\", // translates CSS into CommonJS\n          },\n          {\n            loader: \"stylus-loader\", // compiles Stylus to CSS\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### Source maps\n\nTo enable sourcemaps for CSS, you'll need to pass the `sourceMap` property in the loader's options. If this is not passed, the loader will respect the setting for webpack source maps, set in `devtool`.\n\n**webpack.config.js**\n\n```javascript\nmodule.exports = {\n  devtool: \"source-map\", // any \"source-map\"-like devtool is possible\n  module: {\n    rules: [\n      {\n        test: /\\.styl$/,\n        use: [\n          \"style-loader\",\n          {\n            loader: \"css-loader\",\n            options: {\n              sourceMap: true,\n            },\n          },\n          {\n            loader: \"stylus-loader\",\n            options: {\n              sourceMap: true,\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### Using nib with stylus\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl$/,\n        use: [\n          {\n            loader: \"style-loader\", // creates style nodes from JS strings\n          },\n          {\n            loader: \"css-loader\", // translates CSS into CommonJS\n          },\n          {\n            loader: \"stylus-loader\", // compiles Stylus to CSS\n            options: {\n              stylusOptions: {\n                use: [require(\"nib\")()],\n                import: [\"nib\"],\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### Import JSON files\n\nStylus does not provide resolving capabilities in the `json` function.\nTherefore webpack resolver does not work for `.json` files.\nUse [`stylus resolver`](#stylus-resolver).\n\n**index.styl**\n\n```styl\n// Suppose the file is located here `node_modules/vars/vars.json`\njson('vars.json')\n\n@media queries-small\n  body\n    display nope\n\n```\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl$/,\n        use: [\n          \"style-loader\",\n          \"css-loader\",\n          {\n            loader: \"stylus-loader\",\n            options: {\n              stylusOptions: {\n                // Specify the path. where to find files\n                paths: [\"node_modules/vars\"],\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### In production\n\nUsually, it's recommended to extract the style sheets into a dedicated file in production using the [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin). This way your styles are not dependent on JavaScript.\n\n### webpack resolver\n\nWebpack provides an [advanced mechanism to resolve files](https://webpack.js.org/configuration/resolve/).\nThe `stylus-loader` applies the webpack resolver when processing queries.\nThus you can import your Stylus modules from `node_modules`.\n\n```styl\n@import 'bootstrap-styl/bootstrap/index.styl';\n```\n\nUsing `~` is deprecated and can be removed from your code (**we recommend it**), but we still support it for historical reasons.\nWhy you can removed it? The loader will first try to resolve `@import`/`@require` as relative, if it cannot be resolved, the loader will try to resolve `@import`/`@require` inside [`node_modules`](https://webpack.js.org/configuration/resolve/#resolvemodules).\nJust prepend them with a `~` which tells webpack to look up the [`modules`](https://webpack.js.org/configuration/resolve/#resolvemodules).\n\n```styl\n@import \"~bootstrap-styl/bootstrap/index.styl\";\n```\n\nIt's important to only prepend it with `~`, because `~/` resolves to the home-directory.\nWebpack needs to distinguish between `bootstrap` and `~bootstrap`, because CSS and Styl files have no special syntax for importing relative files.\nWriting `@import \"file\"` is the same as `@import \"./file\";`\n\n### Stylus resolver\n\nIf you specify the `paths` option, modules will be searched in the given `paths`.\nThis is Stylus default behavior.\n\n**webpack.config.js**\n\n```js\nmodule.exports = {\n  module: {\n    rules: [\n      {\n        test: /\\.styl/,\n        use: [\n          {\n            loader: \"style-loader\",\n          },\n          {\n            loader: \"css-loader\",\n          },\n          {\n            loader: \"stylus-loader\",\n            options: {\n              stylusOptions: {\n                paths: [path.resolve(__dirname, \"node_modules\")],\n              },\n            },\n          },\n        ],\n      },\n    ],\n  },\n};\n```\n\n### Extracting style sheets\n\nBundling CSS with webpack has some nice advantages like referencing images and fonts with hashed urls or [hot module replacement](https://webpack.js.org/concepts/hot-module-replacement/) in development. In production, on the other hand, it's not a good idea to apply your style sheets depending on JS execution. Rendering may be delayed or even a [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) might be visible. Thus it's often still better to have them as separate files in your final production build.\n\nThere are two possibilities to extract a style sheet from the bundle:\n\n- [`extract-loader`](https://github.com/peerigon/extract-loader) (simpler, but specialized on the css-loader's output)\n- [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin) (more complex, but works in all use-cases)\n\n## Contributing\n\nPlease take a moment to read our contributing guidelines if you haven't yet done so.\n\n[CONTRIBUTING](./.github/CONTRIBUTING.md)\n\n## License\n\n[MIT](./LICENSE)\n\n[npm]: https://img.shields.io/npm/v/stylus-loader.svg\n[npm-url]: https://npmjs.com/package/stylus-loader\n[node]: https://img.shields.io/node/v/stylus-loader.svg\n[node-url]: https://nodejs.org\n[tests]: https://github.com/webpack-contrib/stylus-loader/workflows/stylus-loader/badge.svg\n[tests-url]: https://github.com/webpack-contrib/stylus-loader/actions\n[cover]: https://codecov.io/gh/webpack-contrib/stylus-loader/branch/master/graph/badge.svg\n[cover-url]: https://codecov.io/gh/webpack-contrib/stylus-loader\n[discussion]: https://img.shields.io/github/discussions/webpack/webpack\n[discussion-url]: https://github.com/webpack/webpack/discussions\n[size]: https://packagephobia.now.sh/badge?p=stylus-loader\n[size-url]: https://packagephobia.now.sh/result?p=stylus-loader\n","funding_links":["https://opencollective.com/webpack"],"categories":["Plugins","JavaScript"],"sub_categories":["Rspack Loaders"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Fstylus-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebpack-contrib%2Fstylus-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebpack-contrib%2Fstylus-loader/lists"}