Installing Weevar

Select your environment#

• Already using an AI coding agent? → Skip everything and use Quick install. Paste one prompt; your agent does the rest.
• Vite + React → Follow the steps below. Vite is the recommended path.
• Next.js (App Router or Pages) → Steps below, then add the SWC plugin for source-accurate prompts.
• Webpack-based stack (CRA, custom) → Steps below, then add the Webpack loader.
• Just trying it out → Steps below. Skip the bundler plugin; prompts will use DOM selectors.

The bundler plugin is optional but strongly recommended. Without it, prompts won't include file:line anchors or component names from JSX.

Quick install (let your AI agent do it)#

If you're already working in Claude Code, Cursor, Codex, Windsurf, or any AI coding agent that can edit files in your project, you can skip the manual steps. Paste this prompt into your agent and it will install the package, detect your bundler, wire up the right plugin, and mount <Weevar /> for you — without disturbing your existing setup.

Install and fully set up Weevar in this project: install dependencies, detect the stack (Vite / Next.js SWC / Webpack), apply the correct Weevar integration, mount <Weevar /> at the app root, and preserve existing config/plugins.

After it finishes:

1. Run npm run dev (or whatever your dev script is).
2. Press ⌘⇧E (Mac) or Ctrl+Shift+E (Windows/Linux) to activate the overlay.
3. Skim the diff before committing. Weevar's footprint is small; one dependency, one plugin entry in your bundler config, one mounted component, but it's worth a glance.

If you'd rather do it yourself, the manual steps are below. They take about a minute.

1. Weevar package installation#

npm install weevar

Yarn, pnpm, and bun all work. Weevar is published as a single package with subpath exports.

2. Mount the component#

Add <Weevar /> once, anywhere in your app's render tree. The root layout is the cleanest place.

// app/layout.tsx (Next.js App Router)
// or src/main.tsx (Vite)
import { Weevar } from "weevar/react";

export default function Root() {
  return (
    <>
      <App />
      <Weevar />
    </>
  );
}

The component renders nothing visible to your users. In development it lazily mounts a Shadow DOM overlay on first activation. In production it resolves to a no-op exported component (a few bytes that returns null).

3. Add the bundler plugin (recommended)#

Vite#

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { weevar } from "weevar/vite";

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

That’s it. The plugin injects a data-wv-source="file:line:col" attribute onto your JSX during dev, which Weevar reads to build accurate prompts. It also detects Tailwind (if present) and exposes a virtual config module to the runtime.

See Vite plugin → for what gets injected and how to opt out.

Next.js (SWC)#

Next compiles JSX with SWC, not Babel, so it needs the SWC variant. Wire it through the transformJsxWithWeevarSourceSwc helper exported from weevar/swc. Full setup on SWC plugin →.

Webpack#

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(tsx|jsx)$/,
        exclude: /node_modules/,
        enforce: "pre",
        loader: "weevar/webpack-loader",
      },
    ],
  },
};

See Webpack loader →.

4. Run your dev server#

npm run dev

Open the app. You'll see a small Weevar logo button in the bottom-right corner. Press ⌘⇧E (Mac) or Ctrl+Shift+E (Windows/Linux), or click the button, to activate the overlay.

Requirements#

• Node.js ≥ 18.18
• React ≥ 17 (peerDep, with react-dom ≥ 17)
• A development build. Weevar's runtime is gated on process.env.NODE_ENV === 'development' and the development exports condition.
• A modern browser. Chromium-based browsers (Chrome, Edge, Brave, Arc) are the primary validation target. Firefox and Safari work on a best-effort basis.

Component props#

All props are optional.

<Weevar
  keybind={{ key: "k", meta: true, shift: true }}
  config={{ prompts: { tailwindVerbatimClasses: true } }}
/>

For full reference: Component API →.

Production safety#

Weevar ships zero runtime to your production bundle. The package.json exports field uses conditional resolution:

"./react": {
  "development": { /* full runtime */ },
  "default":     { /* tiny no-op stub */ }
}

When your bundler builds for production, it picks the default branch and tree-shakes the entire dev runtime away. The remaining stub is a component that returns null.

If you want belt-and-suspenders, gate the import yourself:

{process.env.NODE_ENV === "development" && <Weevar />}

More: Security & Privacy →.