Unplugin Console Log Forwarder

0.0.10 · active · verified Tue Apr 21

Unplugin-console is a cross-bundler JavaScript/TypeScript plugin designed to bridge the gap between browser `console` output and your development server's terminal. It leverages the `unplugin` ecosystem to provide real-time forwarding of `console.log`, `info`, `warn`, and `error` messages from the browser directly to your Node.js terminal. Currently at version `0.0.10`, it is in an early, actively developed stage, suggesting frequent updates and potential iterative improvements. A key differentiator is its AST call-site injection approach, which ensures that browser DevTools maintain accurate source file links for logs, unlike runtime `console` overrides. It integrates seamlessly with Vite via its HMR WebSocket for optimal performance, and offers an HTTP fallback for Webpack, Rspack, and other bundlers. The plugin features robust serialization for complex data types (including circular references, Errors, BigInts), color-coded terminal output, stack trace capture, automatic disabling in production environments, and configurable log level filtering and custom prefixes, making it a powerful debugging aid.

Common errors

```
Error: [plugin:unplugin-console] UnpluginConsole is not a function
```
cause Incorrect import path or default/named import mismatch for the specific bundler.

fix For Vite: `import UnpluginConsole from 'unplugin-console/vite'`. For Webpack: `const UnpluginConsole = require('unplugin-console/webpack')`.
```
TypeError: Cannot read properties of undefined (reading 'plugins') in webpack config
```
cause Webpack plugin was imported incorrectly or not passed as an element of an array to `plugins`.

fix Ensure `require('unplugin-console/webpack')` is inside an array: `plugins: [require('unplugin-console/webpack')()]`.
```
Browser console logs are not appearing in the terminal during development.
```
cause The `NODE_ENV` environment variable is set to `production`, or the `levels` option is too restrictive.

fix Check `NODE_ENV` (it should typically be `development` for dev servers). Ensure `levels` array includes the desired log types, e.g., `levels: ['log', 'info', 'warn', 'error']`.

Warnings

breaking As the package is in a pre-1.0 version (0.0.10), minor updates might introduce breaking changes without adhering to semantic versioning for major bumps. Always review changelogs.
Fix: Pin exact versions (e.g., `"unplugin-console": "0.0.10"`) or use `~` for minor updates, and thoroughly test after upgrades.
gotcha The plugin automatically disables itself when `NODE_ENV` is set to `production`. If you need to observe browser console output in a production-like environment (e.g., staging), you must explicitly set `enabled: true` in the plugin options.
Fix: For production-like environments where logs are desired: `UnpluginConsole({ enabled: true })`.
gotcha Webpack users (or those without Vite's HMR WebSocket) rely on an HTTP fallback server to forward logs. The default `serverPort` (8787) might conflict with other services. Ensure the port is free or configure a different one.
Fix: Configure a different port in the plugin options: `UnpluginConsole({ serverPort: 9000 })`.
gotcha Ensure your bundler's peer dependency (Vite >=3 or Webpack ^4 || ^5) matches the plugin's requirements. Mismatches can lead to plugin loading failures or unexpected behavior.
Fix: Verify and update your bundler version to meet the specified peer dependency ranges.

Install

npm install unplugin-console npm
yarn add unplugin-console yarn
pnpm add unplugin-console pnpm

Imports

UnpluginConsole

wrong:

import { UnpluginConsole } from 'unplugin-console/vite'

correct:

import UnpluginConsole from 'unplugin-console/vite'

For Vite projects, use the `/vite` subpath and import as a default export.

UnpluginConsole
wrong:
```
import UnpluginConsole from 'unplugin-console/webpack'
```
correct:
```
const UnpluginConsole = require('unplugin-console/webpack')
```
For Webpack (including Vue CLI's configureWebpack), use the `/webpack` subpath and require it as a CommonJS module.
Options
```
import type { Options } from 'unplugin-console'
```
Import types for configuration options directly from the base package if needed for type checking.

Quickstart

This Vite configuration integrates unplugin-console, forwarding all browser console messages (log, info, warn, error) to the dev-server terminal with a custom prefix.

import { defineConfig } from 'vite'
import UnpluginConsole from 'unplugin-console/vite'

export default defineConfig({
  plugins: [
    UnpluginConsole({
      levels: ['log', 'info', 'warn', 'error'],
      prefix: '[Browser Log]'
    }),
  ],
})

view raw JSON →