@zubyjs/image 1.0.65

package/README.md

@@ -0,0 +1,182 @@
+# @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](https://www.npmjs.com/package/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
+
+### Image Component
+
+Now you can use the `<Image>` 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 (
+      <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.
+
+```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](https://www.npmjs.com/package/zuby).
+Please refer to it for more details how to contribute.
+
+## License
+
+MIT

package/handler.d.ts

@@ -0,0 +1,8 @@
+import { HandlerContext } from 'zuby/contexts/index.js';
+/**
+ * The image handler that optimizes images
+ * on /_image/:path* endpoint.
+ * @param context
+ * @param _next
+ */
+export default function Handler(context: HandlerContext, _next: () => void): Promise<Response>;

package/handler.js

@@ -0,0 +1,64 @@
+import optimizeImage from './optimizeImage.js';
+import { HTTP_HEADERS } from 'zuby/constants.js';
+import { IMAGE_FORMATS_ARRAY } from 'zuby/types.js';
+import { pathToOptions } from './options/pathToOptions.js';
+/**
+ * The image handler that optimizes images
+ * on /_image/:path* endpoint.
+ * @param context
+ * @param _next
+ */
+export default async function Handler(context, _next) {
+    try {
+        const { src, format, quality, width, height } = pathToOptions(context.url.pathname);
+        if (!src) {
+            return new Response(`ERROR: Missing 'src' attribute.\r\nThe format is '/_image/{quality}/{width}/{height}/{src}'`, { status: 400 });
+        }
+        if (src.startsWith('http://') || src.startsWith('https://')) {
+            return new Response(`ERROR: The 'src' attribute needs to be relative`, { status: 400 });
+        }
+        if ((format && !IMAGE_FORMATS_ARRAY.includes(format)) ||
+            (src && !IMAGE_FORMATS_ARRAY.some(ext => src.endsWith(ext)))) {
+            return new Response(`ERROR: Unsupported 'format' or 'src' file extension. Supported formats are: ${IMAGE_FORMATS_ARRAY.join(', ')}`, { status: 400 });
+        }
+        const origin = context.url.origin.replace('localhost', '127.0.0.1');
+        const imageUrl = new URL(src, origin);
+        if (imageUrl.pathname.startsWith('/_image/')) {
+            return new Response(`ERROR: Cannot fetch self URL '/_image/:path*' to avoid loop.`, {
+                status: 400,
+            });
+        }
+        const imageRes = await fetch(imageUrl);
+        if (!imageRes.ok) {
+            return new Response(`ERROR: Failed to fetch image from the provided 'src' attribute.`, {
+                status: 400,
+            });
+        }
+        if (!imageRes.headers
+            .get(HTTP_HEADERS.ContentType)
+            ?.toString()
+            .match(/image\//)) {
+            return new Response(`ERROR: Unsupported content-type returned while fetching the image.`, {
+                status: 400,
+            });
+        }
+        const input = Buffer.from(await imageRes.arrayBuffer());
+        const { output, outputFormat } = await optimizeImage({
+            input,
+            width,
+            height,
+            format: format,
+            quality,
+        });
+        return new Response(output, {
+            headers: {
+                [HTTP_HEADERS.ContentType]: `image/${outputFormat}`,
+                [HTTP_HEADERS.CacheControl]: 'public, max-age=31536000, immutable',
+            },
+        });
+    }
+    catch (e) {
+        console.error(e);
+        return new Response('ERROR: An error occurred while optimizing your image.', { status: 500 });
+    }
+}

package/imageLoader.d.ts

@@ -0,0 +1,12 @@
+import { ImageLoaderOptions } from 'zuby/types.js';
+/**
+ * The ImageLoader for @zubyjs/image
+ * that is used to generate image URLs
+ */
+export default function imageLoader({ context, src, isAbsolute, format, quality, width, height, }: ImageLoaderOptions): string;
+/**
+ * Returns shared global image URLs set
+ * available across the whole project
+ * on both client and server side
+ */
+export declare function getImageUrls(): Set<string>;

package/imageLoader.js

@@ -0,0 +1,52 @@
+import { optionsToPath } from './options/optionsToPath.js';
+let warningShown = false;
+/**
+ * The ImageLoader for @zubyjs/image
+ * that is used to generate image URLs
+ */
+export default function imageLoader({ context, src, isAbsolute, format, quality, width = 1920, height, }) {
+    const { buildId } = context;
+    if (isAbsolute) {
+        // Just add buildId to the image URL
+        if (src.includes('?'))
+            return `${src}&${buildId}`;
+        return `${src}?${buildId}`;
+    }
+    if (!width && !height && !warningShown) {
+        console.warn('WARNING: You should always provide at least width or height to the Image component to avoid layout shift.');
+        warningShown = true;
+    }
+    // Normalize the src,
+    // remove any query params
+    src = `/${src}`.replace(/\/+/g, '/').replace(/\?(.*)$/, '');
+    // If output format is different from the input format,
+    // add additional extension to the src
+    if (format && !src.endsWith(`.${format}`)) {
+        src = src.replace(/\.(.+)$/, `.$1.${format}`);
+    }
+    // Generate the image URL pointing to the image handler
+    const url = optionsToPath({
+        src,
+        quality,
+        width,
+        height,
+        format,
+        buildId,
+    });
+    // Collect all generated image URLs,
+    // so we can optimize them later during build
+    const imageUrls = getImageUrls();
+    imageUrls.add(url);
+    return url;
+}
+/**
+ * Returns shared global image URLs set
+ * available across the whole project
+ * on both client and server side
+ */
+export function getImageUrls() {
+    if (!globalThis._zubyImageUrls) {
+        globalThis._zubyImageUrls = new Set();
+    }
+    return globalThis._zubyImageUrls;
+}

package/index.d.ts

@@ -0,0 +1,23 @@
+import { ZubyPlugin } from 'zuby/types.js';
+export interface ImagePluginOptions {
+    /**
+     * Set this option to false to disable
+     * build time image optimization.
+     * @default true
+     */
+    buildTime?: boolean;
+    /**
+     * The maximum number of images that can be optimized
+     * during the build. The rest of the images will be
+     * optimized on-demand during runtime.
+     * @default 1000
+     */
+    maxBuildTime?: number;
+}
+/**
+ * Zuby.js plugin that allows you to
+ * optimize images in your project
+ * @returns ZubyPlugin
+ */
+declare const _default: ({ buildTime, maxBuildTime, }?: ImagePluginOptions) => ZubyPlugin;
+export default _default;

package/index.js

@@ -0,0 +1,69 @@
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { normalizePath } from 'zuby/utils/pathUtils.js';
+import { getImageUrls } from './imageLoader.js';
+import { mkdirSync, existsSync } from 'fs';
+import optimizeImage from './optimizeImage.js';
+import { pathToOptions } from './options/pathToOptions.js';
+import chalk from 'chalk';
+import { performance } from 'node:perf_hooks';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Zuby.js plugin that allows you to
+ * optimize images in your project
+ * @returns ZubyPlugin
+ */
+export default ({ buildTime = true, maxBuildTime = 1000, } = {}) => ({
+    name: 'zuby-image-plugin',
+    description: 'optimizing images...',
+    buildStep: true,
+    hooks: {
+        'zuby:config:setup': ({ config, addHandler }) => {
+            const { customLogger: logger } = config;
+            config.image = config.image || {};
+            if (config.image.loader) {
+                logger?.warn(`WARNING: The image.loader config in 'zuby.config.js' is already set.`);
+                logger?.warn(`Zuby.js allows only one image loader to be set at a time.`);
+                logger?.warn(`Using image loader from '@zubyjs/image' package.`);
+            }
+            config.image.loader = normalizePath(resolve(__dirname, 'imageLoader.js'));
+            addHandler(normalizePath(resolve(__dirname, 'handler.js')), '/_image/:path*');
+        },
+        'zuby:build:done': async ({ config, logger }) => {
+            const { outDir } = config;
+            let optimizedImages = 0;
+            const startTime = performance.now();
+            const imageUrls = getImageUrls();
+            if (!buildTime || imageUrls.size === 0) {
+                logger?.info(`Skipping build time image optimization...`);
+                return;
+            }
+            for (const urlString of imageUrls) {
+                if (optimizedImages >= maxBuildTime) {
+                    logger?.warn(`The maximum number of images that can be optimized during the build has been reached.`);
+                    logger?.warn(`The rest of the images will be optimized on-demand during runtime.`);
+                    break;
+                }
+                const url = new URL(urlString, 'http://127.0.0.1');
+                const imageOptions = pathToOptions(url.pathname);
+                const inputFile = normalizePath(resolve(outDir, 'client', imageOptions.src));
+                const outputFile = normalizePath(resolve(outDir, 'client', url.pathname.replace(/^\//, '')));
+                const outputDir = dirname(outputFile);
+                if (existsSync(outputFile))
+                    continue;
+                if (!existsSync(outputDir))
+                    mkdirSync(outputDir, { recursive: true });
+                logger?.info(`Optimizing: ${chalk.blue(`${imageOptions.src} => ${url.pathname}`)}`);
+                await optimizeImage({
+                    ...imageOptions,
+                    inputFile,
+                    outputFile,
+                });
+                optimizedImages++;
+            }
+            const finishTime = performance.now();
+            logger?.info(chalk.green(`✓ optimized ${optimizedImages} images in ${Math.ceil(finishTime - startTime)}ms`));
+        },
+    },
+});

package/optimizeImage.d.ts

@@ -0,0 +1,2 @@
+import { OptimizeImageOptions, OptimizeImageOutput } from './types.js';
+export default function optimizeImage({ input, inputFile, outputFile, quality, width, height, format, }: OptimizeImageOptions): Promise<OptimizeImageOutput>;

package/optimizeImage.js

@@ -0,0 +1,47 @@
+import sharp from 'sharp';
+export default async function optimizeImage({ input, inputFile, outputFile, quality = 75, width, height, format, }) {
+    // Read the image from buffer or filesystem
+    const image = sharp(input || inputFile);
+    const { format: originalFormat = 'webp', width: originalWidth = 0, height: originalHeight = 0, size: inputSize, } = await image.metadata();
+    const widthRatio = originalWidth / originalHeight;
+    const heightRatio = originalHeight / originalWidth;
+    format = format || originalFormat;
+    width = width || (height || originalHeight) * widthRatio;
+    height = height || (width || originalWidth) * heightRatio;
+    width = Math.round(width);
+    height = Math.round(height);
+    if (height !== originalHeight || width !== originalWidth) {
+        image.resize(width, height);
+    }
+    if (format === 'webp') {
+        image.webp({
+            quality,
+            alphaQuality: quality,
+        });
+    }
+    else if (format || quality) {
+        image.toFormat(format, {
+            progressive: true,
+            force: true,
+            quality,
+        });
+    }
+    let outputFileSize = undefined;
+    // Save the image to filesystem
+    if (outputFile) {
+        const outputInfo = await image.toFile(outputFile);
+        outputFileSize = outputInfo.size;
+    }
+    // Return the image as buffer if no output file is set
+    const output = outputFile ? undefined : await image.toBuffer();
+    return {
+        output,
+        outputFile,
+        outputFormat: format,
+        outputWidth: width,
+        outputHeight: height,
+        outputQuality: quality,
+        outputSize: outputFileSize || output?.length,
+        inputSize,
+    };
+}

package/options/optionsToPath.d.ts

@@ -0,0 +1,7 @@
+import { ImageOptions } from '../types.js';
+/**
+ * Converts image options object to a path
+ * that is later parsed by the handler.
+ * @param options
+ */
+export declare function optionsToPath(options: ImageOptions): string;

package/options/optionsToPath.js

@@ -0,0 +1,9 @@
+/**
+ * Converts image options object to a path
+ * that is later parsed by the handler.
+ * @param options
+ */
+export function optionsToPath(options) {
+    const { src, quality, width, height, buildId } = options;
+    return `/_image/${quality || 'auto'}/${width || 'auto'}/${height || 'auto'}${src}?${buildId}`;
+}

package/options/pathToOptions.d.ts

@@ -0,0 +1,8 @@
+import { ImageOptions } from '../types.js';
+/**
+ * Parses the path config options
+ * to an image options object.
+ * @param path
+ */
+export declare function pathToOptions(path: string): ImageOptions;
+export declare function fromAuto(value: string | undefined): string | undefined;

package/options/pathToOptions.js

@@ -0,0 +1,26 @@
+/**
+ * Parses the path config options
+ * to an image options object.
+ * @param path
+ */
+export function pathToOptions(path) {
+    const [_empty, _prefix, quality, width, height, ...srcSegments] = path.split('/') || [];
+    const originalSrc = srcSegments.join('/');
+    const src = originalSrc
+        .replace(/\/+/g, '/')
+        // Remove leading slash
+        .replace(/^\//g, '')
+        // Remove double extension
+        .replace(/\.(.+)\.(.+)$/, '.$1');
+    const format = originalSrc.split('.').pop();
+    return {
+        src,
+        format: format,
+        quality: Number(fromAuto(quality)),
+        width: Number(fromAuto(width)),
+        height: Number(fromAuto(height)),
+    };
+}
+export function fromAuto(value) {
+    return value === 'auto' ? undefined : value;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@zubyjs/image",
+  "version": "1.0.65",
+  "description": "Zuby.js image plugin",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "release": "cd ./dist && npm publish --access public && cd ..",
+    "bump-version": "npm version patch",
+    "build": "rm -rf dist/ stage/ && mkdir dist && tsc && cp -rf package.json README.md stage/image/src/* dist/ && rm -rf stage/",
+    "push-build": "npm run build && cd dist && yalc push --force && cd ..",
+    "test": "exit 0"
+  },
+  "publishConfig": {
+    "directory": "dist",
+    "linkDirectory": true
+  },
+  "peerDependencies": {
+    "zuby": "^1.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "sharp": "^0.32.6"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/futrou/zuby.js/-/issues",
+    "email": "zuby@futrou.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/futrou/zuby.js.git"
+  },
+  "homepage": "https://zubyjs.com",
+  "keywords": [
+    "zuby-plugin",
+    "zuby",
+    "image",
+    "optimization"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/sharp": "^0.32.0"
+  }
+}

package/types.d.ts

@@ -0,0 +1,29 @@
+/// <reference types="node" resolution-mode="require"/>
+import { ImageFormat } from 'zuby/types.js';
+export interface ImageOptions {
+    src: string;
+    quality?: number;
+    width?: number;
+    height?: number;
+    format?: ImageFormat;
+    buildId?: string;
+}
+export interface OptimizeImageOptions {
+    input?: Buffer;
+    inputFile?: string;
+    outputFile?: string;
+    quality?: number;
+    width?: number;
+    height?: number;
+    format?: ImageFormat;
+}
+export interface OptimizeImageOutput {
+    output?: Buffer;
+    outputFile?: string;
+    outputFormat: ImageFormat;
+    outputWidth: number;
+    outputHeight: number;
+    outputQuality: number;
+    outputSize?: number;
+    inputSize?: number;
+}

package/types.js

@@ -0,0 +1 @@
+export {};