How to install netlify-image-cdn
npx skills add https://github.com/netlify/context-and-tools --skill netlify-image-cdnFull instructions (SKILL.md)
Source of truth, from netlify/context-and-tools.
name: netlify-image-cdn description: Guide for using Netlify Image CDN for image optimization and transformation. Use when serving optimized images, creating responsive image markup, setting up user-uploaded image pipelines, or configuring image transformations. Covers the /.netlify/images endpoint, query parameters, remote image allowlisting, clean URL rewrites, and composing uploads with Functions + Blobs.
Netlify Image CDN
Every Netlify site has a built-in /.netlify/images endpoint for on-the-fly image transformation. No configuration required for local images.
Basic Usage
<img src="/.netlify/images?url=/photo.jpg&w=800&h=600&fit=cover&q=80" />
Query Parameters
| Param | Description | Values |
|---|---|---|
url | Source image path (required) | Relative path or absolute URL |
w | Width in pixels | Any positive integer |
h | Height in pixels | Any positive integer |
fit | Resize behavior | contain (default), cover, fill |
position | Crop alignment (with cover) | center (default), top, bottom, left, right |
fm | Output format | avif, webp, jpg, png, gif, blurhash |
q | Quality (lossy formats) | 1-100 (default: 75) |
When fm is omitted, Netlify auto-negotiates the best format based on browser support (preferring webp, then avif).
Remote Image Allowlisting
External images must be explicitly allowed in netlify.toml:
[images]
remote_images = ["https://example\\.com/.*", "https://cdn\\.images\\.com/.*"]
Values are regex patterns.
When referencing an allow-listed remote image, percent-encode the source URL before placing it in the url parameter:
<!-- source: https://cdn.example.com/marketing/banner.jpg -->
<img src="/.netlify/images?url=https%3A%2F%2Fcdn.example.com%2Fmarketing%2Fbanner.jpg&w=800&fm=webp&q=80" />
Percent-encode the source value (e.g. with encodeURIComponent) whenever it contains characters that would otherwise be read as Image CDN params — ?, &, =, #, or whitespace. This applies to remote URLs and relative paths alike (a filename or user-generated key can contain them too, e.g. url=/uploads/a%26b.jpg). Basic paths without those characters don't need encoding.
Clean URL Rewrites
Create user-friendly image URLs with redirects:
# Basic optimization
[[redirects]]
from = "/img/*"
to = "/.netlify/images?url=/:splat"
status = 200
# Preset: thumbnail
[[redirects]]
from = "/img/thumb/:key"
to = "/.netlify/images?url=/uploads/:key&w=150&h=150&fit=cover"
status = 200
# Preset: hero
[[redirects]]
from = "/img/hero/:key"
to = "/.netlify/images?url=/uploads/:key&w=1200&h=675&fit=cover"
status = 200
Caching
- Transformed images are cached at the CDN edge automatically
- Cache invalidates on new deploys
- Set cache headers on source images to control caching:
[[headers]]
for = "/uploads/*"
[headers.values]
Cache-Control = "public, max-age=31536000, immutable"
User-Uploaded Images
Combine Netlify Functions (upload handler) + Netlify Blobs (storage) + Image CDN (serving/transforming) to build a complete user-uploaded image pipeline. See references/user-uploads.md for the full pattern.
Related skills
More from netlify/context-and-tools and the wider catalog.
netlify-ai-gateway
Reference for Netlify AI Gateway — the managed proxy that routes calls to OpenAI, Anthropic, and Google Gemini SDKs without provider API keys. Use this skill any time the user wants to add AI on a Netlify site (chat, completion, reasoning, image generation, image-to-image edit/stylize), choose or change a model, wire up the OpenAI / Anthropic / @google/genai SDK, decide which provider to use for an image-gen feature (it's Gemini-only on the gateway), or debug "model not found" / "API key missing" against the gateway. Required reading before pinning a model — the gateway exposes a curated subset, not every provider model.
netlify-blobs
Guide for using Netlify Blobs for file and asset storage — images, documents, uploads, exports, cached binary artifacts. Covers getStore(), CRUD operations, metadata, listing, deploy-scoped vs site-scoped stores, and local development. Do NOT use Blobs as a dynamic data store — use Netlify Database for that.
netlify-caching
Guide for controlling caching on Netlify's CDN. Use when configuring cache headers, setting up stale-while-revalidate, implementing on-demand cache purge, or understanding Netlify's CDN caching behavior. Covers Cache-Control, Netlify-CDN-Cache-Control, cache tags, durable cache, and framework-specific caching patterns.
netlify-cli-and-deploy
Guide for using the Netlify CLI and deploying sites. Use when installing the CLI, linking sites, deploying (Git-based or manual), managing environment variables, or running local development. Covers netlify dev, netlify deploy, Git vs non-Git workflows, and environment variable management.
context7
Use when looking up library documentation, API references, framework patterns, or code examples for ANY library (React, Next.js, Vue, Django, Laravel, etc.). Fetches current docs via Context7 REST API. Triggers on: how to use library, API docs, framework pattern, import usage, library example.
android-testing
Comprehensive testing strategy involving Unit, Integration, Hilt, and Screenshot tests.