Image optimization

With image optimization on, large source images are resized to fit the visitor's screen and converted to lighter formats such as WebP before they are sent. Results are cached, so later requests are served quickly.

Next.js needs no setupCopy Anchor Link

The default Next.js image loader (next/image) is wired up automatically. Tune image options in next.config as usual, and do not add an images block to nitroship.json.

Other frameworks and static sitesCopy Anchor Link

Add images to nitroship.json at the deployment root.

{
  "images": {
    "protocol": "astro",
    "domains": ["images.example.com"],
    "remotePatterns": [
      {"protocol": "https", "hostname": "cdn.example.com", "pathname": "/**"}
    ]
  }
}

protocol: which URL format to use (required)Copy Anchor Link

Pick the format matching the image URLs your framework generates.

Set path to use a different path.

Which source images are allowedCopy Anchor Link

• Remote images must be allowed explicitly. List hostnames in domains, or use remotePatterns to pin down protocol, host, and path.
• Images from your own site are all allowed by default. Narrow this with localPatterns; an empty array ([]) denies them all.
• Requests for a disallowed source or an unsupported transformation return 400.

SecurityCopy Anchor Link

• SVG is off by default. SVGs can contain scripts, so enable dangerouslyAllowSVG only for sources you trust.
• dangerouslyAllowLocalIP, which would allow sources on private IPs, is not supported. Even if set, images from private networks stay blocked.

CachingCopy Anchor Link

Optimized responses carry an X-Nextjs-Cache: MISS|HIT|STALE header. MISS means freshly converted, HIT means served from cache, and STALE means an expired cached copy was sent while a fresh one is converted in the background.