When the 4.0 version of the ArcGIS API for JavaScript was released, we also released a Bower compatible minified version of the API for users interested in doing their own custom local builds. This was a big step in our direction to help users integrate the ArcGIS API for JavaScript into their own workflows.
We have since had numerous requests to publish the ArcGIS API for JavaScript to NPM. One of the reasons we have not done this is that Bower provides us with some advantages when it comes to creating custom local builds. Publishing the API to NPM will not automatically make it compatible with build tools like Webpack. It actually adds a couple of steps to the Dojo build needed to compile the ArcGIS API for JavaScript.
With the upcoming release of 4.4 we will publish the ArcGIS API for JavaScript to NPM. We will also be providing some updated resources about how to do a Dojo build with the API.
Start using NPM today
However, you could start using NPM today to install the ArcGIS API for JavaScript locally.
Let's start with the sample application provided in the resources repo on github.
Take a look at the bower.json file provided with the ArcGIS API for JavaScript repo.
...
"dependencies": {
"dojo": "Esri/dojo#v1.12.1/esri-3.20.0",
"dojox": "Esri/dojox#v1.12.1/esri-3.20.0",
"dijit": "Esri/dijit#v1.12.1/esri-3.20.0",
"util": "Esri/dojo-util#v1.12.1/esri-3.20.0",
"dgrid": "Esri/dgrid#v1.1.0/esri-3.20.0",
"dstore": "1.1.1", "moment": "2.17.1"
},
...
We can borrow most of this for our package.json of our custom application.
...
"dependencies": {
"dgrid": "Esri/dgrid#v1.1.0/esri-3.20.0",
"dijit": "Esri/dijit#v1.12.1/esri-3.20.0",
"dojo": "Esri/dojo#v1.12.1/esri-3.20.0",
"dojo-dstore": "^1.1.1",
"dojo-util": "^1.12.2",
"dojox": "Esri/dojox#v1.12.1/esri-3.20.0",
"arcgis-js-api": "Esri/arcgis-js-api#4.3.1",
"moment": "2.17.1"
},
...
You can see this looks very similar. Main difference is that util is now dojo-util and dstore is now dojo-dstore, because these are the names of the published packages on NPM. You may also notice that we can bring in the arcgis-js-api repo using Esri/arcgis-js-api#4.3.1. This tells NPM too look on github at the Esri org and install the arcgis-js-api repo using the 4.3.1 release.
At this point you can delete the bower.json and .bowerrc files from the project since they are not going to be used.
One disadvantage of using NPM instead of Bower is that NPM does not allow you to change the name of the folder the package is installed. Meaning that the JavaScript API will installed to node_modules/arcgis-js-api instead of node_modules/esri which would be ideal as far as how we typically use the Dojo build system.
Hint: If you use Yarn instead of NPM, it can install to custom named directories.
Once you NPM install these packages you will have a folder structure that should look something like this.
node_modules/
arcgis-js-api/
dgrid/
dijit/
dojo/
dojo-dstore/
dojo-util/
dojox/
src/
app/
main.js
Now you need to tell Dojo where to locate the packages. You can do this by supplying a global dojoConfig object.
<!-- index.html -->
<script>
// point to node_modules folder
window.dojoConfig = {
baseUrl: '../node_modules/',
packages: [
'dijit',
'dojo',
'dojox',
'dgrid',
'moment',
{
name: 'app',
location: '../src/app'
},
// alias for dstore package
{
name: 'dstore',
location: 'dojo-dstore'
},
// alias for esri package
{
name: 'esri',
location: 'arcgis-js-api'
}
]
};
</script>
<script src="../node_modules/dojo/dojo.js"></script>
<script>require(["app/main"]);</script>
There is one more thing you will need to do your own code in order for this to work. The ArcGIS API for JavaScript uses Web Workers for Vector Tiles. You will need to let the workers know where the esri package is located in order for them to function. You can do this in the following manner using esri/config and dojo/has.
//app/main.js
if (!has("dojo-built")) {
esriConfig.workers.loaderConfig = {
paths: {
"esri": "../arcgis-js-api"
}
};
}
The reason we use dojo/has is that once the application is built, the Dojo build system will install the esri package into an esri folder and not arcgis-js-api. So we only need this configuration during the development process.
Now you can develop your application using the JavaScript API installed in node_modules.
When you do your Dojo build, you will need to do something similar. However, the Dojo build is expecting the build tools to be located in a folder called util, but they are in fact installed in a folder called dojo-util. This requires you to create a dojoConfig for the build system in the root of your project.
// dojoconfig.js
dojoConfig = {
baseUrl: './node_modules/',
packages: [
{
name: 'dojo',
location: 'dojo'
},
{
name: 'build',
location: 'dojo-util/build'
}
]
};
require('./node_modules/dojo/dojo.js');
Then to run your Dojo build from the command line you can use node dojoconfig.js load=build --profile build.profile.js --releaseDir ../dist.
This will now tell Dojo where to find the build tools needed.
You will also need to update the build.profile.js to reflect the new locations of the packages.
// build.profile.js
packages: [
// "app" is a sample path for your application
// set this accordingly
"app",
{
name: 'dijit',
location: '../node_modules/dijit',
trees: [
// don"t bother with .hidden, tests, min, src, and templates
[".", ".", /(\/\.)|(~$)|(test|node_modules)/]
]
},
{
name: 'dojo',
location: '../node_modules/dojo',
trees: [
// don"t bother with .hidden, tests, min, src, and templates
[".", ".", /(\/\.)|(~$)|(test|node_modules)/]
]
},
{
name: 'dojox',
location: '../node_modules/dojox'
},
{
name: 'dstore',
location: '../node_modules/dojo-dstore',
trees: [
// don"t bother with .hidden, tests, min, src, and templates
[".", ".", /(\/\.)|(~$)|(test|txt|src|min|templates|node_modules)/]
]
},
{
name: 'dgrid',
location: '../node_modules/dgrid',
trees: [
// don"t bother with .hidden, tests, min, src, and templates
[".", ".", /(\/\.)|(~$)|(test|node_modules)/]
]
},
{
name: 'esri',
location: '../node_modules/arcgis-js-api'
},
{
name: "moment",
location: "../node_modules/moment",
main: "moment",
trees: [
// don"t bother with .hidden, tests, min, src, and templates
[".", ".", /(\/\.)|(~$)|(test|txt|src|min|templates)/] ],
resourceTags: {
amd: function(filename, mid){
return /\.js$/.test(filename);
}
}
}
],
Notice the addition of the trees array for each package. This lets the Dojo compiler know which files and folders to ignore so it doesn't try to include tests and documentation in the build process.
Summary
So if you are interested in using NPM to install the ArcGIS API for JavaScript locally today, these are the steps you would need to take. All this is still valid once we publish the JavaScript API to NPM, except you will only need to install the arcgis-js-api package by name and not need to install the other dependencies yourself. Bower does provide us with a distinct advantage when it comes naming the folders and locations that packages are installed, but NPM allows to keep all dependency code in a single location.
Please note, that if you want to use RequireJS and the RequireJS Optimizer to build the ArcGIS API for JavaScript, you should continue to use Bower as some of the required build tools cannot be installed via NPM.
Even once the API is published to NPM, we will continue to provide the Bower release for as long as it's sustainable since it's all the same codebase.
Contributed by Rene Rubalcava !
Aug 30, 2018
