{"id":14976513,"url":"https://github.com/drwpow/lightspeed-image-loader","last_synced_at":"2025-10-27T20:32:15.814Z","repository":{"id":57290194,"uuid":"122027472","full_name":"drwpow/lightspeed-image-loader","owner":"drwpow","description":"Responsive images \u0026 optimization made easy","archived":false,"fork":false,"pushed_at":"2018-09-19T00:36:14.000Z","size":18324,"stargazers_count":14,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T08:06:46.121Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drwpow.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2018-02-19T06:42:42.000Z","updated_at":"2021-09-23T02:17:22.000Z","dependencies_parsed_at":"2022-08-25T05:20:55.318Z","dependency_job_id":null,"html_url":"https://github.com/drwpow/lightspeed-image-loader","commit_stats":null,"previous_names":["dangodev/lightspeed-image-loader"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drwpow%2Flightspeed-image-loader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drwpow%2Flightspeed-image-loader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drwpow%2Flightspeed-image-loader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drwpow%2Flightspeed-image-loader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drwpow","download_url":"https://codeload.github.com/drwpow/lightspeed-image-loader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238553303,"owners_count":19491405,"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-09-24T13:54:00.490Z","updated_at":"2025-10-27T20:32:09.581Z","avatar_url":"https://github.com/drwpow.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![lightspeed-image-loader latest version][version]\n![Dependencies status][status]\n![devDependencies status][status-dev]\n\n# Lightspeed Image Loader\n\n![Lightspeed Image Loader](./images/lightspeed.jpg)\n\nOn-the-fly responsive image resizing and minification for webpack v4. Uses\n[mozjpeg][mozjpeg], [Gifsicle][gifsicle], [OptiPNG][optipng], and\n[SVGO][svgo], supports [WebP][webp], and can even generate Medium.com-style\nlow-quality image placeholders (LQIP) for loading.\n\n### Support\n\n| Filetype | Resizing | Optimization | Converting to |\n| :------- | :------: | :----------: | :-----------: |\n| JPG      | ✅        | ✅            | ✅             |\n| PNG      | ✅        | ⚠️ **SLOW**  | ⚠️ **SLOW**   |\n| WebP     | ✅        | ✅            | ✅             |\n| SVG      | N/A      | ✅            | N/A           |\n| GIF      | 🚫       | ✅            | 🚫            |\n\n_Note: GIF resizing/conversion isn’t supported due to lack of support in\n[sharp][sharp]. Overall, it’s a small price to pay for the build speed of the\nsharp library._\n\n## Installation\n\n```\nnpm i --save-dev lightspeed-image-loader\n```\n\n## Usage\n\n### Simple usage\n\nIn your **[production webpack config][webpack-prod],** add the following:\n\n```js\nmodule: {\n  rules: [\n    {\n      test: /\\.(jpe?g|gif|png|svg)/i,\n      use: 'lightspeed-image-loader'\n    }\n  ],\n},\n```\n\nThen from your app, import image files normally. Specify specific\noptimizations per each file:\n\n```js\nimport imgSmall from './img/background-full.jpg?w=600\u0026q=75'; /* 600px wide, 75% quality */\nimport imgLarge from './img/background-full.jpg?w=1200\u0026q=50'; /* 1200px wide, 50% quality */\n```\n\n#### React\n\n```jsx\n\u003cimg src={imgSmall} srcset={`${imgSmall} 600w, ${imgLarge} 1200w`} /\u003e\n```\n\n#### Vue\n\n```vue\n\u003cimg :src=\"imgSmall\" :srcset=\"`${imgSmall} 600w, ${imgLarge} 1200w`\"\u003e\n```\n\n#### Styled Components\n\n```js\nconst Header = styled.header`\n  background-image: ${imgSmall};\n\n  @media (min-width: 600px) {\n    background-image: ${imgLarge};\n  }\n`;\n```\n\n### Examples\n\n#### Responsive (React)\n\n```js\nimport small from './myimage.jpg?w=600\u0026q=80';\nimport medium from './myimage.jpg?w=1200\u0026q=75';\nimport large from './myimage.jpg?w=1800\u0026q=65';\n\n..\n\n\u003cimg\n  srcset={`${medium} 1200w, ${large} 1800w`}\n  src={small}\n  alt=\"image description\"\n/\u003e\n```\n\n#### WebP (React)\n\n```js\nimport webP from './myimage.jpg?f=webp';\nimport fallback from './myimage.jpg';\n\n...\n\n\u003cpicture\u003e\n  \u003csource srcset={webP} type=\"image/webp\" /\u003e\n  \u003csource srcset={fallback} type=\"image/jpeg\" /\u003e\n  \u003cimg src={fallback} alt=\"image description\" /\u003e\n\u003c/picture\u003e\n```\n\n#### Base64 inlined image (Styled Components)\n\n```js\nimport inlineBg from './myimage.jpg?inline';\n\n...\n\nconst Wrapper = styled.div`\n  background-image: url(${inlineBg});\n`;\n```\n\n#### Inline SVG (React)\n\n```js\nimport inlineSVG from './myimage.svg?inline';\n\n...\n\n\u003cdiv dangerouslySetInnerHtml={{ __html: inlineSVG }} /\u003e\n```\n\n#### Resizing pixel art\n\n```js\nimport pixelArt from './pixel-art?w=2048\u0026interpolation=nearest';\n```\n\n#### Low Quality Image Placeholder (LQIP) (React)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/placeholder.jpg\" alt=\"The low quality image placeholder shows a blurry version of the image before the full-resolution original downloads.\" /\u003e\n\u003c/p\u003e\n\n```js\nimport image from './myimage.jpg?w=1200';\nimport placeholder from './myimage.jpg?placeholder';\n\n\u003cimg src={image} style={{ backgroundImage: `url(\"${placeholder}\")` }}/\u003e;\n```\n\n_Note: double quotes inside `url(\"\")` are important! [Why?](#lqip-placeholder-images-are-blank)_\n\nLow quality image placeholders (LQIP) improve user experience by letting\nusers look at something while an image loads ([more info in this\narticle][lqip-article]).\n\nThis loader generates SVG LQIP to avoid that white fuzzy border caused by\nCSS’ blur filter on normal images.\n\nPlaceholders can’t be generated for SVGs.\n\n## Options\n\nSpecifying options per-image is the preferred method of this loader. By\nsetting options per-file, you can fine-tune each image to find the best\nbalance of quality and compression. Plus, you don’t have to touch your\nwebpack config as your images change.\n\n### Query Options\n\n| Name            | Default    | Description                                                                                                                                                                                                                                                                                                                                   |\n| :-------------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `width`         | (original) | Set image width (in pixels). Leave `height` blank to auto-scale. Specify `width` and `height` to ensure image is smaller than both.                                                                                                                                                                                                           |\n| `w`             |            | Shortcut for `width`.                                                                                                                                                                                                                                                                                                                         |\n| `height`        | (original) | Scale image height (in pixels). Leave `width` blank to auto-scale. Specify `width` and `height` to ensure image is smaller than both.                                                                                                                                                                                                         |\n| `h`             |            | Shortcut for `height`.                                                                                                                                                                                                                                                                                                                        |\n| `quality`       | `70`       | Specify `1`–`100` to set the image’s quality\u003csup\u003e\\*\u003c/sup\u003e. For each image, set it as low as possible before compression is noticeable at display size.                                                                                                                                                                                       |\n| `q`             |            | Shortcut for `quality`.                                                                                                                                                                                                                                                                                                                       |\n| `interpolation` | `'cubic'`  | When scaling, specify `'nearest'` for nearest-neighbor (pixel art), `'cubic'` for cubic interpolation, or `'lanczos2'` or `'lanczos3'` for [Lanczos][lanczos] with `a=2` or `a=3`. `'cubic'` is this loader’s default (because it’s what most are used to), as opposed to`'lanczos3'` which is sharp’s default (present for other loaders) |\n| `inline`        | `false`    | Set to `?inline` or `?inline=true` to return the individual image in base64 data URI, or raw SVG code 🎉.                                                                                                                                                                                                                                     |\n| `format`        | (same)     | Specify `jpg`, `webp`, or `png` to convert format from the original.                                                                                                                                                                                                                                                                          |\n| `f`             |            | Shortcut for `format`.                                                                                                                                                                                                                                                                                                                        |\n| `placeholder`   | `false`    | Specify `?placeholder` to return a low-quality image placeholder (technically this can be used alongside other options, but it’s not advised).                                                                                                                                                                                               |\n| `skip`          | `false`    | Set to `?skip` to bypass resizing \u0026 optimization entirely. This is particularly useful for SVGs that don’t optimize well.                                                                                                                                                                                                                    |\n\n_\u003csup\u003e\\*\u003c/sup\u003e Note: GIFsicle and OptiPNG don’t use a 1–100 quality scale, so\n`quality` will convert for you. However, if using loader options below, you’ll\nneed to specify the proper options there._\n\n#### Example\n\n```js\nimport myImage from './large.jpg?q=50\u0026w=1200\u0026f=webp'; // Convert to WebP, 50% quality, and 1200px wide\n```\n\n_Note: this loader **will not** upscale images because it increases file size\nwithout improving image quality. If you need to upscale pixel art, do it in\nCSS with `image-rendering: crisp-edges`._\n\n### Loader options\n\nThe main advantage of this loader is being able to specify quality and width\ninline, but there are some settings which make sense to set globally, such as\n[SVGO][svgo] settings, or a fallback quality. In these cases, pass options to\nthe loader as usual:\n\n| Name         | Default             | Description                                                                                         |\n| :----------- | :------------------ | :-------------------------------------------------------------------------------------------------- |\n| `outputPath` | `output.path`       | Override webpack’s default output path for these images (setting from [file-loader][file-loader]). |\n| `publicPath` | `output.publicPath` | Override webpack’s default output path for these images (setting from [file-loader][file-loader]). |\n| `emitFile`   | `true`              | Set to `false` to skip processing file (setting from [file-loader][file-loader]).                   |\n| `gifsicle`   | (object)            | Specify Gifsicle options ([view options][gifsicle-options]).                                        |\n| `mozjpeg`    | (object)            | Specify mozjpeg options ([view options][mozjpeg-options]).                                          |\n| `optipng`    | (object)            | Specify OptiPNG options ([view options][optipng-options]).                                          |\n| `pngquant`   | (object)            | Specify PNGquant options ([view options][pngquant-options]).                                        |\n| `svgo`       | (object)            | Specify [SVGO][svgo] options.                                                                       |\n\n_Note: because this loader passes images on to [file-loader][file-loader],\nyou should be able to use any of its options within this config. However,\n**don’t use this loader for anything other than images!**_\n\n#### Example\n\n```js\nmodule: {\n  rules: [\n    {\n      test: /(jpe?g|gif|png|svg)$/i,\n      use: {\n        loader: 'lightspeed-image-loader',\n        options: {\n          mozjpeg: {\n            quality: 60, // 1 – 100, higher is heavier\n          },\n          optipng: {\n            optimizationLevel: 5, // 0 = light; 7 = heavy compression\n          },\n          svgo: {\n            addClassesToSVGElement: true,\n            mergePaths: true,\n            removeStyleElement: true,\n          },\n          webp: {\n            quality: 80,\n          },\n        },\n      },\n    },\n  ],\n},\n```\n\n## WebP\n\nBecause WebP currently is only supported by Chrome, you’ll still need to\nconfigure fallbacks. For that reason, you can only convert per-file:\n\n```js\nimport webP from './original.jpg?f=webp';\nimport fallback from './original.jpg';\n```\n\nFor tips on using WebP effectively, read this [CSS Tricks article][csstricks].\n\n## Troubleshooting\n\n### Python Version\n\nIf `python --version` returns ^3 on your system, you’ll likely encounter the\n[frequently-discussed node-gyp][node-gyp] error:\n\n```\nError: Python executable \\\"/usr/local/bin/python\\\" is v3.x.x, which is not supported by gyp.\n```\n\nIf `which python2.7` works on your system, run\n`npm config set python python2.7` (or `yarn config set python python2.7` if\nusing yarn).\n\nIf your machine doesn’t have `python2.7`, install Python 2.x using\n[Homebrew][homebrew] or some other means, and set that executable with\n`npm config set python /path/to/python2` or\n`yarn config set python /path/to/python2`\n\n### LQIP (placeholder images) are blank\n\nThe placeholder SVGs are compressed further by\n[mini-svg-data-uri][mini-svg-data-uri], which requires **double quotes** for\n`\u003cimg src=\"[placeholder]\" /\u003e` and `background-image: url(\"[placeholder]\")`.\nCheck to make sure your code is outputting double quotes in HTML/CSS.\n\nThe tradeoff for having to always use double quotes is much smaller bundles,\nand better GZIP performance without sacrificing browser support.\n[@tigt][@tigt] wrote a [great blog post on the subject][svg-base64-article]\n\n## FAQ\n\n### Why do I have to use one `import` per size?\n\nThere are several advantages to this method:\n\n* **Control**: You can declare options per-size, and fix issues where a particular image size requires different settings.\n* **Speed**: Specifying options per-file keeps the loader fast by only applying operations you specify (e.g., a placeholder image isn’t needlessly generated if you don’t specify one—this can severely slow down build times with many images)\n* **Simplicity**: There’s no syntax to memorize; one reference = one image URL or data-URI\n\n### Why doesn’t this loader chain nicely with others?\n\nTwo reasons: first, image optimization / resizing has a particular order that\nneeds to be kept: resizing first, then optimization. Always. If there’s only\none proper order for images, and if one loader does it all, why chain?\n\nSecond, and more importantly, webpack doesn’t make it easy to serve a single\nfile extension in multiple ways. This makes it difficult to reformat one\nimage type into another as well as apply different compression rules\nper-file. In order to accomplish this, this loader breaks chaining in order\nto do what makes the most sense for image workflows (and if something is\nmissing, please [file an issue][issues]!).\n\n## Special Thanks\n\nThis loader wouldn’t be possible without the significant achievements of:\n\n* [@dcommander][@dcommander] for [mozjpeg][mozjpeg]\n* [@kornelski][@kornelski] for [pngquant][pngquant]\n* [@kevva][@kevva] for [imagemin][imagemin]\n* [@sokra][@sokra], [@d3viant0ne][@d3viant0ne], and [@michael-ciniawsky][@michael-ciniawsky] for [file-loader][file-loader]\n* [@lovell][@lovell] for [sharp][sharp]\n* [@tigt][@tigt] for [mini-svg-data-uri][mini-svg-data-uri]\n\n[@dcommander]: https://github.com/dcommander\n[@d3viant0ne]: https://github.com/d3viant0ne\n[@kevva]: https://github.com/kevva\n[@kornelski]: https://github.com/kornelski\n[@lovell]: https://github.com/lovell\n[@michael-ciniawsky]: https://github.com/michael-ciniawsky\n[@sokra]: https://github.com/sokra\n[@tigt]: https://github.com/tigt\n[csstricks]: https://css-tricks.com/using-webp-images/\n[mini-svg-data-uri]: https://github.com/tigt/mini-svg-data-uri\n[file-loader]: https://github.com/webpack-contrib/file-loader\n[gifsicle]: https://github.com/imagemin/imagemin-gifsicle\n[gifsicle-options]: https://github.com/dangodev/lightspeed-image-loader/wiki/Gifsicle-Settings\n[homebrew]: https://brew.sh/\n[imagemin]: https://github.com/imagemin/imagemin\n[issues]: https://github.com/dangodev/lightspeed-image-loader/issues\n[lanczos]: https://en.wikipedia.org/wiki/Lanczos_resampling\n[lqip-article]: https://jmperezperez.com/medium-image-progressive-loading-placeholder/\n[mozjpeg]: https://github.com/imagemin/imagemin-mozjpeg\n[mozjpeg-options]: https://github.com/dangodev/lightspeed-image-loader/wiki/mozjpeg-Settings\n[node-gyp]: https://github.com/nodejs/node-gyp/issues/1337\n[optipng]: https://github.com/imagemin/imagemin-optipng\n[optipng-options]: https://github.com/dangodev/lightspeed-image-loader/wiki/OptiPNG-Settings\n[pngquant]: https://github.com/imagemin/imagemin-pngquant\n[pngquant-options]: https://github.com/dangodev/lightspeed-image-loader/wiki/PNGQuant-Settings\n[sharp]: https://github.com/lovell/sharp\n[status-dev]: https://david-dm.org/dangodev/lightspeed-image-loader/dev-status.svg\n[status]: https://david-dm.org/dangodev/lightspeed-image-loader/status.svg\n[svg-base64-article]: https://codepen.io/tigt/post/optimizing-svgs-in-data-uris\n[svgo]: https://github.com/svg/svgo\n[version]: https://badge.fury.io/js/lightspeed-image-loader.svg\n[webp]: https://github.com/imagemin/imagemin-webp\n[webpack-prod]: https://webpack.js.org/guides/production/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrwpow%2Flightspeed-image-loader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrwpow%2Flightspeed-image-loader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrwpow%2Flightspeed-image-loader/lists"}