React 19, web components, and future of @arcgis/map-components-react

[timtucker-dte]

Seems like we're stuck in a weird place:

• Esri has been a pretty big proponent of web components.
• React 19 has been out for a while and now has native support for web components:
  • @arcgis/map-components-react 
• arcgis/map-components-react is stuck pinned to React 18 as a peer dependency
• I see some examples of using web components React at:
  • https://github.com/Esri/jsapi-resources/blob/main/component-samples/map-components/samples/react/src... 

Which leaves a few questions:

1. If React is now able to interact natively with web components, what is the value that a wrapper provides?
2. If the plan is to continue developing the wrapper, when should we expect it to be updated to support React 19?

[OmarKawach]

Hi @timtucker-dte,

You are right, it does seem like we're in a weird place, but the good news is that we're not stuck.

React 19 was released two months ago https://www.npmjs.com/package/react/v/19.0.0 which coincided with JavaScript Maps SDK v4.31 release. For v4.32 of the SDK (aimed for end of February 2025), we will be updating our documentation https://developers.arcgis.com/javascript/latest/get-started-react/ to talk about using the Maps SDK in React 19 + some guidance for React 18 developers.

In the meantime, we did update the samples repo to showcase how to work with React 19 https://github.com/Esri/jsapi-resources/tree/main/component-samples/map-components/samples/react (JSX) which uses https://www.npmjs.com/package/@arcgis/map-components  instead of the React wrapper package (see package.json https://github.com/Esri/jsapi-resources/blob/main/component-samples/map-components/samples/react/pac...

To give developers time to migrate from React 18, we will continue to provide the React wrapper package https://www.npmjs.com/package/@arcgis/map-components-react. This package is not necessary for React 19.

For React 18 developers, the wrapper provides "custom events that work with React's synthetic event system, use of PascalCase instead of kebab-case elements, and in TypeScript, you will have increased type safety on components for event listeners, props, and more."

Thank you for taking the time to write this post. I hope this response has been helpful 🙂

[JonathanDawe3]

@OmarKawach thanks for the details. It would be useful to get an example of working directly with the @arcgis/map-components when using typescript as well if possible? 

Currently its not been super clear to me whether there is a pattern we should be following for getting the types for the web components? In fact I've been rather hamfistedly adding them in myself 😬https://github.com/JonnyDawe/UK-Sewage-Map/blob/main/src/types/global.d.ts.

This implementation gives me the allowed props, but unfortunately strips out the actual types for them (everything ends up as any)... 

[OmarKawach]

Fair point! Even though we don't need the React wrapper for React 19, we still need typings for TypeScript. We'll also work on augmenting the documentation to have information about this.

For now, I've included a sample that shows how to use a pre-release version of @ArcGIS/map-components in a React 19 + Vite + TS app. I'll update the sample again once v4.32 is officially released sometime soon https://github.com/omarkawach/maps-sdk-react-ts/tree/main

The line you're looking to replace what is in `global.d.ts` can be found at https://github.com/omarkawach/maps-sdk-react-ts/blob/main/src/vite-env.d.ts 

/// <reference types="@arcgis/map-components/types/react" />

No need to keep maintaining that list of IntrinsicElements in v4.32 🙂

If anyone else sees this later and wants to start from scratch, I followed https://vite.dev/guide/#scaffolding-your-first-vite-project to create the sample.

Ref for 4.32-next.128 and the react.d.ts file https://www.npmjs.com/package/@arcgis/map-components/v/4.32.0-next.128?activeTab=code