Next.js

Cache Rocket for Next.js is an image CDN + optional `/_next/static` 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, can serve hashed JS/CSS from Managed CDN, 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.2.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

# Optional — customer static CDN (/_next/static) from Account → Next.js
# Do not use CacheRocket.com's internal CACHEROCKET_CDN_URL
CACHEROCKET_STATIC_CDN_URL=https://assets.cacherocket.com/org_…/site_…/static

# Server-only — warm / purge / deploy / static upload
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,
    staticCdnUrl: process.env.CACHEROCKET_STATIC_CDN_URL,
  },
  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. Optional: static asset CDN (`/_next/static`)#

For self-hosted or non-Vercel Next.js apps (or when you want hashed JS/CSS off your origin), enable Static asset CDN on Account → Next.js. This requires Managed CDN on your plan. Cache Rocket stores build output in OVH under your tenant path and serves it from Bunny on assets.cacherocket.com. HTML and SSR stay on your host.

Copy staticCdnUrl into CACHEROCKET_STATIC_CDN_URL (never CacheRocket.com’s internal CACHEROCKET_CDN_URL). After every next build, upload assets:

npx cacherocket-next upload-static

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

await uploadStatic()

7. 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.

Static CDN toggle says my plan does not include Managed CDN.

Static /_next/static delivery uses Managed CDN (assets.cacherocket.com) and requires a plan with allowCdn. Image CDN on Free still works via img.cacherocket.com.

/_next/static 404s from the CDN after deploy.

Enable static CDN on the site, set CACHEROCKET_STATIC_CDN_URL, redeploy so assetPrefix is applied, then run npx cacherocket-next upload-static after next build.

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.