Import Utilities

@jssg/utils provides reusable utility functions for JSSG codemods. These helpers handle common import manipulation tasks that are tedious and error-prone when done manually with AST queries.

Installation

Add @jssg/utils to your codemod project:

package.json

{
  "dependencies": {
    "@jssg/utils": "latest"
  }
}

Import

import { getImport, addImport, removeImport } from "@jssg/utils/javascript/imports";

These utilities work with JavaScript, TypeScript, JSX, and TSX ASTs. They handle both ESM (import) and CJS (require()) formats automatically.

Java Utilities

@jssg/utils also includes Java helpers for recurring safe-codemod patterns:

import {
  cleanupImports,
  collectImports,
  createImportCleanupEdits,
  hasConflictingSimpleImport,
  isTypeImported,
} from "@jssg/utils/java/imports";
import { findVisibleDeclarationBeforeUsage } from "@jssg/utils/java/scope";
import { replaceTypeIdentifierSafely } from "@jssg/utils/java/types";
import {
  getMethodInvocationParts,
  getReceiverIdentifier,
} from "@jssg/utils/java/method-invocations";
import {
  getAnonymousClassMethod,
  getAnonymousClassMethods,
  getMethodBodyContent,
  getSingleParameterName,
  renameIdentifiersInNode,
} from "@jssg/utils/java/anonymous-classes";

Use these when Java codemods need to prove type ownership, handle wildcard/conflicting imports, avoid shadowed receivers, replace type identifiers without touching fully qualified names, or inspect anonymous class methods safely.

const imports = collectImports(rootNode);

const isExpectedWidget =
  isTypeImported(imports, {
    simpleName: "Widget",
    fullyQualifiedName: "com.example.Widget",
  }) &&
  !hasConflictingSimpleImport(imports, {
    simpleName: "Widget",
    expectedFullyQualifiedName: "com.example.Widget",
  });

`getImport`

Locate an import of a given module and return its alias/identifier node.

Parameters

SgNode<T, 'program'>

required

The root program node to search within.

GetImportOptions

required

What to look for:

{ type: "default", from: string } — Find the default import from a module.
{ type: "named", name: string, from: string } — Find a specific named import from a module.

Returns

GetImportResult<T> | null — An object containing:

Field	Type	Description
`alias`	`string`	The local name used at call sites (e.g., `baz` in `import { foo as baz }`)
`isNamespace`	`boolean`	`true` if the import is `import * as xyz from '...'`
`moduleType`	`"esm" \| "cjs"`	Whether the import is ESM (`import`) or CJS (`require()`)
`node`	`SgNode<T, "identifier">`	The identifier AST node for the local binding

Returns null if the import is not found.

Supported Import Shapes

Format	Example
ESM default	`import foo from "module"`
ESM named	`import { bar } from "module"`
ESM aliased	`import { bar as baz } from "module"`
ESM namespace	`import * as foo from "module"`
ESM bare	`import "module"`
CJS default	`const foo = require("module")`
CJS destructured	`const { bar } = require("module")`
CJS aliased	`const { bar: baz } = require("module")`
Dynamic import	`const foo = await import("module")`

Example

import type { Codemod } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";
import { getImport } from "@jssg/utils/javascript/imports";

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

  // Find the default import of "express"
  const expressImport = getImport(rootNode, { type: "default", from: "express" });
  if (!expressImport) return null;

  // expressImport.alias is the local name (e.g., "app" from `import app from 'express'`)
  // expressImport.moduleType tells you if it's "esm" or "cjs"
  console.log(`Express imported as: ${expressImport.alias} (${expressImport.moduleType})`);

  // Find a named import
  const useStateImport = getImport(rootNode, { type: "named", name: "useState", from: "react" });
  if (useStateImport) {
    console.log(`useState aliased as: ${useStateImport.alias}`);
  }

  return null;
};

export default codemod;

`getAllImports`

Locate imports of a given module and return their alias/identifier nodes.

Parameters

SgNode<T, 'program'>

required

The root program node to search within.

GetImportOptions

required

What to look for:

{ type: "default", from: string } — Find all default imports from a module.
{ type: "named", name: string, from: string } — Find all instances of a specific named import from a module.

Returns

ResolvedImport<T>[] — An array containing:

Field	Type	Description
`alias`	`string`	The local name used at call sites (e.g., `baz` in `import { foo as baz }`)
`isNamespace`	`boolean`	`true` if the import is `import * as xyz from '...'`
`moduleType`	`"esm" \| "cjs"`	Whether the import is ESM (`import`) or CJS (`require()`)
`node`	`SgNode<T, "identifier">`	The identifier AST node for the local binding

Returns an empty array if no imports are found.

Example

import type { Transform } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";
import { getAllImports } from "@jssg/utils/javascript/imports";

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

  // Find all default imports of "express"
  const expressImports = getAllImports(rootNode, { type: "default", from: "express" });
  for (const imp of expressImports) {
    console.log(`Express imported as: ${imp.alias} (${imp.moduleType})`);
  }

  // Find all named imports
  const useStateImports = getAllImports(rootNode, { type: "named", name: "useState", from: "react" });
  for (const imp of useStateImports) {
    console.log(`useState aliased as: ${imp.alias}`);
  }

  return null;
};

export default transform;

`addImport`

Add an import to the program. Smart behavior:

Skips if the import already exists
Merges named specifiers into an existing import statement from the same source
Creates a new import statement otherwise
Inserts after the last existing import (or at file start if no imports exist)

Parameters

SgNode<T, 'program'>

required

The root program node.

AddImportOptions

required

One of:

{ type: "default", name: string, from: string, moduleType?: "esm" | "cjs" } — Add a default import.
{ type: "namespace", name: string, from: string } — Add a namespace import (import * as name).
{ type: "named", specifiers: Array<{ name: string, alias?: string }>, from: string, moduleType?: "esm" | "cjs" } — Add named imports.

Returns

Edit | null — An edit to apply via rootNode.commitEdits(), or null if the import already exists.

Example

import type { Codemod, Edit } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";
import { addImport } from "@jssg/utils/javascript/imports";

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

  // Add a default import (skipped if already present)
  const defaultEdit = addImport(rootNode, {
    type: "default",
    name: "React",
    from: "react",
  });
  if (defaultEdit) edits.push(defaultEdit);

  // Add named imports (merges into existing `import { ... } from 'react'` if present)
  const namedEdit = addImport(rootNode, {
    type: "named",
    specifiers: [{ name: "useState" }, { name: "useEffect" }],
    from: "react",
  });
  if (namedEdit) edits.push(namedEdit);

  // Add a CJS require
  const cjsEdit = addImport(rootNode, {
    type: "default",
    name: "express",
    from: "express",
    moduleType: "cjs",
  });
  if (cjsEdit) edits.push(cjsEdit);

  return edits.length > 0 ? rootNode.commitEdits(edits) : null;
};

export default codemod;

`removeImport`

Remove an import from the program. Smart behavior:

Default/namespace: Removes the entire import statement.
Named (multiple specifiers): Removes only the specified specifiers, keeping the rest.
Named (last specifier): Removes the entire import statement.
Handles both ESM and CJS formats.

Parameters

SgNode<T, 'program'>

required

The root program node.

RemoveImportOptions

required

One of:

{ type: "default", from: string } — Remove the default import from a module.
{ type: "namespace", from: string } — Remove the namespace import from a module.
{ type: "named", specifiers: string[], from: string } — Remove specific named imports.

Returns

Edit | null — An edit to apply via rootNode.commitEdits(), or null if the import was not found.

Example

import type { Codemod, Edit } from "codemod:ast-grep";
import type TSX from "codemod:ast-grep/langs/tsx";
import { removeImport } from "@jssg/utils/javascript/imports";

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

  // Remove a named import (only removes "PropTypes", keeps other specifiers)
  const removeEdit = removeImport(rootNode, {
    type: "named",
    specifiers: ["PropTypes"],
    from: "react",
  });
  if (removeEdit) edits.push(removeEdit);

  return edits.length > 0 ? rootNode.commitEdits(edits) : null;
};

export default codemod;

`stringToExactRegexString`

Escape a string for use as an exact-match regex pattern. Wraps in ^...$ and escapes special characters.

import { stringToExactRegexString } from "@jssg/utils/javascript/imports";

// Returns "^my\\.module$"
const regex = stringToExactRegexString("my.module");

Common Patterns

Verify Import Before Transforming

Always verify that a symbol is imported from the expected package before transforming its usage:

const reactImport = getImport(rootNode, { type: "named", name: "useState", from: "react" });
if (!reactImport) return null; // Not from React, skip

// Now safe to transform useState usage
// Handles aliased imports like `import { useState as myState }`
const alias = reactImport.alias;

Replace One Import With Another

const edits: Edit[] = [];

// Remove old import
const removeEdit = removeImport(rootNode, {
  type: "named",
  specifiers: ["oldUtil"],
  from: "old-pkg",
});
if (removeEdit) edits.push(removeEdit);

// Add new import
const addEdit = addImport(rootNode, {
  type: "named",
  specifiers: [{ name: "newUtil" }],
  from: "new-pkg",
});
if (addEdit) edits.push(addEdit);

Match Existing Module Style

getImport automatically detects the module type. Use moduleType when adding imports to match the existing style:

const existing = getImport(rootNode, { type: "default", from: "express" });
const moduleType = existing?.moduleType ?? "esm"; // Match existing style

const edit = addImport(rootNode, {
  type: "named",
  specifiers: [{ name: "Router" }],
  from: "express",
  moduleType,
});

First steps

Community

Enterprise

Other Resources

Installation

Import

Java Utilities

`getImport`

Parameters

Returns

Supported Import Shapes

Example

`getAllImports`

Parameters

Returns

Example

`addImport`

Parameters

Returns

Example

`removeImport`

Parameters

Returns

Example

`stringToExactRegexString`

Common Patterns

Verify Import Before Transforming

Replace One Import With Another

Match Existing Module Style

​Installation

​Import

​Java Utilities

​getImport

​Parameters

​Returns

​Supported Import Shapes

​Example

​getAllImports

​Parameters

​Returns

​Example

​addImport

​Parameters

​Returns

​Example

​removeImport

​Parameters

​Returns

​Example

​stringToExactRegexString

​Common Patterns

​Verify Import Before Transforming

​Replace One Import With Another

​Match Existing Module Style

Installation

Import

Java Utilities

`getImport`

Parameters

Returns

Supported Import Shapes

Example

`getAllImports`

Parameters

Returns

Example

`addImport`

Parameters

Returns

Example

`removeImport`

Parameters

Returns

Example

`stringToExactRegexString`

Common Patterns

Verify Import Before Transforming

Replace One Import With Another

Match Existing Module Style