{"id":15171966,"url":"https://github.com/borodean/postcss-assets","last_synced_at":"2025-10-01T07:30:25.993Z","repository":{"id":22797747,"uuid":"26144133","full_name":"borodean/postcss-assets","owner":"borodean","description":"An asset manager for PostCSS","archived":true,"fork":false,"pushed_at":"2022-08-11T12:06:22.000Z","size":610,"stargazers_count":537,"open_issues_count":13,"forks_count":32,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-10-30T00:11:04.288Z","etag":null,"topics":["postcss"],"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/borodean.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-03T23:38:42.000Z","updated_at":"2024-07-06T09:46:45.000Z","dependencies_parsed_at":"2022-08-21T13:00:11.234Z","dependency_job_id":null,"html_url":"https://github.com/borodean/postcss-assets","commit_stats":null,"previous_names":["assetsjs/postcss-assets"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borodean%2Fpostcss-assets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borodean%2Fpostcss-assets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borodean%2Fpostcss-assets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borodean%2Fpostcss-assets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/borodean","download_url":"https://codeload.github.com/borodean/postcss-assets/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234837153,"owners_count":18894548,"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"],"created_at":"2024-09-27T09:22:48.524Z","updated_at":"2025-10-01T07:30:25.542Z","avatar_url":"https://github.com/borodean.png","language":"JavaScript","readme":"# ![postcss-assets](https://cdn.jsdelivr.net/gh/borodean/postcss-assets@master/media/postcss-assets.svg)\r\n\r\nPostCSS Assets is an asset manager for CSS. It isolates stylesheets from environmental changes, gets image sizes and inlines files.\r\n\r\n[![Unix Build Status][travis-badge]][travis] [![Windows Build Status][appveyor-badge]][appveyor] [![Coverage][coveralls-badge]][coveralls]\r\n\r\n[appveyor]:        https://ci.appveyor.com/project/borodean/postcss-assets/branch/master\r\n[appveyor-badge]:  https://img.shields.io/appveyor/build/borodean/postcss-assets/master?label=windows\r\n[coveralls]:       https://coveralls.io/github/borodean/postcss-assets\r\n[coveralls-badge]: https://img.shields.io/coveralls/github/borodean/postcss-assets/master\r\n[travis]:          https://travis-ci.org/borodean/postcss-assets\r\n[travis-badge]:    https://img.shields.io/travis/borodean/postcss-assets/master?label=unix\r\n\r\nTable of contents\r\n-----------------\r\n\r\n* [Terms of use](#terms-of-use)\r\n* [Installation](#installation)\r\n* [Usage](#usage)\r\n* [URL resolution](#url-resolution)\r\n  * [Load paths](#load-paths)\r\n  * [Base path](#base-path)\r\n  * [Base URL](#base-url)\r\n  * [Relative paths](#relative-paths)\r\n* [Cachebuster](#cachebuster)\r\n* [Image dimensions](#image-dimensions)\r\n* [Inlining files](#inlining-files)\r\n* [Full list of options](#full-list-of-options)\r\n\r\nTerms of use\r\n------------\r\n\r\nBy using this project or its source code, for any purpose and in any shape or form, you grant your **implicit agreement** to all the following statements:\r\n\r\n- You **condemn Russia and its military aggression against Ukraine**\r\n- You **recognize that Russia is an occupant that unlawfully invaded a sovereign state**\r\n- You **support Ukraine's territorial integrity, including its claims over temporarily occupied territories of Crimea and Donbas**\r\n- You **reject false narratives perpetuated by Russian state propaganda**\r\n\r\nGlory to Ukraine! 🇺🇦\r\n\r\nInstallation\r\n------------\r\n\r\n```bash\r\nnpm install postcss-assets --save-dev\r\n```\r\n\r\nUsage\r\n-----\r\n\r\n### [Gulp PostCSS](https://github.com/w0rm/gulp-postcss)\r\n\r\n```js\r\ngulp.task('assets', function () {\r\n  var postcss = require('gulp-postcss');\r\n  var assets  = require('postcss-assets');\r\n\r\n  return gulp.src('source/*.css')\r\n    .pipe(postcss([assets({\r\n      loadPaths: ['images/']\r\n    })]))\r\n    .pipe(gulp.dest('build/'));\r\n});\r\n```\r\n\r\n### [Grunt PostCSS](https://github.com/nDmitry/grunt-postcss)\r\n\r\n```js\r\nvar assets  = require('postcss-assets');\r\n\r\ngrunt.initConfig({\r\n  postcss: {\r\n    options: {\r\n      processors: [\r\n        assets({\r\n          loadPaths: ['images/']\r\n        })\r\n      ]\r\n    },\r\n    dist: { src: 'build/*.css' }\r\n  },\r\n});\r\n```\r\n\r\n**Note: all of the listed options below are parameters for the ```assets``` object, not the top level postcss options object.**\r\n\r\nURL resolution\r\n--------------\r\n\r\nThese options isolate stylesheets from environmental changes.\r\n\r\n### Load paths\r\n\r\nTo make PostCSS Assets search for files in specific directories, define load paths:\r\n\r\n```js\r\nvar options = {\r\n  loadPaths: ['fonts/', 'media/patterns/', 'images/']\r\n};\r\n```\r\n\r\nExample:\r\n\r\n```css\r\nbody {\r\n  background: resolve('foobar.jpg');\r\n  background: resolve('icons/baz.png');\r\n}\r\n```\r\n\r\nPostCSS Assets would look for the files relative to the source file, then in load paths, then in the base path. If it succeed, it would resolve a true URL:\r\n\r\n```css\r\nbody {\r\n  background: url('/media/patterns/foobar.jpg');\r\n  background: url('/images/icons/baz.png');\r\n}\r\n```\r\n\r\n### Base path\r\n\r\nIf the root directory of your site is not where you execute PostCSS Assets, correct it:\r\n\r\n```js\r\nvar options = {\r\n  basePath: 'source/'\r\n};\r\n```\r\n\r\nPostCSS Assets would treat `source` directory as `/` for all URLs and load paths would be relative to it.\r\n\r\n### Base URL\r\n\r\nIf the URL of your base path is not `/`, correct it:\r\n\r\n```js\r\nvar options = {\r\n  baseUrl: 'http://example.com/wp-content/themes/'\r\n};\r\n```\r\n\r\n### Relative paths\r\n\r\nTo make resolved paths relative to the input file, set a flag:\r\n\r\n```js\r\nvar options = {\r\n  relative: true\r\n};\r\n```\r\n\r\nTo relate to a particular directory, set it as a string:\r\n\r\n```js\r\nvar options = {\r\n  relative: 'assets/css'\r\n};\r\n```\r\n\r\nCachebuster\r\n-----------\r\n\r\nPostCSS Assets can bust assets cache:\r\n\r\n```js\r\nvar options = {\r\n  cachebuster: true\r\n};\r\n```\r\n\r\nExample:\r\n\r\n```css\r\nbody {\r\n  background: resolve('/images/icons/baz.png');\r\n}\r\n```\r\n\r\nPostCSS Assets will change urls depending on asset’s modification date:\r\n\r\n```css\r\nbody {\r\n  background: url('/images/icons/baz.png?14a931c501f');\r\n}\r\n```\r\n\r\nTo define a custom cachebuster pass a function as an option:\r\n\r\n```js\r\nvar options = {\r\n  cachebuster: function (filePath, urlPathname) {\r\n    return fs.statSync(filePath).mtime.getTime().toString(16);\r\n  }\r\n};\r\n```\r\n\r\nIf the returned value is falsy, no cache busting is done for the asset.\r\n\r\nIf the returned value is an object the values of `pathname` and/or `query` are used to generate a cache busted path to the asset.\r\n\r\nIf the returned value is a string, it is added as a query string.\r\n\r\nThe returned values for query strings must not include the starting `?`.\r\n\r\nBusting the cache via path:\r\n\r\n```js\r\nvar options = {\r\n  cachebuster: function (filePath, urlPathname) {\r\n    var hash = fs.statSync(filePath).mtime.getTime().toString(16);\r\n    return {\r\n      pathname: path.dirname(urlPathname)\r\n        + '/' + path.basename(urlPathname, path.extname(urlPathname))\r\n        + hash + path.extname(urlPathname),\r\n      query: false // you may omit this one\r\n    }\r\n  }\r\n};\r\n```\r\n\r\nImage dimensions\r\n----------------\r\n\r\nPostCSS Assets calculates dimensions of PNG, JPEG, GIF, SVG and WebP images:\r\n\r\n```css\r\nbody {\r\n  width: width('images/foobar.png'); /* 320px */\r\n  height: height('images/foobar.png'); /* 240px */\r\n  background-size: size('images/foobar.png'); /* 320px 240px */\r\n}\r\n```\r\n\r\nTo correct the dimensions for images with a high density, pass it as a second parameter:\r\n\r\n```css\r\nbody {\r\n  width: width('images/foobar.png', 2); /* 160px */\r\n  height: height('images/foobar.png', 2); /* 120px */\r\n  background-size: size('images/foobar.png', 2); /* 160px 120px */\r\n}\r\n```\r\n\r\nInlining files\r\n--------------\r\n\r\nPostCSS inlines files to a stylesheet in Base64 encoding:\r\n\r\n```css\r\nbody {\r\n  background: inline('images/foobar.png');\r\n}\r\n```\r\n\r\nSVG files would be inlined unencoded, because [then they benefit in size](http://css-tricks.com/probably-dont-base64-svg/).\r\n\r\nFull list of options\r\n--------------------\r\n\r\n| Option        | Description                                                                       | Default |\r\n|:--------------|:----------------------------------------------------------------------------------|:--------|\r\n| `basePath`    | Root directory of the project.                                                    | `.`     |\r\n| `baseUrl`     | URL of the project when running the web server.                                   | `/`     |\r\n| `cachebuster` | If cache should be busted. Pass a function to define custom busting strategy.     | `false` |\r\n| `loadPaths`   | Specific directories to look for the files.                                       | `[]`    |\r\n| `relative`    | Directory to relate to when resolving URLs. When `true`, relates to the input file. When `false`, disables relative URLs. | `false` |\r\n| `cache`       | When `true`, if the input file not been modifed, use the results before cached.   | `false` |\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborodean%2Fpostcss-assets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fborodean%2Fpostcss-assets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborodean%2Fpostcss-assets/lists"}