{"id":19652992,"url":"https://github.com/csstools/postcss-custom-utils","last_synced_at":"2025-04-28T17:31:04.236Z","repository":{"id":57327930,"uuid":"159777146","full_name":"csstools/postcss-custom-utils","owner":"csstools","description":"Read, write, and transform Custom Media and Custom Properties from almost anywhere","archived":true,"fork":false,"pushed_at":"2019-06-19T13:03:01.000Z","size":44,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-19T11:05:12.402Z","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":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/csstools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-30T06:14:13.000Z","updated_at":"2024-09-29T10:05:24.000Z","dependencies_parsed_at":"2022-09-17T11:20:49.742Z","dependency_job_id":null,"html_url":"https://github.com/csstools/postcss-custom-utils","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fpostcss-custom-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fpostcss-custom-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fpostcss-custom-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csstools%2Fpostcss-custom-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csstools","download_url":"https://codeload.github.com/csstools/postcss-custom-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251219127,"owners_count":21554443,"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-11-11T15:12:51.434Z","updated_at":"2025-04-28T17:31:04.214Z","avatar_url":"https://github.com/csstools.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostCSS Custom Utils [\u003cimg src=\"https://postcss.github.io/postcss/logo.svg\" alt=\"PostCSS\" width=\"90\" height=\"90\" align=\"right\"\u003e][PostCSS Custom Utils]\n\n[![NPM Version][npm-img]][npm-url]\n[![Build Status][cli-img]][cli-url]\n[![Support Chat][git-img]][git-url]\n\n[PostCSS Custom Utils] lets you read, write, and transform Custom Variables,\nlike Custom Properties, Custom Media, Custom Selectors, and Environment Variables.\n\n## API\n\n### read\n\nThe `read` method reads custom variables from a variety of sources.\n\n```js\nutil.read(\n  '/path/to/source.css',\n  { to: '/path/to/another/source', type: 'css' },\n  '/path/to/source/variables.js',\n  '/path/to/source/variables.json'\n)\n```\n\nFor more details about configuring individual file sources, see\n[readFile](#readFile).\n\n### readCSS\n\nThe `readCSS` method returns an object of custom variables.\n\n```js\nutil.readCSS(root, options) // options = { filename }\n```\n\n#### readCSS filename Option\n\nThe `readCSS` method accepts a `filename` option to determine the source\nmapping for variables.\n\n### readFile\n\n```js\nutil.readFile(filename, options) // options = { from, type, async }\n```\n\n#### readFile Type Option\n\nThe `readFile` method accepts a `type` option to control which kind of file is\nwritten — Common JS using `cjs` or `js`, ES Module using `esm` or `mjs`, JSON\nusing `json`, and css using `css` or anything else. If not specified, the type\nwill be determined by the file extension, and otherwise it will be `css`.\n\n_Note: There is no convention for writing Environment Variable declarations in CSS, and so those variables will not be read from CSS files._\n\n#### readFile Async Option\n\nThe `readFile` method accepts a `async` option to control whether the function\nshould run asynchronously. By default, all read methods run synchronously.\n\n### readRoot\n\nThe `readRoot` method returns an object of custom variables from an AST Root.\n\n```js\nutil.readRoot(root, options) // options = { features, preserve }\n```\n\n_Note: There is no convention for writing Environment Variable declarations in CSS, and so those variables will not be written._\n\n### readRoot Features Option\n\nThe `readRoot` method accepts a `features` option to determine which kinds of\ncustom variables will be read from the AST Root.\n\nThe available options are `customMedia`, `customProperties`, `customSelectors`,\nand `environmentVariables`.\n\n### readRoot Preserve Option\n\nThe `readRoot` method accepts a `preserve` option to determine which kinds of\ncustom variables will be preserved from the AST Root, rather than removed.\n\nThe available options are `customMedia`, `customProperties`, `customSelectors`,\nand `environmentVariables`.\n\n### transformCSS\n\nThe `transformCSS` method returns a transformed string of CSS using custom\nvariables.\n\n```js\nutil.transformCSS(css_string, options) // options = { variables }\n```\n\n### transformFile\n\nThe `transformFile` method returns a transformed string of CSS from a file\nusing custom variables.\n\n```js\nutil.transformFile('path/to/style.css', options) // options = { variables }\n```\n\n### transformRoot\n\nThe `transformRoot` method returns a transformed AST Root using custom\nvariables.\n\n```js\nutil.transformFile('path/to/style.css', options) // options = { variables }\n```\n\n### write\n\nThe `write` method writes custom variables to a variety of destinations.\n\n```js\nutil.write(\n  '/path/to/destination.css',\n  { to: '/path/to/destination', type: 'css' },\n  options // options = { async }\n)\n```\n\nThe last argument passed into the `write` method are the options.\n\n#### write Async Option\n\nThe `write` method accepts a `async` option to control whether the function\nshould run asynchronously. By default, all write methods run synchronously.\n\n### writeFile\n\nThe `writeFile` method writes custom variables to a file.\n\n```js\nutil.writeFile(filename, options) // options = { type }\n```\n\n#### writeFile Type Option\n\nThe `writeCSS` method accepts a `type` option to control which kind of file is\nwritten — Common JS using `cjs` or `js`, ES Module using `esm` or `mjs`, JSON\nusing `json`, and css using `css` or anything else.\n\n_Note: There is no convention for writing Environment Variable declarations in CSS, and so those variables will not be written to CSS files._\n\n#### writeFile Async Option\n\nThe `writeFile` method accepts a `async` option to control whether the function\nshould run asynchronously. By default, the `writeFile` methods runs\nsynchronously.\n\n### writeCJS\n\nThe `writeCJS` method returns custom variables as an Common JS string of code.\n\n```js\nutil.writeCJS(root, options)\n```\n\n### writeCSS\n\nThe `writeCSS` method returns a CSS string of custom variables.\n\n```js\nutil.writeRoot(root, options) // options = { insert }\n```\n\n_Note: There is no convention for writing Environment Variable declarations in CSS, and so those variables will not be written._\n\n#### writeCSS Insert Option\n\nThe `writeCSS` method accepts a `insert` option to control whether the custom\nvariables are inserted `before` or `after` the other CSS.\n\n### writeESM\n\nThe `writeESM` method returns custom variables as an ES Module string of code.\n\n```js\nutil.writeESM(root, options)\n```\n\n### writeJSON\n\nThe `writeJSON` method returns custom variables as a JSON string.\n\n```js\nutil.writeJSON(root, options)\n```\n\n### writeRoot\n\nThe `writeRoot` method returns an Root object with inserted custom variables.\n\n```js\nutil.writeRoot(root, options) // options = { insert }\n```\n\n_Note: There is no convention for writing Environment Variable declarations in CSS, and so those variables will not be written._\n\n#### writeRoot Insert Option\n\nThe `writeRoot` method accepts a `insert` option to control whether the custom\nvariables are inserted `before` or `after` the other CSS.\n\n[cli-img]: https://img.shields.io/travis/csstools/postcss-custom-utils/master.svg\n[cli-url]: https://travis-ci.org/csstools/postcss-custom-utils\n[git-img]: https://img.shields.io/badge/support-chat-blue.svg\n[git-url]: https://gitter.im/postcss/postcss\n[npm-img]: https://img.shields.io/npm/v/postcss-custom-utils.svg\n[npm-url]: https://www.npmjs.com/package/postcss-custom-utils\n\n[PostCSS Custom Utils]: https://github.com/csstools/postcss-custom-utils\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsstools%2Fpostcss-custom-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsstools%2Fpostcss-custom-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsstools%2Fpostcss-custom-utils/lists"}