Astro

The SDK’s components and core API depend on browser APIs. Whether Astro generates static HTML or renders a page on the server, initialize the SDK in the browser.

Before you start, make sure you are using the latest long-term support (LTS) version of Node.js and npm.

Installation

To use Map components in your Astro project, install the @arcgis/map-components package and its dependencies:

npm install @arcgis/map-components @arcgis/core @esri/calcite-components

yarn add @arcgis/map-components @arcgis/core @esri/calcite-components

pnpm add @arcgis/map-components @arcgis/core @esri/calcite-components

Configure CSS

When using components with npm, the SDK’s component styles and Calcite styles are loaded for you. Add the following styles to the Astro page so the map fills the page:

<style>
  html,
  body {
    height: 100%;
    margin: 0;
  }
</style>

Create an Astro page

Add the 2D Map component or 3D Scene component to src/pages/index.astro. Astro can generate the custom-element markup as static HTML or render it on the server.

---
const title = "ArcGIS Maps SDK for JavaScript Astro app";
---

<html lang="en">
  <head>
    <title>{title}</title>
  </head>
  <body>
    <arcgis-map item-id="dd4b2f25487d4a37a45093ba6acd026d">
      <arcgis-zoom slot="top-left"></arcgis-zoom>
    </arcgis-map>
    <script src="../scripts/main.ts"></script>
  </body>
</html>

Astro processes the local script as a browser module. Do not import Map Components or access browser APIs in the page frontmatter.

For an application that only uses static page data, the default Astro output is sufficient and does not require an adapter. Use an adapter only when the application needs server output, server endpoints, or other request-time behavior.

Client directives

Astro’s client:* directives are intended for imported framework components, such as React, Vue, and Svelte islands. For custom elements in a plain .astro file, use a browser script to register the components.

Register components

Import each component used by the page in the client-side script. These side-effect imports register the elements with the browser’s CustomElementRegistry.

import "@arcgis/map-components/components/arcgis-map";
import "@arcgis/map-components/components/arcgis-zoom";

Import a component for every arcgis-* element used by the application. Use the component’s API reference for its properties, events, slots, and lifecycle methods.

Add client-side logic

Use component events and lifecycle methods from the same client-side script. The view is available after the arcgisViewReadyChange event:

const mapElement = document.querySelector("arcgis-map");

mapElement?.addEventListener("arcgisViewReadyChange", () => {
  // Add client-side map logic here.
});

Keep map views, layers, graphics, and other browser APIs in the client-side script. They are not available in Astro page frontmatter during static generation or SSR.

For other SSR frameworks, use the framework’s client directive or client boundary for browser-dependent code. For example, mark a Next.js component with "use client" when it imports components. As an alternative in any framework, dynamically import Map Components and other browser-dependent modules from client-only code to defer their evaluation.