Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(gatsby-plugin-sharp): Base64 features #24999

Merged
merged 9 commits into from
Aug 10, 2020
Merged

docs(gatsby-plugin-sharp): Base64 features #24999

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
9db13b3
chore: Refactor `base64Width`, include in plugin defaults
Jun 15, 2020
67e8128
chore: Change `forceBase64Format` default bool to empty string
Jun 15, 2020
a024f0a
docs: `toFormatBase64` and `base64Width`
Jun 15, 2020
2adbcd8
chore: Replace `args` with `options`
Jun 15, 2020
55600b4
Update packages/gatsby-plugin-sharp/README.md
wardpeet Jul 3, 2020
364bbe5
fix:(gatsby-plugin-sharp): Update pluginOptions to new defaults
polarathene Jul 3, 2020
49bc704
fix: Add new base64 tests
polarathene Jul 14, 2020
b578506
chore: Group `base64Width` and `toFormatBase64` tests separately
polarathene Jul 14, 2020
1419afe
fix: Support background colour option for base64 too
polarathene Jul 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 27 additions & 2 deletions packages/gatsby-plugin-sharp/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,12 @@ plugins: [
{
resolve: `gatsby-plugin-sharp`,
options: {
useMozJpeg: false,
// Available options and their defaults:
base64Width: 20,
forceBase64Format: ``, // valid formats: png,jpg,webp
useMozJpeg: process.env.GATSBY_JPEG_ENCODER === `MOZJPEG`,
stripMetadata: true,
defaultQuality: 75,
defaultQuality: 50,
},
},
]
Expand Down Expand Up @@ -137,6 +140,8 @@ following:
- `grayscale` (bool, default: false)
- `duotone` (bool|obj, default: false)
- `toFormat` (string, default: '')
- `toFormatBase64` (string, default: '')
- `base64Width` (int, default: 20)
- `cropFocus` (string, default: 'ATTENTION')
- `fit` (string, default: 'COVER')
- `pngCompressionSpeed` (int, default: 4)
Expand All @@ -147,6 +152,26 @@ following:
Convert the source image to one of the following available options: `NO_CHANGE`,
`JPG`, `PNG`, `WEBP`.

#### toFormatBase64

base64 image uses the image format from the source , or the value of `toFormat`. This setting allows a different image format instead, available options are: `JPG`, `PNG`, `WEBP`.
muescha marked this conversation as resolved.
Show resolved Hide resolved

`WEBP` allows for a smaller data size, allowing you to reduce your HTML size when transferring over the network, or to use a larger base64 placeholder width default for improved image placeholder quality.

[Not all browsers support `WEBP`](https://caniuse.com/#feat=webp). It would be wasteful to include a fallback image format in this case. Consider also adding a `backgroundColor` placeholder as a fallback instead.

The plugin config option `forceBase64Format` performs the equivalent functionality by default to all your base64 placeholders. `toFormatBase64` has a higher priority for base64 images that need to selectively use a different format.

#### base64Width

The width in pixels for your base64 placeholder to use. The height will also be adjusted based on the aspect ratio of the image. Use this to increase the image quality by allowing more pixels to be used at the expense of increasing the file size of the data to be transferred.

The default for Gatsby is `20`px. This keeps the data size low enough to embed into the HTML document for immediate display on DOM loaded and avoids an additional network request.

[Facebook](https://engineering.fb.com/android/the-technology-behind-preview-photos/) and [Medium](https://jmperezperez.com/medium-image-progressive-loading-placeholder/) are both known to use `42`px width for their image placeholders. However Medium presently uses a solid background color placeholder to load the page as fast as possible, followed by an image placeholder requested over the network instead of embedding it with base64.

The plugin config has an equivalent option, allowing you to change the default for all base64 placeholders. This parameter option has a higher priority over the plugin config option.

#### cropFocus

Change the cropping focus. Available options: `CENTER`, `NORTH`, `NORTHEAST`,
Expand Down
85 changes: 60 additions & 25 deletions packages/gatsby-plugin-sharp/src/__tests__/__snapshots__/index.js.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,16 @@ Object {
}
`;

exports[`gatsby-plugin-sharp base64 should support option: 'background' 1`] = `
Object {
"aspectRatio": 1,
"height": 20,
"originalName": "alphatest.png",
"src": "data:image/jpeg;base64,/9j/2wBDABALDA4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVGC8aGi9jQjhCY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2NjY2P/wgARCAAUABQDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAb/xAAUAQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIQAxAAAAGfAAAB/8QAFBABAAAAAAAAAAAAAAAAAAAAMP/aAAgBAQABBQIf/8QAFBEBAAAAAAAAAAAAAAAAAAAAIP/aAAgBAwEBPwEf/8QAFBEBAAAAAAAAAAAAAAAAAAAAIP/aAAgBAgEBPwEf/8QAFBABAAAAAAAAAAAAAAAAAAAAMP/aAAgBAQAGPwIf/8QAFBABAAAAAAAAAAAAAAAAAAAAMP/aAAgBAQABPyEf/9oADAMBAAIAAwAAABAAAAD/xAAUEQEAAAAAAAAAAAAAAAAAAAAg/9oACAEDAQE/EB//xAAUEQEAAAAAAAAAAAAAAAAAAAAg/9oACAECAQE/EB//xAAUEAEAAAAAAAAAAAAAAAAAAAAw/9oACAEBAAE/EB//2Q==",
"width": 20,
}
`;

exports[`gatsby-plugin-sharp duotone fixed 1`] = `
Object {
"aspectRatio": 1,
Expand Down Expand Up @@ -72,8 +82,9 @@ exports[`gatsby-plugin-sharp fixed correctly infers the width when only the heig
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -126,8 +137,9 @@ exports[`gatsby-plugin-sharp fixed does not warn when the requested width is equ
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -180,8 +192,9 @@ exports[`gatsby-plugin-sharp fixed should give the same result with createJob as
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -220,8 +233,9 @@ exports[`gatsby-plugin-sharp fixed warns when the requested width is greater tha
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -288,8 +302,9 @@ exports[`gatsby-plugin-sharp fluid accepts srcSet breakpoints 1`] = `
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -328,8 +343,9 @@ exports[`gatsby-plugin-sharp fluid adds pathPrefix if defined 1`] = `
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -408,8 +424,9 @@ Array [
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -487,8 +504,9 @@ Array [
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -566,8 +584,9 @@ Array [
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -645,8 +664,9 @@ Array [
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -702,8 +722,9 @@ Array [
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -763,8 +784,9 @@ Array [
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -824,8 +846,9 @@ Array [
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -885,8 +908,9 @@ Array [
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -918,8 +942,9 @@ exports[`gatsby-plugin-sharp fluid does not change the arguments object it is gi
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -986,8 +1011,9 @@ exports[`gatsby-plugin-sharp fluid ensure maxWidth is in srcSet breakpoints 1`]
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1095,8 +1121,9 @@ exports[`gatsby-plugin-sharp fluid infers the maxWidth if only maxHeight is give
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1135,8 +1162,9 @@ exports[`gatsby-plugin-sharp fluid keeps original file name 1`] = `
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1196,8 +1224,9 @@ exports[`gatsby-plugin-sharp fluid prevents duplicate breakpoints 1`] = `
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1264,8 +1293,9 @@ exports[`gatsby-plugin-sharp fluid reject any breakpoints larger than the origin
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1304,8 +1334,9 @@ exports[`gatsby-plugin-sharp fluid should give the same result with createJob as
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1359,8 +1390,9 @@ exports[`gatsby-plugin-sharp queueImageResizing with createJob file name works w
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1401,8 +1433,9 @@ exports[`gatsby-plugin-sharp queueImageResizing with createJob should round heig
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1443,8 +1476,9 @@ exports[`gatsby-plugin-sharp queueImageResizing with createJobV2 file name works
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down Expand Up @@ -1483,8 +1517,9 @@ exports[`gatsby-plugin-sharp queueImageResizing with createJobV2 should round he
},
],
"pluginOptions": Object {
"base64Width": 20,
"defaultQuality": 50,
"forceBase64Format": false,
"forceBase64Format": "",
"lazyImageGeneration": true,
"stripMetadata": true,
"useMozJpeg": false,
Expand Down
Loading