{"id":21071,"library":"convex-vite-plugin","title":"Convex Vite Plugin","description":"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.","status":"active","version":"0.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/juliusmarminge/agent-tools","tags":["javascript"],"install":[{"cmd":"npm install convex-vite-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add convex-vite-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add convex-vite-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin requires Vite >=7.0.0","package":"vite","optional":false}],"imports":[{"note":"ESM-only; the plugin is not CJS compatible. TypeScript definitions are included.","wrong":"const { convexLocal } = require('convex-vite-plugin')","symbol":"convexLocal","correct":"import { convexLocal } from 'convex-vite-plugin'"},{"note":"Named export, not default. The class can be used programmatically for custom setups.","wrong":"import ConvexBackend from 'convex-vite-plugin'","symbol":"ConvexBackend","correct":"import { ConvexBackend } from 'convex-vite-plugin'"},{"note":"TypeScript users should import the type for custom logger interfaces. Available since v0.3.0.","wrong":"","symbol":"ConvexLogger","correct":"import type { ConvexLogger } from 'convex-vite-plugin'"}],"quickstart":{"code":"// vite.config.ts\nimport { convexLocal } from 'convex-vite-plugin';\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n  plugins: [\n    convexLocal({\n      // optional: customize instance name, project dir, etc.\n      instanceName: 'my-convex',\n      reset: false,\n      envVars: { MY_VAR: 'value' },\n      onReady: [\n        { functionPath: 'seed:mySeed' } // runs after backend is ready\n      ]\n    })\n  ]\n});\n\n// Then in your app:\n// import { ConvexProvider, ConvexReactClient } from 'convex/react';\n// const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);","lang":"typescript","description":"Shows minimum plugin setup with convexLocal() and usage of injected VITE_CONVEX_URL."},"warnings":[{"fix":"Update envVars callback to use object destructuring: envVars: ({ vitePort, resolvedUrls }) => ({ ... })","message":"The envVars callback signature changed from (vitePort: number) to ({ vitePort, resolvedUrls }) in v0.4.0.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Use import syntax or configure tsconfig with 'module': 'ESNext' and 'moduleResolution': 'bundler'.","message":"The plugin is ESM-only; require() will fail. Ensure your project uses ESM or Vite's module resolution.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use the 'reset' option to clear state when switching branches, or manually delete the .convex directory.","message":"State persistence relies on git branch. Switching branches with different convex directories may cause data confusion.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"No action needed; older versions that bundled bunx require upgrading. If using bun, ensure npm_config_user_agent is set.","message":"The bun-specific hardcoded dependency was removed in v0.3.2. The plugin now auto-detects package manager.","severity":"deprecated","affected_versions":">=0.3.2"},{"fix":"Upgrade Vite to version 7 or later.","message":"The plugin requires Vite ^7.0.0. Using with older Vite versions will cause install failures or runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"bun add convex-vite-plugin or npm install convex-vite-plugin","cause":"Package not installed; try installing it.","error":"Error: Cannot find module 'convex-vite-plugin'"},{"fix":"Use import { convexLocal } from 'convex-vite-plugin'","cause":"Wrong import pattern: likely using default import instead of named import.","error":"TypeError: convexLocal is not a function"},{"fix":"Ensure envVars returns a record of string keys starting with 'VITE_', e.g., { VITE_MY_VAR: 'value' }","cause":"envVars callback returning invalid format; Vite requires environment variables to be prefixed with VITE_.","error":"The envVars callback must return an object with VITE_ prefix"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}