There are two ways to use the ArcGIS JavaScript SDK in a web project. They look similar in a tutorial but produce meaningfully different architectures. Choosing the wrong one adds unnecessary complexity to simple projects, and choosing the wrong one the other direction limits what a production app can do.
The Two Delivery Methods
CDN — script tag in HTML:
<link rel="stylesheet" href="https://js.arcgis.com/4.32/esri/themes/dark/main.css" />
<script src="https://js.arcgis.com/4.32/"></script>
The SDK is loaded from Esri's servers at page load. No installation. No build step. Works in a plain .html file opened in a browser or served from any static host.
npm — package install:
npm install @arcgis/core
The SDK is installed locally as a Node.js package. You import individual modules in JavaScript files. A build tool (Vite, webpack, Rollup) bundles everything for the browser.
What Each One Requires
| CDN | npm | |
|---|---|---|
| Node.js required | No | Yes |
| Build step required | No | Yes |
| Works in a single HTML file | Yes | No |
| IDE autocomplete on SDK classes | Limited | Full |
| Bundle size optimization | No (full SDK loads) | Yes (tree-shaking) |
| Offline development | No | Yes |
| Works on Vercel / GitHub Pages as static file | Yes | After build |
When CDN Is Correct
Use the CDN when:
- You're building a single-file tool — one
.htmlfile that goes into apublic/folder or a GitHub Pages repo - You want to deploy in minutes without configuring a build pipeline
- The map is the primary content, not part of a larger React or Vue app
- You're prototyping or building a portfolio demo
The CDN approach is not a shortcut or a beginner compromise. Every demo on this site uses it. The ArcGIS JS SDK CDN is served from Esri's own infrastructure, versioned, cached by browsers, and functionally identical to the npm bundle for most use cases. The "thin HTML" pattern — a single file, a Vercel deploy, a live URL — is built on CDN delivery.
If your tool works and the audience can use it, the delivery method is correct.
When npm Is Correct
Use npm when:
- The map is a component inside a larger React, Vue, or Angular application
- You need tree-shaking to reduce bundle size (large apps with many SDK modules)
- Your team has a standard build pipeline and consistency matters more than simplicity
- You're using TypeScript and want full SDK type definitions in the IDE
The npm path is the right choice for production applications embedded in complex frontends. It's also what Esri recommends for SDK 5.0 going forward — the new web components model is designed with npm + build tools as the primary workflow.
The tradeoff: you now have node_modules, a vite.config.js or webpack.config.js, a build step before deployment, and a local dev server to run while developing. For a standalone map tool, that's a lot of infrastructure for a small gain.
The SDK 5.0 Shift
SDK 5.0 (currently in beta as of early 2026) introduces a new web components model — arcgis-map, arcgis-zoom, arcgis-assistant — that changes the calculus slightly.
The web components are designed to work both ways. You can load them via CDN:
<script type="module" src="https://js.arcgis.com/5.0/"></script>
Or install via npm and import in a framework component:
import "@arcgis/map-components";
Esri's DevSummit 2026 messaging leaned toward npm + Vite for 5.0 production apps, particularly for teams building EB-style widget ecosystems. But the CDN path still works for single-file tools, and the thin HTML pattern remains valid for SDK 5.0 just as it was for 4.x.
A Practical Test
If you're deciding which to use for a new project, answer two questions:
- Does this map live inside a React/Vue/Angular app? If yes — npm.
- Is this a standalone tool that deploys as a static file? If yes — CDN.
If neither is clearly true, default to CDN. You can always migrate to npm later. Migrating in the other direction — from an over-engineered npm setup back to a simpler static file — is harder and usually means rewriting.
The Hidden Cost of the Wrong Choice
The most common mistake: reaching for npm and a build pipeline on a tool that didn't need it. This happens because tutorials and official Esri samples increasingly assume a build environment. The CDN pattern is underrepresented in newer documentation.
The result is a developer spending an afternoon configuring Vite to get a map on the screen — when a <script> tag would have done the same thing in five minutes. The complexity didn't add capability. It added friction.
Build tooling is the right answer when the project demands it. It's the wrong answer when it's just the default assumption.
Related: The Thin HTML Deploy Pattern