351 lines
11 KiB
Markdown
351 lines
11 KiB
Markdown
# gatsby-plugin-sharp
|
||
|
||
Exposes several image processing functions built on the
|
||
[Sharp image processing library](https://github.com/lovell/sharp). This is a
|
||
low-level helper plugin generally used by other Gatsby plugins. You generally
|
||
shouldn't be using this directly but might find it helpful if doing very custom
|
||
image processing.
|
||
|
||
It aims to provide excellent out-of-the box settings for processing common web
|
||
image formats.
|
||
|
||
For JPEGs it generates progressive images with a default quality level of 50.
|
||
|
||
For PNGs it uses [pngquant](https://github.com/pornel/pngquant) to compress
|
||
images. By default it uses a quality setting of [50-75]. The `pngCompressionSpeed`
|
||
value is a speed/quality trade-off from 1 (brute-force) to 10 (fastest). Speed
|
||
10 has 5% lower quality, but is 8 times faster than the default (4). In most
|
||
cases you should stick with the default, but if you have very large numbers
|
||
of PNGs then it can significantly reduce build times.
|
||
|
||
## Install
|
||
|
||
`npm install --save gatsby-plugin-sharp`
|
||
|
||
## How to use
|
||
|
||
```javascript
|
||
// In your gatsby-config.js
|
||
plugins: [
|
||
{
|
||
resolve: `gatsby-plugin-sharp`,
|
||
options: {
|
||
useMozJpeg: false,
|
||
stripMetadata: true,
|
||
defaultQuality: 75,
|
||
},
|
||
},
|
||
]
|
||
```
|
||
|
||
## Methods
|
||
|
||
### resize
|
||
|
||
#### Parameters
|
||
|
||
- `width` (int, default: 400)
|
||
- `height` (int)
|
||
- `quality` (int, default: 50)
|
||
- `jpegProgressive` (bool, default: true)
|
||
- `pngCompressionLevel` (int, default: 9)
|
||
- `base64`(bool, default: false)
|
||
|
||
#### Returns
|
||
|
||
- `src` (string)
|
||
- `width` (int)
|
||
- `height` (int)
|
||
- `aspectRatio` (float)
|
||
|
||
### fixed
|
||
|
||
Automatically create sizes for different resolutions — we do 1x, 1.5x, and 2x.
|
||
|
||
#### Parameters
|
||
|
||
- `width` (int, default: 400)
|
||
- `height` (int)
|
||
- `quality` (int, default: 50)
|
||
|
||
#### Returns
|
||
|
||
- `base64` (string)
|
||
- `aspectRatio` (float)
|
||
- `width` (float)
|
||
- `height` (float)
|
||
- `src` (string)
|
||
- `srcSet` (string)
|
||
|
||
### fluid
|
||
|
||
Create fluid sizes (in width) for the image. If the max width of the container for the
|
||
rendered markdown file is 800px, the sizes would then be: 200px, 400px, 800px, 1200px,
|
||
1600px – enough to provide close to the optimal image size for every device
|
||
size / screen resolution.
|
||
|
||
If you want more control over which sizes are output you can use the `srcSetBreakpoints`
|
||
parameter. For example, if you want images that are 200, 340, 520, and 890 wide you
|
||
can add `srcSetBreakpoints: [ 200, 340, 520, 890 ]` as a parameter. You will also get
|
||
`maxWidth` as a breakpoint (which is 800 by default), so you will actually get
|
||
`[ 200, 340, 520, 800, 890 ]` as breakpoints.
|
||
|
||
On top of that, `fluid` returns everything else (namely aspectRatio and
|
||
a base64 image to use as a placeholder) you need to implement the "blur up"
|
||
technique popularized by Medium and Facebook (and also available as a Gatsby
|
||
plugin for Markdown content as gatsby-remark-images).
|
||
|
||
When both a `maxWidth` and `maxHeight` are provided, sharp will use `COVER` as a fit strategy by default. This might not be ideal so you can now choose between `COVER`, `CONTAIN` and `FILL` as a fit strategy. To see them in action the [CSS property object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) comes close to its implementation.
|
||
|
||
#### Note
|
||
|
||
fit strategies `CONTAIN` and `FILL` will not work when `cropFocus` is assigned to [sharp.strategy][6]. The `cropFocus` option cannot be `ENTROPY` or `ATTENTION`
|
||
|
||
#### Parameters
|
||
|
||
- `maxWidth` (int, default: 800)
|
||
- `maxHeight` (int)
|
||
- `quality` (int, default: 50)
|
||
- `srcSetBreakpoints` (array of int, default: [])
|
||
- `fit` (string, default: '[sharp.fit.cover][6]')
|
||
- `background` (string, default: 'rgba(0,0,0,1)')
|
||
- [deprecated] `sizeByPixelDensity` (bool, default: false)
|
||
- Pixel density is only used in vector images, which Gatsby’s implementation of Sharp doesn’t support. This option is currently a no-op and will be removed in the next major version of Gatsby.
|
||
|
||
#### Returns
|
||
|
||
- `base64` (string)
|
||
- `aspectRatio` (float)
|
||
- `src` (string)
|
||
- `srcSet` (string)
|
||
- `srcSetType` (string)
|
||
- `sizes` (string)
|
||
- `originalImg` (string)
|
||
|
||
### Shared Options
|
||
|
||
In addition to their individual parameters, all methods above share the
|
||
following:
|
||
|
||
- `grayscale` (bool, default: false)
|
||
- `duotone` (bool|obj, default: false)
|
||
- `toFormat` (string, default: '')
|
||
- `cropFocus` (string, default: '[sharp.strategy.attention][6]')
|
||
- `pngCompressionSpeed` (int, default: 4)
|
||
|
||
#### toFormat
|
||
|
||
Convert the source image to one of the following available options: `NO_CHANGE`,
|
||
`JPG`, `PNG`, `WEBP`.
|
||
|
||
#### cropFocus
|
||
|
||
Change the cropping focus. Available options: `CENTER`, `NORTH`, `NORTHEAST`,
|
||
`EAST`, `SOUTHEAST`, `SOUTH`, `SOUTHWEST`, `WEST`, `NORTHWEST`, `ENTROPY`,
|
||
`ATTENTION`. See Sharp's [crop][6].
|
||
|
||
#### rotate
|
||
|
||
Rotate the image (after cropping). See Sharp's [rotate][7].
|
||
|
||
#### grayscale
|
||
|
||
Uses Sharp's [greyscale][8] to convert the source image to 8-bit greyscale, 256
|
||
shades of grey, e.g.
|
||
|
||
```javascript
|
||
allImageSharp {
|
||
edges {
|
||
node {
|
||
... on ImageSharp {
|
||
resize(width: 150, height: 150, grayscale: true) {
|
||
src
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### duotone
|
||
|
||
Applys a "duotone" effect (see [I][1], [II][2], [III][3]) to the source image if
|
||
given two hex colors `shadow` and `highlight` defining start and end color of
|
||
the duotone gradient, e.g.
|
||
|
||
```javascript
|
||
fixed(
|
||
width: 800,
|
||
duotone: {
|
||
highlight: "#f00e2e",
|
||
shadow: "#192550"
|
||
}
|
||
) {
|
||
src
|
||
srcSet
|
||
base64
|
||
}
|
||
```
|
||
|
||
the source image colors will be converted to match a gradient color chosen based
|
||
on each pixel's [relative luminance][4].\
|
||
Logic is borrowed from [react-duotone][5].
|
||
|
||
You can pass a third optional parameter, `opacity`:
|
||
|
||
```javascript
|
||
fluid(
|
||
width: 800,
|
||
duotone: {
|
||
highlight: "#f00e2e",
|
||
shadow: "#192550",
|
||
opacity: 50
|
||
}
|
||
) {
|
||
src
|
||
srcSet
|
||
base64
|
||
}
|
||
```
|
||
|
||
If set, a semi-transparent version of duotone'd image will be composited over
|
||
the original image, allowing the original image and its colors to partially
|
||
"shine through". _Heads up_: If the original image contains an alpha channel it
|
||
will be [flattened][15] before creating the composite.
|
||
|
||
This works by adding an alpha channel to the duotone'd image - then we let Sharp
|
||
do its magic via
|
||
[`overlayWith`](http://sharp.pixelplumbing.com/en/stable/api-composite/#overlaywith);
|
||
quoting the Sharp documentation:
|
||
|
||
> If the overlay image contains an alpha channel then composition with
|
||
> <a href="https://en.wikipedia.org/wiki/Alpha_compositing">premultiplication</a>
|
||
> will occur.
|
||
|
||
#### tracedSVG
|
||
|
||
Generates a traced SVG of the image (see [the original GitHub issue][9]) and
|
||
returns the SVG as "[optimized URL-encoded][10]" `data:` URI. It it used in
|
||
[gatsby-image](/packages/gatsby-image/) to provide an
|
||
alternative to the default inline base64 placeholder image.
|
||
|
||
Uses [node-potrace][11] and [SVGO][12] under the hood. Default settings for
|
||
node-potrace:
|
||
|
||
```javascript
|
||
{
|
||
color: `lightgray`,
|
||
optTolerance: 0.4,
|
||
turdSize: 100,
|
||
turnPolicy: TURNPOLICY_MAJORITY,
|
||
}
|
||
```
|
||
|
||
All [node-potrace `Potrace` parameters][13] are exposed and can be set via the
|
||
`traceSVG` argument:
|
||
|
||
```javascript
|
||
fixed(
|
||
traceSVG: {
|
||
color: "#f00e2e"
|
||
turnPolicy: TURNPOLICY_MINORITY
|
||
blackOnWhite: false
|
||
}
|
||
) {
|
||
src
|
||
srcSet
|
||
tracedSVG
|
||
}
|
||
```
|
||
|
||
### Setting a default quality
|
||
|
||
You can pass a default image quality to `sharp` by setting the `defaultQuality` option.
|
||
|
||
### Using MozJPEG
|
||
|
||
You can opt-in to use [MozJPEG][16] for jpeg-encoding. MozJPEG provides even
|
||
better image compression than the default encoder used in `gatsby-plugin-sharp`.
|
||
However, when using MozJPEG the build time of your Gatsby project will increase
|
||
significantly.
|
||
|
||
To enable MozJPEG, you can set the `useMozJpeg` plugin option to `true` in
|
||
`gatsby-config.js`.
|
||
|
||
For backwards compatible reasons, if `useMozJpeg` is not defined in the plugin
|
||
options, the [environment variable](/docs/environment-variables/#environment-variables)
|
||
`GATSBY_JPEG_ENCODER` acts as a fallback if set to `MOZJPEG`:
|
||
|
||
```shell
|
||
GATSBY_JPEG_ENCODER=MOZJPEG
|
||
```
|
||
|
||
### EXIF and ICC metadata
|
||
|
||
By default, `gatsby-plugin-sharp` strips all EXIF, ICC and other metadata
|
||
present in your source file. This is the recommended default as it leads to
|
||
smaller file sizes.
|
||
|
||
However, in situations where you wish to preserve EXIF metadata or ICC profiles
|
||
(example: you are building a photography portfolio and wish to conserve
|
||
the color profile or the copyright information of the photos you've exported
|
||
from Adobe Lightroom or Phase One's Capture One), you can set the `stripMetadata`
|
||
plugin option to `false` in `gatsby-config.js`.
|
||
|
||
It is important to note that if `stripMetadata` is set to `false`, **all**
|
||
metadata information will be preserved from the source image, including but not
|
||
limited to the latitude/longitude information of where the picture was taken
|
||
(if present). If you wish to strip this information from the source file, you
|
||
can either leave `stripMetadata` to its default of `true`, or manually
|
||
pre-process your images with a tool such as [ExifTool][17].
|
||
|
||
## Troubleshooting
|
||
|
||
### Incompatible library version: sharp.node requires version X or later, but Z provides version Y
|
||
|
||
This means that there are multiple incompatible versions of the `sharp` package installed in `node_modules`. The complete error typically looks like this:
|
||
|
||
```
|
||
Something went wrong installing the "sharp" module
|
||
|
||
dlopen(/Users/misiek/dev/gatsby-starter-blog/node_modules/sharp/build/Release/sharp.node, 1): Library not loaded: @rpath/libglib-2.0.dylib
|
||
Referenced from: /Users/misiek/dev/gatsby-starter-blog/node_modules/sharp/build/Release/sharp.node
|
||
Reason: Incompatible library version: sharp.node requires version 6001.0.0 or later, but libglib-2.0.dylib provides version 5801.0.0
|
||
```
|
||
|
||
To fix this, you'll need to update all Gatsby plugins in the current project that depend on the `sharp` package. Here's a list of official plugins that you might need to update in case your projects uses them:
|
||
|
||
- `gatsby-plugin-sharp`
|
||
- `gatsby-plugin-manifest`
|
||
- `gatsby-remark-images-contentful`
|
||
- `gatsby-source-contentful`
|
||
- `gatsby-transformer-sharp`
|
||
- `gatsby-transformer-sqip`
|
||
|
||
To update these packages, run:
|
||
|
||
```sh
|
||
npm install gatsby-plugin-sharp gatsby-plugin-manifest gatsby-remark-images-contentful gatsby-source-contentful gatsby-transformer-sharp gatsby-transformer-sqip
|
||
```
|
||
|
||
If updating these doesn't fix the issue, your project probably uses other plugins from the community that depend on a different version of `sharp`. Try running `npm list sharp` or `yarn why sharp` to see all packages in the current project that use `sharp` and try updating them as well.
|
||
|
||
[1]: https://alistapart.com/article/finessing-fecolormatrix
|
||
[2]: http://blog.72lions.com/blog/2015/7/7/duotone-in-js
|
||
[3]: https://ines.io/blog/dynamic-duotone-svg-jade
|
||
[4]: https://en.wikipedia.org/wiki/Relative_luminance
|
||
[5]: https://github.com/nagelflorian/react-duotone
|
||
[6]: http://sharp.pixelplumbing.com/en/stable/api-resize/#crop
|
||
[7]: http://sharp.pixelplumbing.com/en/stable/api-operation/#rotate
|
||
[8]: http://sharp.pixelplumbing.com/en/stable/api-colour/#greyscale
|
||
[9]: https://github.com/gatsbyjs/gatsby/issues/2435
|
||
[10]: https://codepen.io/tigt/post/optimizing-svgs-in-data-uris
|
||
[11]: https://github.com/tooolbox/node-potrace
|
||
[12]: https://github.com/svg/svgo
|
||
[13]: https://github.com/tooolbox/node-potrace#parameters
|
||
[14]: https://github.com/oliver-moran/jimp
|
||
[15]: http://sharp.pixelplumbing.com/en/stable/api-operation/#flatten
|
||
[16]: https://github.com/mozilla/mozjpeg
|
||
[17]: https://www.sno.phy.queensu.ca/~phil/exiftool/
|
||
[18]: https://www.npmjs.com/package/color
|