Generate appropriately resized and optimized images for your website, using a configuration object that can be shared with client-side libraries.
@mapbox/appropriate-images-react can be used to do this in React, with a component that automatically measures its own available width.
npm install @mapbox/appropriate-images
Returns a Promise that resolves with an array of filenames for the resized and optimized images that have been written to your output directory.
When the Promise rejects, it may reject with a single error or an array of errors.
For each image this function will:
Output filenames have suffixes corresponding to the size of the variant. For example, with the following property in your image configuration:
bear:basename: 'bear.png'sizes:width: 300width: 600 height: 200/* ... */
You will get files with the following basenames:
// Exampleconst appropriateImages = ;const myImageConfig = ;appropriateImages;
An image configuration object. Options for this configuration are documented below.
Path to your directory of source images.
basename in your image configuration should be relative to this directory.
Path to the directory where resized, optimized images should be written.
Ids of images to be processed. Image ids correspond to keys in the image configuration. If this option not provided, all images in the configuration will be processed.
Executes a CLI for your specific directory structure.
The CLI runs
generate using your specified configuration.
It provides a quick way to generate and re-generate images, with nice error handling.
The arguments are the same as for
appropriate-images exposes the
createCli function instead of an actual CLI because it is not convenient to completely configure
generate from the command line, and your configuration should stay constant within a project.
createCli, you can define your configuration within a JS file, then run that JS file as a CLI.
#!/usr/bin/env node'use strict';const appropriateImages = ;const myImageConfig = ;const myOptions =inputDirectory: '../path/to/my/source/image/directory/'outputDirectory: '../path/to/directory/where/i/want/resized/optimized/images/';appropriateImages;
Don't forget to
chmod +x path/to/file to make it executable.
Then you can run it as a CLI:
my-appropriate-images horse bear pigmy-appropriate-images --all --quiet
The image configuration is an object. For every property:
Each image's configuration object includes the following properties.
The path from
options.inputDirectory to the image (including the image's extension).
An array of objects representing sizes. Each size must include a
width, and can optionally include other properties.
A width for the generated image.
A height for the generated image.
height is provided, the
width is used and the image's aspect ratio is preserved.
height is provided and it does not fit the image's aspect ratio, the image will be cropped.
Defines the manner in which the image will be cropped if both
height are provided.
Must be a valid
crop value for sharp: