The Simpcn handbook

We’ll handle it from here.

Add Simpcn as a dev dependency. The CLI will guide you through setup.

Before you start

Use Node.js 24.11+ and an existing Next.js or Vite project. Have a storage bucket, upload credentials, and a public delivery URL ready. For React Native, see the experimental Expo integration. Storage setup →

1. Install Simpcn

Run this in the application directory:

Install as a dev dependency

npm i -D simpcn

2. Let the CLI guide you

npm · initialize

npx simpcn init

Choose a framework and storage provider. The CLI creates the configuration, can install the framework adapter, and prints the next steps.

Set the existing bucket and public delivery URL in simpcn.config.ts. Include the storage prefix once in that URL.

Example storage configuration

simpcn.config.ts · replace the example values

import type { UserConfig } from 'simpcn';

export default {
  root: 'public',
  // Keep essential assets local. Patterns are relative to root, without public/.
  // Example: ['favicon.ico', 'fonts/**', 'offline/**', 'images/fallback.png']
  exclude: [],
  publicBaseUrl: 'https://cdn.example.com/assets/',
  storage: {
    provider: 's3',
    bucket: 'YOUR_EXISTING_BUCKET',
    region: 'us-east-1',
    prefix: 'assets',
  },
} satisfies UserConfig;

Choose what stays local

Keep essential icons, fonts, fallback images, and offline-page assets with your application when they should not depend on CDN delivery. Add their paths to exclude in simpcn.config.ts; Simpcn leaves them out of uploads and keeps their original references.

Patterns are relative to the configured asset root, so images/fallback.png matches public/images/fallback.png with the default root. Keep-local configuration and examples →

3. Add upload credentials

.env.local · beside simpcn.config.ts

AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY

Keep credentials out of source control and browser-exposed variables. More credential options →

4. Connect the framework

Add the adapter to the existing framework configuration:

Next.js · next.config.ts

next.config.ts

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

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

Next.js integration guide →

Vite · vite.config.ts

vite.config.ts

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

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

Vite integration guide →

5. Preview, migrate, build

npm · preview, migrate, build

npx simpcn plan
npx simpcn migrate
npm run build

Preview the assets, upload and verify them, then run the application’s production build. The build rewrites supported references; it does not upload files.

Before deploying, commit simpcn/deployment-state.json with the matching assets, source, root configuration, and lockfile. CI can then build from a fresh checkout without upload credentials. Init ignores generated files under simpcn/.build/. State and CI setup →

All CLI commands →

6. Keep writing the same code

Source · unchanged

<img src="/images/hero.webp" alt="Product preview" />

Development keeps the local path. After migration and a production build, supported references resolve to the configured delivery URL. Source files and original assets stay in place.

Supported references · Troubleshooting