Skip to main content
Build a working JavaScript ast-grep (jssg) codemod in minutes.

​
What is jssg?

JavaScript ast-grep (jssg) is a secure JavaScript runtime for codemods. This runtime is compatible with Node.js and comes with ast-grep as a built-in module.
jssg is built on top of QuickJS, a lightweight JavaScript engine, and uses LLRT for Node.js module compatibility.
jssg follows a deny-by-default security model. Unsafe operations like file system access (fs), network requests (fetch), and process spawning (child_process) are disabled by default. See Security & Capabilities to learn how to enable them.
How it works:
  • A jssg codemod is a module that export defaults a function receiving an SgRoot<L> (the parsed file) and returning a string (modified code) or null/undefined (no change). Any other return type is a runtime error.
  • The codemod:ast-grep built‑in provides parsing and pattern matching. At runtime it exports parse and parseAsync; SgRoot and SgNode are TypeScript types from @codemod.com/jssg-types that describe the AST API you interact with in the transform.
  • You express search conditions as ast-grep rule objects (plain JS), traverse nodes, create edits with node.replace(...), and finalize with rootNode.commitEdits(edits).
For engine details and built-ins, see Runtime and built-ins in the API reference.
Key concepts:
  • Patterns: Describe code shapes using ast-grep’s pattern syntax with captures (for example, $NAME, $$$ARGS).
  • Rules: Compose patterns with any, all, kind, relational constraints (inside, has, precedes, follows), and utilities like matches and constraints.
  • Edits: Build replacements with node.replace(text) and apply them with commitEdits(edits).
  • Lifecycle: Select → Traverse → Capture → Edit → Commit & Return.
You can author rules as plain JavaScript objects. See the ast‑grep rule configuration docs and the jssg API reference.

​
Build your first codemod

1

Scaffold a jssg package

npx codemod init
Pick JavaScript ast-grep (jssg) codemod when prompted.This will scaffold a new folder with the required files and structure.
<your-codemod>/
├── codemod.yaml
├── workflow.yaml       # references scripts/codemod.ts in a js-ast-grep step
└── scripts/
    └── codemod.ts      # write your jssg transform here
2

Write a minimal transform (scripts/codemod.ts)

Key concepts:
  • Transform signature: export default function transform(root, options)
  • Edit flow: find nodes → build edits → commitEdits(edits) → return resulting string
  • Return contract: string → modified (unless equal to input), null/undefined → unmodified; anything else → error
  • Type safety: Always check node types before accessing fields
codemod.ts
import type { Transform } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";

const transform: Transform<TSX> = (root) => {
  const rootNode = root.root();

  // Find all console.* calls with type safety
  const consoleCalls = rootNode.findAll({
    rule: {
      any: [
        { pattern: "console.log($$$ARGS)" },
        { pattern: "console.debug($$$ARGS)" },
        { pattern: "console.warn($$$ARGS)" },
      ],
    },
  });

  if (consoleCalls.length === 0) {
    return null; // No changes needed
  }

  // Create edits with proper validation
  const edits = consoleCalls.map((node) => {
    const callee = node.field("function");
    const method = callee?.field("property")?.text() || "log";
    const args = node.getMultipleMatches("ARGS")
      .map(arg => arg.text())
      .join(", ");
    
    return node.replace(`logger.${method}(${args})`);
  });

  return rootNode.commitEdits(edits);
}

export default transform;
The transform follows this pattern:
  1. If no matches are found, the step is skipped or files are unchanged
  2. When matches exist, files with changes are updated in-memory and reported in the diff
  3. Returning the same string results in “unmodified”; returning null/undefined is also treated as “unmodified”
3

Validate & run

npx codemod workflow validate -w workflow.yaml
npx codemod workflow run -w workflow.yaml --dry-run
The transform will make the following changes:
Before
function example() {
  console.log("Hello");
  console.debug("Debug");
}
After
function example() {
  logger.log("Hello");
  logger.log("Debug");
}

​
Next steps

Security & Capabilities

Learn about jssg’s security model and how to enable file system, network, and process capabilities.

Test your codemod

Validate your codemod with before/after fixtures and the test runner.

jssg reference

Explore the full API reference for node navigation, editing, and pattern matching.

Advanced patterns

Learn advanced transformation techniques and best practices.
⌘I