> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js Image CDN Loader

> Connect next/image to the Convertly Image CDN for automatic formats, responsive resizing, and global edge caching.

The Convertly loader keeps the standard `next/image` developer experience and rewrites compatible image URLs to the CDN in production.

```bash theme={"system"}
npm install @convertly-sh/image
```

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

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

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

export default nextConfig;
```

Create an origin source named `site` that points to your deployed app's public HTTPS URL. A normal image such as `<Image src="/hero.jpg" width={1200} height={800} alt="..." />` will then use Convertly in production.

## Local development

The public CDN cannot fetch `localhost`, private IP addresses, or private-network origins. Keep `localPassthrough` enabled during development so local assets render normally. Test optimized delivery on a public preview deployment or HTTPS tunnel.

<Warning>
  `NEXT_PUBLIC_CONVERTLY_CDN_NAMESPACE` is a CDN endpoint's public URL namespace. Never expose a `cvly_...` API key in browser code.
</Warning>