{"id":13671195,"url":"https://github.com/postcss/postcss-url","last_synced_at":"2025-05-15T05:05:45.917Z","repository":{"id":19920192,"uuid":"23186184","full_name":"postcss/postcss-url","owner":"postcss","description":"PostCSS plugin to rebase url(), inline or copy asset.","archived":false,"fork":false,"pushed_at":"2022-06-28T04:49:10.000Z","size":338,"stargazers_count":380,"open_issues_count":39,"forks_count":59,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-08T04:36:44.901Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postcss.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}},"created_at":"2014-08-21T12:25:39.000Z","updated_at":"2025-04-30T14:54:10.000Z","dependencies_parsed_at":"2022-09-04T10:21:48.311Z","dependency_job_id":null,"html_url":"https://github.com/postcss/postcss-url","commit_stats":null,"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postcss%2Fpostcss-url","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postcss%2Fpostcss-url/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postcss%2Fpostcss-url/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postcss%2Fpostcss-url/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postcss","download_url":"https://codeload.github.com/postcss/postcss-url/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253034086,"owners_count":21843804,"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-08-02T09:01:02.554Z","updated_at":"2025-05-15T05:05:45.897Z","avatar_url":"https://github.com/postcss.png","language":"JavaScript","readme":"# postcss-url\n\n[![Travis Build Status](https://img.shields.io/travis/postcss/postcss-url/master.svg?label=unix%20build)](https://travis-ci.org/postcss/postcss-url)\n[![AppVeyor Build Status](https://img.shields.io/appveyor/ci/MoOx/postcss-url/master.svg?label=windows%20build)](https://ci.appveyor.com/project/MoOx/postcss-url)\n[![dependencies Status](https://david-dm.org/postcss/postcss-url/status.svg)](https://david-dm.org/postcss/postcss-url)\n[![devDependencies Status](https://david-dm.org/postcss/postcss-url/dev-status.svg)](https://david-dm.org/postcss/postcss-url?type=dev)\n\n\u003e [PostCSS](https://github.com/postcss/postcss) plugin to rebase, inline or copy on url().\n\n## Installation\n\n```console\n$ npm install postcss postcss-url\n```\n\n## Basic example - rebase\n\n```js\n// dependencies\nconst fs = require(\"fs\")\nconst postcss = require(\"postcss\")\nconst url = require(\"postcss-url\")\n\n// css to be processed\nconst css = fs.readFileSync(\"input.css\", \"utf8\")\n\n// process css\nconst output = postcss()\n  .use(url({\n    url: \"rebase\"\n  }))\n  .process(css, {\n    from: \"src/stylesheet/index.css\",\n    to: \"dist/index.css\"\n  })\n```\nbefore:\n```css\n.element {\n    background: url('images/sprite.png');\n}\n```\nafter:\n```css\n.element {\n    /* rebasing path by new destination */\n    background: url('../src/stylesheet/images/sprite.png');\n}\n```\n\n\n## Inline\n```js\n// postcss-url options\nconst options = {\n    url: 'inline'\n};\n\npostcss()\n  .use(url(options))\n  .process(css, {\n    from: \"src/stylesheet/index.css\",\n    to: \"dist/index.css\"\n  })\n```\nbefore:\n```css\n.element {\n    background: url('/images/sprite.png');\n    filter: url('/images/circle.svg');\n}\n```\nafter:\n```css\n.element {\n    /* inlined png as base64 */\n    background: url('data:image/png;base64,R0lGODlhAQABAJH/AP///wAAAP///wAAACH/C0FET0JFOklSMS4');\n    /* inlined svg as encodeURIComponent */\n    filter: url('data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E');\n}\n```\n\n## Copy\n```js\n// postcss-url options\nconst options = {\n    url: 'copy',\n    // base path to search assets from\n    basePath: path.resolve('node_modules/bootstrap'),\n    // dir to copy assets\n    assetsPath: 'img',\n    // using hash names for assets (generates from asset content)\n    useHash: true\n};\n\npostcss()\n  .use(url(options))\n  .process(css, {\n    from: \"src/stylesheet/index.css\",\n    to: \"dist/index.css\"\n  })\n```\nbefore:\n```css\n.element {\n    background: url('/images/sprite.png');\n}\n```\nafter:\n```css\n.element {\n    /* copy 'sprite.png' from 'node_modules/bootstrap/images/' to 'dist/img/' */\n    /* and rename it by hash function */\n    background: url('img/a2ds3kfu.png');\n}\n```\n\n### Multiple options\n\nprocess first matched option by default.\n```multi: true``` in `custom` will processing with other options\n\n```js\nconst options = [\n    { filter: '**/assets/copy/*.png', url: 'copy', assetsPath: 'img', useHash: true },\n    { filter: '**/assets/inline/*.svg', url: 'inline' },\n    { filter: '**/assets/**/*.gif', url: 'rebase' },\n    // using custom function to build url\n    { filter: 'cdn/**/*', url: (asset) =\u003e `https://cdn.url/${asset.url}` }\n];\n\npostcss().use(url(options))\n```\n\nCheckout [tests](test) for examples.\n\n### Options combinations\n\n* `rebase` - _default_\n  * `assetsPath` - directory to copy assets (relative to `to` or absolute)\n* `inline`\n  * `basePath` - path or array of paths to search assets (relative to `from`, or absolute)\n  * `encodeType` - `base64`, `encodeURI`, `encodeURIComponent`\n  * `includeUriFragment` - include the fragment identifer at the end of the URI\n  * `maxSize` - file size in kbytes\n  * `fallback` - `copy`, `rebase` or custom function for files \u003e `maxSize`\n  * `ignoreFragmentWarning` - do not warn when an SVG URL with a fragment is inlined\n  * `optimizeSvgEncode` - reduce size of inlined svg (IE9+, Android 3+)\n* `copy`\n    * `basePath` - path or array of paths to search assets (relative to `from`, or absolute)\n    * `assetsPath` - directory to copy assets (relative to `to` or absolute)\n    * `useHash` - use filehash(xxhash) for naming\n    * `hashOptions` - options for hash function\n* `custom {Function}`\n    * `multi` - processing with other options\n\n### Options list\n\n#### `url`\n##### `rebase` - _(default)_\nAllow you to fix `url()` according to postcss `to` and/or `from` options (rebase to `to` first if available, otherwise `from` or `process.cwd()`).\n##### `inline` \nAllow you to inline assets using base64 encoding. Can use postcss `from` option to find ressources.\n##### `copy`\nAllow you to copy and rebase assets according to postcss `to`, `assetsPath` and `from` options (`assetsPath` is relative to the option `to`).\n##### `url: {Function}`\nCustom transform function. Takes following arguments:\n* `asset`\n  * `url` - original url\n  * `pathname` - url pathname (url without search or hash)\n  * `absolutePath` - absolute path to asset\n  * `relativePath` - current relative path to asset\n  * `search` - _search_ from `url`, ex. `?query=1` from `./image.png?query=1`\n  * `hash` - _hash_ from `url`, ex. `#spriteLink` from `../asset.svg#spriteLink`\n* `dir`\n  * `from` - postcss option from\n  * `to` - postcss option to\n  * `file` - decl file path\n* `options` - postcss-url matched options\n* `decl` - related postcss declaration object\n* `warn` - wrapped function `result.warn` for current `decl`\n* `result` – postcss result object\n\nAnd should return the transformed url.\nYou can use this option to adjust urls for CDN.\n\n#### `maxSize`\n\nSpecify the maximum file size to inline (in kbytes)\n\n#### `ignoreFragmentWarning`\n_(default: `false`)_\n\nDo not warn when an SVG URL with a fragment is inlined.\nPostCSS-URL does not support partial inlining.  The entire SVG file will be inlined.  By default a warning will be issued when this occurs.\n\n**NOTE:** Only files less than the maximum size will be inlined.\n\n#### `filter`\n\nA regular expression e.g. `/\\.svg$/`, a [minimatch string](https://github.com/isaacs/minimatch) e.g. `'**/*.svg'` or a custom filter function to determine wether a file should be inlined.\n\n#### `fallback`\n\nThe url fallback method to use if max size is exceeded or url contains a hash.\nCustom transform functions are supported.\n\n#### `includeUriFragment`\n_(default: `false`)_\n\nSpecifies whether the URL's fragment identifer value, if present, will be added\nto the inlined data URI.\n\n#### `basePath`\n\nSpecify the base path or list of base paths where to search images from\n\n#### `assetsPath`\n\n_(default: `false`)_\n\nIf you specify an `assetsPath`, the assets files will be copied in that\ndestination\n\n#### `useHash`\n\n_(default: `false`)_\n\nIf set to `true` the copy method is going to rename the path of the files by a hash name\n\n#### `hashOptions`\n\n##### `method`\n\n_(default: `xxhash32`)_\n\nHash method `xxhash32|xxhash64` or custom function (accept file buffer)\n##### `shrink`\n\n_(default: `8`)_\n\nResult hash shrink count\n##### `append`\n\n_(default: `false`)_\n\nPrepend the original filename in resulting filename\n\n---\n\n## Contributing\n\nWork on a branch, install dev-dependencies, respect coding style \u0026 run tests before submitting a bug fix or a feature.\n\n```console\n$ git clone https://github.com/postcss/postcss-url.git\n$ git checkout -b patch-1\n$ npm install\n$ npm test\n```\n\n## [Changelog](CHANGELOG.md)\n\n## [License](LICENSE)\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostcss%2Fpostcss-url","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostcss%2Fpostcss-url","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostcss%2Fpostcss-url/lists"}