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.

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