Vite

Install and register the plugin#

npm i -D simpcn

The CLI guides setup and can install the framework adapter:

npx simpcn init --framework vite

Then register the plugin:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { simpcn } from '@simpcn/vite';

export default defineConfig({
  plugins: [simpcn(), react()],
});

Place simpcn() before plugins that compile JSX. Keep the application’s existing plugins. Configure storage and publicBaseUrl following the storage guide. The configured asset root must match Vite’s publicDir.

For a configuration at another path, use simpcn({ config: './simpcn.config.ts' }). Paths inside that file resolve relative to the configuration directory.

Build with verified assets#

npx simpcn plan
npx simpcn migrate
npm run build

Development needs no Simpcn configuration or deployment state in the plugin. Production requires publicBaseUrl and matching verified records for referenced managed assets. Builds perform no network calls or uploads. Importing the dynamic helper requires verified records for the entire managed inventory.

Vite may still copy public files to the build output. Simpcn does not remove these copies or local originals. Generated application chunks and imported source assets retain Vite’s normal delivery behavior.

Supported production inputs#

The plugin handles supported static JSX/TSX media attributes, HTML media URLs, icon/preload links, bundled CSS url() declarations, HTML style blocks and inline styles, native public-file URL imports, and managed root-relative ?url imports.

.hero {
  background-image: url("/images/hero.webp");
}

import heroUrl from '/images/hero.webp?url';

Filename encoding, resource queries, and fragments are retained. External URLs, data URLs, excluded files, and navigation links remain unchanged.

Dynamic URLs#

import { assetUrl } from 'virtual:simpcn';

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

For TypeScript, add the virtual-module types alongside the existing Vite types:

{
  "compilerOptions": {
    "types": ["vite/client", "@simpcn/vite/client"]
  }
}

The helper is an identity function in development. In production, it resolves known managed paths from a compiled public URL map; unknown paths stay local.

Know the boundaries#

Dynamic JSX attributes without the helper stay unchanged and generate a diagnostic. Vue/Svelte templates, custom component props, API/JSON strings, JavaScript inline style strings, and arbitrary runtime concatenation are not automatically rewritten.

CSS and scripts uploaded directly from public/ retain their original contents. Use bundled source CSS for rewriting. Relative references inside raw uploaded files must remain valid at the delivery origin; CDN fonts also require suitable CORS response headers.