Skip to content

Commit 3ad780e

Browse files
polarathenepolarathenewardpeet
authored
docs(gatsby-plugin-sharp): Base64 features (#24999)
Co-authored-by: polarathene <brennan.kinney.nz@gmail.com> Co-authored-by: Ward Peeters <ward@coding-tech.com>
1 parent a5c76fc commit 3ad780e

File tree

5 files changed

+203
-42
lines changed

5 files changed

+203
-42
lines changed

‎packages/gatsby-plugin-sharp/README.md

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,12 @@ plugins: [
3030
{
3131
resolve: `gatsby-plugin-sharp`,
3232
options: {
33-
useMozJpeg: false,
33+
// Available options and their defaults:
34+
base64Width: 20,
35+
forceBase64Format: ``, // valid formats: png,jpg,webp
36+
useMozJpeg: process.env.GATSBY_JPEG_ENCODER === `MOZJPEG`,
3437
stripMetadata: true,
35-
defaultQuality: 75,
38+
defaultQuality: 50,
3639
},
3740
},
3841
]
@@ -137,6 +140,8 @@ following:
137140
- `grayscale` (bool, default: false)
138141
- `duotone` (bool|obj, default: false)
139142
- `toFormat` (string, default: '')
143+
- `toFormatBase64` (string, default: '')
144+
- `base64Width` (int, default: 20)
140145
- `cropFocus` (string, default: 'ATTENTION')
141146
- `fit` (string, default: 'COVER')
142147
- `pngCompressionSpeed` (int, default: 4)
@@ -147,6 +152,26 @@ following:
147152
Convert the source image to one of the following available options: `NO_CHANGE`,
148153
`JPG`, `PNG`, `WEBP`.
149154

155+
#### toFormatBase64
156+
157+
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`.
158+
159+
`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.
160+
161+
[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.
162+
163+
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.
164+
165+
#### base64Width
166+
167+
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.
168+
169+
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.
170+
171+
[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.
172+
173+
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.
174+
150175
#### cropFocus
151176

152177
Change the cropping focus. Available options: `CENTER`, `NORTH`, `NORTHEAST`,

‎packages/gatsby-plugin-sharp/src/__tests__/__snapshots__/index.js.snap

Lines changed: 60 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,16 @@ Object {
1010
}
1111
`;
1212

13+
exports[`gatsby-plugin-sharp base64 should support option: 'background' 1`] = `
14+
Object {
15+
"aspectRatio": 1,
16+
"height": 20,
17+
"originalName": "alphatest.png",
18+
"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==",
19+
"width": 20,
20+
}
21+
`;
22+
1323
exports[`gatsby-plugin-sharp duotone fixed 1`] = `
1424
Object {
1525
"aspectRatio": 1,
@@ -72,8 +82,9 @@ exports[`gatsby-plugin-sharp fixed correctly infers the width when only the heig
7282
},
7383
],
7484
"pluginOptions": Object {
85+
"base64Width": 20,
7586
"defaultQuality": 50,
76-
"forceBase64Format": false,
87+
"forceBase64Format": "",
7788
"lazyImageGeneration": true,
7889
"stripMetadata": true,
7990
"useMozJpeg": false,
@@ -126,8 +137,9 @@ exports[`gatsby-plugin-sharp fixed does not warn when the requested width is equ
126137
},
127138
],
128139
"pluginOptions": Object {
140+
"base64Width": 20,
129141
"defaultQuality": 50,
130-
"forceBase64Format": false,
142+
"forceBase64Format": "",
131143
"lazyImageGeneration": true,
132144
"stripMetadata": true,
133145
"useMozJpeg": false,
@@ -180,8 +192,9 @@ exports[`gatsby-plugin-sharp fixed should give the same result with createJob as
180192
},
181193
],
182194
"pluginOptions": Object {
195+
"base64Width": 20,
183196
"defaultQuality": 50,
184-
"forceBase64Format": false,
197+
"forceBase64Format": "",
185198
"lazyImageGeneration": true,
186199
"stripMetadata": true,
187200
"useMozJpeg": false,
@@ -220,8 +233,9 @@ exports[`gatsby-plugin-sharp fixed warns when the requested width is greater tha
220233
},
221234
],
222235
"pluginOptions": Object {
236+
"base64Width": 20,
223237
"defaultQuality": 50,
224-
"forceBase64Format": false,
238+
"forceBase64Format": "",
225239
"lazyImageGeneration": true,
226240
"stripMetadata": true,
227241
"useMozJpeg": false,
@@ -288,8 +302,9 @@ exports[`gatsby-plugin-sharp fluid accepts srcSet breakpoints 1`] = `
288302
},
289303
],
290304
"pluginOptions": Object {
305+
"base64Width": 20,
291306
"defaultQuality": 50,
292-
"forceBase64Format": false,
307+
"forceBase64Format": "",
293308
"lazyImageGeneration": true,
294309
"stripMetadata": true,
295310
"useMozJpeg": false,
@@ -328,8 +343,9 @@ exports[`gatsby-plugin-sharp fluid adds pathPrefix if defined 1`] = `
328343
},
329344
],
330345
"pluginOptions": Object {
346+
"base64Width": 20,
331347
"defaultQuality": 50,
332-
"forceBase64Format": false,
348+
"forceBase64Format": "",
333349
"lazyImageGeneration": true,
334350
"stripMetadata": true,
335351
"useMozJpeg": false,
@@ -408,8 +424,9 @@ Array [
408424
},
409425
],
410426
"pluginOptions": Object {
427+
"base64Width": 20,
411428
"defaultQuality": 50,
412-
"forceBase64Format": false,
429+
"forceBase64Format": "",
413430
"lazyImageGeneration": true,
414431
"stripMetadata": true,
415432
"useMozJpeg": false,
@@ -487,8 +504,9 @@ Array [
487504
},
488505
],
489506
"pluginOptions": Object {
507+
"base64Width": 20,
490508
"defaultQuality": 50,
491-
"forceBase64Format": false,
509+
"forceBase64Format": "",
492510
"lazyImageGeneration": true,
493511
"stripMetadata": true,
494512
"useMozJpeg": false,
@@ -566,8 +584,9 @@ Array [
566584
},
567585
],
568586
"pluginOptions": Object {
587+
"base64Width": 20,
569588
"defaultQuality": 50,
570-
"forceBase64Format": false,
589+
"forceBase64Format": "",
571590
"lazyImageGeneration": true,
572591
"stripMetadata": true,
573592
"useMozJpeg": false,
@@ -645,8 +664,9 @@ Array [
645664
},
646665
],
647666
"pluginOptions": Object {
667+
"base64Width": 20,
648668
"defaultQuality": 50,
649-
"forceBase64Format": false,
669+
"forceBase64Format": "",
650670
"lazyImageGeneration": true,
651671
"stripMetadata": true,
652672
"useMozJpeg": false,
@@ -702,8 +722,9 @@ Array [
702722
},
703723
],
704724
"pluginOptions": Object {
725+
"base64Width": 20,
705726
"defaultQuality": 50,
706-
"forceBase64Format": false,
727+
"forceBase64Format": "",
707728
"lazyImageGeneration": true,
708729
"stripMetadata": true,
709730
"useMozJpeg": false,
@@ -763,8 +784,9 @@ Array [
763784
},
764785
],
765786
"pluginOptions": Object {
787+
"base64Width": 20,
766788
"defaultQuality": 50,
767-
"forceBase64Format": false,
789+
"forceBase64Format": "",
768790
"lazyImageGeneration": true,
769791
"stripMetadata": true,
770792
"useMozJpeg": false,
@@ -824,8 +846,9 @@ Array [
824846
},
825847
],
826848
"pluginOptions": Object {
849+
"base64Width": 20,
827850
"defaultQuality": 50,
828-
"forceBase64Format": false,
851+
"forceBase64Format": "",
829852
"lazyImageGeneration": true,
830853
"stripMetadata": true,
831854
"useMozJpeg": false,
@@ -885,8 +908,9 @@ Array [
885908
},
886909
],
887910
"pluginOptions": Object {
911+
"base64Width": 20,
888912
"defaultQuality": 50,
889-
"forceBase64Format": false,
913+
"forceBase64Format": "",
890914
"lazyImageGeneration": true,
891915
"stripMetadata": true,
892916
"useMozJpeg": false,
@@ -918,8 +942,9 @@ exports[`gatsby-plugin-sharp fluid does not change the arguments object it is gi
918942
},
919943
],
920944
"pluginOptions": Object {
945+
"base64Width": 20,
921946
"defaultQuality": 50,
922-
"forceBase64Format": false,
947+
"forceBase64Format": "",
923948
"lazyImageGeneration": true,
924949
"stripMetadata": true,
925950
"useMozJpeg": false,
@@ -986,8 +1011,9 @@ exports[`gatsby-plugin-sharp fluid ensure maxWidth is in srcSet breakpoints 1`]
9861011
},
9871012
],
9881013
"pluginOptions": Object {
1014+
"base64Width": 20,
9891015
"defaultQuality": 50,
990-
"forceBase64Format": false,
1016+
"forceBase64Format": "",
9911017
"lazyImageGeneration": true,
9921018
"stripMetadata": true,
9931019
"useMozJpeg": false,
@@ -1095,8 +1121,9 @@ exports[`gatsby-plugin-sharp fluid infers the maxWidth if only maxHeight is give
10951121
},
10961122
],
10971123
"pluginOptions": Object {
1124+
"base64Width": 20,
10981125
"defaultQuality": 50,
1099-
"forceBase64Format": false,
1126+
"forceBase64Format": "",
11001127
"lazyImageGeneration": true,
11011128
"stripMetadata": true,
11021129
"useMozJpeg": false,
@@ -1135,8 +1162,9 @@ exports[`gatsby-plugin-sharp fluid keeps original file name 1`] = `
11351162
},
11361163
],
11371164
"pluginOptions": Object {
1165+
"base64Width": 20,
11381166
"defaultQuality": 50,
1139-
"forceBase64Format": false,
1167+
"forceBase64Format": "",
11401168
"lazyImageGeneration": true,
11411169
"stripMetadata": true,
11421170
"useMozJpeg": false,
@@ -1196,8 +1224,9 @@ exports[`gatsby-plugin-sharp fluid prevents duplicate breakpoints 1`] = `
11961224
},
11971225
],
11981226
"pluginOptions": Object {
1227+
"base64Width": 20,
11991228
"defaultQuality": 50,
1200-
"forceBase64Format": false,
1229+
"forceBase64Format": "",
12011230
"lazyImageGeneration": true,
12021231
"stripMetadata": true,
12031232
"useMozJpeg": false,
@@ -1264,8 +1293,9 @@ exports[`gatsby-plugin-sharp fluid reject any breakpoints larger than the origin
12641293
},
12651294
],
12661295
"pluginOptions": Object {
1296+
"base64Width": 20,
12671297
"defaultQuality": 50,
1268-
"forceBase64Format": false,
1298+
"forceBase64Format": "",
12691299
"lazyImageGeneration": true,
12701300
"stripMetadata": true,
12711301
"useMozJpeg": false,
@@ -1304,8 +1334,9 @@ exports[`gatsby-plugin-sharp fluid should give the same result with createJob as
13041334
},
13051335
],
13061336
"pluginOptions": Object {
1337+
"base64Width": 20,
13071338
"defaultQuality": 50,
1308-
"forceBase64Format": false,
1339+
"forceBase64Format": "",
13091340
"lazyImageGeneration": true,
13101341
"stripMetadata": true,
13111342
"useMozJpeg": false,
@@ -1359,8 +1390,9 @@ exports[`gatsby-plugin-sharp queueImageResizing with createJob file name works w
13591390
},
13601391
],
13611392
"pluginOptions": Object {
1393+
"base64Width": 20,
13621394
"defaultQuality": 50,
1363-
"forceBase64Format": false,
1395+
"forceBase64Format": "",
13641396
"lazyImageGeneration": true,
13651397
"stripMetadata": true,
13661398
"useMozJpeg": false,
@@ -1401,8 +1433,9 @@ exports[`gatsby-plugin-sharp queueImageResizing with createJob should round heig
14011433
},
14021434
],
14031435
"pluginOptions": Object {
1436+
"base64Width": 20,
14041437
"defaultQuality": 50,
1405-
"forceBase64Format": false,
1438+
"forceBase64Format": "",
14061439
"lazyImageGeneration": true,
14071440
"stripMetadata": true,
14081441
"useMozJpeg": false,
@@ -1443,8 +1476,9 @@ exports[`gatsby-plugin-sharp queueImageResizing with createJobV2 file name works
14431476
},
14441477
],
14451478
"pluginOptions": Object {
1479+
"base64Width": 20,
14461480
"defaultQuality": 50,
1447-
"forceBase64Format": false,
1481+
"forceBase64Format": "",
14481482
"lazyImageGeneration": true,
14491483
"stripMetadata": true,
14501484
"useMozJpeg": false,
@@ -1483,8 +1517,9 @@ exports[`gatsby-plugin-sharp queueImageResizing with createJobV2 should round he
14831517
},
14841518
],
14851519
"pluginOptions": Object {
1520+
"base64Width": 20,
14861521
"defaultQuality": 50,
1487-
"forceBase64Format": false,
1522+
"forceBase64Format": "",
14881523
"lazyImageGeneration": true,
14891524
"stripMetadata": true,
14901525
"useMozJpeg": false,

0 commit comments

Comments
 (0)