@rolldown/debug

@rolldown/debug

Utilities and generated TypeScript types for reading Rolldown devtools output.

When devtools is enabled, Rolldown writes JSON-lines files to:

<cwd>/node_modules/.rolldown/<session_id>/
  meta.json
  logs.json

<cwd> is the build's InputOptions#cwd, which defaults to the working directory the build ran from. Resolve the files against it rather than your own working directory, which may differ.

logs.json is complete after await bundle.close() resolves.

Parse Events

import fs from 'node:fs';
import { parseToEvents, type Event, type StringRef } from '@rolldown/debug';

const data = fs.readFileSync('<cwd>/node_modules/.rolldown/<session_id>/logs.json', 'utf8');
const events = parseToEvents(data.trim());

type ActionEvent = Exclude<Event, StringRef> & { build_id: string };
const actionEvents = events.filter((event): event is ActionEvent => 'build_id' in event);

Action events include session_id, build_id, timestamp, and an action discriminator. StringRef events contain deduplicated large string content and do not belong to a specific build.

Consume Package Data

Use PackageGraphReady to build a package table. In watch/rebuild sessions, logs.json is append-only, so select the events for the build_id being displayed.

import fs from 'node:fs';
import { parseToEvents, type Event, type StringRef } from '@rolldown/debug';

type ActionEvent = Exclude<Event, StringRef> & { build_id: string };

function isActionEvent(event: Event): event is ActionEvent {
  return 'build_id' in event;
}

const data = fs.readFileSync('<cwd>/node_modules/.rolldown/<session_id>/logs.json', 'utf8');
const actionEvents = parseToEvents(data.trim()).filter(isActionEvent);
const buildId = actionEvents.at(-1)?.build_id;

function latest<T extends ActionEvent['action']>(
  action: T,
): Extract<ActionEvent, { action: T }> | undefined {
  for (let i = actionEvents.length - 1; i >= 0; i--) {
    const event = actionEvents[i];
    if (event.build_id === buildId && event.action === action) {
      return event as Extract<ActionEvent, { action: T }>;
    }
  }
}

const packageGraph = latest('PackageGraphReady');
const chunkGraph = latest('ChunkGraphReady');
const moduleGraph = latest('ModuleGraphReady');

const chunksById = new Map(chunkGraph?.chunks.map((chunk) => [chunk.chunk_id, chunk]) ?? []);
const modulesById = new Map(moduleGraph?.modules.map((module) => [module.id, module]) ?? []);

const packageRows = packageGraph?.packages.map((pkg) => ({
  id: pkg.package_id,
  label: pkg.name ?? pkg.package_root,
  version: pkg.version ?? 'unknown',
  dependencyType: pkg.dependency_type,
  renderedSize: pkg.size,
  isUsed: pkg.is_used,
  chunks: pkg.chunk_ids.flatMap((chunkId) => {
    const chunk = chunksById.get(chunkId);
    return chunk ? [chunk] : [];
  }),
  modules: pkg.modules.map(
    (moduleId) =>
      modulesById.get(moduleId) ?? {
        id: moduleId,
      },
  ),
}));

Package Fields

Field	Consumer meaning
package_id	Stable row key for one emitted package record. Prefer this, or package_root, over name@version.
name / version	Metadata from the resolved package manifest. Either can be null; fall back to package_root or an unknown version label in UI.
package_root	Package directory. Useful for display, duplicate detection, and row identity.
is_used	true when at least one module from the package appears in a generated chunk. false means the package was resolved but tree-shaken away.
dependency_type	direct when any package module is imported by a source module under the build cwd and outside node_modules; otherwise transitive. Rolldown does not inspect package.json dependency fields for this value.
size	Sum of rendered package module bytes after tree-shaking/codegen and before renderChunk, minification, banners, and final asset emission. This is package attribution data, not final asset size.
modules	Generated chunk module IDs for the package. Join with ModuleGraphReady.modules[].id when the module graph is needed. Empty for unused packages.
chunk_ids	IDs of chunks containing modules from the package. Join with ChunkGraphReady.chunks[].chunk_id. Empty for unused packages.

To detect duplicate packages, group records by non-null name, then mark groups that contain more than one version or package root.

See internal-docs/devtools/implementation.md in the Rolldown repository for implementation details and event lifecycle notes.