@convertly-sh/image

Official client SDK for the Convertly image & video CDN. Turns Convertly Storage files or configured HTTPS origin assets into responsive, format-negotiated images and on-the-fly video transforms with one configuration step.

npm install @convertly-sh/image

• Framework-agnostic URL builder (createConvertlyCdn)
• React components (<ConvertlyImage>, <ConvertlyVideo>) with provider
• Next.js loaders (createConvertlyLoader, createConvertlyVideoLoader)
• Vue, Solid, and Svelte adapters
• TypeScript-first, tree-shakeable, zero runtime dependencies

Source on npm

The published package includes compiled dist/ output, README.md, and LICENSE — browse them on npm under Package → Code (no GitHub access required). The main Convertly app repo is private; MIT applies to this published SDK so others can use and build on it.

Before you install

The SDK builds CDN URLs. It does not upload files, scan your repo, or transform images by itself. For a URL to return an optimized image, Convertly must know where to fetch the source from.

| Your images live… | What you must configure first | SDK src example | | --- | --- | --- | | Deployed site public/ folder (Next.js, etc.) | Origin source in the dashboard — slug site, base URL https://your-production-domain.com | origin="site" + src="/hero.jpg" or Next.js loader with origin: "site" | | Public S3/R2/GCS bucket or asset CDN | Origin source for that HTTPS host | cdn.origin("products", "hero.jpg", { w: 1200 }) | | Convertly Storage (uploaded file UUID) | Upload file + delivery key only | src="11111111-1111-1111-1111-111111111111" |

Installing the SDK alone is not enough for repo public/ images. Without an origin source, Convertly has nowhere to fetch /hero.jpg from and CDN requests will fail or never run transforms.

Checklist (framework sites with public/ assets)

1. Delivery key — create in Settings → Image CDN → Delivery keys (cvly_pub_…, safe for NEXT_PUBLIC_*).
2. Origin source — Settings → Image CDN → Sources → add slug site (or your choice) pointing at your deployed HTTPS URL, e.g. https://example.com.
3. Deploy — the origin must serve the file publicly (https://example.com/hero.jpg returns 200).
4. SDK / loader — wire origin: "site" (Next.js) or origin="site" (React) so paths rewrite to /o/site/… CDN URLs.
5. Local dev — use localPassthrough in Next.js; Convertly cannot fetch localhost. Test real CDN URLs against a preview deploy or HTTPS tunnel.

Full walkthrough: Image CDN setup guide.

Storage vs origin (vs open URL fetch)

• Convertly Storage — upload once, use file UUID in URLs. Good for media library, WordPress sync, user uploads.
• Origin sources — images stay on your site or bucket; Convertly fetches on demand. Good for public/ folders and existing asset hosts.
• Not supported: pasting any random third-party URL per request (unlike some competitors' open fetch mode). Each external host must be registered as an origin source in your workspace first.

The SDK rewrites URLs; it does not sync or upload repo files to Convertly Storage.

Quick start

React

import { ConvertlyCdnProvider, ConvertlyImage } from "@convertly-sh/image/react";

function App() {
  return (
    <ConvertlyCdnProvider deliveryKey={process.env.NEXT_PUBLIC_CONVERTLY_DELIVERY_KEY!}>
      <ConvertlyImage
        src="11111111-1111-1111-1111-111111111111"
        width={1200}
        height={800}
        alt="Hero image"
        sizes="(min-width: 768px) 50vw, 100vw"
      />
    </ConvertlyCdnProvider>
  );
}

That single <ConvertlyImage> produces an <img> with:

• A src URL pointing at the Convertly CDN at the right width
• A srcSet with responsive widths (400w, 800w, 1200w, 1600w, 2400w)
• format=auto so modern browsers get AVIF/WebP and old browsers get JPEG
• gravity=auto smart cropping
• loading="lazy" and decoding="async" by default

Next.js

Wire Convertly as the loader for next/image so every existing <Image> in your app benefits without changing markup:

// lib/convertly-loader.ts
import { createConvertlyLoader } from "@convertly-sh/image/nextjs";

export default createConvertlyLoader({
  deliveryKey: process.env.NEXT_PUBLIC_CONVERTLY_DELIVERY_KEY!,
  origin: "site",
  localPassthrough: process.env.NODE_ENV === "development",
});

// next.config.ts
const nextConfig = {
  images: {
    loader: "custom",
    loaderFile: "./lib/convertly-loader.ts",
  },
};
export default nextConfig;

Create site as an origin source that points at your deployed app's public HTTPS URL. In production, every public-folder image that resolves from that deployed app, such as <Image src="/hero.jpg" />, is rewritten to an origin-backed Convertly CDN URL with smart cropping and format negotiation. The SDK does not upload or sync files from your local project folder. During next dev, localPassthrough returns /hero.jpg directly so your local app renders without asking Convertly's public CDN to fetch localhost. To test real CDN optimization before production, point origin at a public preview deployment or an HTTPS tunnel.

Plain HTML / Astro / Vue / Solid

Use the URL builder directly:

import { createConvertlyCdn } from "@convertly-sh/image";

const cdn = createConvertlyCdn({
  deliveryKey: "cvly_pub_…",
});

const heroUrl = cdn.url("fileId", { w: 1200, h: 800, fit: "cover" });
const heroSrcset = cdn.srcset("fileId", { widths: [400, 800, 1200, 1600] });

API

createConvertlyCdn(config)

| Option | Type | Default | | --- | --- | --- | | deliveryKey | string (required) | — | | baseUrl | string | "https://cdn.convertly.sh" |

Returns an object with CDN URL helpers:

| Method | Signature | Use | | --- | --- | --- | | cdn.url(fileId, params?) | (fileId, ConvertlyTransform) => string | Build a single image URL. | | cdn.srcset(fileId, params?) | (fileId, ConvertlyTransform & { widths? }) => string | Build an srcset value. | | cdn.video(fileId, params?) | (fileId, ConvertlyVideoTransform) => string | Transcode or clip a stored video. | | cdn.poster(fileId, params?) | (fileId, ConvertlyPosterTransform) => string | Extract a poster frame (image output). | | cdn.gif(fileId, params?) | (fileId, ConvertlyVideoTransform) => string | Render an animated GIF clip. | | cdn.preset(fileId, name, overrides?) | (fileId, presetName, overrides?) => string | Path-style preset URL. | | cdn.origin(slug, path, params?) | origin-backed image URL | |

Trim transparent borders

Pass trim={true} (or trim: true in cdn.url()) to crop fully transparent pixels — useful for logos exported with extra padding:

<ConvertlyImage src={logoId} width={200} trim alt="Acme logo" />

Format negotiation

format=auto (the default) negotiates AVIF / WebP / JPEG via the browser Accept header. See Image CDN docs for pricing and quotas.

License

MIT © Convertly.

• Read the full license: npm → Code → LICENSE
• License summary: MIT on Open Source Initiative

You may use, modify, and redistribute this SDK under the MIT terms. The Convertly hosted product remains a separate commercial service.