@arcgis/core/config.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * Configure global properties of the library.
 *
 * > [!WARNING]
 * >
 * > **Note**
 * >
 * > It is recommended that properties of the `config` module be set on a global `esriConfig` variable before the API is loaded. Setting properties on the `config` module after the API is loaded may not have the intended effect, as some properties need to be set by the time the first request is made that needs that value. For example, the `apiKey` property needs to be set before the first request is made to a secure service that requires an API key. If the `apiKey` is set after that, the request will fail with an authentication error and prompt for credentials instead of using the API key.
 *
 * @since 4.0
 * @example
 * // Load the config module and set the portalUrl property
 * const config = await $arcgis.import("@arcgis/core/config.js");
 * config.portalUrl = "https://myHostName.esri.com/arcgis";
 * @example
 * <script>
 * // Use the global esriConfig variable to initialize properties
 * var esriConfig = {
 *   portalUrl: "https://myHostName.esri.com/arcgis"
 * };
 * </script>
 */
import type { LogInterceptor } from "./core/types.js";
import type { RequestInterceptor } from "./request/types.js";

declare const config: Config;
export default config;

export interface Config {
  /**
   * An authorization string used to access a resource or service.
   * [API keys](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/) 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.
   * This property is used to configure API keys for ArcGIS Online or ArcGIS Location Platform items/services.
   *
   * > [!WARNING]
   * >
   * > **Note**
   * >
   * > To configure a global API key for ArcGIS Enterprise items/services, use the [`apiKeys`](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKeys) property.
   *
   * @since 4.18
   * @see [API keys](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/api-keys/)
   * @see [API key guide](https://developers.arcgis.com/javascript/latest/secure-resources/#api-keys)
   * @see [API key authentication tutorials](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/tutorials/)
   * @see [Display a map tutorial - get an API key](https://developers.arcgis.com/javascript/latest/display-a-map/#get-an-access-token)
   */
  apiKey?: string | null;
  /**
   * An object that contains global API keys for various services and scopes.
   * This object can be used to configure API keys to access the [basemap style service](https://developers.arcgis.com/javascript/latest/references/core/support/BasemapStyle/) and/or secure ArcGIS Enterprise services/items.
   * Alternatively, a fine-grained API key can be set on a specific class, which will override this global API key.
   * See the [API keys guide page](https://developers.arcgis.com/javascript/latest/secure-resources/#api-keys) for more information.
   *
   * > [!WARNING]
   * >
   * > **Note**
   * >
   * > To configure a global API key for ArcGIS Online or ArcGIS Location Platform items/services, use the [`apiKey`](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKey) property.
   *
   * @since 4.33
   * @see [API keys](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/api-keys/)
   * @see [API key guide](https://developers.arcgis.com/javascript/latest/secure-resources/#api-keys)
   * @see [API key authentication tutorials](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/tutorials/)
   * @see [BasemapStyle](https://developers.arcgis.com/javascript/latest/references/core/support/BasemapStyle/)
   * @example
   * // Set an API key for multiple services.
   * config.apiKeys.scopes = [
   *  {
   *    // The API key value.
   *    token: "API_KEY_FOR_SERVICE",
   *    // An array of URLs that the API key applies to.
   *    urls: [portalURL, serverURL]
   *  },
   * // More scopes can be added here...
   * ];
   * @example
   * // Set an API key for the basemap styles service
   * config.apiKeys.basemapStyles = "API_KEY_FOR_BASEMAP_STYLES";
   */
  apiKeys: ApiKeysConfig;
  /**
   * The name of the application using the API. This value is returned in the output of
   * the [GetEnvironment](https://developers.arcgis.com/arcade/function-reference/debugging_functions/#getenvironment) function in Arcade expressions.
   *
   * @default ""
   * @since 4.27
   * @example config.applicationName = "Sample Application";
   */
  applicationName: string;
  /**
   * Overrides the URL for loading the API assets when using local builds of the `@arcgis/core` npm package. The assets include styles, images, web workers, wasm and localization files. By default, assets are loaded from a CDN at runtime.
   *
   * > [!WARNING]
   * >
   * > For use only in local npm builds.
   *
   * @default "https://js.arcgis.com/<jssdk-version>/@arcgis/core/assets"
   * @since 4.18
   * @see [Working with assets](https://developers.arcgis.com/javascript/latest/working-with-assets/)
   * @example
   * import config from "@arcgis/core/config";
   * config.assetsPath = "./assets";
   */
  assetsPath: string;
  /**
   * The URL for font resources used by the [Font.family](https://developers.arcgis.com/javascript/latest/references/core/symbols/Font/#family) class in
   * non-MapImageLayer labels for both 2D MapViews and 3D SceneViews.
   * This also applies to [TextSymbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/TextSymbol/),
   * [TextSymbol3DLayer](https://developers.arcgis.com/javascript/latest/references/core/symbols/TextSymbol3DLayer/), and
   * [renderPreviewHTML()](https://developers.arcgis.com/javascript/latest/references/core/symbols/support/symbolUtils/#renderPreviewHTML).
   *
   * 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 "https://static.arcgis.com/fonts"
   * @since 4.8
   * @see [Labeling guide](https://developers.arcgis.com/javascript/latest/labeling/#fonts)
   * @example config.fontsUrl = "https://myserver.com/fonts";
   */
  fontsUrl: string;
  /**
   * The URL for the utility service used by [GeoRSSLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/GeoRSSLayer/) to convert GeoRSS documents.
   *
   * @default "https://utility.arcgis.com/sharing/rss"
   * @example config.geoRSSServiceUrl = "https://servername.domain.suffix/arcgis/sharing/rss";
   */
  geoRSSServiceUrl: string;
  /**
   * The default [geometryService](https://developers.arcgis.com/javascript/latest/references/core/rest/geometryService/) used by components and other
   * operations, such as on-the-fly projections.
   *
   * @default "https://utility.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer"
   * @example config.geometryServiceUrl = "https://utility.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer";
   */
  geometryServiceUrl: string;
  /**
   * The URL for the utility service used by [KMLLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/KMLLayer/) to convert KML documents.
   *
   * @default "https://utility.arcgis.com/sharing/kml"
   * @since 4.5
   * @example config.kmlServiceUrl = "https://servername.domain.suffix/arcgis/sharing/kml";
   */
  kmlServiceUrl: string;
  /**
   * 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.
   *
   * @since 4.17
   */
  log: LogConfig;
  /**
   * 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 "https://www.arcgis.com"
   * @see [Portal.url](https://developers.arcgis.com/javascript/latest/references/core/portal/Portal/#url)
   * @example
   * // Set the hostname to the on-premise portal
   * config.portalUrl = "https://myHostName.esri.com/arcgis"
   */
  portalUrl: string;
  /**
   * An object with properties that control various aspects of communication
   * between the library and web servers.
   *
   * @see [Guide topic - Proxy pages](https://developers.arcgis.com/javascript/latest/proxies/)
   * @see [Guide topic - CORS](https://developers.arcgis.com/javascript/latest/cors/)
   */
  request: RequestConfig;
  /**
   * 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](https://developer.mozilla.org/docs/Web/CSS/@media/prefers-reduced-motion) documentation.
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > Reduced motion preferences are only supported in 2D MapView at this time.
   * > 3D SceneView support is planned for a future release.
   *
   * @default true
   * @since 4.30
   * @example
   * // Ignore prefers-reduced-motion flag for all animations
   * config.respectPrefersReducedMotion = false;
   */
  respectPrefersReducedMotion: boolean;
  /**
   * The default routing service used by the [RouteLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/RouteLayer/) and the
   * [Directions](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-directions/)
   * component.
   *
   * @default "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World"
   * @since 4.23
   * @example config.routeServiceUrl = "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";
   */
  routeServiceUrl: string;
  /**
   * The configuration for sessions, which are used with an API key to manage user authentication and authorization with the API.
   * When a session is created, it provides a short-lived session token that can be used to access ArcGIS services for the duration of the session.
   * The API key can be set using the [apiKey](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKey) property or the [apiKeys.basemapStyles](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKeys) property.
   *
   * > [!WARNING]
   * >
   * > Sessions are only used with API keys that are generated from an ArcGIS Location Platform account.
   *
   * @since 5.0
   */
  sessions?: SessionsConfig;
  /**
   * Indicates whether layers should apply privileges of the authenticated user to their capabilities.
   *
   * @default true
   * @since 4.28
   */
  userPrivilegesApplied: boolean;
  /**
   * An object with properties that control various aspects of [the workers framework](https://developers.arcgis.com/javascript/latest/references/core/core/workers/).
   *
   * @example
   * // Set the path for the worker's AMD loader configuration
   * // to a folder called workersFolder.
   * config.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);
   *     }
   *   };
   * });
   */
  workers: WorkersConfig;
}

export interface ApiKeysConfig {
  /**
   * The API key for the [basemap styles service](https://developers.arcgis.com/javascript/latest/references/core/support/BasemapStyle/).
   * This should be set if loading a web map that uses a basemap style service.
   * Otherwise, set a fine-grained API key on the [BasemapStyle.apiKey](https://developers.arcgis.com/javascript/latest/references/core/support/BasemapStyle/#apiKey) class.
   * If user authentication is not required in the application, the [`apiKey`](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKey) property can be set instead.
   */
  basemapStyles?: string;
  /** An array of objects that define ArcGIS Enterprise API keys and their respective portal URLs. */
  scopes?: Array<ApiKeysScopeConfig>;
}

export interface ApiKeysScopeConfig {
  /** The API key used to access a resource or service. */
  token: string;
  /**
   * The URL or multiple URLs to the resource and/or service that the API key was generated for.
   * When accessing a secure layer (such as a [FeatureLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/)) that requires an API key, both the portal URL and server URL should be included in the `urls` array.
   * If the value is type `String`, then it matches if the request URL starts with that string.
   * If using a [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp), the [`g`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/global) and [`y`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) flags should not be used.
   */
  urls: RegExp | string | Array<RegExp | string>;
}

export interface WorkersConfig {
  /** 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](https://github.com/Esri/jsapi-resources/tree/main/templates/geometry-operator-worker). */
  loaderUrl?: string;
  /**
   * This is used by the `@arcgis/core` npm package to control where to load a custom build of the `RemoteClient` from.
   * By default, `RemoteClient` is loaded from the API's [assets](https://developers.arcgis.com/javascript/latest/working-with-assets/). See this [ESM sample](https://github.com/Esri/jsapi-resources/tree/main/templates/geometry-operator-worker).
   */
  workerPath?: string;
  /** The AMD configuration object that is set in each worker. */
  loaderConfig?: WorkersLoaderConfig;
}

export interface WorkersLoaderConfig {
  /** The AMD loader loads all code relative to the baseUrl. */
  baseUrl?: string;
  /** Determines if the specified feature capabilities are supported. */
  has?: Record<string, any>;
  /** Map paths in module identifiers to different paths. */
  map?: Record<string, Record<string, string>>;
  /** An array of objects which provide the package name and its location. */
  packages?: object[];
  /** Map of module id fragments to file paths. */
  paths?: Record<string, string>;
}

export interface RequestConfig {
  /**
   * 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`
   */
  httpsDomains: string[];
  /**
   * Allows developers to modify requests before or after they are sent.
   * The first interceptor that matches the request URL will be used.
   *
   * Example:
   * ```js
   * const featureLayerUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer/0";
   *
   * config.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: (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: (response) => {
   *     if (!response.ssl) {
   *       response.ssl = true;
   *     }
   *   }
   * });
   * ```
   *
   * @since 4.8
   */
  interceptors: RequestInterceptor[];
  /**
   * Maximum number of characters allowed in the URL for HTTP GET requests made by
   * [request](https://developers.arcgis.com/javascript/latest/references/core/request/). If this limit is exceeded, HTTP POST method will be used.
   *
   * @default 2000
   */
  maxUrlLength: number;
  /**
   * 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.
   *
   * @default high
   * @since 4.24
   */
  priority: "auto" | "high" | "low";
  /**
   * A proxy rule defines a proxy for a set of resources with an identical URL prefix.
   * When using [esriRequest](https://developers.arcgis.com/javascript/latest/references/core/request/), 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 [addProxyRule()](https://developers.arcgis.com/javascript/latest/references/core/core/urlUtils/#addProxyRule) method.
   * Rule objects have the following properties:
   */
  proxyRules: Array<RequestProxyRuleConfig>;
  /**
   * 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.
   *
   * ```js
   * const config = await $arcgis.import("@arcgis/core/config.js");
   * config.request.proxyUrl = "/proxy/Java/proxy.jsp";
   * ```
   */
  proxyUrl?: string | null;
  /**
   * Number of milliseconds
   * [request](https://developers.arcgis.com/javascript/latest/references/core/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.
   *
   * @default 62000
   */
  timeout: number;
  /**
   * Indicates whether cross-origin requests made to the associated server
   * should include credentials such as cookies and authorization headers.
   *
   * ```js
   * const config = await $arcgis.import("@arcgis/core/config.js");
   * config.request.trustedServers.push("[<protocol>//]<hostname>.<domain>[:<port>]");
   * ```
   *
   * @since 4.9
   */
  trustedServers: string[];
  /**
   * Indicates whether `esri/request` will request a credential from `IdentityManager`.
   *
   * @default true
   * @since 4.5
   */
  useIdentity: boolean;
}

/**
 * The configuration for sessions, which are used with an API key to manage user authentication and authorization with the API. The API key can be set using the [apiKey](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKey) property or the [apiKeys.basemapStyles](https://developers.arcgis.com/javascript/latest/references/core/config/#Config-apiKeys) property.
 *
 * > [!WARNING]
 * >
 * > Sessions are only used with API keys that are generated from an ArcGIS Location Platform account.
 *
 * @since 5.0
 */
export interface SessionsConfig {
  /**
   * Configuration for a basemap session for use with the [basemap styles service](https://developers.arcgis.com/javascript/latest/references/core/support/BasemapStyle/).
   *
   * @since 5.0
   */
  basemap?: BasemapSessionConfig;
}

/**
 * Configuration for a basemap session for use with the [basemap styles service](https://developers.arcgis.com/javascript/latest/references/core/support/BasemapStyle/). The basemap session is a timeframe during which a single user of a single application can use a session token to access unlimited basemap tiles from the Basemap Styles service.
 *
 * When a basemap session is created, it provides a short-lived session token that can be used to access basemap styles and tiles from the basemap service for the duration of the session. The maximum duration a basemap session and session token are valid for is up to 12 hours.
 *
 * > [!WARNING]
 * >
 * > Basemap sessions are only used with API keys that are generated from an ArcGIS Location Platform account.
 *
 * @since 5.0
 */
export interface BasemapSessionConfig {
  /**
   * Indicates whether the basemap session is enabled.
   *
   * @default false
   */
  enabled?: boolean;
  /**
   * The style family used by the basemap session.
   *
   * A basemap session is valid only for a single style family.
   * This setting determines which basemap styles and tiles can be accessed with the session token.
   * If you switch to a basemap from a different style family, update this property.
   * A new session (and session token) is created only if one does not already exist for the selected style family.
   *
   * @default "arcgis"
   */
  styleFamily?: "arcgis" | "open";
  /**
   * Indicates whether the basemap session should automatically refresh the session token when it expires.
   *
   * @default false
   */
  autoRefresh?: boolean;
  /**
   * The duration of the basemap session in seconds.
   * When the session expires, a new session token will need to be generated to access basemap styles and tiles from the basemap service.
   * If `autoRefresh` is set to `true`, the session will automatically refresh the next time the session token is needed after the session expires.
   *
   * If not provided, the session will default to 43200 seconds (12 hours). Valid range is from 10 to 43200 seconds.
   *
   * @default 43200
   */
  duration?: number;
}

export interface RequestProxyRuleConfig {
  /** The URL of the proxy. */
  proxyUrl: string;
  /**
   * URL prefix for resources that need to
   *                            be accessed through a specific proxy.
   */
  urlPrefix: string;
}

export interface LogConfig {
  /**
   * 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.
   */
  interceptors: LogInterceptor[];
  /**
   * 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".
   */
  level?: "none" | "error" | "warn" | "info" | null;
}