@ecopages/image-processor 0.2.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `@ecopages/image-processor` are documented here.
+
+> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
+
+## [UNRELEASED] — TBD
+
+### Features
+
+- **`image-plugins.ts`** — New file extracting image processing plugin logic for reuse across build adapters (`image-plugins.ts`).
+- Bun-specific plugin helpers moved to `bun-plugins.ts`, separating runtime concerns from the image processing core.
+
+### Refactoring
+
+- `plugin.ts` updated to use the new `image-plugins.ts` abstraction.
+- `image-processor.ts` minor updates.
+- README updated with usage clarification.
+
+### Tests
+
+- `image-renderer.test.ts` expanded (68 lines added).
+- `image-processor.test.ts` and `image-utils.test.ts` updated.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Andrea Zanenghi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# @ecopages/image-processor
+
+A powerful and flexible image processing library designed to optimize and manage responsive images in ecopages applications.
+
+## Features
+
+- **Automatic Image Optimization**: Converts and compresses images to modern formats
+- **Responsive Image Generation**: Creates multiple image variants for different screen sizes
+- **Virtual Module Integration**: Direct import of optimized images through `ecopages:images`
+- **TypeScript Support**: Full type definitions and auto-generated types
+- **Multiple Layout Options**: Supports fixed, constrained, and full-width layouts
+- **Ecopages Integration**: Seamlessly integrated with the ecopages framework
+
+## Installation
+
+```bash
+npm install @ecopages/image-processor
+```
+
+## Configuration
+
+```typescript
+import path from 'node:path';
+import { ConfigBuilder } from '@ecopages/core';
+import { ImageProcessorPlugin } from '@ecopages/image-processor';
+
+const imageProcessor = new ImageProcessorPlugin({
+	name: 'ecopages-image-processor',
+	type: 'image',
+	options: {
+		sourceDir: path.resolve(import.meta.dir, 'src/images'),
+		outputDir: path.resolve(import.meta.dir, '.eco/images'),
+		publicPath: '/images',
+		acceptedFormats: ['jpg', 'jpeg', 'png', 'webp'],
+		quality: 80,
+		format: 'webp',
+		sizes: [
+			{ width: 320, label: 'sm' },
+			{ width: 768, label: 'md' },
+			{ width: 1024, label: 'lg' },
+			{ width: 1920, label: 'xl' },
+		],
+	},
+});
+
+export default await new ConfigBuilder()
+	.setRootDir(import.meta.dir)
+	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
+	.setProcessors([imageProcessor])
+	.build();
+```
+
+### Configuration Options
+
+#### ImageProcessorConfig
+
+| Option            | Type                                    | Default                       | Description                           |
+| ----------------- | --------------------------------------- | ----------------------------- | ------------------------------------- |
+| `sourceDir`       | `string`                                | `'/src/public/assets/images'` | Source directory for images           |
+| `outputDir`       | `string`                                | `'/dist/assets/optimized'`    | Output directory for processed images |
+| `publicPath`      | `string`                                | `'/assets/optimized'`         | Public URL path for images            |
+| `sizes`           | `Array<{width: number, label: string}>` | `[]`                          | Image variants configuration          |
+| `quality`         | `number`                                | `80`                          | Output image quality (0-100)          |
+| `format`          | `'webp' \| 'jpeg' \| 'png' \| 'avif'`   | `'webp'`                      | Output image format                   |
+| `acceptedFormats` | `string[]`                              | `['jpg','jpeg','png','webp']` | Accepted input formats                |
+
+## Usage
+
+### Virtual Module System
+
+The `ecopages:images` virtual module provides a unified, type-safe way to handle images across your project:
+
+```typescript
+// All images from your source directory are available as named exports
+import { heroImage, profilePicture, blogThumbnail } from 'ecopages:images';
+
+// Names are automatically converted to camelCase
+// example:
+// src/images/hero-image.jpg -> heroImage
+// src/images/profile_picture.png -> profilePicture
+```
+
+No manual `dependencies.modules` declaration is required for `ecopages:images`; imports are automatically detected and included in the client bundle.
+
+#### Benefits:
+
+- **TypeScript Integration**: Full autocompletion support for image names
+- **Automatic Processing**: Images are processed at build time
+- **Tree Shaking**: Only imported images and their required metadata are included in the final bundle
+- **Type Safety**: Prevents imports of non-existent images
+- **Unified API**: Consistent way to handle images across your project
+
+### Importing Images
+
+Images are available through the virtual module `ecopages:images`:
+
+```typescript
+import { myImage } from 'ecopages:images';
+
+// myImage contains:
+// {
+//   attributes: {
+//     src: string,
+//     width: number,  // original image width
+//     height: number, // original image height
+//     sizes: string,
+//     srcset: string
+//   },
+//   variants: Array<{ width, height, src, label }>
+// }
+```
+
+### HTML Component
+
+```typescript
+import { EcoImage } from '@ecopages/image-processor/component/html';
+
+// Basic usage
+EcoImage({
+	...myImage,
+	width: 800,
+	height: 600,
+	alt: 'My image',
+});
+
+// Advanced usage
+EcoImage({
+	...myImage,
+	alt: 'My image',
+	layout: 'constrained',
+	priority: true,
+	aspectRatio: '16/9',
+	staticVariant: 'xl',
+});
+```
+
+### React Component
+
+```jsx
+import { EcoImage } from "@ecopages/image-processor/component/react";
+
+// Basic usage
+<EcoImage
+  {...myImage}
+  alt="My image"
+/>
+
+// Advanced usage
+<EcoImage
+  {...myImage}
+  alt="My image"
+  layout="constrained"
+  priority
+  aspectRatio="16/9"
+  staticVariant="xl"
+/>
+```
+
+### Component Props
+
+The component accepts all standard HTML/React image attributes (`src`, `alt`, `data-*`, `crossOrigin`, etc.) in addition to the following specific props:
+
+| Prop            | Type                                       | Default             | Description                                  |
+| --------------- | ------------------------------------------ | ------------------- | -------------------------------------------- |
+| `width`         | `number`                                   | From image metadata | Original width, can be overridden if needed  |
+| `height`        | `number`                                   | From image metadata | Original height, can be overridden if needed |
+| `priority`      | `boolean`                                  | `false`             | Prioritize loading                           |
+| `layout`        | `'fixed' \| 'constrained' \| 'full-width'` | `'constrained'`     | Layout behavior                              |
+| `staticVariant` | `string`                                   | -                   | Force specific size variant                  |
+| `aspectRatio`   | `string`                                   | From width/height   | Override the natural aspect ratio            |
+| `unstyled`      | `boolean`                                  | `false`             | Disable default styling                      |
+
+Note: Images imported through `ecopages:images` automatically include their width and height metadata, preventing layout shifts by default. These values can be overridden when needed, for example when using a different aspect ratio or specific layout requirements.
+
+## Layout Modes
+
+### Fixed Layout
+
+```typescript
+EcoImage({
+	...myImage,
+	layout: 'fixed',
+	width: 400,
+	height: 300,
+	alt: 'Fixed image',
+});
+```
+
+### Constrained Layout
+
+```typescript
+EcoImage({
+	...myImage,
+	layout: 'constrained',
+	width: 800,
+	alt: 'Constrained image',
+});
+```
+
+### Full-Width Layout
+
+```typescript
+EcoImage({
+	...myImage,
+	layout: 'full-width',
+	alt: 'Full-width image',
+});
+```
+
+## Best Practices
+
+1. Always provide `alt` text for accessibility
+2. Use `priority` for above-the-fold images
+3. Always specify both `width` and `height` to prevent layout shifts
+4. Use `aspectRatio` only when you need to force a different aspect ratio than width/height
+5. Choose appropriate `layout` modes based on your needs
+6. Utilize the virtual module for type-safe image imports
+7. Configure size variants that match your breakpoints

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@ecopages/image-processor",
+  "version": "0.2.0-alpha.1",
+  "description": "Image processor, transform and optimize images for web",
+  "keywords": [
+    "image",
+    "processor"
+  ],
+  "license": "MIT",
+  "main": "./src/image-processor.js",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ecopages/ecopages.git",
+    "directory": "packages/processors/image-processor"
+  },
+  "peerDependencies": {
+    "@ecopages/core": "0.2.0-alpha.1"
+  },
+  "dependencies": {
+    "@ecopages/file-system": "0.2.0-alpha.1",
+    "@ecopages/logger": "latest",
+    "react": "^19",
+    "react-dom": "^19",
+    "sharp": "^0.33.5"
+  },
+  "exports": {
+    ".": {
+      "default": "./src/index.js",
+      "types": "./src/index.d.ts"
+    },
+    "./types": {
+      "types": "./src/types.d.ts"
+    },
+    "./component/html": {
+      "default": "./src/component/html.js",
+      "types": "./src/component/html.d.ts"
+    },
+    "./component/react": {
+      "default": "./src/component/react.js",
+      "types": "./src/component/react.d.ts"
+    },
+    "./types.ts": {
+      "types": "./src/types.d.ts"
+    },
+    "./component/html.ts": {
+      "default": "./src/component/html.js",
+      "types": "./src/component/html.d.ts"
+    },
+    "./component/react.ts": {
+      "default": "./src/component/react.js",
+      "types": "./src/component/react.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "ecopages:images": [
+        "./virtual-module.d.ts"
+      ]
+    }
+  },
+  "types": "./src/index.d.ts"
+}

package/src/bun-plugins.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This file contains the plugins for bundling the image specifications.
+ * @module @ecopages/image-processor/bun-plugins
+ */
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type { ImageMap } from './plugin';
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules
+ * @param exports
+ * @returns
+ */
+export declare function createImagePlugin(exports: ImageMap): EcoBuildPlugin;
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * Due to some limitations in the bundler, we need to use a different approach.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules > bun-v1.2.5
+ * (This feature is currently only available at runtime with Bun.plugin and not yet supported in the bundler, but you can mimic the behavior using onResolve and onLoad.)
+ * @param exports
+ * @returns
+ */
+export declare function createImagePluginBundler(exports: ImageMap): EcoBuildPlugin;

package/src/bun-plugins.js

@@ -0,0 +1,33 @@
+import { anyCaseToCamelCase } from "./utils";
+function createPluginResult(exports) {
+  return {
+    contents: `${Object.entries(exports).map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`).join("\n")}`,
+    loader: "ts"
+  };
+}
+function createImagePlugin(exports) {
+  return {
+    name: "ecopages:images",
+    setup(build) {
+      build.module("ecopages:images", () => createPluginResult(exports));
+    }
+  };
+}
+function createImagePluginBundler(exports) {
+  return {
+    name: "ecopages:images",
+    setup(build) {
+      build.onResolve({ filter: /^ecopages:images$/ }, () => {
+        return {
+          namespace: "ecopages-images",
+          path: "ecopages:images"
+        };
+      });
+      build.onLoad({ filter: /.*/, namespace: "ecopages-images" }, () => createPluginResult(exports));
+    }
+  };
+}
+export {
+  createImagePlugin,
+  createImagePluginBundler
+};

package/src/bun-plugins.ts

@@ -0,0 +1,59 @@
+/**
+ * This file contains the plugins for bundling the image specifications.
+ * @module @ecopages/image-processor/bun-plugins
+ */
+
+import type { EcoBuildOnLoadResult, EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type { ImageMap } from './plugin';
+import { anyCaseToCamelCase } from './utils';
+
+/**
+ * This function creates the plugin result for the image specifications.
+ */
+function createPluginResult(exports: ImageMap): EcoBuildOnLoadResult {
+	return {
+		contents: `${Object.entries(exports)
+			.map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`)
+			.join('\n')}`,
+		loader: 'ts',
+	};
+}
+
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules
+ * @param exports
+ * @returns
+ */
+export function createImagePlugin(exports: ImageMap): EcoBuildPlugin {
+	return {
+		name: 'ecopages:images',
+		setup(build) {
+			build.module('ecopages:images', () => createPluginResult(exports));
+		},
+	};
+}
+
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * Due to some limitations in the bundler, we need to use a different approach.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules > bun-v1.2.5
+ * (This feature is currently only available at runtime with Bun.plugin and not yet supported in the bundler, but you can mimic the behavior using onResolve and onLoad.)
+ * @param exports
+ * @returns
+ */
+export function createImagePluginBundler(exports: ImageMap): EcoBuildPlugin {
+	return {
+		name: 'ecopages:images',
+		setup(build) {
+			build.onResolve({ filter: /^ecopages:images$/ }, () => {
+				return {
+					namespace: 'ecopages-images',
+					path: 'ecopages:images',
+				};
+			});
+
+			build.onLoad({ filter: /.*/, namespace: 'ecopages-images' }, () => createPluginResult(exports));
+		},
+	};
+}

package/src/component/html.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Image component that renders the image as a string.
+ * @module @ecopages/image-processor/component/html
+ */
+import { type EcoImageProps } from '../image-renderer';
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as a string
+ * @param props {@link EcoImageProps}
+ */
+export declare const EcoImage: (props: EcoImageProps) => string;

package/src/component/html.js

@@ -0,0 +1,7 @@
+import { renderer } from "../image-renderer";
+const EcoImage = (props) => {
+  return renderer.renderToString(props);
+};
+export {
+  EcoImage
+};

package/src/component/html.ts

@@ -0,0 +1,15 @@
+/**
+ * Image component that renders the image as a string.
+ * @module @ecopages/image-processor/component/html
+ */
+
+import { type EcoImageProps, renderer } from '../image-renderer';
+
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as a string
+ * @param props {@link EcoImageProps}
+ */
+export const EcoImage = (props: EcoImageProps): string => {
+	return renderer.renderToString(props);
+};

package/src/component/react.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Image component that renders the image as a string.
+ * @module @ecopages/image-processor/component/react
+ */
+import { type JSX } from 'react';
+import { type EcoImageProps } from '../image-renderer';
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as JSX
+ * @param props {@link EcoImageProps}
+ * @returns
+ */
+export declare const EcoImage: (props: EcoImageProps) => JSX.Element;

package/src/component/react.js

@@ -0,0 +1,11 @@
+import { createElement } from "react";
+import { renderer } from "../image-renderer";
+const EcoImage = (props) => {
+  return createElement("img", {
+    ...renderer.generateAttributesJsx(props),
+    suppressHydrationWarning: true
+  });
+};
+export {
+  EcoImage
+};

package/src/component/react.ts

@@ -0,0 +1,20 @@
+/**
+ * Image component that renders the image as a string.
+ * @module @ecopages/image-processor/component/react
+ */
+
+import { createElement, type JSX } from 'react';
+import { type EcoImageProps, renderer } from '../image-renderer';
+
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as JSX
+ * @param props {@link EcoImageProps}
+ * @returns
+ */
+export const EcoImage = (props: EcoImageProps): JSX.Element => {
+	return createElement('img', {
+		...renderer.generateAttributesJsx(props),
+		suppressHydrationWarning: true,
+	});
+};

package/src/constants.d.ts

@@ -0,0 +1,6 @@
+import type { ImageLayout } from './image-renderer';
+/**
+ * Default image layout
+ * @constant "constrained"
+ */
+export declare const DEFAULT_LAYOUT: ImageLayout;

package/src/constants.js

@@ -0,0 +1,4 @@
+const DEFAULT_LAYOUT = "constrained";
+export {
+  DEFAULT_LAYOUT
+};

package/src/constants.ts

@@ -0,0 +1,7 @@
+import type { ImageLayout } from './image-renderer';
+
+/**
+ * Default image layout
+ * @constant "constrained"
+ */
+export const DEFAULT_LAYOUT: ImageLayout = 'constrained';

package/src/image-plugins.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This file contains the plugins for bundling the image specifications.
+ * @module @ecopages/image-processor/image-plugins
+ */
+import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type { ImageMap } from './plugin';
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules
+ * @param exports
+ * @returns
+ */
+export declare function createImagePlugin(exports: ImageMap): EcoBuildPlugin;
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * Due to some limitations in the bundler, we need to use a different approach.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules > bun-v1.2.5
+ * (This feature is currently only available at runtime with Bun.plugin and not yet supported in the bundler, but you can mimic the behavior using onResolve and onLoad.)
+ * @param exports
+ * @returns
+ */
+export declare function createImagePluginBundler(exports: ImageMap): EcoBuildPlugin;

package/src/image-plugins.js

@@ -0,0 +1,33 @@
+import { anyCaseToCamelCase } from "./utils";
+function createPluginResult(exports) {
+  return {
+    contents: `${Object.entries(exports).map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`).join("\n")}`,
+    loader: "ts"
+  };
+}
+function createImagePlugin(exports) {
+  return {
+    name: "ecopages:images",
+    setup(build) {
+      build.module("ecopages:images", () => createPluginResult(exports));
+    }
+  };
+}
+function createImagePluginBundler(exports) {
+  return {
+    name: "ecopages:images",
+    setup(build) {
+      build.onResolve({ filter: /^ecopages:images$/ }, () => {
+        return {
+          namespace: "ecopages-images",
+          path: "ecopages:images"
+        };
+      });
+      build.onLoad({ filter: /.*/, namespace: "ecopages-images" }, () => createPluginResult(exports));
+    }
+  };
+}
+export {
+  createImagePlugin,
+  createImagePluginBundler
+};

package/src/image-plugins.ts

@@ -0,0 +1,59 @@
+/**
+ * This file contains the plugins for bundling the image specifications.
+ * @module @ecopages/image-processor/image-plugins
+ */
+
+import type { EcoBuildOnLoadResult, EcoBuildPlugin } from '@ecopages/core/build/build-types';
+import type { ImageMap } from './plugin';
+import { anyCaseToCamelCase } from './utils';
+
+/**
+ * This function creates the plugin result for the image specifications.
+ */
+function createPluginResult(exports: ImageMap): EcoBuildOnLoadResult {
+	return {
+		contents: `${Object.entries(exports)
+			.map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`)
+			.join('\n')}`,
+		loader: 'ts',
+	};
+}
+
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules
+ * @param exports
+ * @returns
+ */
+export function createImagePlugin(exports: ImageMap): EcoBuildPlugin {
+	return {
+		name: 'ecopages:images',
+		setup(build) {
+			build.module('ecopages:images', () => createPluginResult(exports));
+		},
+	};
+}
+
+/**
+ * This function creates a plugin for bundling the image specifications.
+ * Due to some limitations in the bundler, we need to use a different approach.
+ * https://bun.sh/docs/runtime/plugins#virtual-modules > bun-v1.2.5
+ * (This feature is currently only available at runtime with Bun.plugin and not yet supported in the bundler, but you can mimic the behavior using onResolve and onLoad.)
+ * @param exports
+ * @returns
+ */
+export function createImagePluginBundler(exports: ImageMap): EcoBuildPlugin {
+	return {
+		name: 'ecopages:images',
+		setup(build) {
+			build.onResolve({ filter: /^ecopages:images$/ }, () => {
+				return {
+					namespace: 'ecopages-images',
+					path: 'ecopages:images',
+				};
+			});
+
+			build.onLoad({ filter: /.*/, namespace: 'ecopages-images' }, () => createPluginResult(exports));
+		},
+	};
+}