@ecopages/image-processor 0.2.0-rc.0 → 0.2.0-rc.10

package/README.md

@@ -68,6 +68,17 @@ 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 string HTML (KitaJS), Ecopages JSX, and React.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/image-processor",
-  "version": "0.2.0-rc.0",
+  "version": "0.2.0-rc.10",
   "description": "Image processor, transform and optimize images for web",
   "keywords": [
     "image",
@@ -9,14 +9,17 @@
   "license": "MIT",
   "main": "./src/image-processor.js",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ecopages/ecopages.git",
     "directory": "packages/processors/image-processor"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-rc.0",
-    "@ecopages/jsx": ">=0.3.0-rc.0"
+    "@ecopages/core": "0.2.0-rc.10",
+    "@ecopages/jsx": "^0.3.0-rc.9"
   },
   "peerDependenciesMeta": {
     "@ecopages/jsx": {
@@ -24,7 +27,7 @@
     }
   },
   "dependencies": {
-    "@ecopages/file-system": "0.2.0-rc.0",
+    "@ecopages/file-system": "0.2.0-rc.10",
     "@ecopages/logger": "^0.2.3",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
@@ -36,7 +39,7 @@
       "types": "./src/index.d.ts"
     },
     "./types": {
-      "types": "./src/types.d.ts"
+      "types": "./src/image-types.d.ts"
     },
     "./component/html": {
       "default": "./src/component/html.js",
@@ -51,7 +54,7 @@
       "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",
@@ -66,12 +69,5 @@
       "types": "./src/component/react.d.ts"
     }
   },
-  "typesVersions": {
-    "*": {
-      "ecopages:images": [
-        "./virtual-module.d.ts"
-      ]
-    }
-  },
   "types": "./src/index.d.ts"
-}
+}

package/src/image-types.d.ts

@@ -0,0 +1,3 @@
+export type { ImageAttributes, ImageSize, ImageSpecifications, ImageVariant } from './types.js';
+
+declare module 'ecopages:images' {}

package/src/plugin.d.ts

@@ -75,6 +75,16 @@ export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig
     private syncProcessedImagesFromDisk;
     private ensureGeneratedOutputs;
     private writeGeneratedFile;
+    /**
+     * Generates virtual-module declarations from source filenames before image
+     * processing runs.
+     *
+     * @remarks
+     * Editors need the ambient `ecopages:images` module during config build, but
+     * actual image optimization is deferred until {@link setup}. Declaring exports
+     * from the source directory preserves typed named imports on a clean checkout.
+     */
+    private generateSourceTypes;
     /**
      * Ensures optimized image outputs and virtual-module state exist on disk.
      */
@@ -93,6 +103,10 @@ export declare class ImageProcessorPlugin extends Processor<ImageProcessorConfig
      * Generate types for the virtual module.
      */
     private generateTypes;
+    /**
+     * Writes the ambient declaration package for `ecopages:images`.
+     */
+    private writeVirtualModuleTypes;
     /**
      * Teardown the image processor.
      */

package/src/plugin.js

@@ -4,7 +4,7 @@
  */
 import path from 'node:path';
 import { fileSystem } from '@ecopages/file-system';
-import { mergeProcessorOptions, Processor, resolveGeneratedPath, } from '@ecopages/core/plugins/processor';
+import { mergeProcessorOptions, Processor, resolveGeneratedPath, writeGeneratedTypesPackage, } from '@ecopages/core/plugins/processor';
 import { isLitStaticRenderWorkerThread } from '@ecopages/core/build/lit-static-render-worker-context';
 import { Logger } from '@ecopages/logger';
 import { createImagePlugin, createImagePluginBundler } from './image-plugins.js';
@@ -160,6 +160,7 @@ export class ImageProcessorPlugin extends Processor {
             return;
         }
         this.initializeProcessor();
+        await this.generateSourceTypes();
         await this.syncProcessedImagesFromDisk();
         this.buildContributionsPrepared = true;
     }
@@ -222,6 +223,22 @@ export class ImageProcessorPlugin extends Processor {
         }
         fileSystem.write(filePath, content);
     }
+    /**
+     * Generates virtual-module declarations from source filenames before image
+     * processing runs.
+     *
+     * @remarks
+     * Editors need the ambient `ecopages:images` module during config build, but
+     * actual image optimization is deferred until {@link setup}. Declaring exports
+     * from the source directory preserves typed named imports on a clean checkout.
+     */
+    async generateSourceTypes() {
+        if (!this.resolvedConfig) {
+            return;
+        }
+        const sourceImages = await getSourceImagePaths(this.resolvedConfig);
+        this.writeVirtualModuleTypes(sourceImages.map((imagePath) => path.basename(imagePath)));
+    }
     /**
      * Ensures optimized image outputs and virtual-module state exist on disk.
      */
@@ -299,9 +316,26 @@ export class ImageProcessorPlugin extends Processor {
      * Generate types for the virtual module.
      */
     generateTypes() {
-        if (!this.options?.outputDir) {
-            throw new Error('Output directory not set');
-        }
+        this.writeVirtualModuleTypes(Object.keys(this.processedImages));
+        if (!this.context)
+            throw new Error('Processor is not configured correctly');
+        const runtimeVirtualModulePath = resolveGeneratedPath('cache', {
+            root: this.context.distDir,
+            module: this.name,
+            subPath: 'virtual-module.ts',
+        });
+        const runtimeModuleContent = Object.entries(this.processedImages)
+            .map(([key, value]) => {
+            return `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value, null, 2)} as const;`;
+        })
+            .join('\n\n');
+        this.writeGeneratedFile(runtimeVirtualModulePath, runtimeModuleContent);
+        logger.debug('Generated runtime virtual module for images', { runtimeVirtualModulePath });
+    }
+    /**
+     * Writes the ambient declaration package for `ecopages:images`.
+     */
+    writeVirtualModuleTypes(imageKeys) {
         const content = `
 /**
  * Do not edit manually. This file is auto-generated.
@@ -311,9 +345,7 @@ export class ImageProcessorPlugin extends Processor {
 ${IMAGE_VIRTUAL_MODULE_TYPES}
 
 declare module "ecopages:images" {
-	${Object.keys(this.processedImages)
-            .map((key) => `export const ${anyCaseToCamelCase(key)}: ImageSpecifications;`)
-            .join('\n    ')}
+	${imageKeys.map((key) => `export const ${anyCaseToCamelCase(key)}: ImageSpecifications;`).join('\n    ')}
 }`;
         if (!this.context)
             throw new Error('Processor is not configured correctly');
@@ -329,21 +361,15 @@ declare module "ecopages:images" {
             module: this.name,
             subPath: 'index.d.ts',
         });
-        const indexContent = 'import "./virtual-module.d.js";';
+        const indexContent = 'import "./virtual-module.d.js";\n';
         this.writeGeneratedFile(indexTypesDir, indexContent);
         logger.debug('Generated index types for virtual module', { indexTypesDir });
-        const runtimeVirtualModulePath = resolveGeneratedPath('cache', {
-            root: this.context.distDir,
+        writeGeneratedTypesPackage({
+            root: this.context.rootDir,
             module: this.name,
-            subPath: 'virtual-module.ts',
+            packageName: '@types/ecopages-image-processor',
+            writeFile: (filePath, content) => this.writeGeneratedFile(filePath, content),
         });
-        const runtimeModuleContent = Object.entries(this.processedImages)
-            .map(([key, value]) => {
-            return `export const ${anyCaseToCamelCase(key)} = ${JSON.stringify(value, null, 2)} as const;`;
-        })
-            .join('\n\n');
-        this.writeGeneratedFile(runtimeVirtualModulePath, runtimeModuleContent);
-        logger.debug('Generated runtime virtual module for images', { runtimeVirtualModulePath });
     }
     /**
      * Teardown the image processor.