config

AMD: require(["esri/config"], (esriConfig) => { /* code goes here */ });
ESM: import esriConfig from "@arcgis/core/config.js";
Object: esri/config
Since: ArcGIS Maps SDK for JavaScript 4.0

Configure global properties of the library.

The value of this module is an object with the following properties. You can also use the global esriConfig variable to initialize the esri/config module.

Examples
require(["esri/config"], function(esriConfig) {
  esriConfig.portalUrl = "https://myHostName.esri.com/arcgis";
});
<script>
// use the global esriConfig variable to initialize properties
var esriConfig = {
  portalUrl: "https://myHostName.esri.com/arcgis"
};
</script>

Property Overview

Name Type Summary Object

An authorization string used to access a resource or service.

config

The name of the application using the API.

config

Overrides the URL for loading the API assets when using local builds of the @arcgis/core and arcgis-js-api NPM packages.

config

The URL for font resources used by the Font class in non-MapImageLayer labels for both 2D MapViews and 3D SceneViews.

config

The default geometryService used by widgets and other operations, such as on-the-fly projections.

config

The URL for the utility service used by GeoRSSLayer to convert GeoRSS documents.

config

The URL for the utility service used by KMLLayer to convert KML documents.

config

An object with properties that control various aspects of log messages.

config

The default URL of new portal instances.

config

An object with properties that control various aspects of communication between the library and web servers.

config

Controls whether the API respects the user's preference for reduced motion.

config

The default routing service used by the RouteLayer and the Directions widget.

config

Indicates whether layers should apply privileges of the authenticated user to their capabilities.

config

An object with properties that control various aspects of the workers framework.

config

Property Details

apiKey

Property
apiKey String
Since: ArcGIS Maps SDK for JavaScript 4.18 config since 4.0, apiKey added at 4.18.

An authorization string used to access a resource or service. API keys are generated and managed in your portal. An API key is tied explicitly to an ArcGIS account; it is also used to monitor service usage. Setting a fine-grained API key on a specific class overrides this global API key.

Known Limitations

When using an API key, persistence to ArcGIS Online is not supported (e.g. saving web maps, web scenes, feature layers, and other portal items).

applicationName

Property
applicationName String
Since: ArcGIS Maps SDK for JavaScript 4.27 config since 4.0, applicationName added at 4.27.

The name of the application using the API. This value is returned in the output of the GetEnvironment function in Arcade expressions.

Default Value:""
Example
esriConfig.applicationName = "Sample Application";

assetsPath

Property
assetsPath String
Since: ArcGIS Maps SDK for JavaScript 4.18 config since 4.0, assetsPath added at 4.18.

Overrides the URL for loading the API assets when using local builds of the @arcgis/core and arcgis-js-api NPM packages. The assets include styles, images, web workers, wasm and localization files. By default, assets are loaded from a CDN at runtime.

For use only in local NPM builds.

Default Value:"https://js.arcgis.com/[4.x]/@arcgis/core/assets"
See also
Example
import esriConfig from "@arcgis/core/config";
esriConfig.assetsPath = "./assets";

fontsUrl

Property
fontsUrl String
Since: ArcGIS Maps SDK for JavaScript 4.8 config since 4.0, fontsUrl added at 4.8.

The URL for font resources used by the Font class in non-MapImageLayer labels for both 2D MapViews and 3D SceneViews. This also applies to TextSymbol, TextSymbol3DLayer, and symbolUtils.

To use your own hosted fonts, the font files need to be in .pbf format for 2D, .woff2 format for 3D, and .woff2 format for renderPreviewHTML. You also must follow the kebab-case naming convention (e.g. "arial-unicode-ms-bold").

Default Value:"https://static.arcgis.com/fonts"
See also
Example
esriConfig.fontsUrl = "https://myserver.com/fonts";

geometryServiceUrl

Property
geometryServiceUrl String

The default geometryService used by widgets and other operations, such as on-the-fly projections.

Default Value:"https://utility.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer"
Example
esriConfig.geometryServiceUrl = "https://utility.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer";

geoRSSServiceUrl

Property
geoRSSServiceUrl String

The URL for the utility service used by GeoRSSLayer to convert GeoRSS documents.

Default Value:"https://utility.arcgis.com/sharing/rss"
Example
esriConfig.geoRSSServiceUrl = "https://servername.domain.suffix/arcgis/sharing/rss";

kmlServiceUrl

Property
kmlServiceUrl String
Since: ArcGIS Maps SDK for JavaScript 4.5 config since 4.0, kmlServiceUrl added at 4.5.

The URL for the utility service used by KMLLayer to convert KML documents.

Default Value:"https://utility.arcgis.com/sharing/kml"
Example
esriConfig.kmlServiceUrl = "https://servername.domain.suffix/arcgis/sharing/kml";

log

Property
log Object
Since: ArcGIS Maps SDK for JavaScript 4.17 config since 4.0, log added at 4.17.

An object with properties that control various aspects of log messages.

Note that the module name, message and detailed content of log messages is not considered stable and interceptors should not be used to create application error handling control flows.

Properties
interceptors LogInterceptor[]

An array of custom interceptor functions that can be used to intercept log messages. Interceptors are invoked in order until an interceptor returns true. The default log handler that writes log messages to the console will be invoked last.

level String

The level of messages to log. All messages with severity higher or equal than the one configured will be logged. No messages will be logged if the specified level is "none". The default level if left undefined is "warn".

Possible Values:"none"|"error"|"warn"|"info"

portalUrl

Property
portalUrl String

The default URL of new portal instances. If using an on-premise portal, this value should be set to the portal instance, for example: https://www.example.com/arcgis

Default Value:"https://www.arcgis.com"
See also
Example
// Set the hostname to the on-premise portal
esriConfig.portalUrl = "https://myHostName.esri.com/arcgis"

request

Property
request Object

An object with properties that control various aspects of communication between the library and web servers.

Properties
httpsDomains String[]
optional

List of domain suffixes known to support https. This will automatically upgrade requests made to such domains to use https instead of http when the application is not running on http. Note that port numbers should not be included in the domain suffix to be matched.

If no httpsDomains list exists , the API redirects all calls using https. If the list exists and a domain of a required http resource is not listed, the API sends the URL as it is specified within the code. Likewise, if the list exists and the domain of a required http resource is listed in it, the API sends a https request to that resource.

The list includes the following domain suffixes by default:

  • arcgis.com
  • arcgisonline.com
interceptors RequestInterceptor[]
optional

Since: 4.8

Allows developers to modify requests before or after they are sent. The first interceptor that matches the request URL will be used.

Example:

const featureLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/0";

esriConfig.request.interceptors.push({
  // set the `urls` property to the URL of the FeatureLayer so that this
  // interceptor only applies to requests made to the FeatureLayer URL
  urls: featureLayerUrl,
  // use the BeforeInterceptorCallback to check if the query of the
  // FeatureLayer has a maxAllowableOffset property set.
  // if so, then set the maxAllowableOffset to 0
  before: function(params) {
    if (params.requestOptions.query.maxAllowableOffset) {
      params.requestOptions.query.maxAllowableOffset = 0;
    }
  },
  // use the AfterInterceptorCallback to check if `ssl` is set to 'true'
  // on the response to the request, if it's set to 'false', change
  // the value to 'true' before returning the response
  after: function(response) {
    if (!response.ssl) {
      response.ssl = true;
    }
  }
});
maxUrlLength Number
optional
Default Value:2000

Maximum number of characters allowed in the URL for HTTP GET requests made by request. If this limit is exceeded, HTTP POST method will be used.

priority String
optional
Default Value:high

Since: 4.24

The fetch and image network request priority. This is a hint to browsers on how important these requests are relative to other pending requests. The "auto" value lets browsers decide on the priority. They typically use "high" priority for fetch requests, and "low" priority for image requests. See more information at https://web.dev/priority-hints/. See browser support for this feature at https://caniuse.com/mdn-api_request_priority.

Possible Values:"auto"|"high"|"low"

proxyRules Object[]
optional

A proxy rule defines a proxy for a set of resources with an identical URL prefix. When using esriRequest, if a target URL matches a rule, then the request will be sent to the specified proxy. Rather than populating this array directly, use the urlUtils.addProxyRule() method. Rule objects have the following properties:

Specification
proxyUrl String
optional

The URL of the proxy.

urlPrefix String
optional

URL prefix for resources that need to be accessed through a specific proxy.

proxyUrl String
optional
Default Value:null

Resource proxy for your application. It is used by the library when communicating with a web server hosted on a domain that is different from the domain where your application is hosted.

The library may or may not use the proxy depending on the type of request made, whether the server support CORS, whether the application is being run on older versions of browsers etc.

You can download a proxy from this GitHub repo.

require(["esri/config"], function(esriConfig) {
  esriConfig.request.proxyUrl = "/proxy/Java/proxy.jsp";
});
timeout Number
optional
Default Value:60000

Number of milliseconds request will wait for response from a server. If a server fails to respond before this time expires, then the request is considered to have encountered an error.

trustedServers String[]
optional

Since: 4.9

Indicates whether cross-origin requests made to the associated server should include credentials such as cookies and authorization headers.

require(["esri/config"], function(esriConfig) {
  esriConfig.request.trustedServers.push("[<protocol>//]<hostname>.<domain>[:<port>]");
});
useIdentity Boolean
optional
Default Value:true

Since: 4.5

Indicates whether esri/request will request a credential from IdentityManager.

See also

respectPrefersReducedMotion

Property
respectPrefersReducedMotion Boolean
Since: ArcGIS Maps SDK for JavaScript 4.30 config since 4.0, respectPrefersReducedMotion added at 4.30.

Controls whether the API respects the user's preference for reduced motion. When set to true, animations will be minimized or disabled when the user has enabled the prefers-reduced-motion browser or operating system setting. When set to false, the API will ignore the prefers-reduced-motion setting, considering all animations essential.

The prefers-reduced-motion setting is a media feature that can be used to detect if the user has requested that the system minimize the amount of animation or motion it uses. This setting is useful for users who have vestibular disorders or other conditions that make animations problematic. For more information, see the prefers-reduced-motion documentation.

Known Limitations

Reduced motion preferences are only supported in 2D MapView at this time. 3D SceneView support is planned for a future release.

Default Value:true
Example
// Ignore prefers-reduced-motion flag for all animations
esriConfig.respectPrefersReducedMotion = false;

routeServiceUrl

Property
routeServiceUrl String
Since: ArcGIS Maps SDK for JavaScript 4.23 config since 4.0, routeServiceUrl added at 4.23.

The default routing service used by the RouteLayer and the Directions widget.

Default Value:"https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World"
Example
esriConfig.routeServiceUrl = "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";

userPrivilegesApplied

Property
userPrivilegesApplied Boolean
Since: ArcGIS Maps SDK for JavaScript 4.28 config since 4.0, userPrivilegesApplied added at 4.28.

Indicates whether layers should apply privileges of the authenticated user to their capabilities.

Default Value:true

workers

Property
workers Object

An object with properties that control various aspects of the workers framework.

Properties
loaderUrl Object
optional

The absolute url to the AMD or SystemJS loader used in the worker. The AMD CDN build has a default value for when this property isn't set. This is required when using custom workers. See this ESM sample.

workerPath String
optional

This is used by the @arcgis/core and arcgis-js-api NPM packages to control where to load a custom build of the RemoteClient from. By default, RemoteClient is loaded from the API's assets. See this ESM sample.

loaderConfig Object
optional

The AMD configuration object that is set in each worker.

Specification
baseUrl String
optional

The AMD loader loads all code relative to the baseUrl.

has Object
optional

Determines if the specified feature capabilities are supported.

paths Object
optional

Map of module id fragments to file paths.

map Object
optional

Map paths in module identifiers to different paths.

packages Object[]
optional

An array of objects which provide the package name and its location.

Example
// Set the path for the worker's AMD loader configuration
// to a folder called workersFolder.
esriConfig.workers.loaderConfig = {
 paths: {
   myWorkers: new URL("./workersFolder", document.baseURI).href
 }
};

// load myWorkers/Calculator.js in the workers framework
// and invoke its "getMaxNumber" method
workers.open(this, "myWorkers/Calculator")
  .then((connection) => {
    return connection.invoke("getMaxNumber", [0, 1, 2, 3, 4]);
  })
  .then((result) => {
    console.log(result);
  });

//*********************************************************
// module: workerFolder/Calculator.js
//*********************************************************
define([], () => {
  return {
    // this function can be invoked from the main thread
    getMaxNumber: function (number) {
      return Math.max.apply(null, numbers);
    }
  };
});

Type Definitions

AfterInterceptorCallback

Type Definition
AfterInterceptorCallback(response)

Makes changes to the response after the request is sent, but before it's returned to the caller.

Parameter
response RequestResponse

The response object.

Example
const featureLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/0";

esriConfig.request.interceptors.push({
  // set the `urls` property to the URL of the FeatureLayer so that this
  // interceptor only applies to requests made to the FeatureLayer URL
  urls: featureLayerUrl,
  // use the AfterInterceptorCallback to check if `ssl` is set to 'true'
  // on the response to the request, if it's set to 'false', change
  // the value to 'true' before returning the response
  after: function(response) {
    if (!response.ssl) {
      response.ssl = true;
    }
  }
});

BeforeInterceptorCallback

Type Definition
BeforeInterceptorCallback(params){Object}

Makes changes to the request URL or options before the request is sent. A returned value will be used as the response data, which would prevent the request from being sent.

If null or undefined is returned, the request is sent with whatever changes were made to the parameters. If an Error is returned, the request is rejected with an esriError. If any other type is returned, the request is resolved with the returned value as the response data (request will not be sent).

Parameters
Specification
params Object

Parameters object that specifies the two properties that can be set.

Specification
url String

The request URL.

requestOptions RequestOptions

The options specified by the user in the data request. See RequestOptions for available properties.

Returns
Type Description
Object Returns: null, undefined, Error, response data, or a Promise that resolves to any one of these object types.
Examples
// modifying the query parameters
const featureLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/0";

esriConfig.request.interceptors.push({
  // set the `urls` property to the URL of the FeatureLayer so that this
  // interceptor only applies to requests made to the FeatureLayer URL
  urls: featureLayerUrl,
  // use the BeforeInterceptorCallback to check if the query of the
  // FeatureLayer has a maxAllowableOffset property set.
  // if so, then set the maxAllowableOffset to 0
  before: function(params) {
    if (params.requestOptions.query.maxAllowableOffset) {
      params.requestOptions.query.maxAllowableOffset = 0;
    }
  }
});
// fetching the data in place of the requests
const wmsLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/services/911CallsHotspot/MapServer/WMSServer";

esriConfig.request.interceptors.push({
   urls: wmsLayerUrl,
   before: function(params) {
     if (params.url === url && params.requestOptions.responseType === "xml") {
        if ("fetch" in window && "TextDecoder" in window) {
           // decode the response as ISO-8859-1 if it's not UTF-8 as expected
           return fetch(url + "?SERVICE=WMS&REQUEST=GetCapabilities")
             .then(function(response) {
               return response.arrayBuffer();
             })
             .then(function(buffer) {
               let textDecoder = new TextDecoder("ISO-8859-1"); // specified in the Capabilities XML declaration
               let xmlText = textDecoder.decode(buffer);
               let parser = new DOMParser();
               xml = parser.parseFromString(xmlText, "application/xml");
               return xml;
             });
         }
     }
   }
});

ErrorCallback

Type Definition
ErrorCallback(error)

The error function detailing the reason why the request failed.

Parameter
error Error

The error object. See Error for more information.

LogInterceptor

Type Definition
LogInterceptor(level, module, args){Boolean}

A custom log interceptor function.

Parameters
level String

The level of the message.

Possible Values:"error"|"warn"|"info"

module String

The module from which the log message originated.

args *
repeatable

Arguments of any type to be logged.

Returns
Type Description
Boolean Return true to indicate the log message has been handled and should no longer be processed (neither by other interceptors nor by the default handler which logs messages to the console).
Example
// Only show error messages, not warnings nor info messages
esriConfig.log.level = "error";

esriConfig.log.interceptors.push(function(level, module, ...args) {
  // Send all messages to a REST end-point
  request(loggingUrl, {
    method: "post",
    body: {
            level: level,
            module: module,
            details: JSON.stringify(args)
          }
  });

  // Return false so that the default log handler still writes log messages to the console
  return false;
});

RequestInterceptor

Type Definition
RequestInterceptor

Specifies the object used for intercepting and modifying requests made via esriRequest.

Properties
optional

Makes changes to the response after the request is sent, but before it's returned to the caller.

optional

Make changes to the request URL or options before the request is sent. A returned value will be used as the response data, which would prevent the request from being sent.

optional

When an error occurs during the request processing, this function is called with an Error object giving the details about what happened. For example, this could be used to log specific errors occurring with layers or services.

headers Object
optional

Sets or adds headers into requestOptions.headers. See also: requestOptions.

query Object
optional

Sets or adds query parameters into requestOptions.query. See also: requestOptions.

responseData Object
optional

Hardcodes the response. The request will not be sent. This is resolved as the response data.

optional

Specifies the URL(s) to apply to the interceptors. If the value is type String, then it matches if the request URL starts with that string. If null or undefined, the interceptor will apply to all relevant requests.

Examples
const featureLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/0";

esriConfig.request.interceptors.push({
  // set the `urls` property to the URL of the FeatureLayer so that this
  // interceptor only applies to requests made to the FeatureLayer URL
  urls: featureLayerUrl,
  // use the BeforeInterceptorCallback to check if the query of the
  // FeatureLayer has a maxAllowableOffset property set.
  // if so, then set the maxAllowableOffset to 0
  before: function(params) {
    if (params.requestOptions.query.maxAllowableOffset) {
      params.requestOptions.query.maxAllowableOffset = 0;
    }
  },
  // use the AfterInterceptorCallback to check if `ssl` is set to 'true'
  // on the response to the request, if it's set to 'false', change
  // the value to 'true' before returning the response
  after: function(response) {
    if (!response.ssl) {
      response.ssl = true;
    }
  }
});
const featureLayer = new FeatureLayer({
   url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/3"
});

esriConfig.request.interceptors.push({
   urls: featureLayer.url,
   // set the error function and check if an error occurs, and if it's name is "AbortError"
   // if so, display a useful error about the layer, if not, ignore the error
   error: function(error) {
      if (error.name == "AbortError") {
         // we're only interested in aborted request errors
         console.error(`An error happened with layer ${featureLayer.title}`, error);
      }
      return;
   }
});

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.