The Simpcn handbook
Supported references
Automatic rewriting has a defined scope. Use explicit helpers for dynamic asset paths.
Only managed asset references
A reference must resolve to a file in the configured managed inventory. Excluded, unknown, external, and data URLs remain unchanged. Root-relative paths, recognized application base paths, encoded filename segments, queries, and fragments are supported.
Static JSX values can be a string attribute, a string expression, or a template literal without substitutions. A string elsewhere in JavaScript is not automatically an asset reference.
<img src="/images/hero.webp" alt="Product preview" />
<img src={"/images/hero.webp"} alt="Product preview" />
<img src={`/images/hero.webp`} alt="Product preview" />Assets you choose to keep local
Use exclude to keep essential files outside the CDN-managed inventory. Matching files retain their original references in production, including when their paths are passed to assetUrl(). They do not need upload or verification records.
This is useful for fallback images, essential icons, and other assets that should use the application's normal delivery. Configuration, examples, and offline behavior →
Reference support
| Reference | Next.js | Vite |
|---|---|---|
| Static DOM media JSX/TSX attributes | Yes | Yes |
| img/source srcSet; video poster; object data; SVG image href | Yes | Yes |
| Icon, apple-touch-icon, and preload link href | JSX/TSX | JSX/TSX + HTML |
| Static imported next/image | Verified direct URLs + unoptimized | Not applicable |
| Bundled CSS url() | Not implemented | Yes |
| HTML media, style blocks, and inline styles | No standalone HTML pass | Yes |
| Native public-file / managed ?url imports | No equivalent integration | Yes |
| Explicit dynamic helper | @simpcn/next/assets | virtual:simpcn |
| Arbitrary strings, API responses, custom component props | No automatic rewriting | No automatic rewriting |
DOM src targets are img, source, video, audio, track, input, and embed. Ordinary navigation links are intentionally unchanged.
React Native with Expo · experimental
The experimental Expo adapter supports PNG/JPEG sources on named React Native Image/ImageBackground imports and expo-image Image imports. Direct literal relative require() and default image imports are recognized, including binding aliases.
iOS/Android families, @2x/@3x densities, generic fallback, and logical dimensions are handled. All selected siblings require matching verification. Excluded families stay local; an imported asset with other uses remains bundled. Namespace imports, dynamic requires, wrappers, placeholders, and .native families are outside this scope.
Native image sources use module references rather than the web URL rules above. Expo web and bare React Native are not supported. Examples, setup, and validation status →
Make dynamic intent explicit
import { assetUrl } from '@simpcn/next/assets';
<img src={assetUrl(`/images/${name}.webp`)} alt="Product preview" />import { assetUrl } from 'virtual:simpcn';
<img src={assetUrl(`/images/${name}.webp`)} alt="Product preview" />The helper resolves known paths from the compiled map and preserves unknown paths unchanged. It cannot upload new runtime files or discover assets returned later by an API. All managed assets must have verified deployment records when generating the full helper map.
Files uploaded as raw objects
Uploading a public CSS, JS, JSON, or HTML file does not rewrite its contents. Vite transforms bundled source CSS, not the contents of objects after upload. Keep internal relative paths valid in the public namespace or handle them explicitly.
Read next/image handling for direct-delivery conflicts and limitations before migrating an application with custom asset handling.