{"id":20217271,"url":"https://github.com/gojek/postcss-customprop-validate","last_synced_at":"2025-07-14T03:30:58.641Z","repository":{"id":51095409,"uuid":"366026290","full_name":"gojek/postcss-customprop-validate","owner":"gojek","description":"PostCSS plugin to validate fallback values of CSS custom properties","archived":false,"fork":false,"pushed_at":"2023-03-20T18:51:23.000Z","size":176,"stargazers_count":3,"open_issues_count":0,"forks_count":4,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-06-18T17:18:00.239Z","etag":null,"topics":["postcss","postcss-plugin"],"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/gojek.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2021-05-10T11:56:15.000Z","updated_at":"2021-07-26T16:59:54.000Z","dependencies_parsed_at":"2025-04-12T04:30:35.327Z","dependency_job_id":null,"html_url":"https://github.com/gojek/postcss-customprop-validate","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gojek/postcss-customprop-validate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gojek%2Fpostcss-customprop-validate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gojek%2Fpostcss-customprop-validate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gojek%2Fpostcss-customprop-validate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gojek%2Fpostcss-customprop-validate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gojek","download_url":"https://codeload.github.com/gojek/postcss-customprop-validate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gojek%2Fpostcss-customprop-validate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265237695,"owners_count":23732514,"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":["postcss","postcss-plugin"],"created_at":"2024-11-14T06:33:08.182Z","updated_at":"2025-07-14T03:30:58.542Z","avatar_url":"https://github.com/gojek.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostCSS Customprop Validate [![Build](https://img.shields.io/github/workflow/status/gojek/postcss-customprop-validate/Test)](https://github.com/gojek/postcss-customprop-validate/actions/workflows/test.yml)\n\n[PostCSS] plugin to validate [fallback values] of CSS custom properties.\n\nValidating the fallback values of CSS custom properties manually can be error prone and challening, specially if there are many.\n\nThis plugin validates the CSS and returns custom properties with incorrect fallback values. It can also modify the source CSS file with the updated values.\n\n## Usage\n\n```js\nconst postcss = require(\"postcss\");\nconst plugin = require(\"postcss-customprop-validate\");\nconst { readFileSync } = require(\"fs\");\n\nconst cssPath = \"./sample.css\";\nconst css = readFileSync(cssPath, \"utf-8\");\n/*\n{\n  font-size: 1rem;\n  color: var(--color-red, #fa0000);\n}\n*/\n\nconst properties = {\n  \"--color-red\": \"#ff0000\",\n};\n\nconst callback = (err, data) =\u003e {\n  if (err) {\n    console.error(err);\n    return;\n  }\n  console.log(data);\n};\n\npostcss([\n  plugin({\n    properties,\n    write: false,\n    callback,\n  }),\n])\n  .process(css, { from: cssPath })\n  .then((result) =\u003e {\n    console.log(result.wrongProps);\n    /*\n     [\n       {\n         path: \"./sample.js\",\n         line: 3,\n         key: \"--color-red\",\n         current: \"#fa0000\",\n         expected: \"#ff0000\"\n       }\n     ]\n    */\n  });\n```\n\nSee [PostCSS] docs for examples for your environment.\n\n## Options\n\nThe plugin accepts an object containing 3 properties:\n\n### **`properties`**\n\nRequired: `true`\n\nAn object containg key and expected fallback values of custom properties. The plugin uses it as the source of truth to validate the CSS.\n\nExample:\n\n```json\n{\n  \"--border-radius\": \"4px\",\n  \"--color-red\": \"#ff0000\",\n  \"--danger-border\":\n    \"var(--border-radius, 4px) solid var(--color-red, #ff0000)\",\n};\n```\n\n### **`write`**\n\nDefault: `false`\n\nModifies the source CSS file with the correct fallback values.\n\n#### Formatting\n\nThe plugin does not preserves the code formatting. If you use a code formatter like [prettier], you may need to re-run it after the plugin modifies the source file.\n\n### **`callback`**\n\nDefault: `() =\u003e {}`\n\nCallback to handle the output of the plugin. The plugin invokes the callback after it processes the CSS of each file. The callback accepts 2 arguments. The first argument is an error object. The second argument is an array of objects. Each object represents an incorrect fallback value having the following shape:\n\n- `path` - absolute path of the CSS file\n- `line` - line number containing the custom property\n- `key` - key of the custom property\n- `current` - current fallback value\n- `expected` - expected fallback value\n\nThe second argument is also available in the plugin's result as `result.wrongProps`\n\n## Example\n\nA sample CSS:\n\n```css\n.foo {\n  border: var(\n    --danger-border,\n    var(--border-radius, 5px) solid var(--color-red, #fa0000)\n  );\n}\n\n.bar {\n  --danger-text: var(--color-red, red);\n  color: var(--danger-text);\n}\n```\n\nThe resultant CSS that the plugin produces:\n\n```diff\n.foo {\n  border: var(\n    --danger-border,\n-    var(--border-radius, 5px) solid var(--color-red, #fa0000)\n+    var(--border-radius, 4px) solid var(--color-red, #ff0000)\n  );\n}\n\n.bar {\n-  --danger-text: var(--color-red, red);\n+  --danger-text: var(--color-red, #ff0000);\n  color: var(--danger-text);\n}\n```\n\nCustom properties with incorrect fallback values:\n\n```js\n[\n  {\n    path: undefined,\n    line: 2,\n    key: \"--danger-border\",\n    current: \"var(--border-radius, 5px) solid var(--color-red, #fa0000)\",\n    expected: \"var(--border-radius, 4px) solid var(--color-red, #ff0000)\",\n  },\n  {\n    path: undefined,\n    line: 9,\n    key: \"--color-red\",\n    current: \"red\",\n    expected: \"#ff0000\",\n  },\n];\n```\n\n[postcss]: https://github.com/postcss/postcss\n[fallback values]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties#custom_property_fallback_values\n[prettier]: https://github.com/prettier/prettier\n[options]: #options\n[response]: #response\n[official docs]: https://github.com/postcss/postcss#usage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgojek%2Fpostcss-customprop-validate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgojek%2Fpostcss-customprop-validate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgojek%2Fpostcss-customprop-validate/lists"}