require(["esri/config"], (esriConfig) => { /* code goes here */ });
import esriConfig from "@arcgis/core/config.js";
esri/config
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.
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 | 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
apiKey String
Since: ArcGIS Maps SDK for JavaScript 4.18config 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
applicationName String
Since: ArcGIS Maps SDK for JavaScript 4.27config 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:""
ExampleesriConfig.applicationName = "Sample Application";
-
assetsPath
assetsPath String
Since: ArcGIS Maps SDK for JavaScript 4.18config since 4.0, assetsPath added at 4.18. -
Overrides the URL for loading the API assets when using local builds of the
@arcgis/core
andarcgis-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
Exampleimport esriConfig from "@arcgis/core/config"; esriConfig.assetsPath = "./assets";
-
fontsUrl
fontsUrl String
Since: ArcGIS Maps SDK for JavaScript 4.8config 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
ExampleesriConfig.fontsUrl = "https://myserver.com/fonts";
-
geometryServiceUrl
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"
ExampleesriConfig.geometryServiceUrl = "https://utility.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer";
-
geoRSSServiceUrl
geoRSSServiceUrl String
-
The URL for the utility service used by GeoRSSLayer to convert GeoRSS documents.
- Default Value:"https://utility.arcgis.com/sharing/rss"
ExampleesriConfig.geoRSSServiceUrl = "https://servername.domain.suffix/arcgis/sharing/rss";
-
kmlServiceUrl
kmlServiceUrl String
Since: ArcGIS Maps SDK for JavaScript 4.5config 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"
ExampleesriConfig.kmlServiceUrl = "https://servername.domain.suffix/arcgis/sharing/kml";
-
log
log Object
Since: ArcGIS Maps SDK for JavaScript 4.17config 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 StringThe 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
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
request Object
-
An object with properties that control various aspects of communication between the library and web servers.
- Properties
-
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[]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 NumberDefault Value:2000Maximum 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 StringDefault Value:highSince: 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"
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:
proxyUrl StringDefault Value:nullResource 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 NumberDefault Value:60000Number 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.
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 BooleanDefault Value:trueSince: 4.5
Indicates whether
esri/request
will request a credential fromIdentityManager
. - See also
-
respectPrefersReducedMotion
respectPrefersReducedMotion Boolean
Since: ArcGIS Maps SDK for JavaScript 4.30config 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 theprefers-reduced-motion
browser or operating system setting. When set tofalse
, the API will ignore theprefers-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
routeServiceUrl String
Since: ArcGIS Maps SDK for JavaScript 4.23config 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"
ExampleesriConfig.routeServiceUrl = "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";
-
userPrivilegesApplied
userPrivilegesApplied Boolean
Since: ArcGIS Maps SDK for JavaScript 4.28config 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
workers Object
-
An object with properties that control various aspects of the workers framework.
- Properties
-
loaderUrl Object
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 StringThis is used by the
@arcgis/core
andarcgis-js-api
NPM packages to control where to load a custom build of theRemoteClient
from. By default,RemoteClient
is loaded from the API's assets. See this ESM sample.loaderConfig ObjectThe AMD configuration object that is set in each worker.
- Specification
-
baseUrl String
The AMD loader loads all code relative to the baseUrl.
has ObjectDetermines if the specified feature capabilities are supported.
paths ObjectMap of module id fragments to file paths.
map ObjectMap paths in module identifiers to different paths.
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
-
Makes changes to the response after the request is sent, but before it's returned to the caller.
Parameterresponse RequestResponseThe response object.
Exampleconst 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
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
orundefined
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).ParametersSpecificationparams ObjectParameters object that specifies the two properties that can be set.
Specificationurl StringThe request URL.
requestOptions RequestOptionsThe options specified by the user in the data request. See RequestOptions for available properties.
ReturnsType 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; }); } } } });
-
The error function detailing the reason why the request failed.
-
LogInterceptor
LogInterceptor(level, module, args){Boolean}
-
A custom log interceptor function.
ParametersReturnsType 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; });
-
Specifies the object used for intercepting and modifying requests made via esriRequest.
- Properties
-
after AfterInterceptorCallback
Makes changes to the response after the request is sent, but before it's returned to the caller.
before BeforeInterceptorCallbackMake 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.
error ErrorCallbackWhen 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 ObjectSets or adds headers into
requestOptions.headers
. See also: requestOptions.query ObjectSets or adds query parameters into
requestOptions.query
. See also: requestOptions.responseData ObjectHardcodes 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.
Examplesconst 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; } });