@brigad/ideal-image-loader

🖼️ A loader for webpack which handles 2x/3x/webp and works well with gatsby-image and react-ideal-image

Release article (TODO)

Installation

yarn add @brigad/ideal-image-loader

Or, if you are using npm:

npm install --save @brigad/ideal-image-loader

Usage

ideal-image-loader works like file-loader, but will also load @2x, @3x and .webp variations of the file.

// Will also try to resolve:
// - ./image@2x.png
// - ./image@3x.png
// - and try to generate:
// - ./image.webp
// - ./image@2x.webp
// - ./image@3x.webp
import img from './image.png';

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(jpe?g|png|svg|gif)$/i,
        use: [
          {
            loader: '@brigad/ideal-image-loader',
            options: {
              name: 'images/[name].[ext]',
            },
          },
        ],
      },
    ],
  },
};

// output
{
  "x1": {
    "src": "...",
    "preSrc": "data:...",
    "webp": "..."
  },
  "x2": {
    "src": "...",
    "preSrc": "data:...",
    "webp": "..."
  },
  "x3": {
    "src": "...",
    "preSrc": "data:...",
    "webp": "..."
  }
}

And run webpack via your preferred method.

A fully-working component example is available here, feel free to copy it and to adapt it to your needs!

Problem

At Brigad, we have been looking for a solution to lazy-load images in a way that would feel good for the user and the developer. We also wanted our images to be as lightweight as possible for a given screen resolution. We tried to use gatsby-image (but without using Gatsby) and react-ideal-image, but we needed a loader to help us load our images without manually converting all of them to Webp, and manually importing each variation.

Solution

To solve the problems listed above, ideal-image-loader will, based on one imported image, resolve the @2x and @3x formats, and generate the .webp alternatives.

And the cherry on the top: it works seamlessly with gatsby-image without the need to use Gatsby, and also with react-ideal-image!

Browse the documentation to get started! To learn more about the problem and solution, you can also read the release article.

Options

Sensible configuration:

const IS_PRODUCTION = process.env.NODE_ENV === 'production';

options: {
  name: 'images/[name].[hash].[ext]',
  base64: IS_PRODUCTION,
  webp: IS_PRODUCTION ? undefined : false,
  warnOnMissingSrcset: !IS_PRODUCTION,
},

This loader forwards all additional options (such as name) to file-loader.

base64

Type: boolean, Default: true

Specifies whether a low quality image placeholder (lqip) should be generated under the key preSrc.

palette

Type: boolean, Default: false

Specifies whether a color palette should be generated under the key palette.

webp

Specifies whether .webp images should be generated under the key webp.

srcset

Specifies whether @2x and @3x images should be resolved, and new objects x2 and x3 should be put alongside x1.

warnOnMissingSrcset

Specifies whether the loader should warn when there are missing @2x and @3x images.

Peer dependencies

Ideal-image-loader assumes you are using Node 6.9.0, Webpack 4.0.0 and File-loader 2.0.0.

Contributors

Thanks goes to these people (emoji key):

Adrien HARNAY 📝 💻 🎨 📖 💡 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!