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

package/CHANGELOG.md

@@ -8,16 +8,15 @@ All notable changes to `@ecopages/image-processor` are documented here.
 
 ### 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.
+- Added `image-plugins.ts` with shared image plugin creation so the processor can target multiple build adapters.
+- Added `bun-plugins.ts` with Bun-specific build adapter helpers aligned with the shared image plugin layer.
 
-### Refactoring
+### Bug Fixes
 
-- `plugin.ts` updated to use the new `image-plugins.ts` abstraction.
-- `image-processor.ts` minor updates.
-- README updated with usage clarification.
+- Switched public internal imports to explicit relative ESM specifiers so Node thin-host builds can externalize the package without `ERR_MODULE_NOT_FOUND`.
+- Inlined the generated `ecopages:images` declaration source so bundled runtime bootstrap no longer depends on a sibling `types` module at runtime.
+- Re-emitted generated image outputs after static export cleanup so routes that reference `/images/...` keep their optimized files inside `dist`.
 
 ### Tests
 
-- `image-renderer.test.ts` expanded (68 lines added).
-- `image-processor.test.ts` and `image-utils.test.ts` updated.
+- Added image processor and renderer coverage for the current build pipeline.

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
+bunx jsr 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.7",
   "description": "Image processor, transform and optimize images for web",
   "keywords": [
     "image",
@@ -15,10 +15,10 @@
     "directory": "packages/processors/image-processor"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.5"
+    "@ecopages/core": "0.2.0-alpha.7"
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-alpha.5",
+    "@ecopages/file-system": "0.2.0-alpha.7",
     "@ecopages/logger": "latest",
     "react": "^19",
     "react-dom": "^19",

package/src/bun-plugins.d.ts

@@ -3,7 +3,7 @@
  * @module @ecopages/image-processor/bun-plugins
  */
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { ImageMap } from './plugin';
+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/bun-plugins.ts

@@ -4,8 +4,8 @@
  */
 
 import type { EcoBuildOnLoadResult, EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { ImageMap } from './plugin';
-import { anyCaseToCamelCase } from './utils';
+import type { ImageMap } from './plugin.ts';
+import { anyCaseToCamelCase } from './utils.ts';
 
 /**
  * This function creates the plugin result for the image specifications.

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/html.ts

@@ -3,7 +3,7 @@
  * @module @ecopages/image-processor/component/html
  */
 
-import { type EcoImageProps, renderer } from '../image-renderer';
+import { type EcoImageProps, renderer } from '../image-renderer.ts';
 
 /**
  * EcoImage

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/component/react.ts

@@ -4,7 +4,7 @@
  */
 
 import { createElement, type JSX } from 'react';
-import { type EcoImageProps, renderer } from '../image-renderer';
+import { type EcoImageProps, renderer } from '../image-renderer.ts';
 
 /**
  * EcoImage

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/constants.ts

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

package/src/image-plugins.d.ts

@@ -3,7 +3,7 @@
  * @module @ecopages/image-processor/image-plugins
  */
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { ImageMap } from './plugin';
+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-plugins.ts

@@ -4,8 +4,8 @@
  */
 
 import type { EcoBuildOnLoadResult, EcoBuildPlugin } from '@ecopages/core/build/build-types';
-import type { ImageMap } from './plugin';
-import { anyCaseToCamelCase } from './utils';
+import type { ImageMap } from './plugin.ts';
+import { anyCaseToCamelCase } from './utils.ts';
 
 /**
  * This function creates the plugin result for the image specifications.

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

@@ -3,7 +3,7 @@ import { deepMerge } from "@ecopages/core/utils/deep-merge";
 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"
 });

package/src/image-processor.ts

@@ -3,9 +3,9 @@ import { deepMerge } from '@ecopages/core/utils/deep-merge';
 import { fileSystem } from '@ecopages/file-system';
 import { Logger } from '@ecopages/logger';
 import sharp from 'sharp';
-import { ImageUtils } from './image-utils';
-import type { ImageMap, ImageProcessorConfig } from './plugin';
-import type { ImageAttributes, ImageSpecifications, ImageVariant } from './types';
+import { ImageUtils } from './image-utils.ts';
+import type { ImageMap, ImageProcessorConfig } from './plugin.ts';
+import type { ImageAttributes, ImageSpecifications, ImageVariant } from './types.ts';
 
 const appLogger = new Logger('[@ecopages/image-processor]', {
 	debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true',

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-renderer.ts

@@ -3,9 +3,9 @@
  * @module
  */
 
-import { DEFAULT_LAYOUT } from './constants';
-import { ImageUtils } from './image-utils';
-import type { ImageSpecifications, ImageVariant } from './types';
+import { DEFAULT_LAYOUT } from './constants.ts';
+import { ImageUtils } from './image-utils.ts';
+import type { ImageSpecifications, ImageVariant } from './types.ts';
 
 /**
  * Image layout options

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/image-utils.ts

@@ -1,5 +1,5 @@
-import { DEFAULT_LAYOUT } from './constants';
-import type { EcoImageProps } from './image-renderer';
+import { DEFAULT_LAYOUT } from './constants.ts';
+import type { EcoImageProps } from './image-renderer.ts';
 
 /**
  * ImageUtils

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/index.ts

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

package/src/plugin.d.ts

@@ -4,8 +4,8 @@
  */
 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 { ImageProcessor } from './image-processor.js';
+import type { ImageSize, ImageSpecifications } from './types.js';
 /**
  * Configuration for the image processor
  */
@@ -40,10 +40,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 +70,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>;
     /**

package/src/plugin.js

@@ -1,13 +1,12 @@
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { deepMerge } from "@ecopages/core/utils/deep-merge";
 import { GENERATED_BASE_PATHS } from "@ecopages/core/constants";
 import { fileSystem } from "@ecopages/file-system";
 import { Processor } from "@ecopages/core/plugins/processor";
 import { Logger } from "@ecopages/logger";
-import { createImagePlugin, createImagePluginBundler } from "./image-plugins";
-import { ImageProcessor } from "./image-processor";
-import { anyCaseToCamelCase } from "./utils";
+import { createImagePlugin, createImagePluginBundler } from "./image-plugins.js";
+import { ImageProcessor } from "./image-processor.js";
+import { anyCaseToCamelCase } from "./utils.js";
 function resolveGeneratedPath(type, options) {
   const { root, module, subPath } = options;
   const parts = [root, GENERATED_BASE_PATHS[type], module, subPath].filter(Boolean);
@@ -16,8 +15,54 @@ function resolveGeneratedPath(type, options) {
 const logger = new Logger("[@ecopages/image-processor]", {
   debug: process.env.ECOPAGES_LOGGER_DEBUG === "true"
 });
-const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const IMAGE_VIRTUAL_MODULE_TYPES = `/**
+ * ImageAttributes
+ * These are the core attributes for the image element generated by the image processor
+ */
+interface ImageAttributes {
+	src: string;
+	width: number;
+	height: number;
+	sizes: string;
+	srcset?: string;
+}
+
+/**
+ * This represents a single image variant created using the size configuration
+ */
+interface ImageVariant {
+	width: number;
+	height: number;
+	src: string;
+	label: string;
+}
+
+/**
+ * These are the core attributes for the image element and the image variants
+ * This is the representation of the image element in the virtual module
+ */
+interface ImageSpecifications {
+	attributes: ImageAttributes;
+	variants: ImageVariant[];
+	/**
+	 * A unique key used to cache the image specifications.
+	 * This key should uniquely identify the combination of attributes and variants
+	 * to ensure proper caching behavior.
+	 */
+	cacheKey: string;
+}
+
+/**
+ * This is the representation of an image breakpoint
+ * This is used to generate the srcset attribute
+ */
+type ImageSize = {
+	width: number;
+	label: string;
+};`;
 class ImageProcessorPlugin extends Processor {
+  buildContributionsPrepared = false;
+  resolvedConfig;
   processedImages = {};
   constructor(config) {
     const acceptedFormats = config.options?.acceptedFormats ?? ["jpg", "jpeg", "png", "webp"];
@@ -50,20 +95,26 @@ class ImageProcessorPlugin extends Processor {
     return [createImagePlugin(this.processedImages)];
   }
   /**
-   * Generate dependencies for processor.
-   * It is ossible to define which one should be included in the final bundle based on the environment.
-   * @returns
+   * 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.
    */
-  generateDependencies() {
-    const deps = [];
-    if (process.env.NODE_ENV === "development") {
+  replaceProcessedImages(images) {
+    for (const key of Object.keys(this.processedImages)) {
+      delete this.processedImages[key];
     }
-    return deps;
+    Object.assign(this.processedImages, images);
   }
   /**
-   * Setup the image processor and create the virtual module.
+   * Prepares the image virtual-module state before config build seals the app
+   * manifest.
    */
-  async setup() {
+  async prepareBuildContributions() {
+    if (this.buildContributionsPrepared) {
+      return;
+    }
     if (!this.context) {
       throw new Error("ImageProcessor requires context to be set");
     }
@@ -80,16 +131,75 @@ class ImageProcessorPlugin extends Processor {
       format: "webp"
     };
     const config = this.options ? deepMerge(defaultConfig, this.options) : defaultConfig;
+    this.resolvedConfig = config;
     this.processor = new ImageProcessor(config, {
       readCache: (key) => this.readCache(key),
       writeCache: (key, data) => this.writeCache(key, data)
     });
-    this.processedImages = await this.processor.processDirectory();
+    this.replaceProcessedImages(await this.processor.processDirectory());
     if (this.watchConfig) {
       this.watchConfig.paths = [config.sourceDir];
     }
     this.dependencies = this.generateDependencies();
     this.generateTypes();
+    this.buildContributionsPrepared = true;
+  }
+  getRuntimeVirtualModulePath() {
+    if (!this.context) {
+      throw new Error("ImageProcessor requires context to be set");
+    }
+    return resolveGeneratedPath("cache", {
+      root: this.context.distDir,
+      module: this.name,
+      subPath: "virtual-module.ts"
+    });
+  }
+  getGeneratedOutputPath(src) {
+    if (!this.resolvedConfig) {
+      throw new Error("ImageProcessor not initialized");
+    }
+    return path.join(this.resolvedConfig.outputDir, path.basename(src));
+  }
+  hasGeneratedOutputs() {
+    if (!this.resolvedConfig) {
+      return false;
+    }
+    if (!fileSystem.exists(this.resolvedConfig.outputDir) || !fileSystem.exists(this.getRuntimeVirtualModulePath())) {
+      return false;
+    }
+    return Object.values(this.processedImages).every((image) => {
+      const outputPaths = [image.attributes.src, ...image.variants.map((variant) => variant.src)];
+      return outputPaths.every((src) => fileSystem.exists(this.getGeneratedOutputPath(src)));
+    });
+  }
+  async rehydrateGeneratedOutputs() {
+    if (!this.processor) {
+      throw new Error("ImageProcessor not initialized");
+    }
+    if (this.hasGeneratedOutputs()) {
+      return;
+    }
+    this.replaceProcessedImages(await this.processor.processDirectory());
+    this.dependencies = this.generateDependencies();
+    this.generateTypes();
+  }
+  /**
+   * Generate dependencies for processor.
+   * It is ossible to define which one should be included in the final bundle based on the environment.
+   * @returns
+   */
+  generateDependencies() {
+    const deps = [];
+    if (process.env.NODE_ENV === "development") {
+    }
+    return deps;
+  }
+  /**
+   * Prepares build contributions if not already done and rehydrates previously generated image outputs.
+   */
+  async setup() {
+    await this.prepareBuildContributions();
+    await this.rehydrateGeneratedOutputs();
   }
   /**
    * Process images.
@@ -159,14 +269,13 @@ class ImageProcessorPlugin extends Processor {
     if (!this.options?.outputDir) {
       throw new Error("Output directory not set");
     }
-    const requiredTypes = fileSystem.readFileSync(path.join(currentDir, "types.ts")).toString().replaceAll("export ", "");
     const content = `
 /**
  * Do not edit manually. This file is auto-generated.
  * This file contains the type definitions for the virtual module "ecopages:images".
  */
 
-${requiredTypes}
+${IMAGE_VIRTUAL_MODULE_TYPES}
 
 declare module "ecopages:images" {
 	${Object.keys(this.processedImages).map((key) => `export const ${anyCaseToCamelCase(key)}: ImageSpecifications;`).join("\n    ")}

package/src/plugin.ts

@@ -4,7 +4,6 @@
  */
 
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { deepMerge } from '@ecopages/core/utils/deep-merge';
 import { GENERATED_BASE_PATHS } from '@ecopages/core/constants';
 import { fileSystem } from '@ecopages/file-system';
@@ -12,10 +11,10 @@ import { Processor, type ProcessorConfig, type ProcessorWatchConfig } from '@eco
 import type { EcoBuildPlugin } from '@ecopages/core/build/build-types';
 import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
 import { Logger } from '@ecopages/logger';
-import { createImagePlugin, createImagePluginBundler } from './image-plugins';
-import { ImageProcessor } from './image-processor';
-import type { ImageSize, ImageSpecifications } from './types';
-import { anyCaseToCamelCase } from './utils';
+import { createImagePlugin, createImagePluginBundler } from './image-plugins.ts';
+import { ImageProcessor } from './image-processor.ts';
+import type { ImageSize, ImageSpecifications } from './types.ts';
+import { anyCaseToCamelCase } from './utils.ts';
 
 function resolveGeneratedPath(
 	type: keyof typeof GENERATED_BASE_PATHS,
@@ -30,7 +29,51 @@ const logger = new Logger('[@ecopages/image-processor]', {
 	debug: process.env.ECOPAGES_LOGGER_DEBUG === 'true',
 });
 
-const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const IMAGE_VIRTUAL_MODULE_TYPES = `/**
+ * ImageAttributes
+ * These are the core attributes for the image element generated by the image processor
+ */
+interface ImageAttributes {
+	src: string;
+	width: number;
+	height: number;
+	sizes: string;
+	srcset?: string;
+}
+
+/**
+ * This represents a single image variant created using the size configuration
+ */
+interface ImageVariant {
+	width: number;
+	height: number;
+	src: string;
+	label: string;
+}
+
+/**
+ * These are the core attributes for the image element and the image variants
+ * This is the representation of the image element in the virtual module
+ */
+interface ImageSpecifications {
+	attributes: ImageAttributes;
+	variants: ImageVariant[];
+	/**
+	 * A unique key used to cache the image specifications.
+	 * This key should uniquely identify the combination of attributes and variants
+	 * to ensure proper caching behavior.
+	 */
+	cacheKey: string;
+}
+
+/**
+ * This is the representation of an image breakpoint
+ * This is used to generate the srcset attribute
+ */
+type ImageSize = {
+	width: number;
+	label: string;
+};`;
 
 /**
  * Configuration for the image processor
@@ -68,6 +111,8 @@ export type ImageMap = Record<string, ImageSpecifications>;
  */
 export class ImageProcessorPlugin extends Processor<ImageProcessorConfig> {
 	declare private processor: ImageProcessor;
+	private buildContributionsPrepared = false;
+	private resolvedConfig?: ImageProcessorConfig;
 	public processedImages: Record<string, ImageSpecifications> = {};
 
 	constructor(config: Omit<ProcessorConfig<ImageProcessorConfig>, 'name' | 'description'>) {
@@ -106,35 +151,29 @@ export class ImageProcessorPlugin extends Processor<ImageProcessorConfig> {
 	}
 
 	/**
-	 * Generate dependencies for processor.
-	 * It is ossible to define which one should be included in the final bundle based on the environment.
-	 * @returns
+	 * 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 generateDependencies(): AssetDefinition[] {
-		const deps: AssetDefinition[] = [];
-
-		if (process.env.NODE_ENV === 'development') {
-			/**
-			 * Here we can define the dependencies for the development environment
-			 * @example
-			 * deps.push(
-			 *   AssetFactory.createInlineScriptAsset({
-			 *     content: `document.addEventListener("DOMContentLoaded",() => console.log("[@ecopages/image-processor] Processor is loaded"));`,
-			 *     attributes: {
-			 *       type: 'module',
-			 *     },
-			 *   }),
-			 * );
-			 */
+	private replaceProcessedImages(images: ImageMap): void {
+		for (const key of Object.keys(this.processedImages)) {
+			delete this.processedImages[key];
 		}
 
-		return deps;
+		Object.assign(this.processedImages, images);
 	}
 
 	/**
-	 * Setup the image processor and create the virtual module.
+	 * Prepares the image virtual-module state before config build seals the app
+	 * manifest.
 	 */
-	async setup(): Promise<void> {
+	override async prepareBuildContributions(): Promise<void> {
+		if (this.buildContributionsPrepared) {
+			return;
+		}
+
 		if (!this.context) {
 			throw new Error('ImageProcessor requires context to be set');
 		}
@@ -154,23 +193,110 @@ export class ImageProcessorPlugin extends Processor<ImageProcessorConfig> {
 		};
 
 		const config = this.options ? deepMerge(defaultConfig, this.options) : defaultConfig;
+		this.resolvedConfig = config;
 
 		this.processor = new ImageProcessor(config, {
 			readCache: (key) => this.readCache(key),
 			writeCache: (key, data) => this.writeCache(key, data),
 		});
 
-		this.processedImages = await this.processor.processDirectory();
+		this.replaceProcessedImages(await this.processor.processDirectory());
 
 		if (this.watchConfig) {
 			this.watchConfig.paths = [config.sourceDir];
 		}
 
 		this.dependencies = this.generateDependencies();
+		this.generateTypes();
+		this.buildContributionsPrepared = true;
+	}
+
+	private getRuntimeVirtualModulePath(): string {
+		if (!this.context) {
+			throw new Error('ImageProcessor requires context to be set');
+		}
+
+		return resolveGeneratedPath('cache', {
+			root: this.context.distDir,
+			module: this.name,
+			subPath: 'virtual-module.ts',
+		});
+	}
 
+	private getGeneratedOutputPath(src: string): string {
+		if (!this.resolvedConfig) {
+			throw new Error('ImageProcessor not initialized');
+		}
+
+		return path.join(this.resolvedConfig.outputDir, path.basename(src));
+	}
+
+	private hasGeneratedOutputs(): boolean {
+		if (!this.resolvedConfig) {
+			return false;
+		}
+
+		if (
+			!fileSystem.exists(this.resolvedConfig.outputDir) ||
+			!fileSystem.exists(this.getRuntimeVirtualModulePath())
+		) {
+			return false;
+		}
+
+		return Object.values(this.processedImages).every((image) => {
+			const outputPaths = [image.attributes.src, ...image.variants.map((variant) => variant.src)];
+			return outputPaths.every((src) => fileSystem.exists(this.getGeneratedOutputPath(src)));
+		});
+	}
+
+	private async rehydrateGeneratedOutputs(): Promise<void> {
+		if (!this.processor) {
+			throw new Error('ImageProcessor not initialized');
+		}
+
+		if (this.hasGeneratedOutputs()) {
+			return;
+		}
+
+		this.replaceProcessedImages(await this.processor.processDirectory());
+		this.dependencies = this.generateDependencies();
 		this.generateTypes();
 	}
 
+	/**
+	 * Generate dependencies for processor.
+	 * It is ossible to define which one should be included in the final bundle based on the environment.
+	 * @returns
+	 */
+	private generateDependencies(): AssetDefinition[] {
+		const deps: AssetDefinition[] = [];
+
+		if (process.env.NODE_ENV === 'development') {
+			/**
+			 * Here we can define the dependencies for the development environment
+			 * @example
+			 * deps.push(
+			 *   AssetFactory.createInlineScriptAsset({
+			 *     content: `document.addEventListener("DOMContentLoaded",() => console.log("[@ecopages/image-processor] Processor is loaded"));`,
+			 *     attributes: {
+			 *       type: 'module',
+			 *     },
+			 *   }),
+			 * );
+			 */
+		}
+
+		return deps;
+	}
+
+	/**
+	 * Prepares build contributions if not already done and rehydrates previously generated image outputs.
+	 */
+	async setup(): Promise<void> {
+		await this.prepareBuildContributions();
+		await this.rehydrateGeneratedOutputs();
+	}
+
 	/**
 	 * Process images.
 	 * @param images
@@ -254,18 +380,13 @@ export class ImageProcessorPlugin extends Processor<ImageProcessorConfig> {
 			throw new Error('Output directory not set');
 		}
 
-		const requiredTypes = fileSystem
-			.readFileSync(path.join(currentDir, 'types.ts'))
-			.toString()
-			.replaceAll('export ', '');
-
 		const content = `
 /**
  * Do not edit manually. This file is auto-generated.
  * This file contains the type definitions for the virtual module "ecopages:images".
  */
 
-${requiredTypes}
+${IMAGE_VIRTUAL_MODULE_TYPES}
 
 declare module "ecopages:images" {
 	${Object.keys(this.processedImages)