vibecheck0.3.0
Performanceheavy-librarywarning

Heavy dependencies in Next.js

Some libraries are heavy enough that pulling one in for a small feature dominates your bundle and brings its own performance footguns — 3D engines that leak GPU memory, animation libraries that read layout every frame, date libraries many times larger than the native alternative. AI agents reach for whatever library they’ve seen most, so a marketing page ends up shipping a full charting or animation runtime for one small effect.

Framework fixes
GeneralReactNext.jsVanilla JS

Symptoms

  • One dependency accounts for a large share of the bundle
  • A heavy runtime (Three.js, Framer Motion, Moment) loads on a page that barely uses it
  • Known pitfalls: undisposed resources, per-frame layout reads, un-tree-shaken imports
  • The bundle analyzer shows a single package dwarfing the rest

How VibeCheck catches it

In your widget · Problems

warningheavy-libraryFramer Motion detected (58KB)

To your coding agent · MCP

agent › get_detected_issues
→ { detector: "heavy-library", issue: "Framer Motion detected (58KB)", threshold: "Matches one of 16 known heavy-library signatures (globals, DOM patterns, or script URLs)" }

The same string in your widget and in your agent’s context — no screenshot, no copy-paste.

Root causes

  • A large library imported for one small feature
  • Importing the whole library instead of a tree-shakeable subset
  • The library loaded eagerly on a page that only uses it conditionally
  • A dated heavyweight (e.g. Moment.js) where a modern/native option exists

The fix for Next.js

Dynamic-import client-only heavy libraries with ssr:false so they never touch the server bundle or block first paint, and load them behind interaction where possible.

tsx
import dynamic from 'next/dynamic'
const Globe = dynamic(() => import('./Globe'), { ssr: false }) // Three.js stays out of initial JS

Steps

  1. Identify the heavy library and how much of it you actually use
  2. Replace with a native/lighter option, or import a tree-shakeable subset
  3. If it must stay, lazy-load it and dispose its resources on teardown

See the general, framework-agnostic fix →

FAQ

Which libraries does VibeCheck flag?
It fingerprints 16 known-heavy libraries — 3D engines, animation runtimes, charting, CSS-in-JS, date and utility libraries — by their globals, DOM markers, or script URLs, and reports the weight plus that library’s common pitfalls.
Do I have to remove the library?
Not necessarily. Often lazy-loading it (so only users who need the feature download it) or importing a lighter subset is enough. Removal only makes sense when a native API or a much smaller package fully covers your use.
What’s the single most common heavy dependency?
Date libraries and animation runtimes. Moment.js is a classic — the native Intl.DateTimeFormat replaces most of it for zero bytes — and animation libraries are frequently shipped in full when a tree-shaken or lazy subset would do.