Skip to content

Getting Started

Learn how to install, set up, and start graphing numerical values with console-graph in just a few minutes.

Installation

Install the package via your preferred Node.js package manager:

npm install console-graph

yarn add console-graph

pnpm add console-graph

3 Ways to Use

console-graph is designed to adapt to your style—whether you need zero-configuration setup, fine-grained object-oriented control, or a simple one-off string generator.

Method 1: Console Auto-Patching (Zero Config)

The absolute fastest way to get started is by importing the /register module. This injects the console.graph(value, options?) and console.graphReset(label?) methods directly into the global console object.

import 'console-graph/register';

// Graph is automatically created and tracked by label name
console.graph(42, { label: 'Memory', unit: 'MB' });
console.graph(45, { label: 'Memory', unit: 'MB' });
console.graph(50, { label: 'Memory', unit: 'MB' });

require('console-graph/register');

console.graph(72, { label: 'CPU', unit: '%' });

<script type="module">
  import 'https://cdn.jsdelivr.net/npm/console-graph/dist/register.mjs';

  // Works instantly in browser DevTools!
  setInterval(() => {
    console.graph(Math.random() * 100, { label: 'Random', unit: '%' });
  }, 500);
</script>

Tip

Global auto-patched graphs share their configurations across files. If you call console.graph(val, { label: 'CPU', unit: '%' }), the first call configures the graph. Subsequent calls with the same label will read from the same instance and update the rolling window.

Method 2: The ConsoleGraph Class (Full Control)

If you prefer avoiding global scope modification or need complete control over graph lifecycles, import and instantiate the ConsoleGraph class directly.

import { ConsoleGraph } from 'console-graph';

// Create a configured instance
const latencyTracker = new ConsoleGraph({
  label: 'API Latency',
  unit: 'ms',
  bufferSize: 15,
  gradient: 'ocean',
  showStats: true
});

// Log values
latencyTracker.log(120); // Adds 120 and prints the graph
latencyTracker.log(145); // Adds 145 and prints the graph

// Add values silently without logging
latencyTracker.push(98);

// Print the current state manually
latencyTracker.print();

Method 3: One-Shot sparkline() (Convenience Utility)

Need to render a static sparkline representing a fixed historical set of data points? Use the sparkline(values, options?) function. It takes an array of numbers and returns a fully formatted string.

import { sparkline } from 'console-graph';

const numbers = [12, 19, 3, 5, 2, 3, 30, 42, 23, 10];
const chart = sparkline(numbers, { label: 'Historical Trend', gradient: 'cool' });

console.log(chart);
// Output: Historical Trend: [▂▃  ▂▆█▄▂] 10

Common Configuration Patterns

Here are a few quick parameters you will commonly tweak (refer to the API Reference for the full list):

  • bufferSize: Dictates the length of the sparkline chart. Defaults to 20.
  • gradient: Sets the theme. Options include 'green', 'heat', 'cool', 'mono', 'ocean', and 'none'.
  • min / max: Explicitly locks the bounds. If omitted, the sparkline scales automatically based on the lowest and highest values currently in the sliding buffer window.
  • showStats: Appends descriptive statistics (min, max, average) to the output line.