Arcgis Performance

ArcGIS Performance

Use this skill when optimizing ArcGIS Maps SDK for JavaScript applications for faster load times, reduced memory usage, efficient data handling, and smooth rendering in both 2D MapView and 3D SceneView.

Critical Priority (P0)

Map Initialization

Using incorrect readiness patterns causes race conditions, missed events, or wasted CPU cycles.

Map Components

// Anti-pattern: polling or setTimeout to check view readiness
const mapElement = document.querySelector("arcgis-map");
const checkReady = setInterval(() => {
  if (mapElement.view && mapElement.view.ready) {
    clearInterval(checkReady);
    initializeApp(mapElement.view);
  }
}, 100);

// Correct: use viewOnReady() which returns a promise
const mapElement = document.querySelector("arcgis-map");
await mapElement.viewOnReady();
initializeApp(mapElement.view);

Impact: Polling wastes CPU cycles and introduces unpredictable delays. viewOnReady() resolves at the earliest possible moment the view is usable, with zero overhead.

Core API

// Anti-pattern: setTimeout to "wait" for the view
const view = new MapView({ container: "viewDiv", map });
setTimeout(() => {
  console.log("Extent:", view.extent); // May still be undefined
}, 3000);

// Correct: use view.when() which resolves when the view is ready
const view = new MapView({ container: "viewDiv", map });
await view.when();
console.log("Extent:", view.extent);

Impact: setTimeout either fires too early (view not ready) or too late (wasted idle time). view.when() resolves at exactly the right moment.

Layer Readiness

// Anti-pattern: accessing layer properties before it has loaded
const layer = new FeatureLayer({ url: serviceUrl });
map.add(layer);
console.log(layer.fields); // undefined

// Correct: wait for the layer to load
const layer = new FeatureLayer({ url: serviceUrl });
map.add(layer);
await layer.when();
console.log(layer.fields); // Now available

Impact: Accessing properties on an unloaded layer returns undefined or stale data.

Data Loading Waterfalls

// Anti-pattern: sequential layer loading creates a waterfall
for (const url of urls) {
  const layer = new FeatureLayer({ url });
  map.add(layer);
  await layer.when(); // Blocks until this layer loads before starting the next
}

// Correct: parallel layer loading with Promise.all
const layers = urls.map((url) => new FeatureLayer({ url }));
map.addMany(layers);
await Promise.all(layers.map((layer) => layer.when()));

Impact: With 4 layers each taking 500ms, sequential loading takes ~2000ms. Parallel loading takes ~500ms.

Parallel Loading with Error Handling

// Correct: parallel loading with individual error handling
const layers = urls.map((url) => new FeatureLayer({ url }));
map.addMany(layers);

const results = await Promise.allSettled(layers.map((layer) => layer.when()));
results.forEach((result, index) => {
  if (result.status === "rejected") {
    console.warn(`Layer ${index} failed to load:`, result.reason);
    map.remove(layers[index]);
  }
});

Impact: Promise.allSettled prevents one failed layer from blocking all others.

Bundle Size

Core API Imports

// Anti-pattern: barrel imports pull in the entire module tree
import { Map, MapView } from "@arcgis/core";
import { FeatureLayer, GraphicsLayer } from "@arcgis/core/layers";

// Correct: deep imports enable tree-shaking
import Map from "@arcgis/core/Map.js";
import MapView from "@arcgis/core/views/MapView.js";
import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";

Impact: Barrel imports bypass tree-shaking and can add hundreds of kilobytes of unused code to the bundle.

Map Components Imports

// Anti-pattern: importing the entire map-components package
import "@arcgis/map-components";

// Correct: import only the components you use
import "@arcgis/map-components/dist/components/arcgis-map";
import "@arcgis/map-components/dist/components/arcgis-zoom";
import "@arcgis/map-components/dist/components/arcgis-legend";

Impact: Importing the entire package registers every component even if only a few are used.

Bundle Size Comparison

| Import Pattern | Approximate Bundle Impact | | ------------------------------------------------------------ | ------------------------------------ | | import "@arcgis/map-components" | Entire component library loaded | | import "@arcgis/map-components/dist/components/arcgis-map" | Only map component + dependencies | | import { Map } from "@arcgis/core" | Barrel import, entire core pulled in | | import Map from "@arcgis/core/Map.js" | Only Map class + direct dependencies |

Dynamic Imports for Code Splitting

// Anti-pattern: importing heavy modules at startup
import Print from "@arcgis/core/widgets/Print.js";
import Sketch from "@arcgis/core/widgets/Sketch.js";
import Editor from "@arcgis/core/widgets/Editor.js";

// Correct: dynamic import loads modules only when needed
async function addPrintWidget(view) {
  const { default: Print } = await import("@arcgis/core/widgets/Print.js");
  const print = new Print({ view });
  view.ui.add(print, "top-right");
}

Impact: Widgets like Print, Sketch, and Editor are large. Dynamic imports keep them out of the initial bundle, reducing time-to-interactive.

High Impact (P1)

FeatureLayer Query Optimization

Specify outFields

// Anti-pattern: requesting all fields
const results = await layer.queryFeatures({
  where: "status = 'active'",
  outFields: ["*"],
  returnGeometry: true,
});

// Correct: request only the fields you need
const results = await layer.queryFeatures({
  where: "status = 'active'",
  outFields: ["OBJECTID", "name", "status", "category"],
  returnGeometry: true,
});

Impact: For a layer with 50 fields, requesting only 4 reduces payload size by ~90%.

Skip Geometry When Not Needed

// Anti-pattern: fetching geometry for a list view
const results = await layer.queryFeatures({
  where: "population > 100000",
  outFields: ["name", "population"],
  returnGeometry: true, // Default is true
});
// Only using attributes
results.features.forEach((f) => addToList(f.attributes.name));

// Correct: disable geometry when only attributes are needed
const results = await layer.queryFeatures({
  where: "population > 100000",
  outFields: ["name", "population"],
  returnGeometry: false,
});

Impact: Geometry data (especially polygons) can be orders of magnitude larger than attribute data.

Server-Side Filtering with definitionExpression

// Anti-pattern: loading all features then filtering on the client
const allResults = await layer.queryFeatures({
  where: "1=1",
  outFields: ["*"],
});
const filtered = allResults.features.filter(
  (f) => f.attributes.region === "West" && f.attributes.revenue > 50000,
);

// Correct: use definitionExpression for server-side filtering
const layer = new FeatureLayer({
  url: serviceUrl,
  definitionExpression: "region = 'West' AND revenue > 50000",
  outFields: ["OBJECTID", "name", "region", "revenue"],
});

Impact: Loading 100,000 features to filter down to 500 wastes bandwidth, memory, and CPU.

Use Lightweight Query Methods

// Anti-pattern: querying full features just to get a count
const results = await layer.queryFeatures({ where: "status = 'active'" });
const count = results.features.length;

// Correct: use queryFeatureCount for count-only operations
const count = await layer.queryFeatureCount({ where: "status = 'active'" });

// Correct: use queryExtent when you only need the bounding box
const { extent } = await layer.queryExtent({ where: "status = 'active'" });
await view.goTo(extent);

Impact: queryFeatureCount and queryExtent are lightweight server operations.

Large Dataset Handling

Strategy Thresholds

| Feature Count | Strategy | Implementation | | ---------------- | ------------------ | ---------------------------------------- | | 10000", maxScale: 50000, });

### Memory Management

#### Destroying Views

```javascript
// Anti-pattern: removing DOM element without destroying view
function removeMap() {
  document.getElementById("viewDiv").remove();
  // View still alive in memory
}

// Correct: destroy the view to release all resources
function removeMap(view) {
  view.destroy();
}

Impact: A single undestroyed MapView can retain 50-200MB of memory. In SPAs, this causes memory to grow until the tab crashes.

Handle Cleanup with Handle Groups

// Anti-pattern: creating watchers without tracking them
function setupWatchers(view) {
  reactiveUtils.watch(
    () => view.extent,
    (extent) => updatePanel(extent),
  );
  reactiveUtils.watch(
    () => view.scale,
    (scale) => updateScaleBar(scale),
  );
  // These watches live forever
}

// Correct: use handle groups for organized cleanup
import * as reactiveUtils from "@arcgis/core/core/reactiveUtils.js";

function setupWatchers(view) {
  const handle1 = reactiveUtils.watch(
    () => view.extent,
    (extent) => updatePanel(extent),
  );
  const handle2 = reactiveUtils.watch(
    () => view.scale,
    (scale) => updateScaleBar(scale),
  );
  view.addHandles([handle1, handle2], "my-watchers");
}

function cleanup(view) {
  view.removeHandles("my-watchers");
}

Impact: Orphaned watchers continue executing callbacks on destroyed components, causing errors and memory leaks.

AbortController for Cancellable Queries

// Anti-pattern: queries that cannot be cancelled
async function onViewChange(view) {
  const results = await layer.queryFeatures({
    geometry: view.extent,
    outFields: ["name"],
  });
  currentResults = results;
}

// Correct: use AbortController to cancel superseded queries
import * as promiseUtils from "@arcgis/core/core/promiseUtils.js";

let abortController = null;

async function onViewChange(view) {
  if (abortController) abortController.abort();
  abortController = new AbortController();

  try {
    const results = await layer.queryFeatures(
      { geometry: view.extent, outFields: ["name"] },
      { signal: abortController.signal },
    );
    updateUI(results);
  } catch (error) {
    if (!promiseUtils.isAbortError(error)) {
      console.error("Query failed:", error);
    }
  }
}

Impact: Without cancellation, rapid view changes trigger dozens of concurrent queries.

React Cleanup Pattern

// Anti-pattern: no cleanup in React component
function MapComponent() {
  const mapRef = useRef(null);
  useEffect(() => {
    const view = new MapView({
      container: mapRef.current,
      map: new Map({ basemap: "streets-vector" }),
    });
    // Missing cleanup
  }, []);
  return ;
}

// Correct: destroy view on unmount
function MapComponent() {
  const mapRef = useRef(null);
  useEffect(() => {
    const view = new MapView({
      container: mapRef.current,
      map: new Map({ basemap: "streets-vector" }),
    });
    return () => {
      view.destroy();
    };
  }, []);
  return ;
}

Impact: React strict mode mounts and unmounts components twice. Without cleanup, two views are created but only one is visible.

> Note: Map Components (`, `) manage their own lifecycle. When the DOM element is removed by React, Angular, or Vue, the component cleans up internally.

2D View Performance

Waiting for Stationary

// Anti-pattern: running expensive queries on every view change
reactiveUtils.watch(
  () => view.extent,
  async (extent) => {
    // Fires dozens of times per second during panning
    const results = await layer.queryFeatures({
      geometry: extent,
      outFields: ["name", "population"],
    });
    updateSidebar(results);
  },
);

// Correct: wait for view.stationary before querying
import * as reactiveUtils from "@arcgis/core/core/reactiveUtils.js";

reactiveUtils.watch(
  () => view.stationary,
  async (isStationary) => {
    if (isStationary) {
      const results = await layer.queryFeatures({
        geometry: view.extent,
        outFields: ["name", "population"],
      });
      updateSidebar(results);
    }
  },
);

Impact: view.stationary becomes true only after the user stops interacting. Reduces query calls from hundreds per interaction to one.

Debouncing Queries

import * as promiseUtils from "@arcgis/core/core/promiseUtils.js";

const debouncedQuery = promiseUtils.debounce(async (extent) => {
  const results = await layer.queryFeatures({
    geometry: extent,
    outFields: ["name"],
  });
  updateUI(results);
});

reactiveUtils.watch(
  () => view.extent,
  (extent) => debouncedQuery(extent),
);

Impact: promiseUtils.debounce is ArcGIS-aware: it handles abort errors and only executes the latest invocation.

Scale-Dependent Layer Visibility

// Anti-pattern: all layers visible at all zoom levels
const parcelsLayer = new FeatureLayer({ url: parcelsUrl });

// Correct: use minScale and maxScale
const parcelsLayer = new FeatureLayer({
  url: parcelsUrl,
  minScale: 25000, // Only visible when zoomed in past 1:25,000
  maxScale: 0,
});

const regionsLayer = new FeatureLayer({
  url: regionsUrl,
  minScale: 0,
  maxScale: 50000, // Hidden when zoomed in past 1:50,000
});

Impact: Without scale limits, a parcels layer with 500,000 features attempts to render all of them at state level.

3D Scene Performance

Quality Profile

import SceneView from "@arcgis/core/views/SceneView.js";

const view = new SceneView({
  container: "viewDiv",
  map: map,
  qualityProfile: "low", // "low" | "medium" | "high"
});

| Quality Profile | Effect | | --------------- | -------------------------------------------------------------------- | | "low" | Reduced texture resolution, fewer terrain tiles, lower polygon count | | "medium" | Default balance of quality and performance | | "high" | Maximum texture resolution, more terrain detail |

Impact: Switching from "high" to "low" can double frame rates on mid-range hardware.

Local vs Global Viewing Mode

// Anti-pattern: using global mode for a focused area
const view = new SceneView({
  container: "viewDiv",
  map: map,
  camera: { position: { longitude: 8.5, latitude: 47.3, z: 500 }, tilt: 70 },
});

// Correct: use local viewing mode for focused scenes
const view = new SceneView({
  container: "viewDiv",
  map: map,
  viewingMode: "local",
  clippingArea: {
    xmin: 8.4,
    ymin: 47.2,
    xmax: 8.6,
    ymax: 47.4,
    spatialReference: { wkid: 4326 },
  },
  camera: { position: { longitude: 8.5, latitude: 47.3, z: 500 }, tilt: 70 },
});

Impact: Global mode renders the entire Earth. Local mode clips to a flat plane, reducing terrain tiles and rendering complexity.

Shadow Performance

// Anti-pattern: enabling shadows for all scenes by default
const view = new SceneView({
  container: "viewDiv",
  map: map,
  environment: { lighting: { directShadowsEnabled: true } },
});

// Correct: enable shadows only when needed
const view = new SceneView({
  container: "viewDiv",
  map: map,
  environment: { lighting: { directS

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SaschaBrunnerCH](https://github.com/SaschaBrunnerCH)
- **Source:** [SaschaBrunnerCH/arcgis-maps-sdk-js-ai-context](https://github.com/SaschaBrunnerCH/arcgis-maps-sdk-js-ai-context)
- **License:** MIT

Install and usage instructions live in the source repository linked above.