@arcgis/codemod

A codemod toolkit for updating and modernizing ArcGIS Maps SDK for JavaScript codebases.

This package provides automated refactors to help migrate away from deprecated or legacy patterns. These include codemods for removing the __esri namespace and converting global namespace types to explicit @arcgis/core imports, normalizing legacy Calcite icon names, and updating geometry operator usage.

Requirements

• Node.js 24
• A project using the ArcGIS Maps SDK for JavaScript
• This codemod operates exclusively on TypeScript files. You do not need to run this tool if the project does not use TypeScript.

Before you begin

Ensure your project's dependencies are up to date, for example by running pnpm install.

If your project uses ESLint, Prettier, or other formatters/linters, run them after the codemod to ensure consistent formatting.

[!Note] Codemods modify files in place and do not provide an interactive dry-run mode. We recommend running it in a project that is under version control (Git) so you can review changes using git diff or your IDE’s diff tools. If your project is not under version control, create a backup before running the codemod.

By default, codemods run on all TypeScript files in the current directory and subdirectories. You can manually run it on a different directory by providing it as an argument.

Codemods respect .gitignore files and will not modify any files ignored by them.

Available codemods

• refactor-out-esri-namespace
• normalize-calcite-icon-names
• geometry-operator-renames

Refactor out the __esri namespace

The refactor-out-esri-namespace codemod replaces __esri types with explicit imports from @arcgis/core.

Note: Before running the codemod, update all @arcgis/* packages in your package.json to the most recent version.

Run it in the root of your project or with an explicit target directory:

npx @arcgis/codemod run refactor-out-esri-namespace [<target-directory>]

Before:

let geometry: __esri.Geometry;
let featureSet: __esri.FeatureSet;

After:

import type Geometry from "@arcgis/core/geometry/Geometry";
import type FeatureSet from "@arcgis/core/rest/support/FeatureSet";

let geometry: Geometry;

let featureSet: FeatureSet;

Warnings (manual review required)

The codemod will emit warnings for cases it cannot safely rewrite, including:

• __esri references inside JSDoc comments
• Complex computed or dynamic type usage
• Unresolvable symbols

These will be reported in the console. Manually review all changes before committing.

Normalize Calcite icon names

The normalize-calcite-icon-names codemod updates camelCase and legacy Calcite icon names to their normalized kebab-case equivalents. It handles icon attributes on Calcite components and traces icon values through variables, properties, assignments, function returns, and forwarded component properties. This helps prepare for calcite-design-system#14967 and calcite-design-system#14966.

Run it in the root of your project or with an explicit target directory:

npx @arcgis/codemod run normalize-calcite-icon-names [<target-directory>]

Before:

<calcite-button iconStart="i3dGlasses" iconEnd="arrowLeft10" />

After:

<calcite-button iconStart="3d-glasses" iconEnd="arrow-left-10" />

Rename Geometry Operators

In version 5.2, geometry operator exports and option types were renamed to improve consistency and discoverability. The geometry-operator-renames codemod updates geometry operator calls to use the new names. It additionally inlines namespace imports, which are no longer necessary.

Run it in the root of your project or with an explicit target directory:

npx @arcgis/codemod run geometry-operator-renames [<target-directory>]

Before:

import * as bufferOperator from "@arcgis/core/geometry/operators/bufferOperator";
const options: bufferOperator.Options = { unit: "meters" };
const buffered = bufferOperator.execute(polyline, 250, options);

After:

import { bufferExecute, type BufferExecuteOptions } from "@arcgis/core/geometry/operators/bufferOperator";
const options: BufferExecuteOptions = { unit: "meters" };
const buffered = bufferExecute(polyline, 250, options);

Versioning

The codemods are available until the corresponding deprecated feature is removed. If migrating from a much older release, the codemod might no longer be available in the most recent version of the @arcgis/codemod package. In such cases, run the codemod from an older version, matching the version in the release notes:

npx @arcgis/[email protected] run refactor-out-esri-namespace

Troubleshooting

Some codemods rely on type information to perform more accurate migrations. On large codebases, this may require more RAM than the default Node.js limit. If you encounter an out-of-memory error (like Allocation failed - JavaScript heap out of memory), re-run the codemod with a higher RAM limit:

Example on Linux/macOS:

NODE_OPTIONS="--max-old-space-size=10240" npx @arcgis/codemod run normalize-calcite-icon-names

Windows command line and PowerShell use a different environment variable syntax.

License

This package is licensed under the terms described in the LICENSE.md file, located in the root of the package, and at https://js.arcgis.com/5.2/LICENSE.txt. For third party notices, see https://js.arcgis.com/5.2/third-party-notices.txt.