{"id":15029515,"url":"https://github.com/twolfson/grunt-spritesmith","last_synced_at":"2026-04-02T02:17:36.474Z","repository":{"id":4332991,"uuid":"5468551","full_name":"twolfson/grunt-spritesmith","owner":"twolfson","description":"Grunt task for converting a set of images into a spritesheet and corresponding CSS variables","archived":false,"fork":false,"pushed_at":"2022-04-27T04:35:29.000Z","size":501,"stargazers_count":1133,"open_issues_count":2,"forks_count":91,"subscribers_count":50,"default_branch":"master","last_synced_at":"2025-12-13T12:22:08.385Z","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/twolfson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"custom":"https://twolfson.com/support-me"}},"created_at":"2012-08-19T05:08:13.000Z","updated_at":"2025-11-05T11:15:05.000Z","dependencies_parsed_at":"2022-08-10T10:14:15.463Z","dependency_job_id":null,"html_url":"https://github.com/twolfson/grunt-spritesmith","commit_stats":null,"previous_names":["ensighten/grunt-spritesmith"],"tags_count":118,"template":false,"template_full_name":null,"purl":"pkg:github/twolfson/grunt-spritesmith","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twolfson%2Fgrunt-spritesmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twolfson%2Fgrunt-spritesmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twolfson%2Fgrunt-spritesmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twolfson%2Fgrunt-spritesmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twolfson","download_url":"https://codeload.github.com/twolfson/grunt-spritesmith/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twolfson%2Fgrunt-spritesmith/sbom","scorecard":{"id":46081,"data":{"date":"2025-08-04","repo":{"name":"github.com/twolfson/grunt-spritesmith","commit":"f6841df7e4f7611bd23062cdcf8e669413dc8900"},"scorecard":{"version":"v5.2.1-28-gc1d103a9","commit":"c1d103a9bb9f635ec7260bf9aa0699466fa4be0e"},"score":3,"checks":[{"name":"Code-Review","score":0,"reason":"Found 2/27 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#packaging"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#pinned-dependencies"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE-MIT:0","Info: FSF or OSI recognized license: MIT License: LICENSE-MIT:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#license"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#vulnerabilities"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 5 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/c1d103a9bb9f635ec7260bf9aa0699466fa4be0e/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-14T22:48:05.574Z","repository_id":4332991,"created_at":"2025-08-14T22:48:05.574Z","updated_at":"2025-08-14T22:48:05.574Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27758420,"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","status":"online","status_checked_at":"2025-12-16T02:00:10.477Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-09-24T20:10:52.586Z","updated_at":"2025-12-17T06:16:18.146Z","avatar_url":"https://github.com/twolfson.png","language":"JavaScript","readme":"# grunt-spritesmith [![Build status](https://travis-ci.org/twolfson/grunt-spritesmith.svg?branch=master)](https://travis-ci.org/twolfson/grunt-spritesmith) [![Subscribe to newsletter](https://img.shields.io/badge/newsletter-subscribe-blue.svg)](http://eepurl.com/bD4qkf)\n\nGrunt task for converting a set of images into a spritesheet and corresponding CSS variables.\n\nA folder of icons processed by `grunt-spritesmith`:\n\n[![Fork icon][fork-icon]][fork-icon] ![+][]\n[![GitHub icon][github-icon]][github-icon] ![+][]\n[![Twitter icon][twitter-icon]][twitter-icon] ![=][]\n\ngenerates a spritesheet:\n\n[![Spritesheet][spritesheet]][spritesheet]\n\nand CSS variables (available in [CSS][], [JSON][], [SASS][], [SCSS][SASS], [LESS][], [Stylus][]):\n\n```stylus\n$fork_offset_x = 0px;\n$fork_offset_y = 0px;\n$fork_width = 32px;\n$fork_height = 32px;\n...\n$github_offset_x = -32px;\n$github_offset_y = 0px;\n$github_width = 32px;\n$github_height = 32px;\n...\n```\n\n[+]: docs/plus.png\n[=]: docs/equals.png\n[fork-icon]: docs/fork.png\n[github-icon]: docs/github.png\n[twitter-icon]: docs/twitter.png\n[spritesheet]: docs/spritesheet.png\n\n[CSS]: https://developer.mozilla.org/en-US/docs/Web/CSS\n[JSON]: http://www.json.org/\n[SASS]: http://sass-lang.com/\n[LESS]: http://lesscss.org/\n[Stylus]: http://learnboost.github.com/stylus/\n\n### Retina support\nAs of `grunt-spritesmith@4.5.0`, retina spritesheets/templates are supported. See the [Retina parameters section](#retina-parameters) for more information.\n\n### Cross-platform support\n`grunt-spritesmith` is supported and tested on Windows, Linux, and Mac OS X.\n\n### Do you like `grunt-spritesmith`?\n[Support us via donations][support-us] or [spread word on Twitter][twitter]\n\n[support-us]: http://bit.ly/support-spritesmith-1\n[twitter]: https://twitter.com/intent/tweet?text=CSS%20sprites%20made%20easy%20via%20grunt-spritesmith\u0026url=https%3A%2F%2Fgithub.com%2Ftwolfson%2Fgrunt-spritesmith\u0026via=twolfsn\n\n## Breaking changes in 5.0.0\nWe are normalizing sprite variables even further to convert any non-alphanumeric/non-dash/non-underscore character to a delimiter character (e.g. `-`). This allows us to support naming retina sprites with `@2x` suffixes, to prevent regressions like [#137][].\n\n[#137]: https://github.com/twolfson/grunt-spritesmith/issues/137\n\n## Breaking changes in 6.0.0\nWe have moved from [spritesmith-engine-spec@1.1.0][] to [spritesmith-engine-spec@2.0.0][]. This means if you use an custom engine (e.g. `gmsmith`, `canvassmith`), then you will need to upgrade it.\n\n```bash\nnpm install my-engine-smith@latest --save-dev\n```\n\nThis is to enable usage of streaming outputs from engines.\n\n[spritesmith-engine-spec@1.1.0]: https://github.com/twolfson/spritesmith-engine-spec/tree/1.1.0\n[spritesmith-engine-spec@2.0.0]: https://github.com/twolfson/spritesmith-engine-spec/tree/2.0.0\n\n## Getting Started\n`grunt-spritesmith` can be installed via npm: `npm install grunt-spritesmith`\n\nThen, add and configure it to your `Gruntfile.js`:\n\n```js\nmodule.exports = function (grunt) {\n  // Configure grunt\n  grunt.initConfig({\n    sprite:{\n      all: {\n        src: 'path/to/your/sprites/*.png',\n        dest: 'destination/of/spritesheet.png',\n        destCss: 'destination/of/sprites.css'\n      }\n    }\n  });\n\n  // Load in `grunt-spritesmith`\n  grunt.loadNpmTasks('grunt-spritesmith');\n};\n```\n\nRun the `grunt sprite` task:\n\n```bash\n$ grunt sprite\nRunning \"sprite:all\" (sprite) task\nFiles \"destination/of/spritesheet.png\", \"destination/of/sprites.css\" created.\n\nDone, without errors.\n```\n\nResults are a spritesheet:\n\n[![Spritesheet][spritesheet]][spritesheet]\n\nand CSS:\n\n```css\n.icon-fork {\n  background-image: url(spritesheet.png);\n  background-position: 0px 0px;\n  width: 32px;\n  height: 32px;\n}\n...\n```\n\n## Documentation\n`grunt-spritesmith` is a [grunt multitask][multitask]. It supports the following parameters:\n\n- src `String|String[]` - Images to use as sprites in spritesheet\n    - For example this can be a glob, `sprites/*.png` or an array of files `['sprite1.png', sprite2.png']`\n- dest `String` - Output location for generated spritesheet\n    - For example `path/to/output/spritesheet.png`\n- destCss `String` - Output location for generated CSS\n    - For example `path/to/output/sprites.css`\n- imgPath `String` - Optional override for spritesheet path specified in CSS\n    - For example if `../sprite.png` is given, then the CSS will have:\n        - `background-image: url(../sprite.png);`\n- padding `Number` - Padding to place to right and bottom between sprites\n    - By default there is no padding\n    - An example usage can be found in the [Examples section](#padding)\n- algorithm `String` - Algorithm to use for positioning sprites in spritesheet\n    - By default this is `binary-tree` which yields the best possible packing\n    - An example usage can be found in the [Examples section](#algorithm)\n    - For more algorithm options, see the [Algorithms section](#algorithms)\n- algorithmOpts `Mixed` - Options to pass through to algorithm\n    - For example we can skip sorting in some algorithms via `{algorithmOpts: {sort: false}}`\n        - This is useful for sprite animations\n    - See your algorithm's documentation for available options\n        - https://github.com/twolfson/layout#algorithms\n- engine `String` - `spritesmith` engine to use\n    - By default this is `pixelsmith`, a `node` based engine\n    - Alternative engines must be installed via `npm install`\n    - An example usage can be found in the [Examples section](#engine)\n    - For more engine options, see the [Engines section](#engines)\n- engineOpts `Object` - Options to pass through to engine for settings\n    - For example `phantomjssmith` accepts `timeout` via `{engineOpts: {timeout: 10000}}`\n    - See your engine's documentation for available options\n- imgOpts `Object` - Options to pass through to engine uring export\n    - For example `gmsmith` supports `quality` via `{imgOpts: {quality: 75}}`\n    - See your engine's documentation for available options\n- cssFormat `String` - CSS format to use\n    - By default this is the format inferred by `destCss'` extension\n        - For example `.styl -\u003e stylus`\n    - For more format options, see our formatting library\n        - https://github.com/twolfson/spritesheet-templates#templates\n- cssTemplate `String|Function` - CSS template to use for rendering output CSS\n    - This overrides `cssFormat`\n    - If a `String` is provided, it must be a path to a [handlebars][] template\n        - An example usage can be found in the [Examples section](#handlebars-template)\n    - If a `Function` is provided, it must have a signature of `function (data)`\n        - An example usage can be found in the [Examples section](#template-function)\n    - For more templating information, see the [Templating section](#templating)\n- cssHandlebarsHelpers `Object` - Container for helpers to register to [handlebars][] for our template\n    - Each key-value pair is the name of a [handlebars][] helper corresponding to its function\n    - For example, `{half: function (num) { return num/2; }` will add a [handlebars][] helper that halves numbers\n- cssVarMap `Function` - Mapping function for each filename to CSS variable\n    - For more information, see [Variable mapping](#variable-mapping)\n- cssSpritesheetName `String` - Name to use for spritesheet related variables in preprocessor templates\n- cssOpts `Object` - Options to pass through to templater\n    - For example `{cssOpts: {functions: false}}` skips output of mixins\n    - See your template's documentation for available options\n        - https://github.com/twolfson/spritesheet-templates#templates\n\n[multitask]: http://gruntjs.com/creating-tasks#multi-tasks\n[handlebars]: http://handlebarsjs.com/\n\n### Retina parameters\n`grunt-spritesmith` supports retina spritesheet generation via `retinaSrcFilter` and `retinaDest`. If at least one of these is provided, then we will expect the other and enable retina spritesheet generation.\n\nRepeated parameters have the same properties as above but are repeated for clarity with respect to retina spritesheets.\n\nAn example retina spritesheet setup can be found in the [Examples section](#retina-spritesheet).\n\n- src `String|String[]` - Images to use for both normal and retina spritesheet\n    - For example `sprites/*.png` should capture `sprite1.png` and `sprite1@2x.png`\n    - These must be ordered such that when the retina images are filtered into a separate array, the normal and retina images will have the same indices\n    - **We strongly encourage using the `@2x` suffix over `-retina` or `-2x`. There are known ordering issues caused when sharing a `-` delimiter between sprite names and the retina suffix (see [#137][])**\n- retinaSrcFilter `String|String[]` - Images to filter out from `src` for our retina spritesheet\n    - This can be a glob as with `src` (e.g. `sprite/*@2x.png`)\n    - The path/glob used should line up with `src` (e.g. `src: 'sprite/*.png'`, `retinaSrcFilter: 'sprite/*@2x.png'`)\n    - For example `sprites/*@2x.png` will filter out `sprite1@2x.png` for a separate retina spritesheet\n        - Under the hood, we will group `sprite1.png` and `sprite1@2x.png` as a group of normal/retina sprites\n- retinaDest `String` - Output location for generated retina spritesheet\n    - For example `path/to/output@2x.png`\n- retinaImgPath - Optional override for retina spritesheet path specified in CSS\n    - For example `../sprite@2x.png`  will yield CSS with:\n        - `background-image: url(../sprite@2x.png);`\n- padding `Number` - Padding to place to right and bottom between sprites\n    - By default there is no padding\n    - In retina spritesheets, this number will be doubled to maintain perspective\n- cssFormat `String` - CSS format to use\n    - By default this is the format inferred by `destCss'` extension\n        - For example `.styl -\u003e stylus_retina`\n    - For more format options, see our formatting library\n        - https://github.com/twolfson/spritesheet-templates#retina-templates\n- cssVarMap `Function` - Mapping function for each filename to CSS variable\n    - This will run through normal and retina spritesheets\n    - The name used for normal sprites dictates the group name for retina group variables (e.g. `$icon-home` will have group `$icon-home-group`)\n    - For more information, see [Variable mapping](#variable-mapping)\n- cssRetinaSpritesheetName `String` - Name to use for retina spritesheet related variables in preprocessor templates\n- cssRetinaGroupsName `String` - Name to use for retina groups related variables in preprocessor templates\n\n### Algorithms\nImages can be laid out in different fashions depending on the algorithm. We use [`layout`][] to provide you as many options as possible. At the time of writing, here are your options for `algorithm`:\n\n[`layout`]: https://github.com/twolfson/layout\n\n|         `top-down`        |          `left-right`         |         `diagonal`        |           `alt-diagonal`          |          `binary-tree`          |\n|---------------------------|-------------------------------|---------------------------|-----------------------------------|---------------------------------|\n| ![top-down][top-down-img] | ![left-right][left-right-img] | ![diagonal][diagonal-img] | ![alt-diagonal][alt-diagonal-img] | ![binary-tree][binary-tree-img] |\n\n[top-down-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/top-down.png\n[left-right-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/left-right.png\n[diagonal-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/diagonal.png\n[alt-diagonal-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/alt-diagonal.png\n[binary-tree-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/binary-tree.png\n\nMore information can be found in the [`layout`][] documentation:\n\nhttps://github.com/twolfson/layout\n\n### Templating\nThe `cssTemplate` option allows for using a custom template. An example template can be found at:\n\nhttps://github.com/twolfson/spritesheet-templates/blob/9.3.1/lib/templates/stylus.template.handlebars\n\nThe parameters passed into your template are known as `data`. We add some normalized properties via [`spritesheet-templates`][] for your convenience.\n\n- data `Object` Container for parameters\n    - sprites `Object[]` - Array of sprite information\n        - name `String` - Name of the sprite file (sans extension)\n        - x `Number` - Horizontal position of sprite's left edge in spritesheet\n        - y `Number` - Vertical position of sprite's top edge in spritesheet\n        - width `Number` - Width of sprite\n        - height `Number` - Height of sprite\n        - total_width `Number` - Width of entire spritesheet\n        - total_height `Number` - Height of entire spritesheet\n        - image `String` - Relative URL path from CSS to spritesheet\n        - escaped_image `String` - URL encoded `image`\n        - source_image `String` - Path to the original sprite file\n        - offset_x `Number` - Negative value of `x`. Useful to `background-position`\n        - offset_y `Number` - Negative value of `y`. Useful to `background-position`\n        - px `Object` - Container for numeric values including `px`\n            - x `String` - `x` suffixed with `px`\n            - y `String` - `y` suffixed with `px`\n            - width `String` - `width` suffixed with `px`\n            - height `String` - `height` suffixed with `px`\n            - total_width `String` - `total_width` suffixed with `px`\n            - total_height `String` - `total_height` suffixed with `px`\n            - offset_x `String` - `offset_x` suffixed with `px`\n            - offset_y `String` - `offset_y` suffixed with `px`\n    - spritesheet `Object` - Information about spritesheet\n        - width `Number` - Width of entire spritesheet\n        - total_height `Number` - Height of entire spritesheet\n        - image `String` - Relative URL path from CSS to spritesheet\n        - escaped_image `String` - URL encoded `image`\n        - px `Object` - Container for numeric values including `px`\n            - width `String` - `width` suffixed with `px`\n            - height `String` - `height` suffixed with `px`\n    - spritesheet_info `Object` - Container for `spritesheet` metadata and its representation\n        - name `String` - Prefix for spritesheet variables\n    - retina_sprites `Object[]` - Array of retina sprite information\n        - This will only be accessible if we are generating a retina spritesheet\n        - Properties are the same as `sprites` (e.g. `name`, `width`, `source_image`)\n    - retina_spritesheet `Object` - Information about retina spritesheet\n        - This will only be accessible if we are generating a retina spritesheet\n        - Properties are the same as `spritesheet` (e.g. `width`, `px`)\n    - retina_spritesheet_info `Object` - Container for `retina_spritesheet` metadata and its representation\n        - This will only be accessible if we are generating a retina spritesheet\n        - name `String` - Prefix for spritesheet variables\n    - retina_groups `Object[]` - Array of objects that maps to normal and retina sprites\n        - This will only be accessible if we are generating a retina spritesheet\n        - * `Object` - Container for data about sprite mapping\n            - name `String` - Name to refer to mapping by\n            - index `Number` - Index of corresponding normal/retina sprites from `data.sprites`/`data.retina_sprites`\n            - normal `Object` - Normal sprite from `data.sprites` that corresponds to our mapping\n                - This has all the same properties as `data.sprites[*]` (e.g. `name`, `x`, `offset_y`, `px`)\n            - retina `Object` - Retina sprite from `data.retina_sprites` that corresponds to our mapping\n                - This has all the same properties as `data.retina_sprites[*]` (e.g. `name`, `x`, `offset_y`, `px`)\n    - retina_groups_info `Object` - Optional container for metadata about `retina_groups` and its representation\n        - This will only be accessible if we are generating a retina spritesheet\n        - name `String` - Name for `retina_groups`\n    - options `Object` - Options passed in via `cssOpts` in `grunt-spritesmith` config\n\n[`spritesheet-templates`]: https://github.com/twolfson/spritesheet-templates\n\nAn example `sprite` is\n\n```js\n{\n  \"name\": \"sprite2\",\n  \"x\": 10,\n  \"y\": 20,\n  \"width\": 20,\n  \"height\": 30,\n  \"total_width\": 80,\n  \"total_height\": 100,\n  \"image\": \"nested/dir/spritesheet.png\",\n  \"escaped_image\": \"nested/dir/spritesheet.png\",\n  \"source_image\": \"path/to/original/sprite.png\",\n  \"offset_x\": -10,\n  \"offset_y\": -20,\n  \"px\": {\n    \"x\": \"10px\",\n    \"y\": \"20px\",\n    \"width\": \"20px\",\n    \"height\": \"30px\",\n    \"total_width\": \"80px\",\n    \"total_height\": \"100px\",\n    \"offset_x\": \"-10px\",\n    \"offset_y\": \"-20px\"\n  }\n}\n```\n\nIf you are defining a Handlebars template, then you can inherit from an existing template via [`handlebars-layouts`][] (e.g. `{{#extend \"scss\"}}`). An example usage can be found in the [Examples section](#handlebars-inheritance).\n\n[`handlebars-layouts`]: https://github.com/shannonmoeller/handlebars-layouts\n\nExample usages can be found as:\n\n- [Handlebars template](#handlebars-template)\n- [Handlebars inheritance](#handlebars-inheritance)\n- [Template function](#template-function)\n\n#### Variable mapping\nThe `cssVarMap` option allows customization of the CSS variable names\n\n\u003e If you would like to customize CSS selectors in the `css` template, please see https://github.com/twolfson/spritesheet-templates#css\n\nYour `cssVarMap` should be a function with the signature `function (sprite)`. It will receive the same parameters as `sprites` from [Templating](#templating) except for `escaped_image`, `offset_x`,` offset_y`, and `px`.\n\n```js\n// Prefix all sprite names with `sprite-` (e.g. `home` -\u003e `sprite-home`)\ncssVarMap: function (sprite) {\n  sprite.name = 'sprite_' + sprite.name;\n}\n\n// Generates:\n// $sprite_fork_x = 0px;\n// $sprite_fork_y = 0px;\n\n// As oppposed to default:\n// $fork_x = 0px;\n// $fork_y = 0px;\n```\n\n### Engines\nAn engine can greatly improve the speed of your build (e.g. `canvassmith`) or support obscure image formats (e.g. `gmsmith`).\n\nAll `spritesmith` engines adhere to a common specification:\n\nhttps://github.com/twolfson/spritesmith-engine-spec\n\nThis repository adheres to specification version: **2.0.0**\n\nBelow is a list of known engines with their tradeoffs:\n\n#### pixelsmith\n[`pixelsmith`][] is a `node` based engine that runs on top of [`get-pixels`][] and [`save-pixels`][].\n\n[`pixelsmith`]: https://github.com/twolfson/pixelsmith\n[`get-pixels`]: https://github.com/mikolalysenko/get-pixels\n[`save-pixels`]: https://github.com/mikolalysenko/save-pixels\n\n**Key differences:** Doesn't support uncommon image formats (e.g. `tiff`) and not as fast as a compiled library (e.g. `canvassmith`).\n\n#### phantomjssmith\n[`phantomjssmith`][] is a [phantomjs][] based engine. It was originally built to provide cross-platform compatibility but has since been succeeded by [`pixelsmith`][].\n\n**Requirements:** [phantomjs][] must be installed on your machine and on your `PATH` environment variable. Visit [the phantomjs website][phantomjs] for installation instructions.\n\n**Key differences:** `phantomjs` is cross-platform and supports all image formats.\n\n[`phantomjssmith`]: https://github.com/twolfson/phantomjssmith\n[phantomjs]: http://phantomjs.org/\n\n#### canvassmith\n[`canvassmith`][] is a [node-canvas][] based engine that runs on top of [Cairo][].\n\n**Requirements:** [Cairo][] and [node-gyp][] must be installed on your machine.\n\nInstructions on how to install [Cairo][] are provided in the [node-canvas wiki][].\n\n[node-gyp][] should be installed via `npm`:\n\n```bash\nnpm install -g node-gyp\n```\n\n**Key differences:** `canvas` has the best performance (useful for over 100 sprites). However, it is `UNIX` only.\n\n[`canvassmith`]: https://github.com/twolfson/canvassmith\n[node-canvas]: https://github.com/learnboost/node-canvas\n[Cairo]: http://cairographics.org/\n[node-canvas wiki]: (https://github.com/LearnBoost/node-canvas/wiki/_pages\n[node-gyp]: https://github.com/TooTallNate/node-gyp/\n\n#### gmsmith\n[`gmsmith`][] is a [`gm`][] based engine that runs on top of either [Graphics Magick][] or [Image Magick][].\n\n**Requirements:** Either [Graphics Magick][] or [Image Magick][] must be installed on your machine.\n\nFor the best results, install from the site rather than through a package manager (e.g. `apt-get`). This avoids potential transparency issues which have been reported.\n\n[Image Magick][] is implicitly discovered. However, you can explicitly use it via `engineOpts`\n\n```js\n{\n  engineOpts: {\n    imagemagick: true\n  }\n}\n```\n\n**Key differences:** `gmsmith` allows for configuring image quality whereas others do not.\n\n[`gmsmith`]: https://github.com/twolfson/gmsmith\n[`gm`]: https://github.com/aheckmann/gm\n[Graphics Magick]: http://www.graphicsmagick.org/\n[Image Magick]: http://imagemagick.org/\n\n## Examples\n### Algorithm\nIn this example, we will use the `alt-diagonal` algorithm to layout sprites in a non-intersecting manner.\n\n**Configuration:**\n\n```js\n{\n  src: ['fork.png', 'github.png', 'twitter.png'],\n  dest: 'spritesheet.algorithm.png',\n  destCss: 'spritesheet.algorithm.styl',\n  algorithm: 'alt-diagonal'\n}\n```\n\n**Output:**\n\n![algorithm spritesheet](docs/spritesheet.algorithm.png)\n\n### Engine\nIn this example, we will use the `gmsmith` engine to support obscure image formats.\n\n**Requirements:**\n\nInstall `gmsmith` to our `node_modules` via `npm install`.\n\n```bash\nnpm install gmsmith\n```\n\nAlternatively, we can use `--save` or `--save-dev` to save to our `package.json's dependencies` or `devDependenices`.\n\n```bash\nnpm install gmsmith --save  # Updates {\"dependencies\": {\"gmsmith\": \"1.2.3\"}}\nnpm install gmsmith --save-dev  # Updates {\"devDependencies\": {\"gmsmith\": \"1.2.3\"}}\n```\n\n**Configuration:**\n\n```js\n{\n  src: ['fork.png', 'github.png', 'twitter.png'],\n  dest: 'spritesheet.algorithm.png',\n  destCss: 'spritesheet.algorithm.styl',\n  engine: 'gmsmith'\n}\n```\n\n**Output:**\n\n![engine spritesheet](docs/spritesheet.engine.png)\n\n### Padding\nThe `padding` option allows for inserting spacing between images.\n\n**Configuration:**\n\n```js\n{\n  src: ['fork.png', 'github.png', 'twitter.png'],\n  dest: 'spritesheet.padding.png',\n  destCss: 'spritesheet.padding.styl',\n  padding: 20 // Exaggerated for visibility, normal usage is 1 or 2\n}\n```\n\n**Output:**\n\n![padding spritesheet](docs/spritesheet.padding.png)\n\n### Retina spritesheet\nIn this example, we will use generate a normal and retina spritesheet via the `retinaSrcFilter` and `retinaDest` parameters.\n\n**Configuration:**\n\n```js\n{\n  // We have `fork.png`, `fork@2x.png`, ...\n  src: ['fork*.png', 'github*.png', 'twitter*.png'],\n  // This will filter out `fork@2x.png`, `github@2x.png`, ... for our retina spritesheet\n  //   The normal spritesheet will now receive `fork.png`, `github.png`, ...\n  retinaSrcFilter: ['*@2x.png'],\n  dest: 'spritesheet.retina.png',\n  retinaDest: 'spritesheet.retina@2x.png',\n  destCss: 'spritesheet.retina.styl'\n}\n```\n\n**Normal spritesheet:**\n\n![Normal spritesheet](docs/spritesheet.retina.png)\n\n**Retina spritesheet:**\n\n![Retina spritesheet](docs/spritesheet.retina@2x.png)\n\n### Handlebars template\nIn this example, we will use `cssTemplate` with a `handlebars` template to generate CSS that uses `:before` selectors.\n\n**Template:**\n\n```handlebars\n{{#sprites}}\n.icon-{{name}}:before {\n  display: block;\n  background-image: url({{{escaped_image}}});\n  background-position: {{px.offset_x}} {{px.offset_y}};\n  width: {{px.width}};\n  height: {{px.height}};\n}\n{{/sprites}}\n```\n\n**Configuration:**\n\n```js\n{\n  src: ['fork.png', 'github.png', 'twitter.png'],\n  dest: 'spritesheet.handlebarsStr.png',\n  destCss: 'spritesheet.handlebarsStr.css',\n  cssTemplate: 'handlebarsStr.css.handlebars'\n}\n```\n\n**Output:**\n\n```css\n.icon-fork:before {\n  display: block;\n  background-image: url(spritesheet.handlebarsStr.png);\n  background-position: 0px 0px;\n  width: 32px;\n  height: 32px;\n}\n.icon-github:before {\n/* ... */\n```\n\n### Handlebars inheritance\nIn this example, we will extend the SCSS template to provide minimal variables. The JSON at the front comes from the original template and is required to provide consistent casing and default options.\n\nDifferent block sections for each template are documented in:\n\nhttps://github.com/twolfson/spritesheet-templates\n\n**Template:**\n\n```handlebars\n{\n  // Default options\n  'functions': true,\n  'variableNameTransforms': ['dasherize']\n}\n\n{{#extend \"scss\"}}\n{{#content \"sprites\"}}\n{{#each sprites}}\n${{strings.name}}: ({{px.x}}, {{px.y}}, {{px.offset_x}}, {{px.offset_y}}, {{px.width}}, {{px.height}}, {{px.total_width}}, {{px.total_height}}, '{{{escaped_image}}}', '{{name}}', );\n{{/each}}\n{{/content}}\n{{#content \"spritesheet\"}}\n${{spritesheet_info.strings.name_sprites}}: ({{#each sprites}}${{strings.name}}, {{/each}});\n${{spritesheet_info.strings.name}}: ({{spritesheet.px.width}}, {{spritesheet.px.height}}, '{{{spritesheet.escaped_image}}}', ${{spritesheet_info.strings.name_sprites}}, );\n{{/content}}\n{{/extend}}\n```\n\n**Configuration:**\n\n```js\n{\n  src: ['fork.png', 'github.png', 'twitter.png'],\n  dest: 'spritesheet.handlebarsInheritance.png',\n  destCss: 'spritesheet.handlebarsInheritance.css',\n  cssTemplate: 'handlebarsInheritance.scss.handlebars'\n}\n```\n\n**Output:**\n\n```scss\n$fork: (0px, 0px, 0px, 0px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'fork', );\n$github: (32px, 0px, -32px, 0px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'github', );\n$twitter: (0px, 32px, 0px, -32px, 32px, 32px, 64px, 64px, 'spritesheet.handlebarsInheritance.png', 'twitter', );\n$spritesheet-sprites: ($fork, $github, $twitter, );\n$spritesheet: (64px, 64px, 'spritesheet.handlebarsInheritance.png', $spritesheet-sprites, );\n/* ... */\n```\n\n### Template function\nIn this example, we will use `cssTemplate` with a custom function that generates YAML.\n\n**Configuration:**\n\n```js\n// var yaml = require('js-yaml');\n{\n  src: ['fork.png', 'github.png', 'twitter.png'],\n  dest: 'spritesheet.yamlTemplate.png',\n  destCss: 'spritesheet.yamlTemplate.yml',\n  cssTemplate: function (data) {\n    // Convert sprites from an array into an object\n    var spriteObj = {};\n    data.sprites.forEach(function (sprite) {\n      // Grab the name and store the sprite under it\n      var name = sprite.name;\n      spriteObj[name] = sprite;\n\n      // Delete the name from the sprite\n      delete sprite.name;\n    });\n\n    // Return stringified spriteObj\n    return yaml.safeDump(spriteObj);\n  }\n}\n```\n\n**Output:**\n\n```yaml\nfork:\n  x: 0\n  \"y\": 0\n  width: 32\n  height: 32\n  source_image: fork.png\n  image: spritesheet.yamlTemplate.png\n  total_width: 64\n  total_height: 64\n  escaped_image: spritesheet.yamlTemplate.png\n  offset_x: -0.0\n  offset_y: -0.0\n  px:\n    x: 0px\n    \"y\": 0px\n    offset_x: 0px\n    offset_y: 0px\n    height: 32px\n    width: 32px\n    total_height: 64px\n    total_width: 64px\ngithub:\n  x: 32\n  # ...\n```\n\n## Contributing\nIn lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via `npm run lint` and test via `npm test`.\n\n## Attribution\n[GitHub][github-icon] and [Twitter][twitter-icon] icons were taken from [Alex Peattie's JustVector Social Icons][justvector].\n\n[Fork][noun-fork-icon] designed by [P.J. Onori][onori] from The Noun Project\n\n[Plus][+] and [Equals][=] icons were built using the [Ubuntu Light typeface][ubuntu-light].\n\n[justvector]: http://alexpeattie.com/projects/justvector_icons/\n[noun-fork-icon]: http://thenounproject.com/noun/fork/#icon-No2813\n[onori]: http://thenounproject.com/somerandomdude\n[ubuntu-light]: http://font.ubuntu.com/\n\n## License\nCopyright (c) 2012 Todd Wolfson\n\nLicensed under the MIT license.\n","funding_links":["https://twolfson.com/support-me"],"categories":["Generators"],"sub_categories":["Meetups"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwolfson%2Fgrunt-spritesmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwolfson%2Fgrunt-spritesmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwolfson%2Fgrunt-spritesmith/lists"}