fastfetch-json

A robust, fully-typed Node.js wrapper for fastfetch.

fastfetch is a popular, blazing-fast system information tool widely used on Linux (especially Arch-based distros like CachyOS), macOS, and Windows. This package spawns it, parses its native --format json output, and exposes it as strictly typed data — no scraping of colored terminal output required.

If fastfetch isn't already found on your system PATH, the installer automatically downloads the correct prebuilt binary for your platform/architecture. It eliminates the need to install fastfetch yourself first — though if you already have it (e.g. via pacman -S fastfetch), that system copy is used instead.

Installation

npm install fastfetch-json

Usage Guide

The API is fully Promise-based and returns strictly typed objects.

1. Fetching the Full System Report

The getInfo method runs a complete fastfetch fetch and returns every module fastfetch collected, both as a raw ordered list and as a flat, easy-to-index object.

import fastfetch from 'fastfetch-json';

async function fetchSystemInfo() {
  const info = await fastfetch.getInfo();

  console.log(info.modules.OS.prettyName);   // CachyOS
  console.log(info.modules.CPU.cpu);         // AMD Ryzen 9 9950X
  console.log(info.raw.length);              // total modules fastfetch reported
}

JSON Output Structure Example:

{
  "raw": [
    { "type": "OS", "result": { "name": "CachyOS Linux", "prettyName": "CachyOS" } },
    { "type": "CPU", "result": { "cpu": "AMD Ryzen 9 9950X", "cores": { "physical": 16, "logical": 32 } } }
  ],
  "modules": {
    "OS": { "name": "CachyOS Linux", "prettyName": "CachyOS" },
    "CPU": { "cpu": "AMD Ryzen 9 9950X", "cores": { "physical": 16, "logical": 32 } }
  }
}

2. Fetching Only Specific Modules

getModules restricts the fetch to the module keys you ask for (--structure), which is significantly faster than a full getInfo() call when you only need a few values.

import fastfetch from 'fastfetch-json';

const { CPU, Memory, GPU } = await fastfetch.getModules(['CPU', 'Memory', 'GPU']);
console.log(CPU.cpu, Memory.total, GPU);

3. Fetching a Single Module

getModule is a convenience shortcut for a single module, typed via a generic parameter. It throws ModuleUnavailableError when fastfetch reports the module as unsupported instead of returning data (e.g. Battery on a desktop machine).

import fastfetch, { ModuleUnavailableError } from 'fastfetch-json';

try {
  const battery = await fastfetch.getModule<{ percentage: number }>('Battery');
  console.log(`${battery.percentage}%`);
} catch (err) {
  if (err instanceof ModuleUnavailableError) {
    console.log('No battery on this machine.');
  }
}

4. Human-Readable Output

getPretty returns fastfetch's normal terminal output (with logo and ANSI colors, unless you override it via args) as a plain string — useful for piping into a terminal-rendering UI.

import fastfetch from 'fastfetch-json';

const text = await fastfetch.getPretty({ args: ['--logo', 'none'] });
console.log(text);

5. Watching System Stats Over Time

watch polls the report on an interval and calls onUpdate with each fetch — ideal for a live status bar or system monitor widget. Restrict it to a few cheap modules for frequent polling.

import fastfetch from 'fastfetch-json';

const stop = fastfetch.watch(
  (info) => console.log('CPU:', info.modules.CPU),
  { intervalMs: 2000, modules: ['CPU', 'Memory'] }
);

// later, to stop polling:
stop();

6. Cancelling In-Flight Requests

Every method that spawns fastfetch accepts an AbortSignal via options.signal.

import fastfetch from 'fastfetch-json';

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await fastfetch.getInfo({ signal: controller.signal });

7. Typed Errors

Failures are classified into specific error subclasses so callers can branch on why fastfetch failed instead of parsing stderr themselves.

import fastfetch, {
  NotInstalledError,
  InvalidArgumentError,
  ModuleUnavailableError,
  ParseError,
} from 'fastfetch-json';

try {
  await fastfetch.getInfo();
} catch (err) {
  if (err instanceof NotInstalledError) {
    // fastfetch binary missing and no managed copy could be installed
  }
  throw err;
}

8. Checking for / Applying Updates

checkForUpdate compares the running binary's version against the latest GitHub release; updateBinary re-downloads and replaces the managed binary (only works when using a copy this package downloaded itself, not a system install).

import fastfetch from 'fastfetch-json';

const status = await fastfetch.checkForUpdate();
if (status.updateAvailable) {
  const newVersion = await fastfetch.updateBinary();
  console.log('Updated to', newVersion);
}

API Reference

• new FastFetch(binaryPath?: string) Creates a wrapper instance. Defaults to a managed binary if the postinstall script downloaded one, otherwise fastfetch on PATH.

• fastfetch.getInfo(options?: FastFetchOptions): Promise<FastFetchInfo> Fetches the full system report as a raw module list plus a flat modules lookup.

• fastfetch.getModules(names: string[], options?: FastFetchOptions): Promise<Record<string, unknown>> Fetches only the requested module keys, faster than a full getInfo call.

• fastfetch.getModule<T>(name: string, options?: FastFetchOptions): Promise<T> Fetches a single module's data; throws ModuleUnavailableError if unsupported.

• fastfetch.getPretty(options?: FastFetchOptions): Promise<string> Returns fastfetch's normal human-readable text output.

• fastfetch.version(): Promise<string> Returns the version string of the underlying fastfetch binary.

• fastfetch.checkForUpdate(): Promise<UpdateCheckResult> Checks whether a newer fastfetch release exists, without installing it.

• fastfetch.updateBinary(): Promise<string> Downloads the latest fastfetch release and replaces the managed binary. Returns the new version tag.

• fastfetch.watch(onUpdate: (info: FastFetchInfo) => void, options?: WatchOptions): () => void Polls the system report on an interval and invokes onUpdate for every fetch. Returns a stop function.

• fastfetch.exec(args: string[], signal?: AbortSignal): Promise<string> Executes fastfetch with arbitrary arguments and returns raw stdout.

License

MIT