vite-build-monitor

1.0.5 verified Sat Apr 25 auth: no javascript

A Vite plugin (v1.0.5) that monitors heap and RSS memory usage during the build process. It records memory snapshots at configurable intervals, tracks peak usage per build phase, and outputs a summary of the top memory-consuming phases. The plugin supports pretty or JSON log formats, exclusion of specific hooks from logging, and optional uncaught exception capture. It requires Node >=22.0.0 and ships TypeScript declarations. Compared to generic process monitoring, this plugin provides phase-level tracking integrated with Vite's build hooks (buildStart, renderChunk, etc.).

Common errors

error ERR_REQUIRE_ESM: require() of ES Module 'vite-build-monitor' from ... not supported. ↓

cause The package is ESM-only, and you are using require() instead of import.

fix

Use import statement: import memoryMonitor from 'vite-build-monitor';

error TypeError: Cannot read properties of undefined (reading 'sampleIntervalMs') ↓

cause Importing the plugin without calling it as a function (e.g., passing memoryMonitor directly instead of memoryMonitor()).

fix

Call the function: plugins: [memoryMonitor({ ... })]

error Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'vite-build-monitor' ↓

cause Package not installed, or installed as devDependency but runtime resolution fails.

fix

Ensure the package is installed: pnpm add -D vite-build-monitor

Warnings

breaking This package requires Node.js >=22.0.0. Older Node versions will fail to install or import. ↓

fix Upgrade Node.js to v22 or later.

gotcha The sampleIntervalMs option is clamped to minimum 50ms. Setting a value <50 will be silently uplifted to 50. ↓

fix Explicitly set sampleIntervalMs to at least 50 if you need fine-grained polling.

gotcha The logFile path is resolved relative to process.cwd(), not the project root. This can lead to unexpected file locations. ↓

fix Always use an absolute path or ensure cwd is the project root when specifying logFile.

deprecated No deprecated features currently. This is a young package (v1.0.5). Future versions may change defaults or remove options. ↓

fix Pin to a specific version and review changelog before upgrading.

Install

npm install vite-build-monitor

yarn add vite-build-monitor

pnpm add vite-build-monitor

Imports

default (memoryMonitor)

wrong

const memoryMonitor = require('vite-build-monitor')

correct

import memoryMonitor from 'vite-build-monitor'

ESM-only; default export. TypeScript types included.

MemoryMonitorOptions

wrong

import { MemoryMonitorOptions } from 'vite-build-monitor'

correct

import type { MemoryMonitorOptions } from 'vite-build-monitor'

Type import only; the interface is not a runtime value.

HookName

wrong

const { HookName } = require('vite-build-monitor')

correct

import type { HookName } from 'vite-build-monitor'

This is a type union, not a value; requires type import.

Quickstart

Configure vite-build-monitor as a Vite plugin with custom options: log file path, polling interval, log format, and hook exclusions.

// vite.config.ts
import { defineConfig } from 'vite';
import memoryMonitor from 'vite-build-monitor';

export default defineConfig({
  plugins: [
    memoryMonitor({
      logFile: './build-memory.log',
      sampleIntervalMs: 100,
      logFormat: 'pretty',
      summaryTopN: 3,
      excludeHooks: ['buildEnd', 'renderStart'],
      printSummary: true,
    }),
  ],
});