CIT - Cloud Images Toolkit

A powerful toolkit for managing image collections directly in your codebase, with CDN integration and advanced features.

CIT Dashboard screenshot

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)

Coming soon

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

Requirements

Node.js 20.0.0+
npm 10.0.0+

Quick Start

Run without installing:

npx cloud-images-toolkit

If no config file is found, CIT will offer to create one from the reference template.

Installation

Global installation

npm install -g cloud-images-toolkit

Then run from any project directory:

cit

Local installation

npm install cloud-images-toolkit

Add a script to your package.json:

"scripts": {
  "cit": "node ./node_modules/cloud-images-toolkit/src/node/serve.js"
}

Then:

npm run cit

Configuration

Create 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
}

Multi-Collection Support

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

URL Template Syntax

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 configured projectId (e.g., Cloudflare Account ID, Cloudinary Cloud Name).
{HASH} — The MD5 hash used in the imsUrlTemplate to identify an Interactive Media Spot (IMS) descriptor file.

CDN Connectors

CIT includes built-in connectors for popular image CDN providers. Set the cdn field in your config to activate a connector.

Cloudflare Images

{ "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.

Cloudinary

{ "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).

ImageKit

{ "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).

Bunny.net

{ "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.

Custom / No Connector

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

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.

Troubleshooting

Config not found

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.

API key errors

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.

Port conflicts

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.

Upload failures

CIT automatically retries failed uploads up to 3 times. Check your API key and network connection if uploads consistently fail.