@ecopages/image-processor 0.2.0-alpha.5 → 0.2.0-alpha.50

package/README.md

@@ -1,35 +1,38 @@
 # @ecopages/image-processor
 
-A powerful and flexible image processing library designed to optimize and manage responsive images in ecopages applications.
+Image processing pipeline for responsive, optimized images in Ecopages.
+
+It provides automatic image processing (e.g. converting and compressing to WebP) and virtual module integration, allowing you to import your optimized images safely and directly via `ecopages:images`.
 
 ## 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
+- **Automatic Image Optimization**: Converts and compresses images to modern formats at build time.
+- **Responsive Image Generation**: Creates multiple variants for different screen sizes.
+- **Virtual Module Integration**: Type-safe imports through `ecopages:images`.
+- **Ecopages Components**: Ready-to-use HTML (`EcoImage`) and React (`EcoImage`) components.
+- **Multiple Layout Options**: Fixed, constrained, and full-width layouts built-in.
 
 ## Installation
 
 ```bash
-npm install @ecopages/image-processor
+bun add @ecopages/image-processor
 ```
 
 ## Configuration
 
+Import and register the processor in your `eco.config.ts`:
+
 ```typescript
 import path from 'node:path';
-import { ConfigBuilder } from '@ecopages/core';
+import { ConfigBuilder } from '@ecopages/core/config-builder';
 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'),
+		sourceDir: path.resolve(import.meta.dirname, 'src/images'),
+		outputDir: path.resolve(import.meta.dirname, 'dist/images'),
 		publicPath: '/images',
 		acceptedFormats: ['jpg', 'jpeg', 'png', 'webp'],
 		quality: 80,
@@ -44,175 +47,62 @@ const imageProcessor = new ImageProcessorPlugin({
 });
 
 export default await new ConfigBuilder()
-	.setRootDir(import.meta.dir)
+	.setRootDir(import.meta.dirname)
 	.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:
+The `ecopages:images` virtual module provides a type-safe way to import processed images:
 
 ```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
+// Imports from your source directory are resolved automatically and camelCased
+import { heroImage, profilePicture } from 'ecopages:images';
 ```
 
-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
+> [!TIP]
+> **No manual dependencies required.**
+> Ecopages automatically detects these virtual module imports and processes them during the build, enabling effective tree-shaking for only the required images.
 
-### Importing Images
+### Components
 
-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 }>
-// }
-```
+The plugin provides ready-to-use components for HTML (`@kitajs/html`) and React:
 
-### HTML Component
+**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',
+	...heroImage,
 	layout: 'constrained',
+	alt: 'Hero banner',
 	priority: true,
-	aspectRatio: '16/9',
-	staticVariant: 'xl',
 });
 ```
 
-### React Component
+**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.
+import { EcoImage } from '@ecopages/image-processor/component/react';
 
-## Layout Modes
-
-### Fixed Layout
-
-```typescript
-EcoImage({
-	...myImage,
-	layout: 'fixed',
-	width: 400,
-	height: 300,
-	alt: 'Fixed image',
-});
+<EcoImage {...heroImage} alt="Hero banner" layout="constrained" priority />;
 ```
 
-### 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
+### Component Props
 
-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
+The components accept standard HTML/React attributes plus these specifics:
+
+| Prop            | Type                                       | Default         |
+| :-------------- | :----------------------------------------- | :-------------- |
+| `layout`        | `'fixed' \| 'constrained' \| 'full-width'` | `'constrained'` |
+| `priority`      | `boolean`                                  | `false`         |
+| `width`         | `number`                                   | From metadata   |
+| `height`        | `number`                                   | From metadata   |
+| `aspectRatio`   | `string`                                   | Natural ratio   |
+| `staticVariant` | `string`                                   | -               |
+| `unstyled`      | `boolean`                                  | `false`         |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/image-processor",
-  "version": "0.2.0-alpha.5",
+  "version": "0.2.0-alpha.50",
   "description": "Image processor, transform and optimize images for web",
   "keywords": [
     "image",
@@ -15,14 +15,14 @@
     "directory": "packages/processors/image-processor"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.5"
+    "@ecopages/core": "0.2.0-alpha.50"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.5",
-    "@ecopages/logger": "latest",
-    "react": "^19",
-    "react-dom": "^19",
-    "sharp": "^0.33.5"
+    "@ecopages/file-system": "0.2.0-alpha.50",
+    "@ecopages/logger": "^0.2.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "sharp": "^0.34.5"
   },
   "exports": {
     ".": {

package/src/bun-plugins.d.ts

@@ -2,8 +2,8 @@
  * 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';
+import type { EcoBuildPlugin } from '@ecopages/core/plugins/processor';
+import type { ImageMap } from './plugin.js';
 /**
  * This function creates a plugin for bundling the image specifications.
  * https://bun.sh/docs/runtime/plugins#virtual-modules

package/src/bun-plugins.js

@@ -1,4 +1,4 @@
-import { anyCaseToCamelCase } from "./utils";
+import { anyCaseToCamelCase } from "./utils.js";
 function createPluginResult(exports) {
   return {
     contents: `${Object.entries(exports).map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`).join("\n")}`,

package/src/component/html.d.ts

@@ -2,7 +2,7 @@
  * Image component that renders the image as a string.
  * @module @ecopages/image-processor/component/html
  */
-import { type EcoImageProps } from '../image-renderer';
+import { type EcoImageProps } from '../image-renderer.js';
 /**
  * EcoImage
  * This component generates the image element based on the provided props as a string

package/src/component/html.js

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

package/src/component/react.d.ts

@@ -3,7 +3,7 @@
  * @module @ecopages/image-processor/component/react
  */
 import { type JSX } from 'react';
-import { type EcoImageProps } from '../image-renderer';
+import { type EcoImageProps } from '../image-renderer.js';
 /**
  * EcoImage
  * This component generates the image element based on the provided props as JSX

package/src/component/react.js

@@ -1,5 +1,5 @@
 import { createElement } from "react";
-import { renderer } from "../image-renderer";
+import { renderer } from "../image-renderer.js";
 const EcoImage = (props) => {
   return createElement("img", {
     ...renderer.generateAttributesJsx(props),

package/src/constants.d.ts

@@ -1,4 +1,4 @@
-import type { ImageLayout } from './image-renderer';
+import type { ImageLayout } from './image-renderer.js';
 /**
  * Default image layout
  * @constant "constrained"

package/src/image-plugins.d.ts

@@ -2,8 +2,8 @@
  * 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';
+import type { EcoBuildPlugin } from '@ecopages/core/plugins/processor';
+import type { ImageMap } from './plugin.js';
 /**
  * This function creates a plugin for bundling the image specifications.
  * https://bun.sh/docs/runtime/plugins#virtual-modules

package/src/image-plugins.js

@@ -1,4 +1,4 @@
-import { anyCaseToCamelCase } from "./utils";
+import { anyCaseToCamelCase } from "./utils.js";
 function createPluginResult(exports) {
   return {
     contents: `${Object.entries(exports).map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`).join("\n")}`,

package/src/image-processor.d.ts

@@ -1,5 +1,5 @@
-import type { ImageMap, ImageProcessorConfig } from './plugin';
-import type { ImageSpecifications } from './types';
+import type { ImageMap, ImageProcessorConfig } from './plugin.js';
+import type { ImageSpecifications } from './types.js';
 /**
  * ImageProcessor
  * This is the core class for processing images.

package/src/image-processor.js

@@ -1,9 +1,9 @@
 import path from "node:path";
-import { deepMerge } from "@ecopages/core/utils/deep-merge";
+import { mergeProcessorOptions } from "@ecopages/core/plugins/processor";
 import { fileSystem } from "@ecopages/file-system";
 import { Logger } from "@ecopages/logger";
 import sharp from "sharp";
-import { ImageUtils } from "./image-utils";
+import { ImageUtils } from "./image-utils.js";
 const appLogger = new Logger("[@ecopages/image-processor]", {
   debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
 });
@@ -11,7 +11,7 @@ class ImageProcessor {
   config;
   cacheManager;
   constructor(config, cacheManager) {
-    this.config = deepMerge({ cacheEnabled: true }, config);
+    this.config = mergeProcessorOptions({ cacheEnabled: true }, config);
     this.cacheManager = cacheManager;
     fileSystem.ensureDir(this.config.outputDir);
   }

package/src/image-renderer.d.ts

@@ -2,7 +2,7 @@
  * ImageRenderer
  * @module
  */
-import type { ImageSpecifications } from './types';
+import type { ImageSpecifications } from './types.js';
 /**
  * Image layout options
  */

package/src/image-renderer.js

@@ -1,5 +1,5 @@
-import { DEFAULT_LAYOUT } from "./constants";
-import { ImageUtils } from "./image-utils";
+import { DEFAULT_LAYOUT } from "./constants.js";
+import { ImageUtils } from "./image-utils.js";
 class LayoutAttributesManager {
   static shouldIncludeWidthHeight(layout) {
     return layout === "fixed";

package/src/image-utils.d.ts

@@ -1,4 +1,4 @@
-import type { EcoImageProps } from './image-renderer';
+import type { EcoImageProps } from './image-renderer.js';
 /**
  * ImageUtils
  * This class contains utility methods for working with images
@@ -7,7 +7,7 @@ import type { EcoImageProps } from './image-renderer';
 export declare class ImageUtils {
     private static readonly BREAKPOINTS;
     private static readonly VIEWPORT_SIZES;
-    static readonly DEFAULT_LAYOUT: import("./image-renderer").ImageLayout;
+    static readonly DEFAULT_LAYOUT: import("./image-renderer.js").ImageLayout;
     /**
      * Generates a srcset string from processed image variants using relative paths
      * @param {ImageVariant[]} variants - Array of processed image variants

package/src/image-utils.js

@@ -1,4 +1,4 @@
-import { DEFAULT_LAYOUT } from "./constants";
+import { DEFAULT_LAYOUT } from "./constants.js";
 class ImageUtils {
   static BREAKPOINTS = {
     desktop: 1024,

package/src/index.d.ts

@@ -1,3 +1,3 @@
-export * from './image-processor';
-export * from './plugin';
-export * from './types';
+export * from './image-processor.js';
+export * from './plugin.js';
+export * from './types.js';

package/src/index.js

@@ -1,3 +1,3 @@
-export * from "./image-processor";
-export * from "./plugin";
-export * from "./types";
+export * from "./image-processor.js";
+export * from "./plugin.js";
+export * from "./types.js";

package/src/plugin.d.ts

@@ -2,10 +2,9 @@
  * ImageProcessorPlugin
  * @module @ecopages/image-processor
  */
-import { Processor, type ProcessorConfig } from '@ecopages/core/plugins/processor';
-import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import { ImageProcessor } from './image-processor';
-import type { ImageSize, ImageSpecifications } from './types';
+import { Processor, type EcoBuildPlugin, type ProcessorConfig } from '@ecopages/core/plugins/processor';
+import { ImageProcessor } from './image-processor.js';
+import type { ImageSize, ImageSpecifications } from './types.js';
 /**
  * Configuration for the image processor
  */
@@ -40,10 +39,29 @@ export type ImageMap = Record<string, ImageSpecifications>;
  */
 export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig> {
     private processor;
+    private buildContributionsPrepared;
+    private resolvedConfig?;
     processedImages: Record<string, ImageSpecifications>;
     constructor(config: Omit<ProcessorConfig<ImageProcessorConfig>, 'name' | 'description'>);
     get buildPlugins(): EcoBuildPlugin[];
     get plugins(): EcoBuildPlugin[];
+    /**
+     * Replaces image-map contents without swapping the backing object.
+     *
+     * @remarks
+     * The build/runtime virtual-module plugins close over `processedImages`, so
+     * mutating the existing object keeps those plugins live after preparation.
+     */
+    private replaceProcessedImages;
+    /**
+     * Prepares the image virtual-module state before config build seals the app
+     * manifest.
+     */
+    prepareBuildContributions(): Promise<void>;
+    private getRuntimeVirtualModulePath;
+    private getGeneratedOutputPath;
+    private hasGeneratedOutputs;
+    private rehydrateGeneratedOutputs;
     /**
      * Generate dependencies for processor.
      * It is ossible to define which one should be included in the final bundle based on the environment.
@@ -51,7 +69,7 @@ export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig
      */
     private generateDependencies;
     /**
-     * Setup the image processor and create the virtual module.
+     * Prepares build contributions if not already done and rehydrates previously generated image outputs.
      */
     setup(): Promise<void>;
     /**