https://github.com/calvin-ll/webpack-image-resize-loader
Webpack loader to resize imported images
https://github.com/calvin-ll/webpack-image-resize-loader
image loader resize responsive sharp webpack
Last synced: 7 months ago
JSON representation
Webpack loader to resize imported images
- Host: GitHub
- URL: https://github.com/calvin-ll/webpack-image-resize-loader
- Owner: Calvin-LL
- License: mit
- Created: 2020-06-15T01:11:58.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2023-03-06T13:58:23.000Z (almost 3 years ago)
- Last Synced: 2025-05-26T08:43:22.648Z (8 months ago)
- Topics: image, loader, resize, responsive, sharp, webpack
- Language: TypeScript
- Homepage:
- Size: 351 MB
- Stars: 39
- Watchers: 2
- Forks: 4
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# webpack-image-resize-loader
[](https://www.npmjs.com/package/webpack-image-resize-loader) [](https://opensource.org/licenses/MIT)
This loader resize the given images to the desired size.
Supports JPEG, PNG, WebP, AVIF, and, TIFF images.
## Examples
[React](https://github.com/Calvin-LL/webpack-image-resize-loader/tree/main/examples/react)
[Vue](https://github.com/Calvin-LL/webpack-image-resize-loader/tree/main/examples/vue)
[React example with other related loaders](https://github.com/Calvin-LL/react-responsive-images-example)
[Vue example with other related loaders](https://github.com/Calvin-LL/vue-responsive-images-example)
## Install
Install with npm:
```bash
npm install --save-dev webpack-image-resize-loader
```
Install with yarn:
```bash
yarn add --dev webpack-image-resize-loader
```
## Usage
Note: if you only want to shrink some but not all images use webpack's `oneOf` (like in the [examples](#examples)). If you want to use `srcset`, check out [webpack-image-srcset-loader](https://github.com/Calvin-LL/webpack-image-srcset-loader)
You must place `file-loader` or `url-loader` or some other loader capable of handing buffers before `webpack-image-resize-loader`
Use [`webpack-sharp-loader`](https://github.com/Calvin-LL/webpack-sharp-loader) if you want to do other processing to your image before resizing
#### webpack.config.js
```javascript
module.exports = {
// ...
module: {
rules: [
// ...
{
// convert all imported images to have max width 1000px
test: /\.(png|jpe?g|webp|tiff?)$/i,
use: [
"file-loader",
{
loader: "webpack-image-resize-loader",
options: {
width: 1000,
},
},
],
},
],
},
};
```
#### You can override options with queries
```javascript
import image from "./some_pic.png?format=webp";
```
or
```javascript
// or any other options
import image from "./some_pic.png?width=100&height=100&quality=100&background=green&fit=contain&position=left";
```
or
```javascript
// or any other options
import image from './some_pic.png?{"width":500}';
```
## Options
| Name | Type | Default | Description |
| --------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **[`width`](#width)** | `number` | `undefined` | The width of the output image. |
| **[`height`](#height)** | `number` | `undefined` | The height of the output image. |
| **[`scale`](#scale)** | `number` | `undefined` | The fraction of the original size of the output image. `width` and `height` take precedence. |
| **[`scaleUp`](#scaleup)** | `boolean` | `false` | Whether or not to scale up the image when the desired size is larger than the image size. |
| **[`fit`](#fit)** | `"cover"`, `"contain"`, `"fill"`, `"inside"`, or `"outside"` | `"cover"` | How the image should be resized to fit both provided dimensions. |
| **[`position`](#position)** | See **[`position`](#position)** | `"centre"` | Where the image is positioned. |
| **[`background`](#background)** | `string\|object` | `{r:0,g:0,b:0,alpha:1}` | The background color of the image. |
| **[`format`](#format)** | `"jpeg"`, `"png"`, `"webp"`, `"avif"`, or `"tiff"` | `undefined` | The format of the output file. |
| **[`quality`](#quality)** | `number` | `80` for JPEG, WebP, and TIFF. `100` for PNG. | The quality of the output image. |
| **[`sharpOptions`](#sharpoptions)** | `object` | [see below](#sharpoptions) | Additional options for [sharp](https://sharp.pixelplumbing.com). |
| **[`fileLoader`](#fileloader)** | `string` | `"file-loader"` | Name or path of a loader that takes in buffers. ([why?](#fileloader)) |
| **[`fileLoaderOptionsGenerator`](#fileloaderoptionsgenerator)** | `function` | [see below](#fileloaderoptionsgenerator) | A function that generates options for the specified `fileLoader`. |
### `width`
Pixels width the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.
This is passed as `width` to the [`options` of the parameters of sharp's `resize` function](https://sharp.pixelplumbing.com/api-resize#parameters)
### `height`
Pixels height the resultant image should be. Use null or undefined to auto-scale the height to match the width.
This is passed as `height` in the [`options` of the parameters of sharp's `resize` function](https://sharp.pixelplumbing.com/api-resize#parameters)
### `scale`
A number greater than `0`, `1` being the original size, `0.5` being half the size of the original image, `2` being twice the size of the original image.
If both this and `width` or `height` are set, `width` or `height` takes precedence.
### `scaleUp`
When true, images will be scaled up to a larger size. When false, if the desired size, either the `height` is greater than the height of the original image, the `width` is greater than the width of the original image, or `scale` is greater than 1, the size of the output image will be the same as the imported image.
### `fit`
This is passed as `fit` in the [`options` of the parameters of sharp's `resize` function](https://sharp.pixelplumbing.com/api-resize#parameters)
### `position`
type: `"top"`, `"right top"`, `"right"`, `"right bottom"`, `"bottom"`, `"left bottom"`, `"left"`, `"left top"`, `"north"`, `"northeast"`, `"east"`, `"southeast"`, `"south"`, `"southwest"`, `"west"`, `"northwest"`, `"center"`, `"centre"`, `"entropy"`, or `"attention"`
position, gravity or strategy to use when `fit` is `cover` or `contain`.
- `sharp.position`: `top`, `right top`, `right`, `right bottom`, `bottom`, `left bottom`, `left`, `left top`.
- `sharp.gravity`: `north`, `northeast`, `east`, `southeast`, `south`, `southwest`, `west`, `northwest`, `center` or `centre`.
- `sharp.strategy`: `cover` only, dynamically crop using either the `entropy` or `attention` strategy.
This is passed as `position` in the [`options` of the parameters of sharp's `resize` function](https://sharp.pixelplumbing.com/api-resize#parameters)
### `background`
example: `"#7743CE"`, `"rgb(255, 255, 255)"`, `{r:0,g:0,b:0,alpha:1}`
background colour when using a `fit` of `contain`, parsed by the [color](https://www.npmjs.com/package/color) module, defaults to black without transparency.
This is passed as `background` in the [`options` of the parameters of sharp's `resize` function](https://sharp.pixelplumbing.com/api-resize#parameters)
### `format`
When unspecified, outputs the same format as the imported file.
### `quality`
##### default
Defaults to [shape's default is for that given format](https://sharp.pixelplumbing.com/api-output)
| output format | default quality |
| ------------- | --------------- |
| png | 100 |
| jpeg | 80 |
| webp | 80 |
| avif | 50 |
| tiff | 80 |
From 1-100, 1 being most compression and worst quality, 100 being least compression and best quality.
This is passed as `quality` in the [`options` of the parameters of sharp's `png`, `jpeg`, `webp`, `avif`, and `tiff` output functions](https://sharp.pixelplumbing.com/api-output)
### `sharpOptions`
##### default
The default options aim to provide the smallest images even if it takes more time to generate the image.
```javascript
{
png: { compressionLevel: 9, adaptiveFiltering: true },
jpeg: { mozjpeg: true },
webp: { reductionEffort: 6 },
avif: { speed: 0 }
}
```
`sharpOptions` can have any of the following keys: `resize`, `png`, `jpeg`, `webp`, `avif`, and `tiff`. These options will override options specified above.
as in
```javascript
{
resize: {}, // these are passed as the options object in https://sharp.pixelplumbing.com/api-resize#parameters
png: {}, // these are passed as the options object in https://sharp.pixelplumbing.com/api-output#png
jpeg: {}, // these are passed as the options object in https://sharp.pixelplumbing.com/api-output#jpeg
webp: {}, // these are passed as the options object in https://sharp.pixelplumbing.com/api-output#webp
avif: {}, // these are passed as the options object in https://sharp.pixelplumbing.com/api-output#avif
tiff: {}, // these are passed as the options object in https://sharp.pixelplumbing.com/api-output#tiff
}
```
Setting an item in this object overrides all the defaults for that item.
For example:
```javascript
// ...
sharpOptions: {
png: { quality: 80 }
}
// ...
```
`sharpOptions` will become this after being merged with defaults:
```javascript
{
png: { quality: 80 }
jpeg: { mozjpeg: true },
webp: { reductionEffort: 6 },
avif: { speed: 0 }
}
```
### `fileLoader`
Name or path of a loader that takes in buffers.
This is needed because the output file format is sometimes different from the input file format.
By default this loader tries to find `file-loader` and change the `"[ext]"` in their `options.name`.
### `fileLoaderOptions`
##### default
`options` is the options passed to this loader, `existingOptions` is the options passed to the loader specified in [`fileLoader`](#fileloader)
```javascript
function defaultFileLoaderOptionsGenerator(options, existingOptions) {
let name = existingOptions?.name;
if (name === undefined) {
name = `[contenthash].${options.format}`;
} else if (typeof name === "string") {
name = name.replace("[ext]", options.format);
} else if (typeof name === "function") {
name = (file: string) => {
const nameFn = existingOptions.name;
return nameFn(file).replace("[ext]", format);
};
}
return {
...existingOptions,
name,
};
}
```
This function is used to generate the options for the loader specified by [`fileLoader`](#fileloader)