@zubyjs/image NPM

@zubyjs/image

The plugin for Zuby.js that adds image optimization support to your project on top of the existing <Image> component.

It supports both build-time and runtime optimizations and therefore works seamlessly with both static and server output modes.

By default, it performs build-time optimizations for images on pre-rendered pages and runtime optimizations for images on server rendered pages.

This plugin uses sharp binaries under the hood.

Installation

First, install the @zubyjs/image package using your favorite package manager. If you aren't sure, you can use npm:

npm install @zubyjs/image

Then add the @zubyjs/image plugin to your zuby.config.mjs file under the plugins option:

  import { defineConfig } from 'zuby';
  import preact from '@zubyjs/preact';
+ import image from '@zubyjs/image';

  export default defineConfig({
    outDir: '.zuby',
    jsx: preact(),
+   plugins: [
+       image()
+   ]
    ^^^^^^^^
  });

And that's it! NOTE: Always make sure that all zuby packages are in sync in your package.json file:

  {
    "name": "my-zuby-app",
    "version": "1.0.0",
    "dependencies": {
      "zuby": "latest",
      "@zubyjs/image": "latest"
    }
  }

Usage

Image Component

Now you can use the <Image> component in your Zuby.js project as you're used to. Example:

+ import Image from '@zubyjs/preact/image';

  export default function Home() {
    return (
      <div>
-       <img src="/path/to/image.jpg" alt="My image" />
+       <Image src="/path/to/image.jpg" alt="My image" />
      </div>
    );
  }

NOTE: Upper example is showing usage with @zubyjs/preact JsxProvider. If you are using different one, please replace @zubyjs/preact/image with the correct package name.

Image Component Props

Image component accepts following props:

src - path to the image
alt - alt text for the image
width - width of the image
height - height of the image
quality - quality of the image (default: 80)
format - format of the image (default: webp)

If no quality or format is provided, the default quality from zuby.config.mjs will be used. This can be changed globally by setting image.defaultFormat and image.defaultQuality in zuby.config.mjs.

If no width and height are provided, the image will be rendered in its original size with max resolution 1920px.

While resizing the image, the original aspect ratio is always preserved. The Image will try to load the src image with the nearest size to the provided width and height and then resize it to the exact size using CSS.

Runtime Image Optimization

For runtime image optimization, the plugin will add new endpoint to your server at /_image. This endpoint accepts input in the following format:

/_image/${quality}/${width}/${height}/${src}.${format}

The format is used to find the optimized images in the client directory on filesystem and allows you to easily serve already optimized images from the CDN or custom web server.

For example to optimize image on path /images/dog.jpg to 80% quality, 300px width, 200px height and output format webp you can use the following URL:

/_image/80/300/200/path/to/image.jpg.webp

To omit any of the parameters and use the default values or the original image values, you can use auto as the value. Example:

/_image/auto/300/200/path/to/image.jpg.webp

If the output format is same as the input format, you can leave the extension unchanged. Example:

/_image/auto/300/200/path/to/image.jpg

Build-time Image Optimization

During the build, the plugin will optimize all images on pre-rendered pages and put them into the client/_image directory. Those images won't be optimized again on runtime.

If you're satisfied with the build-time optimization results, you can copy the client/_image directory to your public directory to skip the build-time optimization for those images in the future.

The build-time optimization is very useful for static output mode and can save a lot of time and resources on the server. On the other hand, it can significantly increase your build time.

If you want to disable the build-time optimization, you can set buildTime plugin option to false in your zuby.config.mjs or set maximum number of images to optimize using maxBuildTime option. The default value is 1000 images and the rest is optimized on-demand on runtime.

  import { defineConfig } from 'zuby';
  import preact from '@zubyjs/preact';
+ import image from '@zubyjs/image';

  export default defineConfig({
    outDir: '.zuby',
    jsx: preact(),
    plugins: [
       image({
+           maxBuildTime: 100,
+           buildTime: true
            ^^^^^^^^
       })
    ]
  });