To help you get started, we've collected the most common ways that esri-loader is being used within popular public projects.

sean-olson-e / Angular-and-the-ArcGIS-API-for-JavaScript / sample_apps / 7-async-observables / src / app / esri-map / esri-map.component.ts View on Github

public ngOnInit() {

    this.panRequestSubscription = this.mapService.panRequest.subscribe(() => {
      this.panMap(this.mapService.wonderCoordinates);
    });

    // use esri-loader to load JSAPI modules
    return loadModules([
      'esri/Map',
      'esri/views/MapView',
      'esri/Graphic'
    ])
      .then(([Map, MapView, Graphic]) => {
        const map: __esri.Map = new Map({
          basemap: 'hybrid'
        });

        this.mapView = new MapView({
          container: this.viewNode.nativeElement,
          center: [-12.287, -37.114],
          zoom: 12,
          map: map
        });
      })

View more ways to use esri-loader

esri-loader

A tiny library to help you use the ArcGIS API for JavaScript AMD modules in applications built with popular JavaScript frameworks and bundlers.

NOTE: It is recommended to try installing @arcgis/core and building with ES Modules instead of using esri-loader. Read more below about when you might want to use esri-loader.

Ready to jump in? Follow the Install and Usage instructions below to get started. Then see more in depth instructions on how to configure esri-loader.

Want to learn more? Learn how esri-loader can help improve application load performance and allow you to use the ArcGIS API in server side rendered applications.

Looking for legacy examples from a variety of frameworks, or 3.x information? Visit the archive page.

Table of Contents

d

• Known Limitations
• Install
• Usage
  • Loading Modules from the ArcGIS API for JavaScript
  • Lazy Loading the ArcGIS API for JavaScript
  • Loading Styles
• Do I need esri-loader?
• Advanced Usage
  • ArcGIS Types
    • esri-loader-typings-helper Plugin
  • Configuring esri-loader
  • Configuring Dojo
  • Overriding ArcGIS Styles
  • Pre-loading the ArcGIS API for JavaScript
  • Using your own script tag
  • Without a module bundler
    • Using a module script tag
    • Using the esriLoader Global
• Pro Tips
  • Using Classes Synchronously
  • Server Side Rendering
  • FAQs
• Updating from previous versions
  • From < v1.5
  • From angular-esri-loader
• Dependencies
  • Browsers
  • Promises
• Issues
• Contributing
• Licensing

Known Limitations

• Compatibility with implementations that don't support async/await at runtime, within AMD modules, is deprecated at version 4.25 (November 2022) - this means the functionality will be removed in a future release. In particular, this affects Angular applications using esri-loader because of well-known limitations in Zone.js. Angular users will need to migrate from AMD modules to using @arcgis/core ES modules in order to continue using the latest release of the API. Refer to the APIs FAQ for more information on breaking changes.

Install

npm install --save esri-loader

or

yarn add esri-loader

Usage

The code snippets below show how to load the ArcGIS API and its modules and then use them to create a map. Where you would place similar code in your application will depend on which application framework you are using.

Loading Modules from the ArcGIS API for JavaScript

From the Latest Version

Here's an example of how you could load and use the WebMap and MapView classes from the latest 4.x release to create a map (based on this sample):

import { loadModules } from 'esri-loader';

// this will lazy load the ArcGIS API
// and then use Dojo's loader to require the classes
loadModules(['esri/views/MapView', 'esri/WebMap'])
  .then(([MapView, WebMap]) => {
    // then we load a web map from an id
    const webmap = new WebMap({
      portalItem: { // autocasts as new PortalItem()
        id: 'f2e9b762544945f390ca4ac3671cfa72'
      }
    });
    // and we show that map in a container w/ id #viewDiv
    const view = new MapView({
      map: webmap,
      container: 'viewDiv'
    });
  })
  .catch(err => {
    // handle any errors
    console.error(err);
  });

From a Specific Version

By default esri-loader will load modules from the latest 4.x release of the API from the CDN, but you can configure the default behavior by calling setDefaultOptions() once before making any calls to loadModules().

// app.js
import { setDefaultOptions } from 'esri-loader';

// configure esri-loader to use version 4.24 from the ArcGIS CDN
// NOTE: make sure this is called once before any calls to loadModules()
setDefaultOptions({ version: '4.24' })

Then later, for example after a map component has mounted, you would use loadModules() as normal.

// component.js
import { loadModules } from 'esri-loader';

// this will lazy load the ArcGIS API
// and then use Dojo's loader to require the map class
loadModules(['esri/map'])
  .then(([Map]) => {
    // create map with the given options at a DOM node w/ id 'mapNode'
    let map = new Map('mapNode', {
      center: [-118, 34.5],
      zoom: 8,
      basemap: 'dark-gray'
    });
  })
  .catch(err => {
    // handle any script or module loading errors
    console.error(err);
  });

You can load the "next" version of the ArcGIS API by passing version: 'next'.

From a Specific URL

If you want to load modules from a build that you host on your own server (i.e. that you've downloaded or built with Dojo), you would set the default url option instead:

// app.js
import { setDefaultOptions } from 'esri-loader';

// configure esri-loader to use version from a locally hosted build of the API
// NOTE: make sure this is called once before any calls to loadModules()
setDefaultOptions({ url: `https://server/path/to/esri` });

See Configuring esri-loader for all available configuration options.

Lazy Loading the ArcGIS API for JavaScript

Lazy loading the ArcGIS API can dramatically improve the initial load performance of your mapping application, especially if your users may never end up visiting any routes that need to show a map or 3D scene. That is why it is the default behavior of esri-loader. In the above snippets, the first time loadModules() is called, it will lazy load the ArcGIS API by injecting a `

### Without a module bundler

Typically you would [install the esri-loader package](#install) and then use a module loader/bundler to `import` the functions you need as part of your application's build. However, ES5 builds of esri-loader are also distributed on [UNPKG](https://unpkg.com/) both as ES modules and as a [UMD](https://jargon.js.org/_glossary/UMD.md) bundle that exposes the `esriLoader` global.

This is an _excellent_ way to prototype how you will use the ArcGIS API for JavaScript, or to isolate any problems that you are having with the API. Before we can help you with any issue related to the behavior of a map, scene, or widgets, we will **require** you to reproduce it _outside_ your application. A great place to start is one of the codepens linked below.

#### Using a module script tag

You can load the esri-loader [ES modules directly in modern browsers](https://caniuse.com/#feat=es6-module) using `

You can fork this codepen to try this out yourself.

A disadvantage of this approach is that the ES module build of esri-loader is not bundled. This means your browser will make multiple requests for a few (tiny) JS files, which may not be suitable for a production application.

Using the esriLoader Global

If you need to run the script in an older browser, you can load the UMD build and then use the esriLoader global.

You can fork this codepen to try this out yourself.

Pro Tips

Using Classes Synchronously

Let's say you need to create a map in one component, and then later in another component add a graphic to that map. Unlike creating a map, creating a graphic and adding it to a map is ordinarily a synchronous operation, so it can be inconvenient to have to wait for loadModules() just to load the Graphic class. One way to handle this is have the function that creates the map also load the Graphic class before its needed. You can then hold onto that class for later use to be exposed by a function like addGraphicToMap(view, graphicJson):

// utils/map.js
import { loadModules } from 'esri-loader';

// NOTE: module, not global scope
let _Graphic;

// this will be called by the map component
export function loadMap(element, mapOptions) {
  return loadModules(['esri/Map', 'esri/views/MapView', 'esri/Graphic'])
  .then(([Map, MapView, Graphic]) => {
    // hold onto the graphic class for later use
    _Graphic = Graphic;
    // create the Map
    const map = new Map(mapOptions);
    // return a view showing the map at the element
    return new MapView({
      map,
      container: element
    });
  });
}

// this will be called by the component that needs to add the graphic to the map
export function addGraphicToMap(view, graphicJson) {
  // make sure that the graphic class has already been loaded
  if (!_Graphic) {
    throw new Error('You must load a map before creating new graphics');
  }
  view.graphics.add(new _Graphic(graphicJson));
}

You can see this pattern in use in a real-world application.

See #124 (comment) and #71 (comment) for more background on this pattern.

Server Side Rendering

This library also allows you to use the ArcGIS API in applications that are rendered on the server. There's really no difference in how you invoke the functions exposed by this library, however you should avoid trying to call them from any code that runs on the server. The easiest way to do this is to call loadModules() in component lifecyle hooks that are only invoked in a browser, for example, React's useEffect or componentDidMount, or Vue's mounted.

Alternatively, you could use checks like the following to prevent calling esri-loader functions on the server:

import { loadCss } from 'esri-loader';

if (typeof window !== 'undefined') {
  // this is running in a browser, so go ahead and load the CSS
  loadCss();
}

See next-arcgis-app or esri-loader-react-starter-kit for examples of how to use esri-loader in server side rendered (SSR) applications.

FAQs

In addition to the pro tips above, you might want to check out some frequently asked questions.

Updating from previous versions

From < v1.5

If you have an application using a version that is less than v1.5, this commit shows the kinds of changes you'll need to make. In most cases, you should be able to replace a series of calls to isLoaded(), bootstrap(), and dojoRequire() with a single call to loadModules().

From angular-esri-loader

The angular-esri-loader wrapper library is no longer needed and has been deprecated in favor of using esri-loader directly. See this issue for suggestions on how to replace angular-esri-loader with the latest version of esri-loader.

Dependencies

Browsers

This library doesn't have any external dependencies, but the functions it exposes to load the ArcGIS API and its modules expect to be run in a browser. This library officially supports the same browsers that are supported by the latest version of the ArcGIS API for JavaScript.

You cannot use this helper library in Node.js, but you can use this library in server side rendered applications as well as Electron. If you need to execute requests to ArcGIS REST services from something like a Node.js CLI application, see ArcGIS Rest JS.

Promises

The asynchronous functions like loadModules() and loadScript() return Promises, so if your application has to support browsers that don't support Promise (i.e. IE) you have a few options.

If there's already a Promise implementation loaded on the page you can configure esri-loader to use that implementation. For example, in ember-esri-loader, we configure esri-loader to use the RSVP Promise implementation included with Ember.js.

import { utils } from  'esri-loader';

init () {
  this._super(...arguments);
  // have esriLoader use Ember's RSVP promise
  utils.Promise = Ember.RSVP.Promise;
},

Otherwise, you should consider using a Promise polyfill, ideally only when needed.

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Licensing

Copyright © 2016-2022 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.