{"id":13519790,"url":"https://github.com/assetgraph/assetgraph-sprite","last_synced_at":"2025-03-31T14:31:11.324Z","repository":{"id":497445,"uuid":"1940646","full_name":"assetgraph/assetgraph-sprite","owner":"assetgraph","description":"AssetGraph plugin for creating sprites from background images","archived":false,"fork":false,"pushed_at":"2025-03-08T22:42:19.000Z","size":538,"stargazers_count":36,"open_issues_count":9,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-17T04:39:13.264Z","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":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/assetgraph.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}},"created_at":"2011-06-23T09:30:42.000Z","updated_at":"2023-05-24T17:19:04.000Z","dependencies_parsed_at":"2023-01-13T10:23:44.814Z","dependency_job_id":"f673bb1b-39e4-41c4-9c8b-5ec1b2b72e13","html_url":"https://github.com/assetgraph/assetgraph-sprite","commit_stats":{"total_commits":397,"total_committers":11,"mean_commits":36.09090909090909,"dds":0.6322418136020151,"last_synced_commit":"7d65516fe7996d5de752306ede397840b7b659f0"},"previous_names":["one-com/assetgraph-sprite"],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assetgraph%2Fassetgraph-sprite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assetgraph%2Fassetgraph-sprite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assetgraph%2Fassetgraph-sprite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/assetgraph%2Fassetgraph-sprite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/assetgraph","download_url":"https://codeload.github.com/assetgraph/assetgraph-sprite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246482961,"owners_count":20784804,"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-01T05:02:03.220Z","updated_at":"2025-03-31T14:31:10.914Z","avatar_url":"https://github.com/assetgraph.png","language":"JavaScript","readme":"# AssetGraph-sprite\n\n[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/assetgraph/assetgraph-sprite?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![NPM version](https://badge.fury.io/js/assetgraph-sprite.svg)](http://badge.fury.io/js/assetgraph-sprite)\n[![Build Status](https://travis-ci.org/assetgraph/assetgraph-sprite.svg?branch=master)](https://travis-ci.org/assetgraph/assetgraph-sprite)\n[![Coverage Status](https://coveralls.io/repos/assetgraph/assetgraph-sprite/badge.svg?style=flat)](https://coveralls.io/r/assetgraph/assetgraph-sprite)\n[![Dependency Status](https://david-dm.org/assetgraph/assetgraph-sprite.svg)](https://david-dm.org/assetgraph/assetgraph-sprite)\n\nA plugin (or \"transform\") for \u003ca\nhref=\"http://github.com/One-com/assetgraph\"\u003eAssetGraph\u003c/a\u003e that\noptimizes CSS background images by creating sprite images. The\nspriting is guided by GET parameters and a set of custom CSS\nproperties with a `-sprite-` prefix.\n\nYou can tell AssetGraph-sprite that you want to sprite a given CSS\nbackground image by adding a `sprite` parameter to its query string:\n\n```css\n.classone {\n  background-image: url(images/thething.png?sprite=mySpriteGroup);\n}\n.classtwo {\n  background-image: url(images/theotherthing.png?sprite=mySpriteGroup);\n}\n```\n\nThis is valid CSS and will also work fine on its own in \"development\nmode\" without a compilation step, so you don't need to rebuild your\nproject all the time, except when you want to test the spriting\nitself. After being run through the AssetGraph-sprite transform it\nwill look something like this (`123` is the id of the generated sprite\nasset and could be any number):\n\n```css\n.classone {\n  background-image: url(123png);\n  background-position: 0 0;\n}\n.classtwo {\n  background-image: url(123png);\n  background-position: -34px 0;\n}\n```\n\nSome additional parameters are supported:\n\n#### `padding=\u003ctop\u003e,\u003cright\u003e,\u003cbottom\u003e,\u003cleft\u003e`\n\nAdds \"keepaway space\" around the image in the sprite. Sometimes\nuseful if the background image is applied to an element that takes\nup a bigger area than the background image. Supports regular CSS\npadding syntax, including the shorthand variants with 1, 2, or 3\nvalues. The only supported unit is `px`. Defaults to `0 0 0 0`. Not\nsupported by the `jim-scott` packer (see the docs for\n`-sprite-packer` below).\n\n#### `spriteNoGroup`\n\nTells AssetGraph-sprite that you want this selector to contain a\n`background-image` property pointing at the sprite image, even\nif the sprite group has a \"group selector\" configured (see below).\n\n## Configuring a sprite\n\nIf you can guarantee that the HTML elements that need to have the\nbackground image applied are also matched by another selector, you can\nsave some more bytes by telling AssetGraph-sprite that it only needs\nto add the `background-image` property pointing at the sprite to that\nselector using the `-sprite-selector-for-group` property:\n\n```css\n.foo {\n  -sprite-selector-for-group: mySpriteGroup;\n}\n.classone {\n  background-image: url(images/thething.png?sprite=mySpriteGroup);\n}\n.classtwo {\n  background-image: url(images/theotherthing.png?sprite=mySpriteGroup);\n}\n```\n\n... which compiles to:\n\n```css\n.foo {\n  background-image: url(123png);\n}\n.classone {\n  background-position: 0 0;\n}\n.classtwo {\n  background-position: -34px 0;\n}\n```\n\nAssetGraph-sprite tries to preserve as much of the original CSS as\npossible, including existing `background` or `background-image`\nproperties in the group selector and the priority (`!important`\nstatus), for example:\n\n```css\n.foo {\n  -sprite-selector-for-group: mySpriteGroup;\n  background: red !important;\n}\n.classone {\n  background: blue url(images/thething.png?sprite=mySpriteGroup) !important;\n}\n```\n\nCompiles to:\n\n```css\n.foo {\n  background: red url(123png) !important;\n}\n.classone {\n  background: blue !important;\n  background-position: 0 0;\n}\n```\n\nYou can tweak the generated sprite images by putting additional\n`-sprite`-prefixed configuration properties into the \"group\nselector\", for example:\n\n```css\n.foo {\n  -sprite-selector-for-group: mySpriteGroup;\n  -sprite-packer: horizontal;\n  -sprite-background-color: #a767ac;\n}\n```\n\nThese options are currently supported:\n\n#### `-sprite-packer: horizontal|vertical|jim-scott|try-all`\n\nSelects the packing algorithm for the sprite. The `horizontal` and\n`vertical` variants naively lay out the images one after the other.\nThis works well when you have a bunch of images with the same height\nor width. The `jim-scott` packer is a little fancier, it's an\nimplementation of \u003ca\nhref=\"http://www.blackpawn.com/texts/lightmaps/\"\u003ea floor planning\nalgorithm\u003c/a\u003e originally invented by Jim Scott for packing\nlightmaps. The Jim Scott packer doesn't support the\n`-sprite-padding` property on the individual images. If you don't\nspecify `-sprite-packer`, the default is `try-all`, which runs all\nthe algorithms and chooses the packing that produces the smallest\nsprite image (area-wise).\n\n#### `-sprite-location: url(...)`\n\nSpecifies the desired location of the sprite. This is useful in\ncombination with the `processImages` transform if you want to\npostprocess the generated sprite image:\n\n```css\n.foo {\n  -sprite-selector-for-group: mySpriteGroup;\n  -sprite-location: url(mySprite.png?pngquant=128);\n}\n.classone {\n  background-position: 0 0;\n}\n```\n\nCompiles to:\n\n```css\n.foo {\n  background: red url(mySprite.png?pngquant=128) !important;\n}\n.classone {\n  background-position: 0 0;\n}\n```\n\n#### `-sprite-image-format: png|jpg`\n\nThe format of the generated sprite. More will be added when \u003ca\nhref=\"http://github.com/LearnBoost/node-canvas\"\u003enode-canvas\u003c/a\u003e gains\nsupport for more image formats.\n\n#### `-sprite-background-color: red|yellow|#123123|transparent|...`\n\nSpecifies the background color for the generated sprite image,\nsupports any color syntax understood by node-canvas, which is the\nentire \u003ca\nhref=\"http://www.w3.org/TR/2003/CR-css3-color-20030514/#numerical\"\u003eCSS3\nColor Module\u003c/a\u003e, as far as I can tell. Defaults to `transparent`.\n\n## Installation\n\n```\n$ npm install assetgraph-sprite\n```\n\n## Usage\n\nSince AssetGraph-sprite is intended to be used as part of an AssetGraph\nworkflow, first you'll need to have AssetGraph installed to use it properly:\n\n```\n$ npm install assetgraph\n```\n\nHere's a stripped-down example that loads all CSS files in a\ndirectory, loads all the images linked to by `background` and\n`background-image` properties, sprites them according to the\n`-sprite-...` instructions, then writes the resulting CSS and\nall the images to a different directory:\n\n```javascript\nvar AssetGraph = require('assetgraph');\n\nnew AssetGraph({ root: 'path/to/css/files' })\n  .loadAssets('*.css')\n  .populate({ followRelations: { type: 'CssImage' } })\n  .queue(require('assetgraph-sprite')())\n  .writeAssetsToDisc({ url: /^file:/ }, 'file:///my/output/dir')\n  .run(function (err) {\n    if (err) throw err;\n    // All done!\n  });\n```\n\nFor a more elaborate example of how AssetGraph-sprite can fit in a\nworkflow, see the \u003ca href=\"https://github.com/One-com/assetgraph-builder/blob/master/bin/buildProduction\"\u003ebuildProduction script in AssetGraph-builder\u003c/a\u003e\n\n## Releases\n\n[Changelog](https://github.com/assetgraph/assetgraph-sprite/blob/master/CHANGELOG.md)\n\n## License\n\nAssetGraph-sprite is licensed under a standard 3-clause BSD license --\nsee the `LICENSE`-file for details.\n","funding_links":[],"categories":["JavaScript","Generators","Sprite Generators"],"sub_categories":["Meetups"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassetgraph%2Fassetgraph-sprite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fassetgraph%2Fassetgraph-sprite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassetgraph%2Fassetgraph-sprite/lists"}