{"id":13797,"library":"postcss-styl","title":"PostCSS Stylus Parser","description":"postcss-styl is a PostCSS parser plugin designed to convert Stylus syntax into a PostCSS Abstract Syntax Tree (AST). This allows developers to process Stylus code using the extensive PostCSS plugin ecosystem, enabling transformations like autoprefixing, minification, or custom linting. The current stable version is 0.12.3. The package maintains a fairly active release cadence, primarily addressing bug fixes related to AST correctness and stringification, as seen in recent versions. Its primary differentiator is providing a bridge between the Stylus language and PostCSS, allowing Stylus users to leverage PostCSS tools directly on their `.styl` files, most notably for integration with linters like stylelint.","status":"active","version":"0.12.3","language":"javascript","source_language":"en","source_url":"https://github.com/stylus/postcss-styl","tags":["javascript","postcss","stylus","styl","parser","stringifier","syntax","css"],"install":[{"cmd":"npm install postcss-styl","lang":"bash","label":"npm"},{"cmd":"yarn add postcss-styl","lang":"bash","label":"yarn"},{"cmd":"pnpm add postcss-styl","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a PostCSS plugin and requires PostCSS to function as a parser or syntax definition.","package":"postcss","optional":false}],"imports":[{"note":"Primarily consumed in CommonJS environments or via PostCSS configuration objects. While it might work with `import` for its default export, `require` is the idiomatic way shown in documentation for direct programmatic use.","wrong":"import postcssStyl from 'postcss-styl';","symbol":"postcssStyl","correct":"const postcssStyl = require('postcss-styl');"},{"note":"When used within `stylelint` configuration or `postcss.config.js`, the package name string is passed, not the imported module itself. PostCSS resolves this internally.","wrong":"customSyntax: require('postcss-styl'),","symbol":"customSyntax","correct":"customSyntax: 'postcss-styl',"},{"note":"When programmatically using PostCSS with this parser, pass the imported `postcssStyl` module directly to the `syntax` option of `postcss.process()`.","symbol":"syntax","correct":"postcss([plugin]).process(css, { syntax: postcssStyl });"}],"quickstart":{"code":"const postcss = require('postcss');\nconst autoprefixer = require('autoprefixer');\nconst postcssStyl = require('postcss-styl');\n\nconst stylusCode = `\na\n  color red\n  display flex\n  transform scale(0.5)\n  &__element\n    font-size 14px\n`;\n\nasync function processStylus() {\n  try {\n    const result = await postcss([autoprefixer])\n      .process(stylusCode, {\n        syntax: postcssStyl,\n        from: 'input.styl',\n        to: 'output.css'\n      });\n    console.log(result.css);\n    // Expected output:\n    // a\n    //   color red;\n    //   display -webkit-box;\n    //   display -ms-flexbox;\n    //   display flex;\n    //   -webkit-transform scale(0.5);\n    //   -moz-transform scale(0.5);\n    //   transform scale(0.5);\n    //   &__element {\n    //     font-size 14px;\n    //   }\n  } catch (error) {\n    console.error('Error processing Stylus:', error);\n  }\n}\n\nprocessStylus();","lang":"javascript","description":"This quickstart demonstrates how to use `postcss-styl` to parse Stylus code and apply PostCSS transformations, specifically using `autoprefixer`."},"warnings":[{"fix":"Refer to the GitHub issues and changelog for known limitations or recent fixes before relying on it for critical production workflows without thorough testing.","message":"The plugin is still explicitly stated as being in an 'experimental state' in its README. Users should be aware that while functional, there might be edge cases or breaking changes not yet fully stabilized.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Update any direct GitHub links to `https://github.com/stylus/postcss-styl`.","message":"In version 0.10.0, the package's GitHub repository moved from `ota-meshi/postcss-styl` to `stylus/postcss-styl`. While this primarily affects development and contribution, users referencing the old repository for issues or documentation links should update them.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Always update to the latest patch release (e.g., `0.12.3`) to benefit from the most recent bug fixes. Thoroughly test with your specific Stylus syntax, especially with comments, nesting, and complex expressions.","message":"Incorrect AST generation or stringification for certain Stylus constructs (e.g., comments, indentation, nested blocks with trailing comments, linebreak escapes) has been a recurring theme in bug fixes across multiple minor versions. This indicates potential fragility in parsing complex Stylus structures.","severity":"gotcha","affected_versions":"<0.12.3"}],"env_vars":null,"search_vec":"'0.12.3':50 'abstract':20 'activ':56 'address':60 'allow':25,87 'ast':23,65 'autoprefix':40 'bridg':80 'bug':61 'cadenc':58 'code':30 'convert':14 'correct':66 'css':114 'current':46 'custom':43 'design':12 'develop':26 'differenti':76 'direct':94 'ecosystem':36 'enabl':37 'extens':33 'fair':55 'file':98 'fix':62 'integr':102 'javascript':107 'languag':84 'leverag':91 'like':39,105 'lint':44 'linter':104 'maintain':53 'minif':41 'notabl':100 'packag':52 'parser':3,10,111 'plugin':11,35 'postcss':1,5,9,19,34,86,92,108 'postcss-styl':4 'primari':75 'primarili':59 'process':28 'provid':78 'recent':72 'relat':63 'releas':57 'seen':70 'stabl':47 'stringif':68 'stringifi':112 'styl':6,97,110 'stylelint':106 'stylus':2,15,29,83,88,109 'syntax':16,21,113 'tool':93 'transform':38 'tree':22 'use':31 'user':89 'version':48,73","created_at":"2026-04-20T01:56:21.745896+00:00","updated_at":"2026-04-20T01:56:21.745896+00:00","problems":[{"fix":"Set `customSyntax: 'postcss-styl'` as a string in your configuration files; PostCSS/stylelint handle the resolution.","cause":"Using `customSyntax: require('postcss-styl')` directly in `stylelint` or PostCSS config.","error":"Unknown word `customSyntax`"},{"fix":"Ensure `postcss-styl` is installed as a `devDependency` (`npm install -D postcss-styl` or `yarn add -D postcss-styl`) and is accessible from where stylelint is run.","cause":"The `postcss-styl` package is not installed or not resolvable in the current environment.","error":"Error: Cannot find module 'postcss-styl' when running stylelint."},{"fix":"Use `const postcssStyl = require('postcss-styl');` for Node.js scripts unless your environment explicitly supports ESM.","cause":"Attempting to use ES Modules `import` syntax in a CommonJS-only Node.js environment or configuration file without proper transpilation.","error":"SyntaxError: Missing parentheses in call to 'require' (or similar unexpected token error with import)."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/stylus/postcss-styl","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/postcss-styl","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","http-networking","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}