@rolldown/debug

Utilities and generated TypeScript types for reading Rolldown devtools output.

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

text

<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.