Installing the ArcGIS API for JavaScript

Installing the ArcGIS API for JavaScript library on Windows

The instructions below assume that you are installing the ArcGIS API for JavaScript library in the following location https://www.example.com/arcgis_js_api/library/4.14/ (C:\Inetpub\wwwroot\arcgis_js_api\library\4.14\) on Internet Information Services (IIS) for Windows® Server, where www.example.com is the combination of the fully qualified domain name and top level domain of your web site.

If you are using a non-Windows operating system, please see the instructions on deploying the library on Unix/Linux.

The ArcGIS API for JavaScript library can be copied in its entirety to your web server directory (C:\Inetpub\wwwroot\arcgis_js_api\library\4.14\). Copy \arcgis_js_api\library\4.14\ and all its contents from the ArcGIS API for JavaScript download to your web server. In this example the files are copied to: C:\Inetpub\wwwroot\arcgis_js_api\library\4.14\.

After copying the files to your web server, you will need to edit some files to specify the baseUrl (www.example.com/arcgis_js_api/library/4.14/) for the default Dojo configuration.

Requirements

The default hosting configuration for both the ArcGIS API for JavaScript library and documentation is HTTPS.

• HTTPS requires your web server to use a web server certificate.
• IIS will need to have the following MIME types registered.

  extension	MIME/type	Description
  .ttf	application/octet-stream	True Type Fonts
  .wasm	application/wasm	WebAssembly
  .woff	application/font-woff	Web Open Font Format
  .woff2	application/font-woff2	WOFF File Format 2.0
  .wsv	application/octet-stream	Supports SceneView's stars visualization

• Google: Why HTTPS Matters
• Google: Secure your site with HTTPS
• Ignore and use HTTP

Modify the Build (manually)

1. Open C:\Inetpub\wwwroot\arcgis_js_api\library\4.14\dojo\dojo.js in a text editor and search for the text [HOSTNAME_AND_PATH_TO_JSAPI], and replace this text with www.example.com/arcgis_js_api/library/4.14/.
2. Open C:\Inetpub\wwwroot\arcgis_js_api\library\4.14\init.js in a text editor and search for the text [HOSTNAME_AND_PATH_TO_JSAPI], and replace this text with www.example.com/arcgis_js_api/library/4.14/.

Modify the Build (script)

Note: Scripting the update might be useful in a multi-machine deployment. Otherwise, it is not necessary.

This section will modify the ArcGIS API for JavaScript library [HOSTNAME_AND_PATH_TO_JSAPI] text with www.example.com/arcgis_js_api/library/4.14/.

1. Node.js must be installed on the machine running the Example Node.js script (update-library.js).
2. Create a file such as update-library.js in a local directory.
3. Copy the contents of the example Node.js script (update-library.js) into the update-library.js file.
4. Open a terminal window and change directory (cd) to the directory containing the update-library.js script.
5. Verify node --version return the currently installed version of Node.js.
6. Update the localHost, apiDirectory, and jsapiDownloadLocation script variables.
7. The apiDirectory and jsapiDownloadLocation script variables will not need modified if using the same directories described in this documentation.
8. Execute the update-library.js script using the command node update-library.js.
9. Open https://www.example.com/arcgis_js_api/library/4.14/init.js and https://www.example.com/arcgis_js_api/library/4.14/dojo/dojo.js in a browser of your choice.
10. Search for baseUrl:" and verify [HOSTNAME_AND_PATH_TO_JSAPI] has been replaced with the value of localHost.

Example Node.js script

The code sample below is written in JavaScript for Node.js and will automate replacing the ArcGIS API for JavaScript library [HOSTNAME_AND_PATH_TO_JSAPI] text with www.example.com/arcgis_js_api/library/4.14/.

Note: A script like update-library.js could be written in any scripting language that supports reading/writing files and some type of string substitution manipulation such as regular expressions.

// --------------------------------------------------------------------
// update-library.js
//
// Helper script to replace the ArcGIS API for JavaScript library
// `[HOSTNAME_AND_PATH_TO_JSAPI]` text with `www.example.com/arcgis_js_api/library/4.14/`.
//
// Note: requires node version 7.10.0 and npm version 4.2.0 or higher.
// --------------------------------------------------------------------
let fs                       = require("fs"),
    path                     = require("path"),
    util                     = require("util"),
    // --------------------------------------------------------------------
    // hostname to replace js.arcgis.com in the library such as:
    // www.example.com
    // apiDirectory would be the virtual directory in the web server hosting
    // the ArcGIS API for JavaScript library
    // --------------------------------------------------------------------
    localHost                = "www.example.com",
    apiDirectory             = "arcgis_js_api/library/4.14/",
    // --------------------------------------------------------------------
    // path to the downloaded ArcGIS API for JavaScript library
    // download archive contents arcgis_js_v414_api\arcgis_js_api\4.14\
    // to IIS virtual directory C:\Inetpub\wwwroot\arcgis_js_api\library\4.14\
    // --------------------------------------------------------------------
    jsapiDownloadLocation    = path.join("C:", "inetpub", "wwwroot", "arcgis_js_api", "library", "4.14"),
    // --------------------------------------------------------------------
    // Regular expression to match the template text
    // [HOSTNAME_AND_PATH_TO_JSAPI] in
    // baseUrl:"https://[HOSTNAME_AND_PATH_TO_JSAPI]dojo"
    // --------------------------------------------------------------------
    hostnameAndPathRegEx            = /\[HOSTNAME_AND_PATH_TO_JSAPI\]/i,
    // --------------------------------------------------------------------
    // base url for the locally hosted ArcGIS API for JavaScript such as:
    // www.example.com/arcgis_js_api/library/4.14/
    // --------------------------------------------------------------------
    jsapiURLBaseLocal        = util.format("%s/%s", localHost, apiDirectory),
    // --------------------------------------------------------------------
    // Dojo file containing the CDN link to ArcGIS API for JavaScript
    // C:\Inetpub\wwwroot\arcgis_js_api\library\4.14\dojo\dojo.js
    // --------------------------------------------------------------------
    jsapiDojoFile = path.join(jsapiDownloadLocation, "dojo", "dojo.js"),
    // --------------------------------------------------------------------
    // Dojo file containing the CDN link to ArcGIS API for JavaScript
    // C:\Inetpub\wwwroot\arcgis_js_api\library\4.14\init.js
    // --------------------------------------------------------------------
    jsapiInitFile = path.join(jsapiDownloadLocation, "init.js");

// --------------------------------------------------------------------
// 1) Read the ArcGIS API for JavaScript library files
// 2) Replace the script src attribute for the ArcGIS API for JavaScript CDN
// --------------------------------------------------------------------

// --------------------------------------------------------------------
// Read the dojo file contents from disk
// --------------------------------------------------------------------
console.log("library - reading %s", jsapiDojoFile);
let rawDojoContent = fs.readFileSync(jsapiDojoFile, "utf-8");
// --------------------------------------------------------------------
// Replace the script src attribute for the ArcGIS API for JavaScript CDN
// --------------------------------------------------------------------
console.log("library - replacing script tag for %s", jsapiDojoFile);
let updatedDojoContent = rawDojoContent.replace(hostnameAndPathRegEx, jsapiURLBaseLocal);
// --------------------------------------------------------------------
// Save the dojo file contents to disk
// --------------------------------------------------------------------
console.log("library - saving %s", jsapiDojoFile);
fs.writeFileSync(jsapiDojoFile, updatedDojoContent, "utf-8");

// --------------------------------------------------------------------
// Read the init file contents from disk
// --------------------------------------------------------------------
console.log("library - reading %s", jsapiInitFile);
let rawInitContent = fs.readFileSync(jsapiInitFile, "utf-8");
// --------------------------------------------------------------------
// Replace the script src attribute for the ArcGIS API for JavaScript CDN
// --------------------------------------------------------------------
console.log("library - replacing script tag for %s", jsapiInitFile);
let updatedInitContent = rawInitContent.replace(hostnameAndPathRegEx, jsapiURLBaseLocal);
// --------------------------------------------------------------------
// Save the init file contents to disk
// --------------------------------------------------------------------
console.log("library - saving %s", jsapiInitFile);
fs.writeFileSync(jsapiInitFile, updatedInitContent, "utf-8");

Test the Install

Now you should be able to access the ArcGIS API for JavaScript library from your web server using the following URL:

<script src="https://www.example.com/arcgis_js_api/library/4.14/dojo/dojo.js"></script>

Test your install. You can use the following test code to validate your ArcGIS API for JavaScript library installation.

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="initial-scale=1, maximum-scale=1,user-scalable=no" />
    <title>Test Map</title>
    <link rel="stylesheet" href="https://www.example.com/arcgis_js_api/library/4.14/dijit/themes/claro/claro.css" />
    <link rel="stylesheet" href="https://www.example.com/arcgis_js_api/library/4.14/esri/themes/light/main.css" />
    <style>
      html,
      body,
      #viewDiv {
        margin: 0;
        padding: 0;
        width: 100%;
        height: 100%;
      }
    </style>
    <script src="https://www.example.com/arcgis_js_api/library/4.14/dojo/dojo.js"></script>
    <script>
      var myMap, view;
      require([
        "esri/Basemap",
        "esri/layers/TileLayer",
        "esri/Map",
        "esri/views/MapView"
      ], function (Basemap, TileLayer, Map, MapView){
        // --------------------------------------------------------------------
        // If you do not have public internet access then use the Basemap class
        // and point this URL to your own locally accessible cached service.
        //
        // Otherwise you can just use one of the named hosted ArcGIS services.
        // https://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer
        // --------------------------------------------------------------------
        var layer = new TileLayer({
          url: "https://www.example.com/arcgis/rest/services/Folder/Custom_Base_Map/MapServer"
        });
        var customBasemap = new Basemap({
          baseLayers: [layer],
          title: "Custom Basemap",
          id: "myBasemap"
        });
        myMap = new Map({
          basemap: customBasemap
        });
        view = new MapView({
          center: [-111.87, 40.57], // long, lat
          container: "viewDiv",
          map: myMap,
          zoom: 6
        });
      });
    </script>
  </head>
  <body class="claro">
    <div id="viewDiv"></div>
  </body>
</html>

Using HTTP

Note: While not recommended, it is possible to host the ArcGIS API for JavaScript library using http. The dojo.js and init.js files would need modification to update https to http.

Before: baseUrl:"https://www.example.com/arcgis_js_api/library/4.14/dojo"

After: baseUrl:"http://www.example.com/arcgis_js_api/library/4.14/dojo"

Installing Node.js

For assistance installing Node.js on Windows, see the Installing Node.js topic in the Windows: Hosting the ArcGIS API for JavaScript documentation help topic.