h-vue-scan/README.md

A Vue 3 plugin for scanning re-rendering states and show them in the browser dom.

# 🔬 Vue Scan — The Flashlight for Your Vue Re-renders

### Enjoying my project? Please show your appreciation by starring it on GitHub! ⭐

> Because sometimes your components are doing too much, and it's time to shine a light on 'em. Literally.

A lightweight `Vue 3` dev plugin that visually which components are re-rendering. Every time a component updates, its root element flashes a stylish overlay.

> [!NOTE]
> This is a “just-for-fun” project. It’s probably not the best way to do this. But hey! it’s simple, effective, and most importantly: [Because I wanted to](https://aaronfrancis.com/2024/because-i-wanted-to-12c5137c)
>
> Need something fancier, more efficient, and twice as intimidating? Check out the brilliant [z-vue-scan](https://github.com/zcf0508/vue-scan). It's like this plugin but with a PhD.

## ✨ Features

- 🔌 **Plug and Play**: Just install and it works. No configs needed.
- 🧠 **TypeScript Native**: Fully typed plugin and options interface.
- 🚫 **Zero Runtime Bloat**: Only runs in dev mode, so your users never see the flashing.
- 🎨 **Fully Customizable**: Pick your color, duration, opacity, and even border width. Go wild.

## 📦 Installation

```bash
npm install h-vue-scan
# or
yarn add h-vue-scan
```

> [!WARNING]
> Peer dependency alert! Requires: `vue@^3.x`

## 🚀 Usage

```ts
import RenderDebugPlugin from 'h-vue-scan'
// main.ts
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(RenderDebugPlugin, {
  autoInject: true, // Injects overlay in all components automagically
  color: '#00ff00', // Overlay color (CSS format)
  duration: 1000, // Duration in ms the overlay sticks around
  opacity: 0.3, // Transparency level of the flash
  borderWidth: '2px', // Because chunky borders are cool sometimes
  enabled: import.meta?.env?.MODE === 'development', // Only flash when coding
})

app.mount('#app')
```

## 🥊 z-vue-scan vs h-vue-scan

| Feature            | `h-vue-scan`               | `z-vue-scan`                                                              |
| ------------------ | -------------------------- | ------------------------------------------------------------------------- |
| Rendering Method   | DOM overlays per component | One big HTML5 Canvas                                                      |
| Complexity         | 🍃 \~200 LOC               | 🧠 1000+ LOC and a PhD in canvas juggling                                 |
| Performance Tricks | Browser-native rendering   | Viewport culling, throttling, caching, animation queuing, and black magic |
| Flash Features     | Just a glow-up             | Flash count, component name, and animated effects                         |

### TL;DR

- `h-vue-scan` = **easy mode**: DOM-based, simple, and shitter.
- `z-vue-scan` = **power mode**: optimized, robust, and animated.

## 🧩 Contribute Your Spark

This plugin is intentionally **so minimal**, like “did you even try to do it?”

Why?
So **you** can make it better and learn with doing.

Here are some cool ideas I _totally_ meant to build but conveniently “left for the community”:

- 📈 **Flash Counter**: Show how many times a component has re-rendered. Great for catching hot loops and flexing on metrics nerds.
- 🕵️ **Component Name Tooltip**: Hover to see the name of the re-rendering component. Bonus points if it shows the file path.
- ⏱️ **Render Timeline Panel**: Like a mini profiler, but made with Vue and vibes.
- 💅 **Custom Animations**: Want the overlay to shake, fade, pulse, or play elevator music? Go for it.
- 🧪 **Unit Tests**: 😅

If you’ve got an idea, a bug fix, or just want to mess around! PRs are very welcome!

> 🛠 Check out the [issues](https://github.com/hetari/vue-scan/issues) or open a discussion.