Using the SDK with TypeScript

TypeScript is a powerful language that offers static type checking to identify errors during development instead of at runtime. This enhances productivity and reduces troubleshooting time.

TypeScript definitions are provided when the SDK is installed locally using npm.

To compile TypeScript to JavaScript, you must configure the TypeScript compiler by creating a tsconfig.json file. If a tsconfig.json file was created automatically during project installation, review all settings.

When using the core API’s TypeScript decorators, such as when building Accessor subclasses or extending base layers, it may be necessary to set the useDefineForClassFields flag to false for backwards compatibility. More information on this flag is available in the TSConfig Reference.

When using the SDK’s components with TypeScript, set the moduleResolution option in your tsconfig.json to either “node16” or “bundler” if you want TypeScript to honor the exports field in a package’s package.json. These settings ensure TypeScript uses the modern Node.js resolution algorithm, which respects “exports” mappings. With older strategies like “node” or “classic”, TypeScript ignores the “exports” field. In those cases, you can still import internal files by referencing their direct paths, for example: import '@arcgis/map-components/dist/components/arcgis-map';

Here is a minimal example of a tsconfig.json:

{
  // An array of folders, filenames or patterns to include.
  "include": ["src"],
  "compilerOptions": {
    // When `true`, this allows use of `import` syntax such as `import x from 'xyz'`.
    "esModuleInterop": true,
    // Specify library type definitions to be included in the compilation.
    "lib": ["DOM", "DOM.Iterable", "ES2024"],
    // The module system to use for compilation.
    "module": "ES2020",
    // Respects package.json's "exports" conditions.
    "moduleResolution": "bundler",
    // Allow importing from JSON files
    "resolveJsonModule": true,
    // Sets the output at the minimum version of JavaScript features that will be supported.
    "target": "ES2024",
    // Improves performance by checking only the .ts files you write
    // rather than the .d.ts files from the libraries you are using.
    "skipLibCheck": true,
    // Results in stronger guarantees of program correctness
    "strict": true
  }
}

The SDK’s Vite, React, and Angular template projects use TypeScript by default. Use the templates as complete examples of working with both components and the core API in TypeScript.