Server Side Rendering Frameworks with @arcgis/core

The First Attempt

If you tried this on your own, you likely ran into the following error message:

Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: …
require() of ES modules is not supported.

… is an ES module file as it is a .js file whose nearest parent package.json contains
“type”: “module” which defines all .js files in that package scope as ES modules.

Instead rename FeatureLayer.js to end in .cjs, change the requiring code to 
use import(), or remove “type”: “module” from …

ECMAScript modules on Node are still relatively new. Therefore, ESMs are not currently supported on the server for NextJS nor NuxtJS (two of the most popular SSR frameworks for React and Vue respectively). The SSR frameworks use CommonJS modules instead, which are not included in @arcgis/core. The omission of CommonJS modules cuts the package size roughly in half.

As suggested in the error message, I started changing file extensions to cjs (CommonJS) or mjs (ECMAScript). However, it quickly diverged into a game of whack-a-mole. I came across another solution for using ES modules in SSR frameworks: transpiling the dependencies with babel.

NuxtJS has a built in method for transpiling dependencies, documented here. Transpiling @arcgis/core will take several minutes on the first build, so have patience! You will also see a few errors (below) concerning file size.

However, most of us like maps in our apps. And this is where we run into the second error message:

ReferenceError: Element is not defined

This error is referring to a Document Object Model (DOM) Element. The DOM exists in the browser, and is therefore unavailable to code executed on the server by Node. Rendering an ArcGIS JS map on the server may not work, but there are always other options. I scrapped the module transpilation workflow and moved on.

 

Forgoing SSR for the ArcGIS Component

The solution for getting @arcgis/core working on a SSR framework is disabling server side rendering for the map component. I know, I know, that sounds like cheating right? It’s actually a viable option. The rest of your application will still reap the benefits of SSR. How much information for Search Engine Optimization (SEO) lives in the map component anyway?

Many SSR frameworks provide the option, with varying degrees of difficulty, to only render a component on the client side. This is what we need. Of the options I explored, NextJS has the clearest workflow. Here is the code for using a component without SSR in NextJS:

import dynamic from "next/dynamic";

const EsriMapWithNoSSR = dynamic(() => import("../components/EsriMap"), {
  ssr: false,
});

export default () => <EsriMapWithNoSSR />

That’s it. Now you can use the EsriMapWithNoSSR component and the map will render!

I found solutions for rendering a map in NuxtJS and Sapper as well, which are included in the GitHub repo. The samples contain additional framework specific documentation.

Ben Elan

Web developer specializing in UI/UX and spatial data visualization/analysis. Product Engineer for Calcite Components and ArcGIS API for JavaScript.