Unplugin Build Time Statistics

0.3.0 · active · verified Tue Apr 21

unplugin-time-stat is a utility that provides unified build time stat reporting across various JavaScript bundlers, including Vite, Webpack, Rspack, Rollup, and esbuild, by leveraging the `unplugin` ecosystem. It addresses the common challenge of inconsistent build performance reporting mechanisms across different build tools, offering a single interface to monitor and report build durations. The current stable version is `0.3.0`. The project has seen regular, feature-driven releases, indicating active development. A key differentiator is its ability to integrate custom hooks, allowing developers to programmatically capture build metrics and integrate them with external services or custom reporting tools, beyond just console output. This makes it a versatile tool for performance monitoring in diverse build environments.

Common errors

```
Cannot find module 'unplugin-time-stat/vite'
```
cause The specific bundler integration module could not be found, often due to a typo in the import path or a missing `unplugin-time-stat` package installation.

fix Verify the package is installed (`npm install unplugin-time-stat`) and that the import path matches your bundler (e.g., `unplugin-time-stat/vite`, `unplugin-time-stat/webpack`).
```
TypeError: TimeStat is not a function
```
cause This error occurs when trying to invoke `TimeStat` as a function, but the imported value is not a function. This can happen with incorrect CommonJS `require` usage for an ESM default export, or vice-versa.

fix Ensure you are using the correct import syntax for your environment: `import TimeStat from '...'` for ESM, and `const TimeStat = require('...')` for CommonJS, especially for Webpack/Rspack integrations.

Warnings

gotcha This package acts as an `unplugin` wrapper, requiring you to import the specific bundler integration (e.g., `/vite`, `/webpack`). Importing the wrong path for your bundler will lead to runtime errors or the plugin not functioning.
Fix: Ensure you are importing `unplugin-time-stat/<your-bundler>` (e.g., `/vite`, `/rollup`, `/esbuild`, `/webpack`, `/nuxt`) as per your project's build tool.
gotcha Using `unplugin-time-stat` requires the corresponding bundler package (e.g., `vite`, `webpack`, `rollup`, `esbuild`, `@nuxt/kit`) as a peer dependency. If the peer dependency is not installed, the plugin might fail to initialize or cause resolution errors.
Fix: Install the appropriate peer dependency for your bundler, e.g., `npm install vite` or `npm install webpack`.
gotcha As a `0.x.x` version package, the API of `unplugin-time-stat` might undergo minor changes in future releases. While recent updates have been additive, always review release notes for potential adjustments.
Fix: Refer to the official GitHub repository's release notes for each new version to understand any API changes or new features.

Install

npm install unplugin-time-stat npm
yarn add unplugin-time-stat yarn
pnpm add unplugin-time-stat pnpm

Imports

TimeStat (Vite)

wrong:

const TimeStat = require('unplugin-time-stat/vite')

correct:

import TimeStat from 'unplugin-time-stat/vite'

Use this specific import for Vite projects. ESM syntax is preferred.

TimeStat (Webpack)
wrong:
```
import TimeStat from 'unplugin-time-stat/webpack'
```
correct:
```
const TimeStat = require('unplugin-time-stat/webpack')
```
Webpack and Rspack configurations often use CommonJS `require` for plugins. Also applicable for Vue CLI.
TimeStat (Nuxt module)
wrong:
```
import TimeStat from 'unplugin-time-stat/nuxt'
```
correct:
```
export default defineNuxtConfig({ modules: [['unplugin-time-stat/nuxt', {}]] })
```
Nuxt integration is typically added as a string path in the `modules` array within `defineNuxtConfig`.
TimeStatHook
```
import type { TimeStatHook } from 'unplugin-time-stat'
```
Imports the TypeScript type definition for custom build hooks, available since v0.3.0.

Quickstart

This quickstart demonstrates how to integrate unplugin-time-stat into a Vite project with a custom hook to process build time metrics.

import { defineConfig } from 'vite'
import TimeStat from 'unplugin-time-stat/vite'

function metrics(buildTime, raw) {
  // raw contains { start: Date, end: Date, buildTime: string }
  const duration = raw.end.getTime() - raw.start.getTime();
  console.log(`[Custom Metrics] Build finished in ${duration}ms`);
  // Example: send data to an external monitoring service
  // sendToDatadog('build_time', duration);
  
  // Optionally return a string to be displayed in the console
  return `Custom Report: ${duration}ms`;
}

export default defineConfig({
  plugins: [
    TimeStat({
      hook: metrics,
      // Optional: disable default console output if you only want custom handling
      // outputConsole: false 
    })
  ]
})

view raw JSON →