@zubyjs/image

The plugin for Zuby.js that adds image optimization support to your project
on top of the existing 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:

``sh
npm install @zubyjs/image
`

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

`diff lang="js" title="zuby.config.mjs"
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:

`diff lang="json"
{
"name": "my-zuby-app",
"version": "1.0.0",
"dependencies": {
"zuby": "latest",
"@zubyjs/image": "latest"
}
}
`

Usage

$3

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

`diff lang="jsx" title="pages/index.jsx"
+ import Image from '@zubyjs/preact/image';

export default function Home() {
return (



);
}
`

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.

$3

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.

`diff lang="js" title="zuby.config.mjs"
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
^^^^^^^^
})
]
});
``

Contributing

This package is part of Zuby.js workspace and maintained by the team behind the Zuby package.
Please refer to it for more details how to contribute.

License

MIT