Weevar's Component API

`<Weevar />`#

Mount once, anywhere in your app's render tree. The component returns null and renders no DOM in your tree, its overlay is portaled into a closed shadow root attached to document.body.

import { Weevar } from "weevar/react";

<Weevar />

In production builds, the imported component resolves to a tiny stub that returns null. Bundlers tree-shake away the rest of the runtime.

Props#

Prop	Type	Default	Description
`keybind`	`WeevarKeybind`	`{ key: "e", meta: true, ctrl: true, shift: true }`	Override the activation shortcut. `meta` matches Cmd on macOS; `ctrl` matches Ctrl. The default matches if either modifier is held.
`disabled`	`boolean`	`false`	When true, the trigger doesn't render and the keybind is ignored. The shadow host isn't even mounted.
`config`	`WeevarRuntimeConfig`	`{}`	Inline runtime config. Deep-merged with `virtual:weevar-config` if you're using the Vite plugin.

`WeevarKeybind`#

type WeevarKeybind = {
  key: string;     // e.g. "e", "k", "/"
  meta?: boolean;  // Cmd on macOS, Win key on Windows
  ctrl?: boolean;  // Ctrl on all platforms
  shift?: boolean;
  alt?: boolean;
};

When you provide a custom keybind, all listed modifiers must match (set undefined modifiers to false if you want them required-off, the default is "may be present"). Single-key triggers are not recommended; use at least one modifier.

`WeevarRuntimeConfig`#

See Config file → for the full schema.

Examples#

Custom shortcut#

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

Activate with ⌘⇧K (or Ctrl+Shift+K).

Disable in CI#

<Weevar disabled={process.env.CI === "true"} />

Force Tailwind verbatim, override the auto-detect#

<Weevar config={{ prompts: { tailwindVerbatimClasses: true } }} />

Combine all three#

<Weevar
  keybind={{ key: "e", meta: true, ctrl: true, shift: true }}
  disabled={false}
  config={{ prompts: { tailwindVerbatimClasses: true } }}
/>

Subpath exports#

The weevar package ships these subpath imports:

Import	Purpose
`weevar/react`	The `<Weevar />` component. Resolves to a no-op stub in production.
`weevar/vite`	The Vite plugin (`weevar()` and `loadMergedWeevarConfig`).
`weevar/swc`	SWC-based JSX source-injection helper.
`weevar/webpack-loader`	Webpack 5 loader.

Notes on lifecycle#

The shadow host is mounted lazily, on first activation, and reused across re-renders.
HMR is handled — Weevar marks its host with an owner token and reclaims stale hosts owned by previous instances on re-mount.
Unmounting the component schedules cleanup of the host on the next tick (so React's reconciliation completes first).

<Weevar />#