Image Processing Pipeline may be configured by using any of the file naming schemes supported by cosmiconfig.
A custom configuration file may also be specified using the
--config flag, which will override the
default searching behaviour and instead exclusivly attempt to use the provided config path.
The loaded configuration will be validated using a JSON schema to check for inconsistencies and warn you of any problems.
If no configuration is explicitly specified via the
--config flag, IPP will attempt to search the
current working directory and parent directories for a recognised configuration file. Any file
supported by cosmiconfig will be correctly understood by IPP.
For example, you may define one of the following files (in order of priority):
- an ipp property in your package.json
- a JSON or YAML .ipprc file
IPP eventually converts configuations to JS, but understands several base formats. Each have slight differences, with more abstraction towards the top of the list.
- YAML is the most human-friendly and compact (recommended for most users)
- JSON is a widely recognised universal format, similar to JS
- JS allows for dynamic configs and lambda pipe functions
Calling the CLI's
startCLI() function programatically bypasses any configuration searching or
validation. Instead, the configuration is passed as a function parameter.
If you are using TypeScript, you can rest easy knowing that the function is strongly typed, providing the same level of safety against faulty configuration, if not better.
If you save your configuration in the JSON format, you may benefit from intelligent JSON Schema
features offered by your IDE by specifying a root
$schema property that points to this permanant
Below is a good starting point for building a set of responsive website images. Give it a try and then adjust it to suit your needs.
In order to use the following configuration, you will also need to install the @ipp/compress and @ipp/primitive packages.
This configuration will do things. Firstly, it will generate four different sizes, labelled sm, md, lg and xl, saving them in the original format and as a WebP image, and secondly, create an SVG placeholder using the primitive pipe.
Every exported format is then saved to the manifest with the original image's hash for easy lookup, and the exported format's image dimensions.
In this example, we first convert the image to raw pixel data and use that to resize the image and convert back to lossy formats, such as JPEG and WebP.
This will yield slightly better results (especially for the WebP image, as it has a better source),
at the cost of using more memory during image processing. If your system doesn't have enough RAM,
consider lowering the concurrency or removing the raw and original convert pipes and removing
the resize pipe's
quality: 100 option.
All of IPP's built-in and official pipes support raw pixel data.
The WebP export does not need a compression pipe, there aren't any good compression algorithms that beat the reference codec encoder.
|input||string or array||The path to an image, or a folder containing images (required)|
|output||string||The path to the directory to output images to (required)|
|pipeline||array||See the pipeline (required)|
|concurrency||number||Allows for more fine-grain control of the program options|
|clean||boolean||Delete the output directory before processing (dangerous!)|
|flat||boolean||Whether to flatten the output directory structure|
|manifest||object||See the manifest|
concurrency is not actually required as it is populated by the inititialisation script by default.
clean option is enabled, the path specified as the output folder will be unrecoverably
deleted with no additional checks in place. Use with care.
|source||object||Per-image exported metadata keys|
|format||object||Per-format exported metadata keys|
The manifest property lets you select which metadata values you would like to include in the manifest file, essentially mapping metadata to new property names in the manifest.
There are two sub-properties,
source, which lets you include metadata that is relevant to the
source image, and
format which is exported separately for every format.
The key is used as the new name of the metadata value, while the value is the name of the
metadata key. The length selector "
:" may also be used to limit the size of the metadata value.
To learn more about the manifest, see this dedicated page.
The pipeline is an array of pipeline branches. It is a recursive structure, as each pipeline branch may additionally define another pipeline that receives its output. It is best to imagine it like a tree, where each branch is a pipe that can split into more branches.
A pipeline is just a collection of ordered pipeline branches. A pipeline branch defines a single pipe that the image will be processed by, along with additional options and whether or not to save the exported formats.
It may also additionally define an ensuing pipeline that will receive the output of the pipe. Branches may only split, but not rejoin. This is to keep the pipeline schema as simple as possible.
|pipe||string or object or function||Per-image exported metadata keys (required)|
|options||object||Per-format exported metadata keys|
|save||string or ||Per-format exported metadata keys|
|then||object||Per-format exported metadata keys|
This property tells IPP how to find the pipe. It can be:
- a string for a built-in pipe
- an object to resolve a pipe from an npm package
- a function (advanced usage)
When resolving using an object, you may define a resolve property which is the npm package name, and optionally a module property that lets you choose the module export (see ES Modules). See the example above for the primitive pipe.
To mark an image format for export, it must have a
save key. This key must be a string and is used
to determine the format's filename. The save key can contain template literals using square brackets
that are substituted with values from the metadata.