Troubleshooting

Fixes for the most common issues across install, versioning, detection, and rendering.

Fixes for common questions across installation, configuration, and rendering.

Quick Problem Index

Install & CLI

`npx vectorvesper` runs an old version

npx caches packages locally, so it can sometimes run a stale copy. Pin the latest version explicitly:

npx vectorvesper@latest add video-card

Check your active version with npx vectorvesper --version. Note that a local or global install will shadow the npm package, so check your node_modules or global path if the version appears stale.

`npm i -g vectorvesper` fails with EEXIST or EPERM

Vector Vesper is npx-first, meaning global installation is not required. These errors usually mean a previous global install left a locked executable shim behind (common on Windows when a terminal, editor, or antivirus locks the binary).

Use npx vectorvesper … instead. If you prefer a global binary, close locking processes, run npm rm -g vectorvesper, and reinstall.

"Component not found in the registry"

Check the exact slug against npx vectorvesper list. For example, use physics-buttons (plural) rather than physics-button.

Peer dependencies weren't installed

You may have passed --no-install, or the dependency step was interrupted. Re-run the installation command printed by the CLI, or re-run add without --no-install.

Config & detection

Components landed in `src/` instead of `src/components/vv`

Your import alias is set to @/ (or src/) rather than @/components/vv. The install location follows aliases.vv in vv.config.json.

Update aliases.vv to @/components/vv, then remove and re-add the component:

npx vectorvesper remove <slug>
npx vectorvesper add <slug>

Tailwind shows "No" even though it's installed

Older CLI versions only looked for a tailwind.config.* file, so Tailwind v4 projects (which use @import "tailwindcss"; without a config file) reported "No". Update to the latest CLI: npx vectorvesper@latest info correctly detects Tailwind v4. See the Tailwind guide.

Rendering

"Hydration failed" / mismatch (Next.js)

A component rendered different markup on the server versus the client. Ensure WebGL components are loaded with dynamic(..., { ssr: false }) from a Client Component, and avoid introducing non-deterministic values (such as Math.random() or client-only window measurements) during the initial render pass.

WebGL component is blank, or "window is not defined"

The component was server-rendered. On the Next.js App Router, load it with dynamic(..., { ssr: false }) from a Client Component, a file that starts with "use client". See the Next.js guide.

Styles are missing / the component looks unstyled

The component uses Tailwind CSS, and your Tailwind setup doesn't scan the install directory. See Tailwind setup.