vite-plugin-agent-tail

0.4.0 verified Mon Apr 27 auth: no javascript

A Vite plugin that captures browser console.log, console.warn, console.error, unhandled errors, and unhandled promise rejections during development and writes them to timestamped log files on disk. Current stable version is 0.4.0. Published as part of the agent-tail ecosystem, it injects a script via HTML transformation that intercepts console methods, batches output, and sends it to the dev server via sendBeacon. Key differentiators: provides tail -f friendly logs, latest symlink, and integrates with the agent-tail CLI for combined browser+server log viewing. Requires Vite >=5.0.0 and ships TypeScript types.

Common errors

error ERR_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE For agent-tail@0.4.0, the dependency vite@>=5.0.0 not satisfied in workspace ↓

cause Vite version in project is below 5.0.0.

fix

Update Vite to >=5.0.0: npm install vite@^5.0.0

error Error: agentTail is not a function ↓

cause Calling agentTail as a plain plugin without invoking the factory function.

fix

Use plugins: [agentTail()] instead of plugins: [agentTail].

error Cannot find module 'agent-tail/vite' or its corresponding type declarations. ↓

cause Importing from 'agent-tail/vite' but package is not installed or not using the umbrella package.

fix

Install agent-tail: npm install -D agent-tail

error TypeError: Failed to execute 'sendBeacon' on 'Navigator': The body of the beacon is not a valid type. ↓

cause The injected script uses sendBeacon; if the browser or environment blocks it (e.g., HTTP vs HTTPS mismatch), logs may fail silently.

fix

Ensure the dev server runs on HTTPS or same-origin. agent-tail attempts to send to the current origin.

Warnings

breaking As of v0.4.0, the import path changed from 'vite-plugin-agent-tail' to 'agent-tail/vite'. Old path no longer works. ↓

fix Update import from 'vite-plugin-agent-tail' to 'agent-tail/vite'.

gotcha The plugin only captures logs during development (vite dev server). It does not work in production builds. ↓

fix Use a production logging solution like Sentry or LogRocket for production builds.

gotcha The plugin injects a script into HTML via transformIndexHtml. If your Vite config uses custom HTML or SSR, injection may not work correctly. ↓

fix Ensure your HTML entry point (index.html) is present and not served externally.

gotcha Logs are written to a 'tmp/logs/' directory relative to the project root. Ensure this directory is writable and not excluded by .gitignore if you want to track logs. ↓

fix Add 'tmp/logs/' to .gitignore to avoid committing logs, or use a custom log directory.

Install

npm install vite-plugin-agent-tail

yarn add vite-plugin-agent-tail

pnpm add vite-plugin-agent-tail

Imports

agentTail
wrong
```
import agentTail from 'agent-tail/vite'
```
correct
```
import { agentTail } from 'agent-tail/vite'
```
Named export from 'agent-tail/vite' subpath. Default import will fail.
agentTail()
wrong
```
export default defineConfig({ plugins: [agentTail] })
```
correct
```
export default defineConfig({ plugins: [agentTail()] })
```
agentTail is a factory function, must be called. Omitting parentheses is a common mistake.
agent-tail (CLI)
wrong
```
import { agentTail } from 'agent-tail'
```
correct
```
import { agentTail } from 'agent-tail/vite'; import { defineConfig } from 'vite'
```
The main 'agent-tail' package does not export the Vite plugin directly; use 'agent-tail/vite' subpath.

Quickstart

Install agent-tail, add the Vite plugin to vite.config.ts, and tail the browser log file.

// install: npm install -D agent-tail
// vite.config.ts
import { defineConfig } from 'vite';
import { agentTail } from 'agent-tail/vite';

export default defineConfig({
  plugins: [agentTail()],
});

// Terminal 2: view logs
// tail -f tmp/logs/latest/browser.log
// or use CLI: agent-tail tail browser -f