@arcgis/codemod

@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. Starting with removing the __esri namespace in TypeScript projects and replacing it with explicit imports.

Features

• Automated refactor to remove __esri namespace usage
• Converts global namespace types to explicit @arcgis/core imports
• Detects edge cases and warns when changes can’t be safely automated
• Respects .gitignore by default

Requirements

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

Usage

The 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:

npx @arcgis/codemod run refactor-out-esri-namespace

By default, the codemod runs on all TypeScript files in the current directory and subdirectories, excluding files ignored by your .gitignore. You can manually run it on a different directory by providing an argument:

npx @arcgis/codemod run refactor-out-esri-namespace target-directory

What codemod does

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. If your project uses ESLint, Prettier, or other formatters/linters, run them after the codemod to ensure consistent formatting.

Note: This codemod modifies files in place and does 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.

License

COPYRIGHT Esri

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.0/LICENSE.txt.

For third party notices, see https://js.arcgis.com/5.0/third-party-notices.txt.