Skip to content

npm Package

Jump to bottom
Alex Neamtu edited this page Jan 16, 2026 · 1 revision

npm Package

The htoprc parser is available as a standalone npm package for use in your own projects.

npm

Installation

npm install @htoprc/parser
# or
pnpm add @htoprc/parser
# or
yarn add @htoprc/parser

Features

  • Parse htoprc files into typed TypeScript objects
  • Serialize config objects back to htoprc format
  • Support for htop 2.x and 3.x config formats
  • Zero runtime dependencies
  • Full TypeScript support

Quick Start

Parsing an htoprc file

import { parseHtoprc } from '@htoprc/parser'
import { readFileSync } from 'fs'

const content = readFileSync('~/.config/htop/htoprc', 'utf-8')
const result = parseHtoprc(content)

console.log(result.config.colorScheme)     // 0-6
console.log(result.config.treeView)        // true/false
console.log(result.config.leftMeters)      // [{ type: 'CPU', mode: 'bar' }, ...]
console.log(result.version)                // 'v3' | 'v2' | 'unknown'
console.log(result.warnings)               // Any parsing warnings

Serializing a config

import { serializeHtoprc, parseHtoprc } from '@htoprc/parser'

const result = parseHtoprc(content)

// Modify the config
result.config.colorScheme = 5
result.config.treeView = true

// Serialize back to htoprc format
const output = serializeHtoprc(result.config)
// Write to ~/.config/htop/htoprc

API Reference

parseHtoprc(input: string): ParseResult

Parses an htoprc configuration string.

Returns:

interface ParseResult {
  config: HtopConfig       // Parsed configuration
  warnings: ParseWarning[] // Non-fatal parsing issues
  errors: ParseError[]     // Fatal parsing errors
  version: 'v2' | 'v3' | 'unknown'
  score: number            // Config customization score
}

serializeHtoprc(config: HtopConfig, options?: SerializeOptions): string

Serializes an HtopConfig object back to htoprc format.

Options:

interface SerializeOptions {
  includeVersion?: boolean    // Include htop_version (default: true)
  onlyNonDefaults?: boolean   // Only non-default options (default: false)
  includeUnknown?: boolean    // Include unknown options (default: true)
}

DEFAULT_CONFIG

The default htoprc configuration values. Useful for comparison or creating new configs.

Types

HtopConfig

The main configuration interface includes:

Category Properties
Display colorScheme, headerLayout, showProgramPath, highlightBaseName, etc.
Meters leftMeters, rightMeters
Process List columns, sortKey, sortDirection, treeView
Threading hideKernelThreads, hideUserlandThreads
Screens screens (htop 3.x screen definitions)

Meter

interface Meter {
  type: string        // e.g., 'CPU', 'Memory', 'LoadAverage'
  mode: MeterMode     // 'bar' | 'text' | 'graph' | 'led'
}

HeaderLayout

Supported layouts:

  • two_50_50 (default)
  • two_33_67, two_67_33
  • three_33_34_33, three_25_25_50, three_25_50_25, three_50_25_25
  • four_25_25_25_25

Use Cases

  • Dotfiles managers - Parse and validate htoprc in dotfiles tools
  • Config generators - Generate htoprc programmatically
  • Visualization tools - Build htop config previewers
  • Migration scripts - Convert between htop versions
  • Backup tools - Extract and store htop settings

Links

Clone this wiki locally