Next.js

Install and wrap the configuration#

npm i -D simpcn

The CLI guides setup and can install the framework adapter:

npx simpcn init --framework next

Then wrap the existing configuration:

import { withSimpcn } from '@simpcn/next';

export default withSimpcn({
  // Keep existing Next.js configuration here.
});

The wrapper accepts a configuration object or a synchronous/asynchronous configuration function. Existing settings and a synchronous webpack callback are preserved. Use a storage configuration with publicBaseUrl; the asset root must be the application’s public/ directory.

Migrate before production compilation#

npx simpcn plan
npx simpcn migrate
npm run build

The repository verifies Next.js 16.4 production builds with both next build --turbopack and next build --webpack. Development paths remain local. The production adapter requires matching verified records for every managed asset, not only the files referenced in one component.

No credentials, original manifests, or storage SDK are needed by the deployed URL helper. In CI, run migration separately or restore trusted deployment-state artifacts matching the current asset bytes and target before building.

Static media references#

export function Hero() {
  return <img src="/images/hero.webp" alt="Product preview" />;
}

Supported DOM media attributes are rewritten in compiled output when they refer to the managed public inventory. Source imports, navigation links, arbitrary strings, CSS URLs, and metadata objects are not automatically rewritten.

Known paths retain encoded filenames, query strings, and fragments. A configured Next.js basePath is recognized when resolving local paths; it is not added to the CDN namespace.

Using next/image#

import Image from 'next/image';

<Image src="/images/hero.webp" width={1200} height={800} alt="Product preview" />

A verified static next/image source becomes a direct CDN URL with unoptimized during production compilation. This bypasses Next.js image optimization for that reference. The adapter does not resize, compress, or convert images, and it does not change global image settings or remotePatterns.

Spreads, duplicate src, explicit loader or overrideSrc, and false/dynamic unoptimized leave the element unchanged with a diagnostic. Explicit global optimization or custom-loader settings are respected unless the element opts into direct delivery with unoptimized.

Default imports and default-import aliases are recognized. Namespace components, CommonJS bindings, and locally re-exported wrappers are not automatically recognized.

Dynamic paths need an explicit helper#

import { assetUrl } from '@simpcn/next/assets';

<img src={assetUrl(`/images/${name}.webp`)} alt="Product preview" />

The helper looks up known managed files. Unknown paths remain unchanged. Development returns the original URL. For dynamic next/image use src={assetUrl(path)} with unoptimized and the normal required image props.

Use the helper explicitly for asset URLs in metadata too. App-directory metadata files are outside the public inventory.

Deployment and scope#

The compiled mapping works in server and client components. Repository tests cover prerendering, request-rendered routes, and Pages Router ISR using a local asset origin. Uploads or delivery-URL changes require another application build and deployment.