{"id":13492815,"url":"https://github.com/mixtur/webpack-spritesmith","last_synced_at":"2025-05-15T23:06:33.779Z","repository":{"id":2236921,"uuid":"46037934","full_name":"mixtur/webpack-spritesmith","owner":"mixtur","description":"Webpack plugin that converts set of images into a spritesheet and SASS/LESS/Stylus mixins","archived":false,"fork":false,"pushed_at":"2023-01-04T01:12:19.000Z","size":1450,"stargazers_count":498,"open_issues_count":18,"forks_count":52,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-09T16:53:57.418Z","etag":null,"topics":["spritesmith","webpack-plugin"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mixtur.png","metadata":{"files":{"readme":"Readme.md","changelog":"CHANGELOG.MD","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-12T07:54:38.000Z","updated_at":"2025-01-01T08:01:42.000Z","dependencies_parsed_at":"2023-01-13T11:43:23.782Z","dependency_job_id":null,"html_url":"https://github.com/mixtur/webpack-spritesmith","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixtur%2Fwebpack-spritesmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixtur%2Fwebpack-spritesmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixtur%2Fwebpack-spritesmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixtur%2Fwebpack-spritesmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mixtur","download_url":"https://codeload.github.com/mixtur/webpack-spritesmith/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436944,"owners_count":22070946,"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":["spritesmith","webpack-plugin"],"created_at":"2024-07-31T19:01:09.477Z","updated_at":"2025-05-15T23:06:28.728Z","avatar_url":"https://github.com/mixtur.png","language":"JavaScript","readme":"[![npm](https://img.shields.io/npm/v/webpack-spritesmith.svg)](https://www.npmjs.com/package/webpack-spritesmith)\n\nA webpack plugin that converts a set of images into a spritesheet and SASS/LESS/Stylus mixins, using\n[spritesmith](https://github.com/Ensighten/spritesmith) and [spritesheet-templates](https://github.com/twolfson/spritesheet-templates)\n\nAll ideas are shamelessly taken from [gulp.spritesmith](https://github.com/twolfson/gulp.spritesmith).\n\n### Example\n\nLet's say you have the following folder structure\n\n```\n/\n|-src\n| |-ico\n| | |-new.png\n| | |-open.png\n| | |-save.png\n| | ...\n| |-style.styl\n| ...\n|-webpack.config.js\n\n```\n\nThen you need to instantiate the plugin in the webpack config like this:\n\n```javascript\n\n//webpack.config.js\nvar path = require('path');\n\nvar SpritesmithPlugin = require('webpack-spritesmith');\n\nmodule.exports = {\n    // ...\n    module: {\n        rules: [\n            {test: /\\.styl$/, use: [\n                'style-loader',\n                'css-loader',\n                'stylus-loader'\n            ]},\n            {test: /\\.png$/, use: [\n                'file-loader?name=i/[hash].[ext]'\n            ]}\n        ]\n    },\n    resolve: {\n        modules: [\"node_modules\", \"spritesmith-generated\"]\n    },\n    plugins: [\n        new SpritesmithPlugin({\n            src: {\n                cwd: path.resolve(__dirname, 'src/ico'),\n                glob: '*.png'\n            },\n            target: {\n                image: path.resolve(__dirname, 'src/spritesmith-generated/sprite.png'),\n                css: path.resolve(__dirname, 'src/spritesmith-generated/sprite.styl')\n            },\n            apiOptions: {\n                cssImageRef: \"~sprite.png\"\n            }\n        })\n    ]\n    // ...\n};\n\n\n```\n\nAnd then just use it\n\n\n```stylus\n\n//style.styl\n@import '~sprite.styl'\n\n.close-button\n    sprite($close)\n.open-button\n    sprite($open)\n\n```\n\nThere are a few things to notice in config\n\n- file-loader used for generated image\n- `resolve` contains location of where generated image is\n- cssImageRef is specified as '~sprite.png'\n\nSo the way generated image is accessed from the generated API now must be specified manually.\n\n### Config\n\n- `src` - used to build a list of source images\n    - `cwd` should be the closest common directory for all source images;\n    - `glob` well... it is a glob\n    - `options` - optional. These options are passed down to the packages that handle the globbing of images. (We use [gaze](https://github.com/shama/gaze), which passes them down to [globule](https://github.com/cowboy/node-globule), which also passes them down to [node-glob](https://github.com/isaacs/node-glob#options).)\n\n    `cwd` and `glob` both will be passed directly to [glob](https://github.com/isaacs/node-glob) (and [gaze](https://github.com/shama/gaze)\n    in watch mode), then the resulting list of files will be used as a list of source images\n\n- `target` - generated files\n    - `image` - the target image's filename. Can be interpolated with [loader-utils](https://github.com/webpack/loader-utils#interpolatename). I would recommend to use file-loader for interpolation though.\n    - `css` - can be one of the following\n        - `\"full/path/to/spritesheet/api\"` - for example `path.resolve(__dirname, 'src/spritesmith-generated/sprite.styl')`\n        - `[\"full/path/to/spritesheet/api1\", \"full/path/to/spritesheet/api2\"]`,\n        - `[\"full/path/to/spritesheet/api1\", [\"full/path/to/spritesheet/api2\", spritesmithTemplatesOptions]]`\n            spritesmithTemplatesOptions - is the second argument [here](https://github.com/twolfson/spritesheet-templates#templaterdata-options)\n\n            for example\n\n            ```javascript\n                ...\n                css: [\n                    path.resolve(__dirname, 'src/spritesmith-generated/sprite.styl'),\n                    [path.resolve(__dirname, 'src/spritesmith-generated/sprite.json'), {\n                        format: 'json_texture'\n                    }]\n                ]\n            ```\n- `apiOptions` - optional\n    - `generateSpriteName` - a function. Takes a full path to a source image file and expected to return\n    name by which it will be referenced in API. Return value will be used as `sprite.name` for\n    [spritesheet-templates](https://github.com/twolfson/spritesheet-templates). Default behaviour is to\n    use filename (without dirname and extension)\n    - `spritesheet_name`, `retina_spritesheet_name` - passed to [spritesheet-templates](https://github.com/twolfson/spritesheet-templates) (`retina_spritesheet_name` only takes effect if `apiOptions.retina` is also specified)\n    - `cssImageRef` - a path by which a generated image will be referenced in API. If target.image is interpolated, `cssImageRef` should be interpolated the same way too.\n    - `handlebarsHelpers` - an 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        - Note that handlebarsHelpers is global. If you have multiple instances of SpritesmithPlugin, helpers defined later will override helpers defined earlier.\n- `spritesmithOptions` - optional. Options for [spritesmith](https://github.com/Ensighten/spritesmith)\n- `retina` - optional, when specified, uses retina capabilities of [spritesheet-templates](https://github.com/twolfson/spritesheet-templates). Can be either a suffix string (like '@2x') or an object consisting of three fields:\n    - `classifier` - `Function` that allows to say which source is for retina spritesheet and which is not. Will be called with full path to source file, and should return an object of this format -\n        ```javascript\n\n            {\n                type: String, // determines which kind of source is this. May take one of the two values: 'retina' and 'normal'\n                normalName: String, //a full path to the corresponding normal source image\n                retinaName: String, //a full path to the corresponding retina source image\n            }\n        ```\n    - `targetImage` - a full path to the generated retina image\n    - `cssImageRef` - a path by which generated image will be referenced in the API\n\n    When used as a suffix string it applies to source files, a filename for retina spritesheet image and cssImageRef\n\n    `apiOptions.generateSpriteName` will be applied to `normalName` returned by `retina.classifier`\n- `customTemplates` - optional. An object with keys and values corresponding to format names and template descriptions respectively.\n    Template description can be either a `path/to/handlebars/template/file` or a template function\n\n    You can use templates registered here as `format` in \"target.css\"\n\n    For example you can write something like this\n\n    ```javascript\n\n    //webpack.config.js\n    var templateFunction = function (data) {\n        var shared = '.ico { background-image: url(I) }'\n            .replace('I', data.sprites[0].image);\n\n        var perSprite = data.sprites.map(function (sprite) {\n            return '.ico-N { width: Wpx; height: Hpx; background-position: Xpx Ypx; }'\n                .replace('N', sprite.name)\n                .replace('W', sprite.width)\n                .replace('H', sprite.height)\n                .replace('X', sprite.offset_x)\n                .replace('Y', sprite.offset_y);\n        }).join('\\n');\n\n        return shared + '\\n' + perSprite;\n    };\n\n    module.exports = {\n        ...\n        plugins: [\n            new SpritesmithPlugin({\n                target: {\n                    ...\n                    css: [\n                        [path.resolve(__dirname, 'src/spritesmith-generated/sprite-1.css'), {\n                            format: 'function_based_template'\n                        }],\n                        [path.resolve(__dirname, 'src/spritesmith-generated/sprite-2.css'), {\n                            format: 'handlebars_based_template'\n                        }]\n                    ]\n                },\n                customTemplates: {\n                    'function_based_template': templateFunction,\n                    'handlebars_based_template': path.resolve(__dirname, '../my_handlebars_template.handlebars')\n                },\n                ...\n            })\n        ]\n    }\n\n    ```\n\n- `logCreatedFiles` optional. When set to `true` will `console.log` a list of created files.\n\n\n\n__This scary readme file is a cry for help. If someone can improve it please do. Also the config itself is terrible, it could also use some improvement. I welcome any reasonable suggestions. Thank you.__ \n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmixtur%2Fwebpack-spritesmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmixtur%2Fwebpack-spritesmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmixtur%2Fwebpack-spritesmith/lists"}