{"id":13685670,"url":"https://github.com/sprity/sprity","last_synced_at":"2025-04-12T15:34:27.947Z","repository":{"id":30701910,"uuid":"34257932","full_name":"sprity/sprity","owner":"sprity","description":"A image sprite generator","archived":false,"fork":false,"pushed_at":"2022-01-18T13:14:12.000Z","size":251,"stargazers_count":480,"open_issues_count":60,"forks_count":71,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-03T15:09:12.117Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/sprity.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-20T12:04:08.000Z","updated_at":"2025-01-24T02:05:32.000Z","dependencies_parsed_at":"2022-08-07T15:16:54.505Z","dependency_job_id":null,"html_url":"https://github.com/sprity/sprity","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprity%2Fsprity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprity%2Fsprity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprity%2Fsprity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprity%2Fsprity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sprity","download_url":"https://codeload.github.com/sprity/sprity/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248589964,"owners_count":21129714,"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-02T14:00:55.628Z","updated_at":"2025-04-12T15:34:27.924Z","avatar_url":"https://github.com/sprity.png","language":"JavaScript","readme":"# sprity\n\n[![NPM version](https://badge.fury.io/js/sprity.svg)](http://badge.fury.io/js/sprity) [![Build Status](https://travis-ci.org/sprity/sprity.svg?branch=master)](https://travis-ci.org/sprity/sprity) [![Coverage Status](https://img.shields.io/coveralls/sprity/sprity.svg)](https://coveralls.io/r/sprity/sprity) [![Code Climate](https://codeclimate.com/github/sprity/sprity/badges/gpa.svg)](https://codeclimate.com/github/sprity/sprity) [![Dependencies](https://david-dm.org/sprity/sprity.svg)](https://david-dm.org/sprity/sprity)\n\n\u003e A modular image sprite generator.\n\n\u003e Generates sprites and proper style files out of a directory of images.\n\n\u003e Supports retina sprites.\n\n\u003e Can inline base64 encoded sprites.\n\n\u003e Supports different output formats\n\n\u003e Supports different image engines\n\n## Install\n\nInstall with [npm](https://npmjs.org/package/sprity)\n\n```\nnpm install sprity --save\n```\n\nIf you want to use `sprity` on your cli install with:\n\n```\nnpm install sprity -g\n```\n\n## Usage\n\n### Programatic usage\n\n```js\nvar sprity = require('sprity');\nsprity.create(options, cb);\n```\n\n### CLI\n\nSee [sprity-cli](https://npmjs.org/package/sprity-cli) for how to use `sprity` on the command line.\n\n### With [Gulp](http://gulpjs.com)\n\nYou can use the sprity.src method with gulp. It creates a gulp compatible vinyl stream. It takes an options object as its only argument.\n\n```js\nvar gulp = require('gulp');\nvar gulpif = require('gulp-if');\nvar sprity = require('sprity');\n\n// generate sprite.png and _sprite.scss\ngulp.task('sprites', function () {\n  return sprity.src({\n    src: './src/images/**/*.{png,jpg}',\n    style: './sprite.css',\n    // ... other optional options\n    // for example if you want to generate scss instead of css\n    processor: 'sass', // make sure you have installed sprity-sass\n  })\n  .pipe(gulpif('*.png', gulp.dest('./dist/img/'), gulp.dest('./dist/css/')))\n});\n```\n\n### With [Grunt](http://gruntjs.com)\n\nSee [grunt-sprity](https://npmjs.org/package/grunt-sprity) for how to use `sprity` with [Grunt](http://gruntjs.com).\n\n## Options\n\n* **src:**               Array or string of globs to find source images to put into the sprite. Read more about globs [here](https://github.com/isaacs/node-glob) [required]\n* **out:**               path of directory to write sprite file to  [*Default:* process.cwd()]\n* **base64:**            inlines base64 encoded sprites in the style file\n* **cssPath:**           path or url of sprites on the web server used to reference the sprite in the styles (relative or absolute path or full url)  [*Default:* ../images]\n* **dimension:**         used dimensions for the sprite. A combination of ratio and dpi. Read more about dimensions: [How to specify dimensions](#how-to-specify-dimensions)\n* **engine**             image processing engine.  Read more about engines: [Image processing engines](#image-processing-engines) [*Default:* lwip]\n* **format**             output format of the sprite (Depends on what engine is used) [*Default:* png when used with lwip]\n* **name**               name of sprite file without file extension [*Default:* sprite]\n* **processor**          style processing module. Read more about style processors: [Style processors](#style-processors) [css]\n* **template**           output template file, overrides processor option. Read more about templates: [Templates](#templates)\n* **style**              file to write css to, if omitted no css is written (relative to out path)\n* **background**         background color of the sprite in hex  [*Default:* #FFFFFF]\n* **cachebuster**        appends a \"cache buster\" to the background image in the form \"?\u003c...\u003e\" (Boolean)  [*Default:* false]\n* **margin**             margin in px between tiles  [*Default:* 4]\n* **opacity**            background opacity (0 - 100) of the sprite. defaults to 0 when png or 100 when jpg [*Default:* 0]\n* **orientation**        orientation of the sprite image (vertical|horizontal|binary-tree)  [*Default:* vertical]\n* **prefix**             prefix for the class name used in css (without .)\n* **no-sort**            disable sorting of layout. Read more about: [Layout algorithms](https://github.com/twolfson/layout#algorithms)\n* **split**              create sprite images for every sub folder [*Default:* false] [How to use split option](#how-to-use-split-option)\n* **style-indent-char**  Character used for indentation of styles (space|tab) [*Default:* space]\n* **style-indent-size**  Number of characters used for indentation of styles  [*Default:* 2]\n\n## How to specify dimensions\n\nDimensions are used to specify different sizes of sprites. You can for example create a normal and a retina sprite by providing the following object to `sprity's` options:\n\n```js\n'dimension': [{\n  ratio: 1, dpi: 72\n}, {\n  ratio: 2, dpi: 192\n}],\n```\n\nOn command line this would work as follows:\n\n```sh\nsprity out/ images/*.png -s style.css -d 1:72 -d 2:192\n```\n\nYou can provide as many dimensions as you want. Just keep in mind that the source images you provide need to be for the biggest dimension. For the above example the images would need to have 192dpi.\n\n## How to use split option\n\nWhen you enable the split option `sprity` will look at sub directories of the src option and will generate a sprite per sub directory.\nFor example if you have the following directory structure:\n\n```\nsrc\n |- icons\n      |- editor\n      |- file\n      |- maps\n      |- navigation\n      |- notification\n```\n\nand the options:\n\n```javascript\nvar options = {\n  out: './dist',\n  src: './src/icons/**/*.png',\n  split: true\n}\n```\n\n`sprity` will generate the following sprites in ./dist:\n\n* sprite-editor.png\n* sprite-file.png\n* sprite-maps.png\n* sprite-navigation.png\n* sprite-notification.png\n\nWith [sprity-cli](https://npmjs.org/package/sprity-cli) you would use the command:\n\n```sh\nsprity create \"./dist\" \"src/sprites/**/*.png\" --split\n```\n\nTo change the name of the sprites to for example icons-editor.png use the name option:\n\n```javascript\nvar options = {\n  out: './dist',\n  src: './src/icons/**/*.png',\n  split: true,\n  name: 'icons'\n}\n```\n\n## Image processing engines\n\n`sprity` can use different image processing engines. `sprity` uses the engine to create and manipulate the sprites. Image processing engines may have there specific requirements. So before installing one please have a look at the documentation of the engine.\n\n### Installation\n\nSince image engines are just node.js modules you can install them with npm.\n\n```sh\nnpm install \u003cengine-name\u003e\n```\n\n### Usage\n\nYou can switch image engines with the engine option. If the image engine name starts with `sprity-` you can omit that. For example to use [sprity-canvas](https://npmjs.org/package/sprity-canvas):\n\n```sh\nsprity out/ images/*.png -s style.css --engine canvas\n# or\nsprity out/ images/*.png -s style.css --engine sprity-canvas\n```\n\n### Available image processing engines\n\n* [sprity-lwip](https://npmjs.org/package/sprity-lwip) - the default engine. is automatically installed, when installing `sprity`\n* [sprity-canvas](https://npmjs.org/package/sprity-canvas) - uses [node-canvas](https://github.com/Automattic/node-canvas) to create sprites. Has some non-nodejs requirements.\n* [sprity-gm](https://npmjs.org/package/sprity-gm) - uses [gm](https://www.npmjs.com/package/gm) as its image processing library. Requires GraphicsMagick or ImageMagick.\n\n### Write your own\n\nYou can find more about how to write an image processing engine for `sprity` in the [sprity wiki](https://github.com/sprity/sprity/wiki/How-to-write-a-sprity-image-processor-engine)\n\n## Style processors\n\nStyle processors generate are used for the generation of the style files. By default `sprity` can create css files, but with the help of style processors it can generate a lot of different formats.\n\n### Installation\n\nStyle processors are simple node modules, you can install them with npm:\n\n```sh\nnpm install \u003cprocessor-name\u003e\n```\n\n### Usage\n\nYou can switch style processors with the processor option. If the processor name starts with `sprity-` you can omit that. For example to use [sprity-sass](https://npmjs.org/package/sprity-sass):\n\n```sh\nsprity out/ images/*.png -s style.scss --processor sass\n# or\nsprity out/ images/*.png -s style.scss --processor sprity-sass\n```\n\n### Available style processors\n\n* [sprity-css](https://npmjs.org/package/sprity-css) - the default style processor. is automatically installed, when installing `sprity`\n* [sprity-sass](https://npmjs.org/package/sprity-sass) - generates scss or sass files\n* [sprity-less](https://npmjs.org/package/sprity-less) - generates less files\n* [sprity-css-rollover](https://github.com/xErik/sprity-css-rollover) - generates css rollovers\n### Write your own\n\nYou can find more about how to write your own style processor in the [sprity wiki](https://github.com/sprity/sprity/wiki/How-to-write-a-sprity-style-processor)\n\n## Templates\n\nIf you don't want to write a processor module or you only need a simple template for one of you're projects you can use the templating system of `sprity`.\n\n`sprity` uses [http://handlebarsjs.com/](Handlebars) to process your templates. To quickly start you can use the templates from [sprity-css](https://github.com/sprity/sprity-css/blob/master/template/css.hbs) as a starting point.\n\n### Available variables\n\nYou can find more about the variables and functions available in the handlebars templates in the [sprity wiki](https://github.com/sprity/sprity/wiki/Available-variable-in-custom-templates)\n\n---\n[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/sprity/sprity?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n","funding_links":[],"categories":["JavaScript","Generators"],"sub_categories":["Meetups"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsprity%2Fsprity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsprity%2Fsprity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsprity%2Fsprity/lists"}