Reporter

Reporter plugins receive events from Parcel as they happen throughout the build process. For example, reporters may write status information to stdout, run a dev server, or generate a bundle analysis report at the end of a build.

Example

This example writes the number of bundles and build time to stdout when a build is successful.

import {Reporter} from '@parcel/plugin';

export default new Reporter({
  report({event}) {
    if (event.type === 'buildSuccess') {
      let bundles = event.bundleGraph.getBundles();
      process.stdout.write(`✨ Built ${bundles.length} bundles in ${event.buildTime}ms!\n`);
    }
  }
});

Build start

The buildStart event is emitted when a build is started. In watch mode, it is emitted at the start of each rebuild.

import {Reporter} from '@parcel/plugin';

export default new Reporter({
  report({event}) {
    if (event.type === 'buildStart') {
      process.stdout.write('Started build!\n');
    }
  }
});

Build progress

The buildProgress event is emitted throughout the build. It includes a phase property that indicates which phase of the build is occurring, and events include additional information specific to the phase. For example, events in the transforming phase include a filePath property of the asset being transformed. See BuildProgressEvent.

import {Reporter} from '@parcel/plugin';

export default new Reporter({
  report({event}) {
    if (event.type === 'buildProgress') {
      switch (event.phase) {
        case 'transforming':
          process.stdout.write(`Transforming ${event.filePath}...\n`);
          break;
        case 'resolving':
          process.stdout.write(`Resolving ${event.dependency.specifier}...\n`);
          break;
        case 'bundling':
          process.stdout.write('Bundling...\n');
          break;
        case 'packaging':
          process.stdout.write(`Packaging ${event.bundle.displayName}...\n`);
          break;
        case 'optimizing':
          process.stdout.write(`Optimizing ${event.bundle.displayName}...\n`);
         break;
      }
    }
  }
});

Build success

The buildSuccess event is emitted when a build completes successfully. It includes the full bundleGraph that was built, the buildTime, and a list of changedAssets.

import {Reporter} from '@parcel/plugin';

export default new Reporter({
  report({event}) {
    if (event.type === 'buildSuccess') {
      process.stdout.write(`✨ Rebuilt ${event.changedAssets.size} assets in ${event.buildTime}ms!\n`);
    }
  }
});

Build failure

The buildFailure event is emitted when a build is completes with errors. It includes a list of Diagnostic objects describing the errors. See Diagnostics for details.

import {Reporter} from '@parcel/plugin';

export default new Reporter({
  report({event}) {
    if (event.type === 'buildFailure') {
      process.stdout.write(`🚨 Build failed with ${event.diagnostics.length} errors.\n`);
    }
  }
});

Logging

All logging in Parcel is routed through Reporter plugins. The level property indicates the type of each log event. The info, warn, error, and verbose log levels include a Diagnostic object, which provides detail about the context of the log. Other log levels include only a message property.

import {Reporter} from '@parcel/plugin';

export default new Reporter({
  report({event}) {
    if (event.type === 'log') {
      switch (event.level) {
        case 'info':
        case 'verbose':
          process.stdout.write(`ℹ️ ${event.diagnostic.message}\n`);
          break;
        case 'warn':
          process.stdout.write(`⚠️ ${event.diagnostic.message}\n`);
          break;
        case 'error':
          process.stdout.write(`🚨 ${event.diagnostic.message}\n`);
          break;
      }
    }
  }
});

Watcher events

The watchStart and watchEnd events are emitted when watch mode starts and ends. Unlike buildStart and buildSuccess/buildFailure, the watcher events are only fired once rather than for each build.

import {Reporter} from '@parcel/plugin';

export default new Reporter({
  report({event}) {
    if (event.type === 'watchStart') {
      process.stdout.write(`Watching started\n`);
    } else if (event.type === 'watchEnd') {
      process.stdout.write(`Watching ended\n`);
    }
  }
});

Relevant API

type ProgressLogEvent = {|

  +type: 'log',

  +level: 'progress',

  +phase?: string,

  +message: string,

|}

type DiagnosticLogEvent = {|

  +type: 'log',

  +level: 'error' | 'warn' | 'info' | 'verbose',

  +diagnostics: Array<Diagnostic>,

|}

type TextLogEvent = {|

  +type: 'log',

  +level: 'success',

  +message: string,

|}

type LogEvent = ProgressLogEvent | DiagnosticLogEvent | TextLogEvent;

type BuildStartEvent = {|

  +type: 'buildStart',

|}

type WatchStartEvent = {|

  +type: 'watchStart',

|}

type WatchEndEvent = {|

  +type: 'watchEnd',

|}

type ResolvingProgressEvent = {|

  +type: 'buildProgress',

  +phase: 'resolving',

  +dependency: Dependency,

|}

type TransformingProgressEvent = {|

  +type: 'buildProgress',

  +phase: 'transforming',

  +filePath: FilePath,

|}

type BundlingProgressEvent = {|

  +type: 'buildProgress',

  +phase: 'bundling',

|}

type PackagingProgressEvent = {|

  +type: 'buildProgress',

  +phase: 'packaging',

  +bundle: NamedBundle,

|}

type OptimizingProgressEvent = {|

  +type: 'buildProgress',

  +phase: 'optimizing',

  +bundle: NamedBundle,

|}

type BuildProgressEvent = ResolvingProgressEvent | TransformingProgressEvent | BundlingProgressEvent | PackagingProgressEvent | OptimizingProgressEvent;

type BuildSuccessEvent = {|

  +type: 'buildSuccess',

  +bundleGraph: BundleGraph<PackagedBundle>,

  +buildTime: number,

  +changedAssets: Map<string, Asset>,

  +requestBundle: (bundle: NamedBundle) => Promise<BuildSuccessEvent>,

|}

type BuildFailureEvent = {|

  +type: 'buildFailure',

  +diagnostics: Array<Diagnostic>,

|}

type BuildEvent = BuildFailureEvent | BuildSuccessEvent;

type ValidationEvent = {|

  +type: 'validation',

  +filePath: FilePath,

|}

type ReporterEvent = LogEvent | BuildStartEvent | BuildProgressEvent | BuildSuccessEvent | BuildFailureEvent | WatchStartEvent | WatchEndEvent | ValidationEvent;

type Reporter = {|

  report({|
    event: ReporterEvent,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<void>,

|}