Next.js

Cache Rocket for Next.js is an image CDN + cache warming package that sits beside your existing host. You keep SSR and HTML where they are (Vercel, Netlify, Cloudflare Pages, or your own Node host). Cache Rocket optimizes and delivers images, and can warm URLs after each deploy.

1. Create a Next.js site#

In the dashboard open Account → Next.js, create a site for your hostname, and copy the site token, site ID, and API keys. Add image host allowlist entries for every origin you load images from (your site hostname is always included).

2. Install the package#

@cacherocket/next is published on GitHub Packages. Add a project .npmrc, then install:

@cacherocket:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

npm i @cacherocket/next@0.1.0

3. Environment variables#

# Public — safe in the browser / image URLs
CACHEROCKET_SITE_TOKEN=site_xxx
# Absolute origin for relative /public images (optional but recommended)
CACHEROCKET_ASSET_ORIGIN=https://www.example.com

# Server-only — warm / purge / deploy hooks
CACHEROCKET_PUBLIC_KEY=...
CACHEROCKET_SECRET_KEY=...
CACHEROCKET_SITE_ID=...

4. Wrap next.config#

import type { NextConfig } from 'next'
import { withCacheRocket } from '@cacherocket/next'

const nextConfig: NextConfig = {
  // your config
}

export default withCacheRocket(
  {
    siteToken: process.env.CACHEROCKET_SITE_TOKEN,
    assetOrigin: process.env.CACHEROCKET_ASSET_ORIGIN,
  },
  nextConfig
)

5. Use next/image as usual#

Prefer absolute image URLs, or relative paths when CACHEROCKET_ASSET_ORIGIN is set. The loader rewrites requests to path-based transform URLs on img.cacherocket.com:

https://img.cacherocket.com/i/site_xxx/w_1200,q_75,f_auto/https%3A%2F%2F...

6. Warm on deploy#

Add a Route Handler and point a Vercel Deploy Hook (or equivalent webhook) at it:

import { onVercelDeploy } from '@cacherocket/next/server'

export const POST = onVercelDeploy()

Or call helpers from a script or CI step:

import { warm, purge } from '@cacherocket/next/server'

await warm({ urls: ['https://www.example.com/'] })
await purge({ rewarm: true })

Platform webhook URLs without the npm package are covered in Deploy triggers.

Package exports#

Common problems#

Images still go through /_next/image on my host.

Confirm withCacheRocket wraps your exported config and that CACHEROCKET_SITE_TOKEN is set at build time. Redeploy after changing env vars.

I see “Unknown or inactive site token”.

The token in the image URL does not match an active Next.js site. Copy the current site token from Account → Next.js and redeploy.

Remote images return an error or fall back to the original URL.

Add the image’s hostname to the site allowlist. Only allowlisted origins can be optimized. Soft-fail to the original URL also happens when you are over plan quota.

Relative /public images fail to optimize.

Set CACHEROCKET_ASSET_ORIGIN (or your public site origin) so Cache Rocket can resolve an absolute fetch URL.

Deploy warming never runs.

Confirm the webhook hits your /api/cacherocket/deploy route (or the public deploy webhook), that server-only API keys and CACHEROCKET_SITE_ID are set, and that the hostname matches an active warmer. See Deploy triggers.

Need help?#

Open Account → Support and choose the Next.js category, or start from Troubleshooting. Include your site ID, package version, and whether the issue is image delivery or deploy warming.