crossterm-system-theme

Detect the current system theme (light / dark) in Node.js CLI and TUI apps — and optionally monitor for live theme changes.

Install

npm i crossterm-system-theme

Read current theme

import { getSystemTheme } from 'crossterm-system-theme'

const theme = await getSystemTheme()
console.log(theme) // 'light' | 'dark'

Monitor theme changes

import {
  monitorSystemTheme,
  MonitoringUnsupportedError
} from 'crossterm-system-theme'

try {
  const monitor = await monitorSystemTheme((theme) => {
    console.log('Theme changed to:', theme)
  })

  // later, when you no longer need updates:
  monitor.stop()
} catch (error) {
  if (error instanceof MonitoringUnsupportedError) {
    console.log('Live monitoring is unavailable here. Fall back to polling.')
  } else {
    throw error
  }
}

API

• getSystemTheme(): Promise<'light' | 'dark'>
• monitorSystemTheme(onChange): Promise<{ stop(): void }>
• MonitoringUnsupportedError
• ThemeDetectionError

Notes

• monitorSystemTheme is a native event listener (no internal polling fallback).
• On macOS, monitoring runs through a dedicated native helper process with an AppKit run loop (improves reliability for Control Center / menu bar toggles).
• If native monitoring is unavailable in the current platform/session, monitorSystemTheme throws MonitoringUnsupportedError so you can gracefully fall back to your own polling strategy.