This programming pattern describes how to work with local assets and is only meant for projects that install the ArcGIS Maps SDK for JavaScript ArcGIS Maps SDK for JavaScript, previously known as ArcGIS API for JavaScript, is a developer product for building mapping and spatial analysis applications for the web. Learn more from npm. For projects that use the JavaScript Maps SDK on a locally hosted CDN in a disconnected environment, visit the Downloads and previous versions page.

In a project using the core API, Map components, Charts components, Coding components, and Common components the JavaScript Maps SDK‘s assets include styles, images, web workers, wasm and localization files.

Local assets

In some cases, you may need to run the SDK in an environment that is disconnected from public internet (e.g., LAN) to avoid making external requests to resources, such as those to https://js.arcgis.com, where ArcGIS CDN assets (styles, web workers, localization files, etc.) are hosted.

In such a case, you must manage assets locally by copying them into your project from the following directories:

  • @arcgis/core
    • /node_modules/@arcgis/core/assets/
  • @arcgis/map-components
    • /node_modules/@arcgis/map-components/dist/cdn/assets/
  • @arcgis/charts-components
    • /node_modules/@arcgis/charts-components/dist/cdn/assets/
  • @arcgis/coding-components
    • /node_modules/@arcgis/coding-components/dist/cdn/assets/
  • @arcgis/common-components
    • /node_modules/@arcgis/common-components/dist/cdn/assets/
  • @esri/calcite-components
    • /node_modules/@esri/calcite-components/dist/cdn/assets/

Explicitly import local stylesheets if necessary

Starting with the 4.34 release, CSS is loaded automatically when using the SDK’s components with npm, including stylesheets for both the components and Calcite.

However, if your app is built with Angular or a build tool that does not have a CSS plugin, this won’t work automatically.

In case stylesheets are not automatically imported for you, ensure that you have added imports in your style.css file to reference local copies of the stylesheets.

style.css
/* Core API stylesheet */
/* Only necessary if you still work with widgets and/or programmatically initializing a new MapView/SceneView */
/* @import "@arcgis/core/assets/esri/themes/light/main.css"; */

Copy and point to local assets

You can use a build tool plugin to manage local assets during development and copy them into your build output. For Vite, there is vite-plugin-static-copy, and for webpack, there is copy-webpack-plugin.

If you prefer writing your own asset copying scripts rather than using a plugin, you can use a package like cpx2, but you are responsible for running them during development and builds, and for keeping the copied assets in sync with your dependencies.

package.json
{
"scripts": {
"dev": "npm run copy:all && vite",
"build": "npm run copy:all && vite build",
"preview": "vite preview",
"copy:all": "npm run copy:calcite && npm run copy:core && npm run copy:components",
"copy:calcite": "cpx \"node_modules/@esri/calcite-components/dist/cdn/assets/**/*.*\" ./public/assets",
"copy:core": "cpx \"node_modules/@arcgis/core/assets/**/*.*\" ./public/assets",
"copy:components": "cpx \"node_modules/@arcgis/coding-components/dist/cdn/assets/**/*.*\" ./public/assets && cpx \"node_modules/@arcgis/map-components/dist/cdn/assets/**/*.*\" ./public/assets && cpx \"node_modules/@arcgis/charts-components/dist/cdn/assets/**/*.*\" ./public/assets && cpx \"node_modules/@arcgis/common-components/dist/cdn/assets/**/*.*\" ./public/common-components/assets"
}
}

The Vite configuration below uses vite-plugin-static-copy to copy assets from installed packages into the build output and filters translation files to minimize build size. In your vite.config.js, import Vite and the copy plugin, then set includedLocales to specify which languages and regional variants (such as en-US) your app needs. The patterns will identify and retain only those locale-specific files. For webpack users, use the plugin’s filter option to exclude unnecessary translation files.

vite.config.js
import { defineConfig, normalizePath } from "vite";
import { viteStaticCopy } from "vite-plugin-static-copy";
// Most users only need translation files for one or few languages.
// This helps decrease build size by excluding languages from the final build output.
const includedLocales = new Set(["en"]);
const localePatterns = [
/(?:^|\/)t9n\/[^/]+\.([a-z]{2,3}(?:-[a-z0-9]{2,8})*)\.(?:json|js)$/i,
/\.t9n\.([a-z]{2,3}(?:-[a-z0-9]{2,8})*)\.(?:json|js)$/i,
/(?:^|\/)messages?\.([a-z]{2,3}(?:-[a-z0-9]{2,8})*)\.(?:json|js)$/i,
/(?:^|\/)translations\/([a-z]{2,3}(?:-[a-z0-9]{2,8})*)\.(?:json|js)$/i,
];
const isIncludedLocale = (locale) =>
[...includedLocales].some((includedLocale) => {
const normalizedIncludedLocale = includedLocale.toLowerCase();
return (
locale === normalizedIncludedLocale ||
locale.startsWith(`${normalizedIncludedLocale}-`) ||
normalizedIncludedLocale.startsWith(`${locale}-`)
);
});
const isExcludedLocaleAsset = (path) => {
const normalized = path.replaceAll("\\", "/");
const locale = localePatterns
.map((pattern) => normalized.match(pattern)?.[1])
.find(Boolean)
?.toLowerCase();
return locale !== undefined && !isIncludedLocale(locale);
};

Next, define the copy targets for the packages your app uses. Each target specifies a source, an output folder, and the number of source path segments to remove with stripBase. Remove the targets for any component packages your app does not use.

Most assets go into assets. Common component assets go into common-components/assets. The mapping normalizes source paths and filters out translation files for unselected locales.

vite.config.js
const targets = [
{
src: "node_modules/@esri/calcite-components/dist/cdn/assets/**/*.*",
dest: "assets",
stripBase: 6,
},
{
src: "node_modules/@arcgis/core/assets/**/*.*",
dest: "assets",
stripBase: 4,
},
{
src: "node_modules/@arcgis/coding-components/dist/cdn/assets/**/*.*",
dest: "assets",
stripBase: 6,
},
{
src: "node_modules/@arcgis/map-components/dist/cdn/assets/**/*.*",
dest: "assets",
stripBase: 6,
},
{
src: "node_modules/@arcgis/charts-components/dist/cdn/assets/**/*.*",
dest: "assets",
stripBase: 6,
},
{
src: "node_modules/@arcgis/common-components/dist/cdn/assets/**/*.*",
dest: "common-components/assets",
stripBase: 6,
},
].map(({ src, dest, stripBase }) => ({
src: normalizePath(src),
dest,
rename: { stripBase },
transform: {
encoding: "buffer",
handler: (content, filename) => (isExcludedLocaleAsset(filename) ? null : content),
},
}));

Finally, register the targets with the copy plugin. Vite writes the build output to dist and opens the app in a browser when the development server starts.

vite.config.js
export default defineConfig({
plugins: [viteStaticCopy({ structured: true, targets })],
build: {
outDir: "dist",
},
server: {
open: true,
},
});

After copying, the next step is to configure the asset paths in your code to ensure the SDK can correctly locate and load these resources. This step is crucial in a local build environment, because the default asset paths may not align with your project’s structure.

index.html
<head>
<title>Maps SDK in a disconnected environment</title>
<script>
globalThis.esriConfig = {
assetsPath: "./assets",
// Optional: point to your Enterprise portal and /portal/apps/fonts directory
// portalUrl: "https://<your-enterprise-portal>.com/portal",
// fontsUrl: "https://<your-enterprise-portal>.com/portal/apps/fonts/",
};
</script>
</head>
main.js
import { setAssetPath as setCalciteAssetPath } from "@esri/calcite-components";
import { setAssetPath as setMapAssetPath } from "@arcgis/map-components";
import { setAssetPath as setChartsAssetPath } from "@arcgis/charts-components";
import { setAssetPath as setCodingAssetPath } from "@arcgis/coding-components";
import { setAssetPath as setCommonAssetPath } from "@arcgis/common-components";
// Set assets paths
setCalciteAssetPath("./assets");
setMapAssetPath("./assets");
setChartsAssetPath("./assets");
setCodingAssetPath("./assets");
setCommonAssetPath("./common-components/assets");
// Individual imports for each component used
import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/charts-components/components/arcgis-chart";
import "@arcgis/coding-components/components/arcgis-arcade-editor";
import "@esri/calcite-components/components/calcite-button";
import "@esri/calcite-components/components/calcite-scrim";

Additional considerations

Fonts

For some disconnected environments, font references need to be changed. For example, if a feature layer has labels then a request will be made to static.arcgis.com for the label font unless the config.fontUrl has been set up to point to your Enterprise /portal/apps/fonts directory.

For more information, check out the Labeling guide topic which includes information about custom fonts and disconnected environments.

Basemaps and data

Basemaps and data, such as web maps, that are hosted in ArcGIS Online are not accessible from a disconnected environment. Prepare basemaps for use in ArcGIS Enterprise or work without a basemap. In addition, prepare data for use in ArcGIS Enterprise or use client-side data. See the ArcGIS portal guide for more details.

Conclusion

You may use default ArcGIS CDN assets or local assets from /node_modules. If you followed all local assets instructions, your browser’s developer tools network tab shouldn’t show requests to https://js.arcgis.com.

As an alternative for offline workflows where individual devices work with limited or no internet connection, use the ArcGIS Maps SDKs for native apps. They offer robust offline coding patterns and are designed for building apps that run directly on mobile, desktop, and embedded devices, using .NET, Qt, Swift or Kotlin.