netlify-image-cdn

Q: How do I install netlify-image-cdn?

Run npx skills add https://github.com/netlify/context-and-tools --skill netlify-image-cdn in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/netlify-image-cdn/ (personal) or .claude/skills/netlify-image-cdn/ (project).

by netlifyMedia & Creative

Transforms images on demand via Netlify Image CDN's /.netlify/images endpoint with query parameters for resizing/cropping/format/quality. Use when adding image optimization or responsive images, converting formats (WebP/AVIF/PNG), generating thumbnails or blur placeholders, serving remote/third-party images through the CDN, allowlisting remote domains in netlify.toml, setting up image redirects or cache headers, building user-uploaded image pipelines, or debugging a 404 on /.netlify/images. Also covers framework image handling for Angular/Astro/Gatsby/Next.js/Nuxt.

Installs: 3.1K
Last 24h: +20
Trending rank: #5835
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/netlify/context-and-tools --skill netlify-image-cdn

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads netlify-image-cdn automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Netlify Image CDN

Transform images by requesting the endpoint with a url query parameter. This is the current and only documented surface — there is no legacy form.

GET /.netlify/images?url=<source>[&w=][&h=][&fit=][&position=][&fm=][&q=]

# resize a deployed image to 50px wide
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&w=50'

url is required; all other parameters are optional.

Query parameters

Parameter	Purpose	Values	Default
`url`	Source asset (required)	Relative path or remote URL	—
`w`	Width in pixels	Integer	—
`h`	Height in pixels	Integer	—
`fit`	Resize behavior	`contain`, `cover`, `fill`	`contain`
`position`	Crop anchor when `fit=cover`	`top`, `bottom`, `left`, `right`, `center`	`center`
`fm`	Output format	`avif`, `jpg`, `png`, `webp`, `gif`, `blurhash`	content-negotiated
`q`	Quality for lossy output	Integer `1`–`100`	`75`

Common transformations

# resize + crop to a 50px square, retaining the left side
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fit=cover&w=50&h=50&position=left'

# convert JPEG to PNG (response carries content-type: image/png)
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=png'

# convert JPEG to AVIF at medium quality
curl -vs 'https://mysitename.netlify.app/.netlify/images?url=/owl.jpeg&fm=avif&q=50'

fit behavior

contain (default): maintains aspect ratio; one dimension may come back smaller than requested. Supply one dimension and the other is computed.
cover: fills exactly, cropping excess. Requires BOTH w and h — omitting either is invalid. Use position to choose what's retained.
fill: fills exactly, stretching/squishing if aspect ratios differ.

Format notes

q applies only when output is avif, jpg, gif, or webp.
webp and gif can be static or animated.
If fm is omitted, format is content-negotiated from the Accept header: webp if accepted, else avif if accepted, else the original format. A source-only request (no other params) still converts to webp/avif but keeps size and shape.

Remote source images

Remote sources must be allowlisted in netlify.toml before transformation, or the request fails.

[images]
  remote_images = ['https://my-images\.com/.*', 'https://animals.more-images.com/[bcr]at/.*']

Percent-encode remote source URLs before placing them in the url parameter with encodeURIComponent — a URL containing ? or & breaks otherwise.

const src = `/.netlify/images?url=${encodeURIComponent('https://my-images.com/owl.jpeg?v=2')}&w=400`;

Constraints:

Remote sources must be publicly accessible.
Credential-bearing headers (Authorization, Cookie) are NOT forwarded when fetching a remote source. For authenticated sources, use URLs that carry their own authorization (e.g. S3 presigned URLs) and make sure your remote_images patterns match those full URLs.

remote_images regex escaping

The only meaningful escape is the literal dot (\.). Forward slashes are NOT metacharacters — never write https:\/\/. In netlify.toml, use single-quoted literal strings ('https://example\.com/.*') or double the backslash in double-quoted strings ("https://example\\.com/.*"). A bare \. inside double quotes is invalid TOML.

Response codes

Invalid transformation parameter values → 404.
Valid new transformation → 200 with content and matching content-type.
Previously transformed (cached) image → 304.

Reusing parameters across images

Map a friendly path to the endpoint with a redirect/rewrite.

_redirects:

/transform-small/* /.netlify/images?url=/:splat&w=50&h=50 200

netlify.toml:

[[redirects]]
  from = "/transform-small/*"
  to = "/.netlify/images?url=/:splat&w=50&h=50"
  status = 200

Then GET /transform-small/owl.jpeg returns the transformed image. Cross-site redirects for transformations are NOT recommended — they can degrade site performance.

Caching headers

Apply custom headers to source images on the site's own domain; they carry through to the transformed output.

netlify.toml:

[[headers]]
  for = "/source-images/*"
  [headers.values]
    Cache-Control = "public, max-age=604800, must-revalidate"

Custom headers can be applied to source images on the site's domain only — NOT to remote source images (Netlify does respect cache headers the external domain sends).
Cache-Control on source images applies only to browsers and CDNs in front of Netlify, NOT the Netlify Cache itself.

Blur placeholders (fm=blurhash)

fm=blurhash returns a BlurHash text string, not image bytes. Pointing an <img src> (or CSS background) at it renders nothing. Fetch the string ahead of time, decode it client-side with a BlurHash library (https://blurha.sh), and load the real image as a separate request without fm=blurhash.

Local development

The /.netlify/images endpoint, [images] allowlisting, and image redirects only exist under netlify dev (Netlify CLI). A local 404 on /.netlify/images almost always means a framework dev server (vite, next dev, astro dev) is running instead of netlify dev — the URL itself is usually fine. Start the local environment with netlify dev.

User-uploaded image pipelines

For pipelines composing Functions + Blobs + Image CDN (handling user-uploaded images), see references/user-uploads.md.

Framework image handling

Many frameworks route their built-in image optimization through Netlify Image CDN — use the framework's standard image component/syntax and only configure the remote allowlist. For unlisted frameworks, call /.netlify/images directly.

Framework	Prerequisites	Remote allowlist location
Angular	None; `NgOptimizedImage` uses it automatically	`[images] remote_images` in `netlify.toml`
Astro	None; `<Image />` uses it automatically	`image.domains` or `image.remotePatterns` in `astro.config.mjs`
Gatsby (both 5.13+ and 5.11 or earlier)	Set env `NETLIFY_IMAGE_CDN=true`; use Contentful/Drupal/WordPress source plugins	`[images] remote_images` in `netlify.toml`
Next.js	Next.js 13.5+ and Next.js adapter v5	`remotePatterns` in `next.config.js`
Nuxt	None; `nuxt/image` module uses it automatically	`image.domains` in `nuxt.config.ts`

Setup guides: Angular, Astro, Gatsby, Next.js, Nuxt.

Additional constraints

Deploy behavior: transforms respect atomic deploys; changing a source image in a new deploy re-runs transforms on subsequent requests.
Split Testing is NOT supported — image results may be inconsistent across split test branches.
Netlify Image CDN is NOT part of Netlify's HIPAA-compliant hosting offering.

Interactive parameter playground: https://image-cdn-playground.netlify.app/

Netlify house rules (image-cdn)

These are org conventions, not docs facts — merged into the rendered skill by ctx-gen and never generated. Owned by the skills maintainer.

For user-uploaded image pipelines (Functions + Blobs + Image CDN composed), see references/user-uploads.md in this skill — an authored guide with no single docs source.
Percent-encode remote source URLs before placing them in the url parameter (encodeURIComponent) — URLs containing ? or & break otherwise.
fm=blurhash returns a BlurHash TEXT string, not image bytes. Pointing an <img src> (or CSS background) at it renders nothing — fetch the string ahead of time, decode it client-side with a BlurHash library, and load the real image as a separate request without fm=blurhash.
A local 404 on /.netlify/images almost always means a framework dev server (vite, next dev, astro dev) is running instead of netlify dev — the endpoint, [images] allowlisting, and image redirects only exist under netlify dev. The URL itself is usually fine.
In remote_images patterns, the meaningful regex escape is the dot; forward slashes are not metacharacters — do not write https:\/\/. In netlify.toml, use a single-quoted literal string ('https://example\.com/.*') or double the backslash in a double-quoted string ("https://example\\.com/.*") — a bare \. inside double quotes is invalid TOML.

FAQ

What does the netlify-image-cdn skill do?

How do I install netlify-image-cdn?

Run npx skills add https://github.com/netlify/context-and-tools --skill netlify-image-cdn in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/netlify-image-cdn/ (personal) or .claude/skills/netlify-image-cdn/ (project).

Which AI agents can use netlify-image-cdn?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is netlify-image-cdn safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains netlify-image-cdn?

It is published by netlify in netlify/context-and-tools. It has 3,076 recorded installs.

More from netlify/context-and-tools

View all →

netlify-deploy

netlify/context-and-tools

Create, configure, and manage Netlify deploys from code — reach for this when setting up Git continuous deployment, running netlify deploy or netlify deploy --prod from the CLI, writing netlify.toml deploy contexts, adding a Deploy to Netlify button, wiring build hooks, configuring Deploy Previews or branch deploys, locking or skipping deploys, fixing a failed or secrets-scanning deploy, or when someone asks to "deploy my site", "set up preview deploys", "add per-branch build config", "keep staging out of Google", or "add a deploy button to my README".

DevOps & Cloud3.4K installs

netlify-config

netlify/context-and-tools

Configure Netlify builds and routing via netlify.toml, redirects, and headers. Use when setting a build command or publish directory, adding redirects or rewrites or proxies, adding an SPA fallback rewrite, setting custom response headers or basic auth, managing environment variables and secrets, scoping vars per deploy context, marking a var as secret, disabling secret scanning, configuring functions bundling, ignoring builds, or wiring up a monorepo or JavaScript SPA on Netlify.

DevOps & Cloud3.3K installs

netlify-functions

netlify/context-and-tools

Write, configure, and deploy Netlify serverless functions in TypeScript, JavaScript, or Go. Use this when adding an API endpoint or backend route, adding a contact form handler, wiring auth or Identity signup/login hooks, identifying which Netlify user is calling a private or team-login-protected app, building streaming or AI-proxy responses, scheduling cron jobs, running long background jobs (batch processing/scraping), reacting to deploy or form events, setting up rate limiting or region/memory config, or reading environment variables and secrets inside a function. Covers file locations, the Request/Context/Response handler shape, path routing, config options, and local testing with netlify dev.

DevOps & Cloud3.3K installs

netlify-frameworks

netlify/context-and-tools

Deploy and configure web frameworks on Netlify — build settings and SSR/edge adapters plus local platform emulation and env vars. Use when setting up or fixing a framework deploy (Next.js / Astro / Nuxt / SvelteKit / Remix / React Router / TanStack Start / SolidStart / Gatsby / Angular / Vite / Express / Hydrogen / Hugo / Eleventy / Vue / React), adding SSR or edge functions or middleware wired to Netlify context, fixing SPA redirect and catch-all rules, setting a build command or publish directory, or debugging "why isn't my env var updating" and framework build failures.

DevOps & Cloud3.2K installs

netlify-edge-functions

netlify/context-and-tools

Write, route, cache, and debug Netlify Edge Functions, the Deno-based TypeScript or JavaScript handlers in netlify/edge-functions that run at the network edge in front of static files and serverless functions. Activate this skill whenever someone wants to add auth middleware or a login gate, redirect or rewrite visitors by country or cookie, localize or personalize a page with geolocation, run A/B testing, transform or inject HTML into a response, stream server-side rendering at the edge, or cache an edge response. Also use it when an edge function silently does nothing, runs in the wrong order, ignores its Cache-Control headers, or cannot read an environment variable.

DevOps & Cloud3.1K installs

netlify-forms

netlify/context-and-tools

Serverless form handling on Netlify-hosted sites — detects HTML forms at deploy time, stores submissions, filters spam, and sends notifications. Use when adding a contact form, lead-capture form, file-upload form, or newsletter signup to a Netlify site; wiring AJAX form submission; setting up a custom thank-you page; adding a honeypot or reCAPTCHA to a form; getting forms working in Next.js, Nuxt, SvelteKit, Astro, or Gatsby; reading form submissions via the Netlify API; setting up submission notifications or ChatGPT automations on form submission events; or debugging missing submissions and forms that silently fail to register.

DevOps & Cloud3.1K installs

Popular media & creative skills

View category →

hyperframes

heygen-com/hyperframes

Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.

Media & Creative1.2M installs

media-use

heygen-com/hyperframes

Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.

Media & Creative1.1M installs

hyperframes-registry

heygen-com/hyperframes

About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.

Media & Creative1M installs

hyperframes-creative

heygen-com/hyperframes

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use hyperframes-animation.

Media & Creative916.5K installs

ai-video-generation

101-skills/superpowers

Generate AI videos with Google Veo, Seedance 2.0, HappyHorse, Wan, Grok and 40+ models via inference.sh CLI. Models: Veo 3.1, Veo 3, Seedance 2.0, HappyHorse 1.0, Wan 2.5, Grok Imagine Video, OmniHuman, Fabric, HunyuanVideo. Capabilities: text-to-video, image-to-video, reference-to-video, video editing, lipsync, avatar animation, video upscaling, foley sound. Use for: social media videos, marketing content, explainer videos, product demos, AI avatars. Triggers: video generation, ai video, text to video, image to video, veo, animate image, video from image, ai animation, video generator, generate video, t2v, i2v, ai video maker, create video with ai, runway alternative, pika alternative, sora alternative, kling alternative, seedance, happyhorse

Media & Creative881.5K installs

ai-image-generation

101-skills/superpowers

Generate AI images with GPT-Image-2, FLUX, Gemini, Grok, Seedream, Reve and 50+ models via inference.sh CLI. Models: GPT-Image-2, FLUX Dev LoRA, FLUX.2 Klein LoRA, Gemini 3 Pro Image, Grok Imagine, Seedream 4.5, Reve, ImagineArt. Capabilities: text-to-image, image-to-image, inpainting, LoRA, image editing, upscaling, text rendering. Use for: AI art, product mockups, concept art, social media graphics, marketing visuals, illustrations. Triggers: flux, image generation, ai image, text to image, stable diffusion, generate image, ai art, midjourney alternative, dall-e alternative, text2img, t2i, image generator, ai picture, create image with ai, generative ai, ai illustration, grok image, gemini image, gpt image, openai image, chatgpt image

Media & Creative880.3K installs

netlify-image-cdn

Install

Install

Describe the task

Review the result

SKILL.md

Netlify Image CDN

Query parameters

Common transformations

fit behavior

Format notes

Remote source images

remote_images regex escaping

Response codes

Reusing parameters across images

Caching headers

Blur placeholders (fm=blurhash)

Local development

User-uploaded image pipelines

Framework image handling

Additional constraints

Netlify house rules (image-cdn)

FAQ

More from netlify/context-and-tools

Popular media & creative skills