Test page

Next.js

Install @cacherocket/next for image CDN via next/image, optional /_next/static CDN, and warm URLs after every deploy — hosting stays on Vercel, Netlify, Cloudflare Pages, or your own Node host.

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.

INFO: What @cacherocket/next includes

withCacheRocket for next.config, a custom next/image loader on img.cacherocket.com, optional assetPrefix for /_next/static via Managed CDN (assets.cacherocket.com), and server helpers (warm, purge, uploadStatic, onVercelDeploy). It does not replace Next.js hosting or Next.js Data Cache / use cache APIs.

TIP: Plans

Free includes a trial of 25 image transforms / month and 1 GB image CDN bandwidth. Static asset CDN requires Managed CDN on a paid plan (same assets.cacherocket.com meter as WordPress). See Plans and limits.

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 the public npm registry:


npm i @cacherocket/next

3. Environment variables

_Vercel / .env.local_


# 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 cache-rocket.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

_next.config.ts_


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

SUCCESS: Soft-fail on quota

If a plan or monthly transform quota is exceeded, Cache Rocket redirects to the original image URL so the page still loads.

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 cache-rocket.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:

_app/api/cacherocket/deploy/route.ts_


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.