Load ArcGIS API for JavaScript modules using SystemJS
TypeScript
Latest commit 3678a09 Feb 21, 2017 @tomwayson tomwayson added typescript info to README
resolves #18

README.md

esri-system-js

Load ArcGIS API for JavaScript modules using SystemJS

Provides a wrapper around SystemJS's register() function that will first use Dojo's AMD loader to load Esri modules, and then register a SystemJS module that will expose them.

SystemJS Plugin

systemjs-plugin-dojo is a SystemJS plugin for loading Dojo modules that works with the ArcGIS API for JavaScript. ng2-esri-demo shows how to use that plugin to load ArcGIS modules in an Angular application.

This library (esri-system-js) predates the above SystemJS plugin, but is not a SystemJS plugin, and therefore requires you to perform the additional configuration steps shown below.

Quick Start

For example, if you wanted to use ArcGIS API for JavaScript modules in your TypeScript code in an Angular 2 application.

1) Install:

npm install esri-system-js@beta --save

2) Include (in index.html):

<!-- load SystemJS library -->
<script src="node_modules/systemjs/dist/system.src.js"></script>

<!-- load Esri library -->
<link rel="stylesheet" href="//js.arcgis.com/4.0/esri/css/main.css">
<script src="//js.arcgis.com/4.0/"></script>

<!-- load esri-system-js library -->
<script src="node_modules/esri-system-js/dist/esriSystem.js"></script>

3) Configure (in index.html):

<script>
// configure system.js
System.config({
  packages: {
    app: {
      defaultExtension: 'js'
    }
  }
});

// load esri modules needed by this application
// and then regsiter each as it's own SystemJS module
esriSystem.register(
  // array of Esri module names to load and then register with SystemJS
  [
    'esri/Map',
    'esri/views/MapView',
    'esri/widgets/Home/HomeViewModel',
    'esri/request'
  ],

  // optional callback function
  function() {
    // then bootstrap application
    System.import('app/boot')
      .then(null, console.error.bind(console));
  });
</script>

4) Import modules (in app/boot.ts or any other application module):

import Map from 'esri/Map';
import MapView from 'esri/views/MapView';
import esriRequest from 'esri/request';

If your project requires you to configure SystemJS with defaultJSExtensions: true, see this issue for additional configuration steps.

Using esri-system-js in TypeScript Applications

If you're writing your application code in TypeScript, you can now get type checking and intellisense for the above modules by downloading and using the ArcGIS API for JavaScript type definitions. Note that you will need to configure the TypeScript compiler to use "allowSyntheticDefaultImports": true.

Registering as a Single Module

You can supply a third, optional argument to esriSystem.register() with options to register all the required Esri modules to a single new module. Note that registering all modules as a single SystemJS module will not work with the ArcGIS API for JavaScript type definitions).

// load esri modules needed by this application
// and then regsiter a new SystemJS module that exposes them
esriSystem.register(
  // array of Esri module names to load and then register with SystemJS
  [
    'esri/Map',
    'esri/views/MapView',
    'esri/widgets/Home/HomeViewModel',
    'esri/request'
  ],

  // optional callback function
  function() {
    // then bootstrap application
    System.import('app/boot')
      .then(null, console.error.bind(console));
  },
  // options to register a new, single SystemJS module
  {
    // name of SystemJS module that you will import from
    outModuleName: 'esri-mods',
    // by default each module will use everything after the last '/' in their name
    // however you can override that for specific modules here
    moduleNameOverrides: {
      'esri/request': 'esriRequest'
    }
  });
</script>

Now you can import these modules as follows:

import { Map, MapView, esriRequest } from 'esri-mods';

Why?

The ArcGIS API for JavaScript is based on Dojo, which uses AMD modules, and SystemJS can load AMD modules, so why is this needed? We've not been able to figure out a way to have SystemJS load Esri's modules directly. As with other loaders that support AMD, the issue is around plugins. You can see a summary of the issue here.

Example Applications

See these applications for examples of how to use this library:

Have you built an application using esri-system-js? Let us know and we'll add it here.

Development Instructions

Make sure you have Node installed.

  1. Fork and clone this repo
  2. cd into the esri-system-js folder
  3. Install the dependencies with npm install
  4. run npm start from the command line. This will run the TypeScript compiler then start a local web server hosting the application under the docs folder
  5. Modify the source files (under src)
  6. Make a pull request to contribute your changes

Credit

This pattern was established by @odoe in the load.js file of his example of using ErsiJS 4.0 view models with Angular 2.

Later, @nickcam came up with the idea to register one SystemJS module for each Esri module required and maintain the exact same module names, which makes it possible to use the ArcGIS API for JavaScript type definitions for the modules you import.

Resources

Issues

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

Contributing

Anyone and everyone is welcome to contribute. Please see our guidelines for contributing.

Licensing

Copyright 2016 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

http://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.txt file.