CIT - Cloud Images Toolkit

A powerful developer workspace tool for managing image collections with CDN integration, Git-based collaboration, and automatic adaptive embed code generation.

npm GitHub

The Problem

Working with images on the web is deceptively complex. What starts as a simple <img src="cat.jpg"> quickly spirals into a cascade of requirements: resizing for responsive layouts, accounting for high-DPI screens, choosing optimal formats like WEBP and AVIF, setting up lazy loading, and generating proper srcset / sizes markup. CDN services can solve much of this, but they introduce their own friction — separate upload workflows, opaque IDs instead of filenames, limited organization, and vendor lock-in over your assets.

On top of that, collaborating with teammates on image collections through Git is impractical — binary files bloat repositories and lack meaningful diffs.

For a deeper dive into these challenges, read our article: Images on the Web — Not as Easy as It Seems.

How CIT Solves It

CIT bridges the gap between your local file system and the cloud. It watches a designated folder, automatically uploads images to the CDN, and stores all metadata in a local JSON file — perfect for Git tracking and team collaboration. No manual upload steps, no copy-pasting IDs, no losing track of your assets.

Automatic Sync

Point CIT at a local folder and it handles the rest. New and updated images are uploaded to the CDN automatically. The local directory structure is preserved in metadata, even if the cloud storage itself is flat.

Adaptive Embed Code

CIT generates production-ready HTML with srcset, sizes, loading="lazy", and decoding="async" — all tailored to your configured variants. No more hand-writing complex responsive image markup.

Git-Friendly Collaboration

Image metadata is stored as a structured JSON file in your repository. Your team can track changes, resolve conflicts, and review image updates through regular Git workflows — without storing heavy binaries in the repo.

Dashboard UI

CIT includes a built-in web application for managing your image collections. Start the server and open the dashboard to browse, upload, organize, and preview all of your assets.

CIT (Cloud Images Toolkit) dashboard screenshot

File Management

Browse and manage your images in a clean visual interface. CIT maps your local folder hierarchy to the flat cloud storage, so you can organize assets into logical groups:

CIT (Cloud Images Toolkit) image files view screenshot

CIT supports full folder structure even when your cloud storage doesn't — folders are maintained locally in metadata and reflected in the dashboard for intuitive, hierarchical browsing:

CIT (Cloud Images Toolkit) folder view screenshot

IMS Editor

CIT features a built-in visual editor for interactive media widgets. Create and configure galleries, panorama viewers, 360° spinners, and comparisons — then publish them alongside your images:

CIT (Cloud Images Toolkit) IMS Editor screenshot

Key Features

Local-to-CDN sync — automatic upload from a watched folder
Folder structure mapping — organize assets logically, even on flat storage
Adaptive embed code — generate responsive <img> markup with all the right attributes
Smart caching — download cloud images locally only when needed
Automatic sorting — ordered sequences for galleries and spinners
Data-in-image encoding — store widget data as images in the CDN for a unified asset pipeline
Built-in UI dashboard — visual management for files, folders, and widgets
Multi-CDN support — built-in connectors for Cloudflare Images, Cloudinary, ImageKit, and Bunny.net
Custom CDN endpoints — via flexible URL templates
IMS integration — create and edit interactive media widgets directly

Getting Started

CIT requires Node.js 20+ and supports multiple CDN providers out of the box.

Run without installing:

npx cloud-images-toolkit

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

Alternatively, install globally:

npm install -g cloud-images-toolkit

Create a cit-config.json in your project root:

{
  "name": "My Collection",
  "cdn": "cloudflare",
  "syncDataPath": "./cit-sync-data.json",
  "imsDataFolder": "./ims-widgets/",
  "imgSrcFolder": "./cit-store/",
  "apiKeyPath": "./CIT_API_KEY",
  "projectId": "<YOUR_PROJECT_ID>",
  "imgUrlTemplate": "https://<YOUR_DOMAIN>/images/{UID}/{VARIANT}",
  "variants": ["120", "320", "640", "860", "1024", "1200", "2048", "max"]
}

Start the toolkit:

cit

Then open the dashboard at http://localhost:8081. (Ports are auto-discovered if not specified, or can be configured via wsPort and httpPort).

Important: Add your image folder, config, and API key file to .gitignore.

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.

Coming Soon

Video publishing & video collections management
Advanced IMS editor with full scene composition
Built-in AI image generation with prompt editor
Image transformations: watermarks, filters, cropping, rotating
Tag-based grouping and filtering

Open Source

CIT is released under the MIT license. You are free to use, modify, and redistribute the code. Contributions, feedback, and stars on GitHub are always welcome.