Registry / devops / convex-vite-plugin

convex-vite-plugin

library0.4.0jsnpmunverified

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.

devops web-framework http-networking

npm install convex-vite-plugin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONVEX-VITE-PLUGIN

convex-vite-plugin

devopsjavascriptv0.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

convexLocal

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

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

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

ConvexBackend

✓ import { ConvexBackend } from 'convex-vite-plugin'

✗ 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.

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);

Debug

Known issues

breakingThe 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 }) => ({ ... })

affects: >=0.4.0

gotchaThe 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'.

affects: >=0.1.0

gotchaState 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.

affects: >=0.1.0

deprecatedThe 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.

affects: >=0.3.2

gotchaThe 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

Package not installed; try installing it.

fix

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

TypeError: convexLocal is not a function

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

fix

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

The envVars callback must return an object with VITE_ prefix

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' }

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

viterequiredPeer dependency; plugin requires Vite >=7.0.0

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/juliusmarminge/agent-tools ↗

packagehttps://www.npmjs.com/package/convex-vite-plugin ↗

homepagehttps://www.convex.dev ↗