Metrics

Metrics allow you to collect and aggregate data while running codemods. This is useful for:

Codebase analysis: Count occurrences of patterns, prop usages, component instances
Migration tracking: Track what needs to be migrated before making changes
Read-only codemods: Gather insights without modifying code

Basic Usage

Import useMetricAtom from codemod:metrics to create a metric tracker:

import { useMetricAtom } from "codemod:metrics";

const metric = useMetricAtom("my-metric");

// Increment with cardinality dimensions
metric.increment({ category: "buttons", variant: "primary" });

// Increment by a specific amount
metric.increment({ category: "buttons" }, 5);

// Increment without cardinality (simple counter)
metric.increment();

Cardinality

Cardinality dimensions are key-value pairs that let you group and filter metrics. When you call increment(), you pass an object with string keys and values:

metric.increment({
  propName: "className",
  propValue: "container",
  component: "Button"
});

This creates a unique metric entry for each combination of cardinality values. You can later group by any dimension (e.g., all entries where component=Button).

Use cardinality to capture context about what you’re counting. For example, when counting prop usages, include both the prop name and the component it belongs to.

Example: Counting Prop Usage

This read-only codemod counts how many times each prop is used on Button components:

import type { Codemod } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";
import { useMetricAtom } from "codemod:metrics";

const propUsageMetric = useMetricAtom("prop-usage");

const codemod: Codemod<TSX> = async (root) => {
  const rootNode = root.root();

  const jsxAttrs = rootNode.findAll({
    rule: {
      kind: "jsx_attribute",
      inside: {
        any: [
          { kind: "jsx_opening_element" },
          { kind: "jsx_self_closing_element" },
        ],
        has: {
          field: "name",
          kind: "identifier",
          regex: "^Button$"
        },
      },
    },
  });

  for (const attr of jsxAttrs) {
    const name = attr?.find({ rule: { kind: "property_identifier" } });
    const propName = name?.text();
    if (propName) {
      propUsageMetric.increment({ propName });
    }
  }

  return null;
};

export default codemod;

Running this codemod produces output like:

Metrics:
  prop-usage:
    propName=onClick: 42
    propName=className: 38
    propName=disabled: 15
    propName=variant: 12

Insights

Insights binds each dashboard query to one workflow step and loads that step’s js-ast-grep script from the published package. Metric names must be statically visible in that script (useMetricAtom + increment)—not only in a different package file or helper import. This is the selected step’s script, not necessarily the package entry (for example scripts/codemod.ts). For scale (transforms or mining), see Performant codemods. Insights runs the selected step on its own, so that step must compute its metric from the repository directly. Don’t rely on files written by an earlier step (for example, a collect step that writes JSON shards for an analyze step); the widget will return no results.

First steps

Community

Enterprise

Other Resources

Basic Usage

Cardinality

Example: Counting Prop Usage

Insights

​Basic Usage

​Cardinality

​Example: Counting Prop Usage

​Insights

Basic Usage

Cardinality

Example: Counting Prop Usage

Insights