@ecopages/image-processor 0.2.1 → 0.3.0

package/README.md

@@ -6,16 +6,18 @@ It provides automatic image processing (e.g. converting and compressing to WebP)
 
 ## Features
 
-- **Automatic Image Optimization**: Converts and compresses images to modern formats at build time.
+Build contributions use one `plugins(app)` method with server and browser environment declarations. Image processing, type generation and the cache restore run in `setup()`; `ecopages types` runs it. The virtual image module resolves through the implementation for the requested environment.
+
+- **Automatic Image Optimization**: Converts and compresses images to modern formats at build time. Each variant is named from a hash of its encoded bytes, so a quality or format change gets a new URL.
 - **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.
+- **Ecopages Components**: Ready-to-use HTML, Ecopages JSX, and React (`EcoImage`) components.
 - **Multiple Layout Options**: Fixed, constrained, and full-width layouts built-in.
 
 ## Installation
 
 ```bash
-bunx jsr add @ecopages/image-processor
+bun add @ecopages/image-processor
 ```
 
 ## Configuration
@@ -24,7 +26,7 @@ Import and register the processor in your `eco.config.ts`:
 
 ```typescript
 import path from 'node:path';
-import { ConfigBuilder } from '@ecopages/core/config-builder';
+import { defineConfig } from '@ecopages/core/config';
 import { ImageProcessorPlugin } from '@ecopages/image-processor';
 
 const imageProcessor = new ImageProcessorPlugin({
@@ -46,11 +48,7 @@ const imageProcessor = new ImageProcessorPlugin({
 	},
 });
 
-export default await new ConfigBuilder()
-	.setRootDir(import.meta.dirname)
-	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
-	.setProcessors([imageProcessor])
-	.build();
+export default defineConfig({ processors: [imageProcessor] });
 ```
 
 ## Usage
@@ -68,11 +66,22 @@ import { heroImage, profilePicture } from 'ecopages:images';
 > **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.
 
+## TypeScript Setup
+
+Add one import to the app `modules.d.ts`:
+
+```typescript
+import '@ecopages/image-processor/types';
+```
+
+That declares `ecopages:images`. Named exports are generated at dev/build time into
+`node_modules/@types/ecopages-image-processor`, which TypeScript loads automatically.
+
 ### Components
 
-The plugin provides ready-to-use components for HTML (`@kitajs/html`) and React:
+The plugin provides ready-to-use components for string HTML (KitaJS), Ecopages JSX, and React.
 
-**HTML Component:**
+**HTML Component** (returns a markup string; use as a function, or in string-based JSX runtimes like KitaJS):
 
 ```typescript
 import { EcoImage } from '@ecopages/image-processor/component/html';
@@ -85,6 +94,14 @@ EcoImage({
 });
 ```
 
+**Ecopages JSX Component:**
+
+```jsx
+import { EcoImage } from '@ecopages/image-processor/component/jsx';
+
+<EcoImage {...heroImage} alt="Hero banner" layout="constrained" priority />;
+```
+
 **React Component:**
 
 ```jsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/image-processor",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Image processor, transform and optimize images for web",
   "keywords": [
     "image",
@@ -9,20 +9,29 @@
   "license": "MIT",
   "main": "./src/image-processor.js",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ecopages/ecopages.git",
+    "url": "git+https://github.com/ecopages/ecopages.git",
     "directory": "packages/processors/image-processor"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.1"
+    "@ecopages/core": "0.3.0",
+    "@ecopages/jsx": "^0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@ecopages/jsx": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.1",
+    "@ecopages/file-system": "0.3.0",
     "@ecopages/logger": "^0.2.3",
-    "react": "^19",
-    "react-dom": "^19",
-    "sharp": "^0.34.5"
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "sharp": "^0.35.3"
   },
   "exports": {
     ".": {
@@ -30,34 +39,35 @@
       "types": "./src/index.d.ts"
     },
     "./types": {
-      "types": "./src/types.d.ts"
+      "types": "./src/image-types.d.ts"
     },
     "./component/html": {
       "default": "./src/component/html.js",
       "types": "./src/component/html.d.ts"
     },
+    "./component/jsx": {
+      "default": "./src/component/jsx.js",
+      "types": "./src/component/jsx.d.ts"
+    },
     "./component/react": {
       "default": "./src/component/react.js",
       "types": "./src/component/react.d.ts"
     },
     "./types.ts": {
-      "types": "./src/types.d.ts"
+      "types": "./src/image-types.d.ts"
     },
     "./component/html.ts": {
       "default": "./src/component/html.js",
       "types": "./src/component/html.d.ts"
     },
+    "./component/jsx.ts": {
+      "default": "./src/component/jsx.js",
+      "types": "./src/component/jsx.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/component/html.js

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

package/src/component/jsx.d.ts

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

package/src/component/jsx.js

@@ -0,0 +1,18 @@
+/**
+ * Image component that renders as an Ecopages JSX element.
+ * @module @ecopages/image-processor/component/jsx
+ */
+import { jsx } from '@ecopages/jsx';
+import { renderer } from '../image-renderer.js';
+/**
+ * EcoImage
+ * This component generates the image element based on the provided props as JSX
+ * @param props {@link EcoImageProps}
+ */
+export const EcoImage = (props) => {
+    const attributes = renderer.generateAttributes(props);
+    if (!attributes) {
+        return null;
+    }
+    return jsx('img', attributes);
+};

package/src/component/react.js

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

package/src/constants.js

@@ -1,4 +1,5 @@
-const DEFAULT_LAYOUT = "constrained";
-export {
-  DEFAULT_LAYOUT
-};
+/**
+ * Default image layout
+ * @constant "constrained"
+ */
+export const DEFAULT_LAYOUT = 'constrained';

package/src/image-plugins.d.ts

@@ -2,21 +2,13 @@
  * 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 { EcoBuildPlugin } from '@ecopages/core/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
- * @param exports
- * @returns
+ * Declares `ecopages:images` as a virtual module for server builds.
  */
 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
+ * Resolves `ecopages:images` with `onResolve` and `onLoad` for browser builds.
  */
 export declare function createImagePluginBundler(exports: ImageMap): EcoBuildPlugin;

package/src/image-plugins.js

@@ -1,33 +1,44 @@
-import { anyCaseToCamelCase } from "./utils.js";
+/**
+ * This file contains the plugins for bundling the image specifications.
+ * @module @ecopages/image-processor/image-plugins
+ */
+import { anyCaseToCamelCase } from './utils.js';
+/**
+ * This function creates the plugin result for the image specifications.
+ */
 function createPluginResult(exports) {
-  return {
-    contents: `${Object.entries(exports).map(([key, value]) => `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value)};`).join("\n")}`,
-    loader: "ts"
-  };
+    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));
-    }
-  };
+/**
+ * Declares `ecopages:images` as a virtual module for server builds.
+ */
+export 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));
-    }
-  };
+/**
+ * Resolves `ecopages:images` with `onResolve` and `onLoad` for browser builds.
+ */
+export 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-processor.d.ts

@@ -13,7 +13,13 @@ export declare class ImageProcessor {
         writeCache: <T>(key: string, data: T) => Promise<void>;
     });
     private calculateDimensions;
-    private getOutputPath;
+    /**
+     * @remarks
+     * Includes encoding options so a quality or format change cannot reuse a previous
+     * variant. File names come from a hash of the encoded bytes, not this key.
+     */
+    private encodingCacheKey;
+    private writeEncodedVariant;
     processImage(imagePath: string): Promise<ImageSpecifications | null>;
     processDirectory(): Promise<ImageMap>;
 }