babel-plugin-shotgun-logs

0.0.5 verified Sat Apr 25 auth: no javascript

A Babel plugin for automatically injecting detailed function entry and exit log statements into JavaScript code. Version 0.0.5 is the latest. The plugin instruments every function call with colored entry/exit logs including argument values, return values, and nested call indentation. It integrates with log management tools and supports options for function blacklisting, blackout lists, external JSON storage, and time profiling. Differentiates from simple logging libraries by being compile-time, thus requiring no runtime changes and providing full call tree visibility.

Common errors

error ReferenceError: regeneratorRuntime is not defined ↓

cause Babel transforms async functions but does not polyfill regeneratorRuntime. This plugin does not add the polyfill.

fix

Add @babel/plugin-transform-runtime and @babel/runtime to your Babel config.

error TypeError: Cannot read property 'toString' of undefined ↓

cause The plugin tries to log arguments that are undefined, causing a crash when calling .toString.

fix

Set entryLogShowFullArgs to false or ensure all function arguments are defined.

error Module not found: Can't resolve 'aws-sdk' ↓

cause storeJSONexternally with location 's3' requires aws-sdk as a peer dependency, which is not installed automatically.

fix

Install aws-sdk: npm install aws-sdk --save-dev

Warnings

gotcha Plugin modifies all functions, including third-party code if not scoped. Use withIncludes/withExcludes to restrict. ↓

fix Configure Babel to exclude node_modules by default or use include/exclude patterns.

gotcha Logging large arguments with entryLogShowFullArgs can produce enormous log files, potentially filling disk. ↓

fix Set entryLogShowFullArgs to false or use storeJSONexternally with a reasonable sizeThreshold.

gotcha The plugin does not work with TypeScript out-of-the-box; it only transforms JavaScript. ↓

fix Use @babel/preset-typescript to strip types before this plugin runs, or use babel-plugin-ts2js.

gotcha S3 storage (storeJSONexternally.location: 's3') requires AWS credentials via environment variables, which may be a security risk. ↓

fix Ensure AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set properly and restricted to the specific bucket.

Install

npm install babel-plugin-shotgun-logs

yarn add babel-plugin-shotgun-logs

pnpm add babel-plugin-shotgun-logs

Imports

default

wrong

const plugin = require('babel-plugin-shotgun-logs').default

correct

import plugin from 'babel-plugin-shotgun-logs'

ESM default import works; CJS require yields the plugin function directly.

(plugin is default export)
wrong
```
plugins: [{ 'babel-plugin-shotgun-logs': {} }]
```
correct
```
plugins: ['babel-plugin-shotgun-logs']
```
Do not wrap with extra object. In .babelrc or babel.config.js, just use the string name or an array tuple.

Quickstart

Shows installation, Babel configuration, and an example of instrumented function entry/exit logs.

// Install: npm install babel-plugin-shotgun-logs --save-dev
// In .babelrc:
{
  "plugins": [
    ["babel-plugin-shotgun-logs", {
      "isTerminal": true,
      "entryLogShowFullArgs": true,
      "exitLogReturnOutputInline": true
    }]
  ]
}

// Example instrumented code (before/after):
// Before:
function add(a, b) {
  return a + b;
}
// After (output to log):
// 🟢  add( a: 2, b: 3 ) {"a":2,"b":3}
// 🔴  add() ⇒ 5 {"return":5}