Convex Vite Plugin

0.4.0 verified Mon Apr 27 auth: no javascript

A Vite plugin (v0.4.0) that automatically starts a local Convex backend during development, deploys functions on startup, watches for changes in the convex/ directory, and injects VITE_CONVEX_URL and VITE_CONVEX_SITE_URL environment variables. It persists backend state across restarts based on git branch, supports custom logging, and provides methods like getAdminKey(). The plugin detects the package manager (npm, yarn, pnpm, bun) automatically. Requires Vite ^7.0.0.

Common errors

error Error: Cannot find module 'convex-vite-plugin' ↓

cause Package not installed; try installing it.

fix

bun add convex-vite-plugin or npm install convex-vite-plugin

error TypeError: convexLocal is not a function ↓

cause Wrong import pattern: likely using default import instead of named import.

fix

Use import { convexLocal } from 'convex-vite-plugin'

error The envVars callback must return an object with VITE_ prefix ↓

cause envVars callback returning invalid format; Vite requires environment variables to be prefixed with VITE_.

fix

Ensure envVars returns a record of string keys starting with 'VITE_', e.g., { VITE_MY_VAR: 'value' }

Warnings

breaking The envVars callback signature changed from (vitePort: number) to ({ vitePort, resolvedUrls }) in v0.4.0. ↓

fix Update envVars callback to use object destructuring: envVars: ({ vitePort, resolvedUrls }) => ({ ... })

gotcha The plugin is ESM-only; require() will fail. Ensure your project uses ESM or Vite's module resolution. ↓

fix Use import syntax or configure tsconfig with 'module': 'ESNext' and 'moduleResolution': 'bundler'.

gotcha State persistence relies on git branch. Switching branches with different convex directories may cause data confusion. ↓

fix Use the 'reset' option to clear state when switching branches, or manually delete the .convex directory.

deprecated The bun-specific hardcoded dependency was removed in v0.3.2. The plugin now auto-detects package manager. ↓

fix No action needed; older versions that bundled bunx require upgrading. If using bun, ensure npm_config_user_agent is set.

gotcha The plugin requires Vite ^7.0.0. Using with older Vite versions will cause install failures or runtime errors. ↓

fix Upgrade Vite to version 7 or later.

Install

npm install convex-vite-plugin

yarn add convex-vite-plugin

pnpm add convex-vite-plugin

Imports

convexLocal

wrong

const { convexLocal } = require('convex-vite-plugin')

correct

import { convexLocal } from 'convex-vite-plugin'

ESM-only; the plugin is not CJS compatible. TypeScript definitions are included.

ConvexBackend
wrong
```
import ConvexBackend from 'convex-vite-plugin'
```
correct
```
import { ConvexBackend } from 'convex-vite-plugin'
```
Named export, not default. The class can be used programmatically for custom setups.
ConvexLogger
```
import type { ConvexLogger } from 'convex-vite-plugin'
```
TypeScript users should import the type for custom logger interfaces. Available since v0.3.0.

Quickstart

Shows minimum plugin setup with convexLocal() and usage of injected VITE_CONVEX_URL.

// vite.config.ts
import { convexLocal } from 'convex-vite-plugin';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    convexLocal({
      // optional: customize instance name, project dir, etc.
      instanceName: 'my-convex',
      reset: false,
      envVars: { MY_VAR: 'value' },
      onReady: [
        { functionPath: 'seed:mySeed' } // runs after backend is ready
      ]
    })
  ]
});

// Then in your app:
// import { ConvexProvider, ConvexReactClient } from 'convex/react';
// const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);