jssg is a JavaScript/TypeScript toolkit that simplifies writing and testing ast-grep codemods. It’s built into the Codemod CLI, making it easy to run codemods from the command line and publish them to the registry. If you’ve used tools like jscodeshift, jssg will feel familiar—but with key advantages. Unlike jscodeshift, jssg is built on the robust and high-performance ast-grep engine, written in Rust and optimized for fast, large-scale code transformations. Most importantly, thanks to ast-grep’s tree-sitter foundation, jssg supports a wide range of languages—including custom ones.

​
Running Codemods

To run a jssg codemod on a target directory for a specific language like Java, use the following command:

npx codemod@latest jssg run /path/to/my-codemod.js /path/to/target --language java

Note: Although your jssg codemods are written in JS/TS, the target language can be something else.

​
Options

​
--language <LANG>
string
required

Target language (e.g., javascript, typescript, python, java, cpp, php, kotlin, etc.).

​
--extensions <ext1,ext2>
string

Comma-separated list of file extensions to process.

​
--no-gitignore
boolean

Do not respect .gitignore files.

​
--include-hidden
boolean

Include hidden files and directories in the scan.

​
--max-threads <N>
number

Maximum number of concurrent threads to use.

​
--dry-run
boolean

Perform a dry-run to see the changes without applying them.

​
Testing Framework

The jssg testing framework provides testing capabilities for jssg codemods using before/after fixture files.

​
Quick Start

  1. Create your test directory. A common structure includes input and expected files for each test case.

    tests/
├── simple-transform/
│   ├── input.js
│   └── expected.js
└── multi-file-case/
    ├── input/
    │   ├── file1.js
    │   └── file2.js
    └── expected/
        ├── file1.js
        └── file2.js

  2. Run the tests using the npx codemod@latest jssg test command.

    # Run tests for a codemod
npx codemod@latest jssg test /path/to/my-codemod.js --language javascript

# Update snapshots (creates or updates the `expected.js` files)
npx codemod@latest jssg test /path/to/my-codemod.js --language javascript --update-snapshots

​
Required Arguments

These options are required for running tests with jssg.

​
codemod_file
string
required

Path to the jssg codemod file, which is a JS/TS file.

​
--language
string
required

Target language (e.g., javascript, typescript, python, java, cpp, php, kotlin, etc.).

​
Test Discovery & Filtering

Control which tests are discovered and run.

​
--test-directory
string

The directory containing your tests (default: "tests").

​
--filter
string

A pattern to run only tests whose names match the filter.

​
Output & Reporting

Options for controlling test output and reporting.

​
--reporter
string

The output format for test results. Can be console, json, or terse.

​
--verbose
boolean

Show detailed output, including diffs for failed tests.

​
--context-lines
number

The number of context lines to show in diffs (default: 3).

​
--ignore-whitespace
boolean

Ignore whitespace differences when comparing test outputs.

​
Execution Control

Options for controlling how tests are executed.

​
--timeout
number

Test timeout in seconds (default: 30).

​
--max-threads
number

Maximum number of concurrent threads to use for running tests.

​
--sequential
boolean

Run tests sequentially instead of in parallel.

​
--fail-fast
boolean

Stop the test run on the first failure.

​
Snapshot & Error Management

Options for managing test snapshots and expected errors.

​
--update-snapshots, -u
boolean

Create or update the expected files with the output of the codemod.

​
--expect-errors
string

A comma-separated list of test patterns that are expected to fail.

​
Development

Development-focused options for rapid iteration.

​
--watch
boolean

Enable watch mode to automatically re-run tests when files change.