JavaScript and TypeScript

These helpers locate, add, remove, and rename imports in JavaScript and TypeScript programs.

import {
  getImport,
  getAllImports,
  addImport,
  removeImport,
  updateImport,
} 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.

`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"` — no binding, so `getImport` returns `null`. Remove it with `removeImport` and `removeSideEffectForms: true`.
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, removeSideEffectForms?: boolean } — Remove the default import from a module. Set removeSideEffectForms to also remove a side-effect-only import "module" or require("module") when no binding import exists.
{ 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;

`updateImport`

Replace named specifiers of an existing import or require in place. The whole clause is one edit, so the rewrite does not overlap other specifier edits.

import { foo } from "mod" with { name: "foo", to: "bar" } becomes import { bar } from "mod".
An existing local alias is kept: import { foo as f } becomes import { bar as f }. Pass alias to override that local name.
Works for ESM named imports, destructured require(), and destructured dynamic import().
If to is already imported in the same clause, the old specifier is dropped instead of duplicated.

Parameters

SgNode<T, 'program'>

required

The root program node.

UpdateImportOptions

required

Named imports only:

{ type: "named", from: string, specifiers: Array<{ name: string, to: string, alias?: string }> } — Rename name to to in the import from from.

Returns Edit | null — An edit to apply via rootNode.commitEdits(), or null if none of the named specifiers is found or specifiers is empty. Example

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

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

  const edit = updateImport(rootNode, {
    type: "named",
    from: "mod",
    specifiers: [{ name: "foo", to: "bar" }],
  });

  return edit ? rootNode.commitEdits([edit]) : null;
};

export default codemod;

`stringToExactRegexString`

Escape a string and return a regex that matches only that exact text. The result is wrapped in ^...$, with regex metacharacters escaped.

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

Rename a named specifier in the same module with updateImport:

const edit = updateImport(rootNode, {
  type: "named",
  from: "mod",
  specifiers: [{ name: "oldUtil", to: "newUtil" }],
});

Switch packages with removeImport and addImport:

const edits: Edit[] = [];

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

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

JavaScript and TypeScript

`getImport`

`getAllImports`

`addImport`

`removeImport`

`updateImport`

`stringToExactRegexString`

Common Patterns

Verify Import Before Transforming

Replace One Import With Another

Match Existing Module Style

​getImport

​getAllImports

​addImport

​removeImport

​updateImport

​stringToExactRegexString

​Common Patterns

​Verify Import Before Transforming

​Replace One Import With Another

​Match Existing Module Style

`getImport`

`getAllImports`

`addImport`

`removeImport`

`updateImport`

`stringToExactRegexString`

Common Patterns

Verify Import Before Transforming

Replace One Import With Another

Match Existing Module Style