holistic-image

Holism is the idea that various systems should be viewed as wholes, not merely as a collection of parts.

Build-time Automatic image transformation and Holistic management

• 🍊 uses squoosh to derive jpg, webp, avif from your sources
• 📦 hides implementation details behind Webpack
• 🤖 on demand file creation, and CLI utils to verify integrity
• ⚛️ optional React implementation

Structure

This is a convention over configuration library, and all you need is to follow our convention

Having ➡️

├── [email protected]

️Will produce ⬇️

├── [email protected]
├── .holistic (you can hide this directory)
│   └─ image@2x
│      ├─ [email protected]
│      ├─ [email protected]
│      ├─ [email protected]
│      ├─ [email protected]
│      ├─ [email protected]
│      ├─ [email protected]
|      ├─ derived.scss
│      └─ [email protected]

The same principle will be applied during the import - instead of importing [email protected] you will get a pointer to all files below

Note: holistic-image does not produce png output (configurable) as the end user is expected to use webp or avif

Usage

Step 1 - derive files

holistic-image is looking for files named accordingly - image.holistic.png(or jpg) and derives the "missing" ones - optimized jpg, webp and avif

If the source file named as [email protected](Figma standard), then @1x version will be generated automatically

How to use

• via Webpack loader Just use webpack loader with autogenerate option enabled (default)
• via API

// generate-images.js
import {deriveHolisticImages} from "holistic-image/api";

deriveHolisticImages(
  /root folder*/
process.argv[2],
  /*mask*/ process.argv[3],
// /*optional*/ squoosh ecoders with options
)

And then in package.json

// package.json
 "autogen:images": "yarn generate-images.js $INIT_CWD 'src/**/*'",

• via CLI

// package.json
"autogen:images":"holistic-image derive  $INIT_CWD 'src/**/*'"
"validate:images":"holistic-image validate  $INIT_CWD 'src/**/*'"

Step 2 - configure webpack to process images

• Optimized config, will remove originals from the final bundle

import { holisticImage } from 'holistic-image/webpack';

webpack.config = {
  module: {
    rules: {
      oneOf: [holisticImage, yourFileLoader],
      // .. rest of your config
    },
  },
};

• automatic image generation will be enabled if process.env.NODE_ENV is set to development

• to fine control settings use:

  • import { holisticImagePresetFactory } from 'holistic-image/webpack';
  • import { holisticImageLoader } from 'holistic-image/webpack';

• Easy config (for storybook for example), everything will work as well

import { holisticImage } from 'holistic-image/webpack';

webpack.config = {
  module: {
    rules: {
      holisticImage,
      yourFileLoader,
      // .. and rest of your config
    },
  },
};

Step 3 - use

import image from './image.holistic.jpg';
// ^ not an image, but HolisticalImageDefinition
image = {
  base: [1x, 2x],
  webp: [1x, 2x],
  avif: [1x, 2x],
  [META]: {width, height, ratio}
}

Build in React component

import { Image } from 'holistical-image/react';
import image from './image.holistic.jpg';
import imageXS from './imageXS.holistic.jpg';

<Image src={image} media={{ 'max-width: 600px': imageXS }} />;
// 👇 6-12 images generated, the right picked, completely transparent

TypeScript integration

While this library provides d.ts for the file extension it can be more beneficial to provide your own ones, as you did for .jpg and other static asses already

declare module '*.holistic.jpg' {
  import type { HolisticalImageDefinition } from 'holistic-image';

  const content: HolisticalImageDefinition;
  export default content;
}

Configuration

Configuration is possible in two modes:

• full control via API
• config-file based (via cosmic-config)

.holistic-imagerc.yaml (can be json or js as well)

# derived from https://github.com/GoogleChromeLabs/squoosh/blob/61de471e52147ecdc8ff674f3fcd3bbf69bb214a/libsquoosh/src/codecs.ts
---
jpg:
  use: mozjpeg
  # with default 75
  options:
    - quality: 80 # for scale 1x
    - quality: 70 # for scale 2x
webp:
  use: webp
  # with default 75
  options:
    - quality: 85
      method: 6
avif:
  use: avif
  # with default 33
  options:
    - cqLevel: 20
      effort: 5
    - cqLevel: 28
      effort: 5

Hiding .holistic output files

folders starting from . already expected to be hidden for IDE, but keep in mind - derived files are expected to be commited.

WebStorm/IDEA

You can use idea-exclude to automaticaly configure Idea-based solutions to exclude these folders

• run idea-exclude holistic-images "src/**/.holistic"

VCS

"files.exclude": {
    "**/.holistic": true
}

See also

• imagemin (unmaintaned) the same defiving mechanics, with no further management
• image-webpack-loader not creates, but optimizes existing images
• nextjs/image serves optimized image via CDN transformation

License

MIT