A powerful toolkit for managing image collections directly in your codebase, with CDN integration and advanced features.
- Automatic synchronization between local images and CDN
- Git-based image collection data tracking and collaboration
- Flat structured cloud data to local folders mapping
- Automatic image sorting for ordered sequences
- Adaptive image embed code generation
- Smart local caching - download cloud images only when needed
- Built-in image management UI application with drag-and-drop uploads
- Interactive widget generation using Immersive Media Spots (IMS):
- Image galleries
- Panorama viewers
- 360° object views
- And more...
- Multi-CDN support with built-in connectors:
- Custom CDN endpoints via URL templates
- Data-to-image encoding for the uniform asset control workflow (store your widgets data directly in image CDN)
- Video publishing & video collections view
- Advanced IMS-based hypermedia composer
- Built-in AI image generation support and prompt editor
- Image modifications and transformations:
- Watermarks
- Filters
- Cropping
- Rotating
- Additional tag-based grouping and filtering
- Node.js 20.0.0+
- npm 10.0.0+
Run without installing:
npx cloud-images-toolkitIf no config file is found, CIT will offer to create one from the reference template.
npm install -g cloud-images-toolkitThen run from any project directory:
citnpm install cloud-images-toolkitAdd a script to your package.json:
"scripts": {
"cit": "node ./node_modules/cloud-images-toolkit/src/node/serve.js"
}Then:
npm run citCreate a cit-config.json file in your project root. A reference template is included in the package as cit-config_REFERENCE.json:
{
"name": "My Collection",
"cdn": "cloudflare",
"syncDataPath": "./cit-sync-data.json",
"imsDataFolder": "./ims-widgets/",
"imsDataMinify": true,
"imgSrcFolder": "./cit-store/",
"apiKeyPath": "./CIT_API_KEY",
"projectId": "<YOUR_PROJECT_ID>",
"imgUrlTemplate": "https://<YOUR_DOMAIN>/images/{UID}/{VARIANT}",
"previewUrlTemplate": "https://<YOUR_DOMAIN>/images/{UID}/{VARIANT}",
"imsUrlTemplate": "https://<YOUR_DOMAIN>/ims/{HASH}.json",
"variants": ["120", "320", "640", "860", "1024", "1200", "2048", "max"],
"imgTypes": ["png", "jpg", "jpeg", "webp", "gif", "svg"],
"wsPort": 8080,
"httpPort": 8081
}CIT supports managing multiple collections simultaneously. Instead of a single object, you can configure cit-config.json as an array of collection objects. Each collection will operate independently with its own CDN settings, keys, and paths. A reference for this format can be found in cit-config_MULTI_REFERENCE.json.
When the cdn field is set, CIT uses a built-in connector that auto-fills upload, fetch, and remove URL templates with provider-specific defaults. You can still override any template manually.
To use custom URLs for your images, you need to enable this feature and configure it in your service provider dashboard.
Important: Add your image folder and API key file to
.gitignore:cit-store/ CIT_API_KEY cit-config.json
CIT uses specific macros in URL templates to dynamically construct paths. These macros are automatically replaced with runtime values:
{UID}— The unique identifier of the image (typically the CDN ID).{VARIANT}— The specific variant string requested (e.g.,320,public).{PROJECT}— Your configuredprojectId(e.g., Cloudflare Account ID, Cloudinary Cloud Name).{HASH}— The MD5 hash used in theimsUrlTemplateto identify an Interactive Media Spot (IMS) descriptor file.
CIT includes built-in connectors for popular image CDN providers. Set the cdn field in your config to activate a connector.
{ "cdn": "cloudflare", "projectId": "<ACCOUNT_ID>" }API key file (CIT_API_KEY): your Cloudflare Images API Bearer token.
Variants: must be pre-created in your Cloudflare Images dashboard. Use custom domains for custom image URLs.
{ "cdn": "cloudinary" }API key file (CIT_API_KEY): three values separated by colons:
cloud_name:api_key:api_secret
The projectId is auto-extracted from the cloud name. Variants map to Cloudinary's URL-based width transformations (e.g. variant 320 → w_320,c_fit,f_auto,q_auto).
{ "cdn": "imagekit" }API key file (CIT_API_KEY): two values separated by a colon:
private_key:url_endpoint
Example: your_private_key:https://ik.imagekit.io/your_id
Variants map to ImageKit's URL-based transformations (e.g. variant 320 → tr:w-320).
{ "cdn": "bunny" }API key file (CIT_API_KEY): three values separated by colons:
storage_password:storage_zone:pull_zone_url
Example: your-password:my-zone:https://my-zone.b-cdn.net
Variants map to Bunny Optimizer query parameters (e.g. variant 320 → ?width=320). Make sure Bunny Optimizer is enabled on your pull zone.
Omit the cdn field and provide all URL templates manually. CIT will use Bearer auth with the raw API key:
{
"projectId": "<YOUR_PROJECT_ID>",
"imgUrlTemplate": "https://...",
"uploadUrlTemplate": "https://...",
"fetchUrlTemplate": "https://...",
"removeUrlTemplate": "https://..."
}Variants are very important part of the CIT workflow. They are necessary for the adaptive image embed code generation and image size control. CIT uses the convention of the variant names to generate the image URLs, based on the image width.
For example, if you have a variant named 120, CIT will generate the URL for the image with the width of 120px.
It's a good practice to create variants for the screens with different DPI. For example, you can create a variant for the image with the width of 120 and the DPI of 1.0, and another variant for the image with the width of 240 and the DPI of 2.0.
For Cloudflare Images, variants must be pre-created in the Cloudflare dashboard. For Cloudinary, ImageKit, and Bunny.net, variants are applied dynamically via URL-based transformations.
CIT looks for cit-config.json in the current working directory. Make sure you're running the command from your project root. When run without a config, CIT will offer to create one from the reference template.
Ensure your API key file path in cit-config.json points to a valid file. The file format depends on your CDN connector — see the CDN Connectors section for details.
If manually pre-configured ports (like 8080 or 8081) are already in use by other applications, update wsPort and httpPort in your config file to use different ports. Alternatively, you can omit these properties from your configuration, and CIT will automatically discover and bind to available network ports.
CIT automatically retries failed uploads up to 3 times. Check your API key and network connection if uploads consistently fail.
MIT License © rnd-pro.com