CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-envinfo

Command-line tool and library for collecting development environment information needed for debugging and troubleshooting software issues

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

output-formatting.mddocs/

Output Formatting

Multiple output formats with customizable options for different use cases including YAML, JSON, and Markdown formatting.

Capabilities

YAML Formatting (Default)

Default human-readable format with hierarchical structure and console styling options.

/**
 * Format environment data as YAML (default format)
 * @param data - Environment data object to format
 * @param options - Formatting options including console styling and title
 * @returns string - YAML formatted output with optional console colors
 */
formatters.yaml(data, options);

Usage Examples:

const { formatters } = require('envinfo');

// Basic YAML formatting
const data = {
  System: {
    OS: 'macOS Mojave 10.14.5',
    CPU: '(8) x64 Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz'
  },
  Binaries: {
    Node: '16.14.0 - /usr/local/bin/node',
    npm: '8.3.1 - /usr/local/bin/npm'
  }
};

const yamlOutput = formatters.yaml(data);
console.log(yamlOutput);
// Output:
// System:
//   OS: macOS Mojave 10.14.5
//   CPU: (8) x64 Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz
// Binaries:
//   Node: 16.14.0 - /usr/local/bin/node
//   npm: 8.3.1 - /usr/local/bin/npm

// With console styling (for terminal output)
const styledOutput = formatters.yaml(data, { console: true });

// With title
const titledOutput = formatters.yaml(data, { 
  title: 'Development Environment Report',
  console: true 
});

JSON Formatting

Structured JSON output for programmatic consumption and API integration.

/**
 * Format environment data as JSON with optional indentation
 * @param data - Environment data object to format
 * @param options - Formatting options including indentation and title
 * @returns string - JSON formatted output
 */
formatters.json(data, options);

Usage Examples:

const { formatters } = require('envinfo');

const data = {
  System: { OS: 'Ubuntu 20.04.1 LTS', CPU: '(4) x64 Intel i5-8265U' },
  Binaries: { Node: '16.14.0', npm: '8.3.1' }
};

// Basic JSON formatting
const jsonOutput = formatters.json(data);
console.log(jsonOutput);
// Output: {"System":{"OS":"Ubuntu 20.04.1 LTS","CPU":"(4) x64 Intel i5-8265U"},...}

// Pretty-printed JSON with custom indentation
const prettyJson = formatters.json(data, { indent: '  ' });
console.log(prettyJson);
// Output:
// {
//   "System": {
//     "OS": "Ubuntu 20.04.1 LTS",
//     "CPU": "(4) x64 Intel i5-8265U"
//   },
//   "Binaries": {
//     "Node": "16.14.0",
//     "npm": "8.3.1"
//   }
// }

// With title wrapper
const titledJson = formatters.json(data, { 
  title: 'Environment Report',
  console: true 
});
// Output includes title as top-level key

Markdown Formatting

Markdown format suitable for documentation, issue templates, and reports.

/**
 * Format environment data as Markdown
 * @param data - Environment data object to format
 * @param options - Formatting options including title
 * @returns string - Markdown formatted output with headers and lists
 */
formatters.markdown(data, options);

Usage Examples:

const { formatters } = require('envinfo');

const data = {
  System: { OS: 'Windows 10', CPU: '(8) x64 AMD Ryzen 7' },
  Binaries: { Node: '16.14.0', npm: '8.3.1' },
  Browsers: { Chrome: '98.0.4758.102', Firefox: '97.0.1' }
};

// Basic markdown formatting
const markdownOutput = formatters.markdown(data);
console.log(markdownOutput);
// Output:
// # System
//  - OS: Windows 10
//  - CPU: (8) x64 AMD Ryzen 7
// # Binaries
//  - Node: 16.14.0
//  - npm: 8.3.1
// # Browsers
//  - Chrome: 98.0.4758.102
//  - Firefox: 97.0.1

// With custom title
const titledMarkdown = formatters.markdown(data, { 
  title: 'Bug Report Environment' 
});
// Output starts with:
// # Bug Report Environment
// ## System
// ...

Formatting Options

interface FormattingOptions {
  console?: boolean;        // Enable console colors and styling (YAML only)
  title?: string;          // Add title to output
  indent?: string;         // JSON indentation (default: '  ')
  showNotFound?: boolean;  // Include "Not Found" values
  duplicates?: boolean;    // Format duplicate package information
}

Integration with Core Functions

Formatters are automatically applied based on options passed to core functions:

const envinfo = require('envinfo');

// Automatic YAML formatting (default)
const yamlResult = await envinfo.run({
  System: ['OS', 'CPU'],
  Binaries: ['Node', 'npm']
});

// Automatic JSON formatting
const jsonResult = await envinfo.run({
  System: ['OS', 'CPU'],
  Binaries: ['Node', 'npm']
}, { json: true });

// Automatic Markdown formatting
const markdownResult = await envinfo.run({
  System: ['OS', 'CPU'], 
  Binaries: ['Node', 'npm']
}, { markdown: true });

// With title and console output
const styledResult = await envinfo.run({
  System: ['OS', 'CPU']
}, { 
  console: true, 
  title: 'Development Environment' 
});

Data Preprocessing

All formatters apply consistent data preprocessing:

// Data cleaning and transformation steps:
interface DataPreprocessing {
  clean: (data, options) => object;           // Remove empty/not found values
  formatPackages: (data) => object;          // Format npm package information
  serializeArrays: (data) => object;         // Convert arrays to comma-separated strings
  serializeVersionsAndPaths: (data) => object; // Combine version and path info
}

Example of preprocessing:

// Raw data from helpers
const rawData = {
  System: {
    OS: 'macOS Mojave 10.14.5',
    CPU: '(8) x64 Intel Core i7',
    Memory: '8.00 GB / 16.00 GB'
  },
  Binaries: {
    Node: { version: '16.14.0', path: '/usr/local/bin/node' },
    npm: { version: '8.3.1', path: '/usr/local/bin/npm' }
  },
  npmPackages: {
    react: { installed: '17.0.2', wanted: '^17.0.0', duplicates: ['16.14.0'] },
    lodash: 'Not Found'
  }
};

// After preprocessing (with showNotFound: false)
const processedData = {
  System: {
    OS: 'macOS Mojave 10.14.5',
    CPU: '(8) x64 Intel Core i7', 
    Memory: '8.00 GB / 16.00 GB'
  },
  Binaries: {
    Node: '16.14.0 - /usr/local/bin/node',
    npm: '8.3.1 - /usr/local/bin/npm'
  },
  npmPackages: {
    react: '^17.0.0 => 17.0.2 (16.14.0)'  // wanted => installed (duplicates)
  }
  // lodash removed because it was 'Not Found'
};

Console Styling

YAML formatter supports console styling for terminal output:

// Console styling features:
const styledOptions = {
  console: true,  // Enables the following features:
  // - Underlined headers
  // - Color coding for different data types
  // - Enhanced readability in terminal
};

// Example styled output:
const styledOutput = formatters.yaml(data, { console: true });
// Headers will be underlined when displayed in terminal
// System:      <- underlined
//   OS: macOS Mojave 10.14.5
//   CPU: (8) x64 Intel Core i7

Custom Formatting Pipeline

For advanced use cases, you can use the formatting pipeline directly:

const { formatters, utils } = require('envinfo');

// Custom formatting pipeline
const customFormat = (data, options) => {
  return utils.pipe([
    () => clean(data, options),
    formatPackages,
    serializeArrays, 
    serializeVersionsAndPaths,
    options.title ? d => ({ [options.title]: d }) : utils.noop,
    formatters.yaml,
    options.console ? formatHeaders : utils.noop,
  ])(data, options);
};

Output Examples

YAML Output:

System:
  OS: macOS Mojave 10.14.5
  CPU: (8) x64 Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz
  Memory: 2.97 GB / 16.00 GB
Binaries:
  Node: 16.14.0 - /usr/local/bin/node
  npm: 8.3.1 - /usr/local/bin/npm

JSON Output:

{
  "System": {
    "OS": "macOS Mojave 10.14.5",
    "CPU": "(8) x64 Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz",
    "Memory": "2.97 GB / 16.00 GB"
  },
  "Binaries": {
    "Node": "16.14.0 - /usr/local/bin/node",
    "npm": "8.3.1 - /usr/local/bin/npm"
  }
}

Markdown Output:

# System
 - OS: macOS Mojave 10.14.5
 - CPU: (8) x64 Intel(R) Core(TM) i7-7820HQ CPU @ 2.90GHz
 - Memory: 2.97 GB / 16.00 GB
# Binaries
 - Node: 16.14.0 - /usr/local/bin/node
 - npm: 8.3.1 - /usr/local/bin/npm

Install with Tessl CLI

npx tessl i tessl/npm-envinfo

docs

configuration-presets.md

core-functions.md

environment-detection.md

index.md

output-formatting.md

package-management.md

tile.json