airi/packages/cap-vite

@proj-airi/cap-vite

CLI for Capacitor live-reload development using Vite.

Usage

cap-vite [vite args...] -- <ios|android> [cap run args...]

Examples:

pnpm exec cap-vite -- ios --target <DEVICE_ID_OR_SIMULATOR_NAME>
pnpm exec cap-vite -- --host 0.0.0.0 --port 5173 -- android --target <DEVICE_ID_OR_SIMULATOR_NAME> --flavor release
CAPACITOR_DEVICE_ID=<DEVICE_ID_OR_SIMULATOR_NAME> pnpm exec cap-vite -- ios
pnpm -F @proj-airi/stage-pocket run dev:ios -- --target <DEVICE_ID_OR_SIMULATOR_NAME>

• Arguments before -- are forwarded to vite.
• Arguments after -- are forwarded to cap run.
• If CAPACITOR_DEVICE_ID is set and cap run args do not contain --target, cap-vite injects --target <CAPACITOR_DEVICE_ID> automatically.
• cap-vite always launches the Vite dev server. Do not pass vite dev or vite serve as extra args.

You can see the list of available devices and simulators by running pnpm exec cap run ios --list or pnpm exec cap run android --list.

Capacitor Configuration

You need to set server.url in capacitor.config.ts to the env variable CAPACITOR_DEV_SERVER_URL, then the cli will handle rest for you.

const serverURL = env.CAPACITOR_DEV_SERVER_URL
const isCleartext = serverURL?.startsWith('http://') ?? false

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  webDir: 'dist',
  server: serverURL
    ? {
        url: serverURL,
        cleartext: isCleartext,
      }
    : undefined,
}

export default config

Why we need this?

• No need to care what server.url should be, it will be automatically set to the correct value.
• Rerun native app when native code changes, you won't forget to start it.
• No need to open two terminals to run the project, you can run it with one command.

Architecture Notes

• Vite arguments are left to the real Vite CLI instead of being reimplemented inside cap-vite.
• cap-vite injects a wrapper config so it can append its own Vite plugin without editing the user's existing vite.config.*.
• The injected plugin reads server.resolvedUrls, starts cap run, and restarts it when files under the native platform directory change.
• cap-vite only splits the two argument groups and passes the cap run arguments into the injected plugin through environment variables.