{"id":19252727,"url":"https://github.com/morevm/postcss-specificity-decorator","last_synced_at":"2026-02-18T01:02:25.476Z","repository":{"id":37025660,"uuid":"488961724","full_name":"MorevM/postcss-specificity-decorator","owner":"MorevM","description":"PostCSS plugin to increase the specificity of selectors","archived":false,"fork":false,"pushed_at":"2024-06-07T15:17:44.000Z","size":1188,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-09T08:17:34.511Z","etag":null,"topics":["css","postcss","postcss-plugin","specificity"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/MorevM.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-05T12:23:27.000Z","updated_at":"2024-06-07T15:17:48.000Z","dependencies_parsed_at":"2024-11-09T18:29:28.733Z","dependency_job_id":"fed75c59-4e23-41fb-9dc8-3e2051bd4c4f","html_url":"https://github.com/MorevM/postcss-specificity-decorator","commit_stats":{"total_commits":18,"total_committers":2,"mean_commits":9.0,"dds":0.2222222222222222,"last_synced_commit":"290be065e6db709dee5acf72d54018b81158838a"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/MorevM/postcss-specificity-decorator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorevM%2Fpostcss-specificity-decorator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorevM%2Fpostcss-specificity-decorator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorevM%2Fpostcss-specificity-decorator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorevM%2Fpostcss-specificity-decorator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MorevM","download_url":"https://codeload.github.com/MorevM/postcss-specificity-decorator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MorevM%2Fpostcss-specificity-decorator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001101,"owners_count":26082991,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["css","postcss","postcss-plugin","specificity"],"created_at":"2024-11-09T18:28:12.696Z","updated_at":"2025-10-09T08:17:34.743Z","avatar_url":"https://github.com/MorevM.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostCSS specificity decorator\n\n![Stability of \"master\" branch](https://img.shields.io/github/workflow/status/MorevM/postcss-specificity-decorator/Build/master)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n![Last commit](https://img.shields.io/github/last-commit/morevm/postcss-specificity-decorator)\n![Release version](https://img.shields.io/github/v/release/morevm/postcss-specificity-decorator?include_prereleases)\n![GitHub Release Date](https://img.shields.io/github/release-date/morevm/postcss-specificity-decorator)\n![Keywords](https://img.shields.io/github/package-json/keywords/morevm/postcss-specificity-decorator)\n\n[PostCSS](https://github.com/postcss/postcss) plugin to increase the specificity of selectors via decorator-like syntax. \\\nOriginally inspired from [postcss-increase-specificity](https://github.com/MadLittleMods/postcss-increase-specificity),\nthis plugin provides an easier way to pick selectors more selectively.\n\nThe main use case is to provide an easy way to increase the specificity of a selector when there is no way to control\nthe order of file inclusion and, accordingly, the order of selectors. \\\nThese can be glob imports or usage of component frameworks using HOC strategy, etc. \\\nSee details in [\"Why\"](#why) section.\n\n## Table of contents\n\n* [Installation](#installation)\n* [Usage](#usage)\n* [Why?](#why)\n* [SASS limitations](#sass-limitations)\n* [Plugin options](#plugin-options)\n* [Inline plugin options](#inline-plugin-options)\n\n## Installation\n\n\u003e The plugin doesn't ship with `postcss` - so make sure it's already installed.\n\n### Using `yarn`\n\n```bash\nyarn add postcss-specificity-decorator --dev\n```\n\n### Using `npm`\n\n```bash\nnpm install -D postcss-specificity-decorator\n```\n\n### Using `pnpm`\n\n```bash\npnpm add -D postcss-specificity-decorator\n```\n\n\n## Usage\n\n### Basic Example\n\n\u003e The plugin's default export provides a version for PostCSS 8. \\\n\u003e If you need the version for PostCSS 7, import it with `/7` suffix like \\\n\u003e `import specificityDecorator from 'postcss-specificity-decorator/7';`\n\n```js\nimport postcss from 'postcss';\nimport specificityDecorator from 'postcss-specificity-decorator';\nimport fs from 'fs';\n\nconst input = fs.readFileSync('input.css', { encoding: 'utf8' });\n\nconst output = postcss([\n  specificityDecorator({ /* options */ })\n]).process(input).css;\n\nconsole.log(output);\n```\n\n### Results\n\n#### Input:\n\n```css\n/* @specificity */\n.block {\n  background-color: #ffffff;\n}\n\n.unchanged {\n  color: rebeccapurple;\n}\n\n/* @specificity */\n.foo, .bar {\n  display: none;\n}\n```\n\n#### Output:\n\n```css\n:not(#\\9) .block {\n  background-color: #ffffff;\n}\n\n.unchanged {\n  color: rebeccapurple;\n}\n\n:not(#\\9) .foo,\n:not(#\\9) .bar {\n  display: inline-block;\n  width: 50%;\n}\n```\n\n### What it does?\n\nIt's just prepend a descendant selector piece: `:not(#\\9)` (affects really nothing) repeated the specified `options.repeat` number of times.\n\n---\n\n## Why?\n\nLet's imagine the situation:\n\n```html\n\u003cdiv class=\"external-lib-class my-custom-class\"\u003e\u003c/div\u003e\n```\n\n```css\n/* external lib with no write access */\n.external-lib-class { overflow: hidden; }\n```\n\n```css\n/* our custom styles */\n.my-custom-class { overflow: visible; }\n```\n\nIf external lib stylesheet comes first, the block will have `overflow: visible`. \\\nBut if our custom styles come first, block will have `overflow: hidden;` applied (what's wrong with our intention).\n\nSome environments don't provide a way to control the order in which stylesheets are included. Plugin solves it.\n\n---\n\nIt seems not a big deal to increase specificity manually like `html .my-custom-class`,\nbut it becomes more complicated if you a trying to keep styles structure max flat as possible\n(for example using [BEM methodology](https://en.bem.info/methodology/)) and/or using SCSS:\n\n```html\n\u003cdiv class=\"block\"\u003e\n  \u003cdiv class=\"block__element another-element\"\u003e\u003c/div\u003e\n\u003c/div\u003e\n```\n\n```scss\n// another-element.scss\n.another-element { color: #ffffff; }\n\n// block.scss\n.block {\n  $b: \u0026;\n\n  \u0026__element {\n    color: red;\n\n    #{$b}--active \u0026 { color: blue; }\n  }\n}\n```\n\nThis is a very contrived example, but it shows the point. \\\nThere needs to be a reliable way to make sure that the styles of an element take precedence over the styles of the block itself\nregardless of the order in which the style files are included.\n\n* **But...Can't we use `\u0026 \u0026__element`?** \\\n  No, because nested parent selector will resolve to `.block--active .block .block__element` this way. \\\n  This scenario is solved by adding a modifier to the element itself instead of accessing through the parent block,\n  but this is not always can be controlled (for example, in the case of using external libraries)\n* **Maybe `html .block`?** \\\n  It actually works the same as previous example.\n\nWith plugin:\n\n```scss\n// block.scss\n.block {\n  $b: \u0026;\n\n  \u0026__element { /* specificity */\n    color: red;\n\n    #{$b}--active \u0026 { /* specificity */\n      color: blue;\n    }\n  }\n}\n```\n\nThe problem is gone. \\\nYes, DX in case of using SCSS not so pleasant due [SASS limitations](#sass-limitations),\nbut all way better than other attempts to provide reliable mechanics.\n\n## SASS limitations\n\n### TL;DR\n\n* It works only with `loud comments` because silent comments are stripped during `SCSS` -\u003e `CSS` transformation.\n* Decorator should be placed **inside** of rule, not on top. If there nested rules, decorator should be defined on each rule needed to process. \\\n  Good news is inner media queries can be applied automatically.\n\n### Explanations\n\nThe main thing is, **PostCSS works with CSS**. \\\nIt means `SCSS` -\u003e `CSS` transformation happens **before** plugin runs, and here we are very much tied to how SASS compiler works. \\\nIt doesn't bind comments to rules, so after transformation there is no way to know what the original comment referred to:\n\n```scss\n.block {\n  /* @specificity */\n  \u0026__element {}\n  /* @specificity */\n  \u0026__another-one {}\n}\n\n// It compiles into...\n\n.block {\n  /* @specificity */\n  /* @specificity */\n}\n.block__element {}\n.block__another-one {}\n```\n\n**Thats why we need to put decorator inside the rule** - just to know what it belongs to:\n\n```scss\n.block {\n  \u0026__element { /* @specificity */\n    // ...\n  }\n\n  \u0026__another-one { /* @specificity */\n    // ...\n  }\n}\n```\n\nNested media queries applied automatically:\n\n```scss\n.block {\n  \u0026__element { /* @specificity */\n    // ...\n    @media (max-width: 768px) {\n      // ...\n    }\n  }\n}\n\n// Resolves to...\n\n:not(#\\9) .block__element {}\n\n@media (max-width: 768px) {\n  :not(#\\9) .block__element {}\n}\n```\n\n---\n\nUsing SASS, I believe you are mostly use the silent comments (`// comment`). \\\nBad news here they are never emitted to compiled CSS, so there is no way to make it work. Only loud comments (`/* */`)\n\n## Plugin options\n\n* **``keyword``** \\\n  The keyword in comment that triggers plugin to process the rule. \\\n  The comment should start with that keyword to run. \\\n  Default: `'@specificity'`\n\n* **``sourceType``** \\\n  Set it to `scss` if you are write your styles in SCSS. \\\n  Make sure you are read about [SASS limitations](#sass-limitations). \\\n  Default: `'css'`\n\n## Inline plugin options\n\nBy default, plugin increases specificity with only one `:not(#\\9)` prefix. \\\nIf you need to increase specificity more, you must specify it explicitly by using inline `repeat` option represented by integer number:\n\n```scss\n/* @specificity 3 */\n.block {}\n\n// After transformation it becomes...\n:not(#\\9):not(#\\9):not(#\\9) .block {}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorevm%2Fpostcss-specificity-decorator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorevm%2Fpostcss-specificity-decorator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorevm%2Fpostcss-specificity-decorator/lists"}