vite-plugin-dev-file-tags

Zero-config source file overlay for Vite + React. See which file renders every part of your UI — without touching a single component.

---

What it does

Adds a tiny filename badge to every page, layout, and shared component — automatically. No manual imports, no wrapper components, no config files.

┌─────────────────────────────────────────┐
│ pages/super-admin/VendorMenu.tsx        │
│ ┌─────────────────────────────────────┐ │
│ │                                     │ │
│ │        Your actual page UI          │ │
│ │                                     │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘
         ↑ badge appears here in dev mode

Toggle all tags: Ctrl+Shift+F

---

Install

Copy devFileTags.ts into your project (e.g. plugins/devFileTags.ts), then add to your Vite config:

// vite.config.ts
import devFileTags from './plugins/devFileTags'

export default defineConfig({
  plugins: [
    react(),
    devFileTags(), // ← add this
  ],
})

Done. Start your dev server and you'll see file tags on every page.

---

How it works

The plugin runs only in dev mode (apply: 'serve') and does two things:

1. Transform — For every .tsx file in the configured directories, it finds the export default function's main return statement and injects a data-dev-file="path" attribute on the root JSX element.

2. CSS + Toggle — Injects a <style> block and a small <script> into index.html that:

   • Uses ::before pseudo-element to display the filename badge (no extra DOM nodes)
   • Listens for Ctrl+Shift+F to toggle visibility
   • Persists toggle state in localStorage

Production builds are completely unaffected — the plugin never runs during vite build.

---

Options

devFileTags({
  // Directories inside `src/` to tag (default shown below)
  dirs: ['pages/', 'layouts/', 'components/shared/'],

  // Toggle shortcut (default: Ctrl+Shift+F)
  shortcut: { ctrl: true, shift: true, key: 'F' },
})

dirs

Array of directory prefixes relative to src/. Only .tsx files inside these directories get tagged.

// Tag everything in src/
devFileTags({ dirs: [''] })

// Only tag pages
devFileTags({ dirs: ['pages/'] })

// Custom directories
devFileTags({ dirs: ['pages/', 'layouts/', 'views/', 'features/'] })

shortcut

Customize the toggle keyboard shortcut.

// Alt+Shift+D
devFileTags({ shortcut: { ctrl: false, shift: true, key: 'D' } })

---

Requirements

• Vite 5+
• React with .tsx files
• Components must use export default function pattern

// ✅ Works — named default export
export default function VendorMenu() {
  return (
    <div>...</div>
  )
}

// ❌ Won't tag — arrow function export
const VendorMenu = () => <div>...</div>
export default VendorMenu

// ❌ Won't tag — no parenthesized JSX return
export default function VendorMenu() {
  return <div>...</div>  // single-line return without parens
}

---

FAQ

Does it affect production? No. The plugin sets apply: 'serve', so it only runs during vite dev. Production bundles have zero overhead.

Does it add elements to the DOM? No. It uses CSS ::before pseudo-elements — no extra React components or DOM nodes.

Will it break my layout? It adds position: relative to tagged elements when tags are visible. In rare cases this could affect stacking contexts. Toggle off with Ctrl+Shift+F if needed.

Can I use it with Vue/Svelte? Currently only supports React .tsx files with export default function pattern. PRs welcome for other frameworks.

---

License

MIT — use it anywhere, modify freely.