resium: React components for the Cesium globe

The globe as JSX, with Cesium options as props

resium is a React component library for Cesium, and the pitch is declarative Cesium: create a highly maintainable Cesium app in React. The example in the README is the whole idea in a dozen lines. A Viewer component with the full prop wraps an Entity, and the Entity carries a description, a name, a point with a pixel size, and a position built from Cartesian3.fromDegrees with a longitude, a latitude and a height. The structure of that snippet is the design: the viewer is a React tree, the entity is a child of it, and the things that would be constructor options on a Cesium object become props. The library is fully typed in TypeScript, hot module reloading works, and the claim is that you end up with a maintainable application rather than a pile of imperative scene construction. The primary language of the repository is TypeScript, and the topics are cesium, javascript, map and react.

Installing it and rendering your first entity

There is no install command in the documentation, so the path is the package registry and the installation page of the documentation site. The package is published on npm under the name resium, and because Cesium, React and ReactDOM are peer dependencies rather than direct ones, the application installs those itself and the library sits alongside them. The engines field requires Node 20.19.0 or newer, and the peer ranges are cesium at 1.x with react and react-dom at 18.2.0 or newer. The first real use is the example from the documentation, and it is short enough to type:

<Viewer full>
  <Entity
    description="test"
    name="tokyo"
    point={{ pixelSize: 10 }}
    position={Cartesian3.fromDegrees(139.767052, 35.681167, 100)}
  />
</Viewer>

A Viewer with the full prop contains an Entity, and the Entity takes a description, a name, a point rendered at a pixel size of 10, and a position built from a longitude, a latitude and a height. The longitudes and latitudes are the coordinates of Tokyo, so the example is deliberately recognisable on the globe. Everything you see here is a component and a prop, and the values in the props are the Cesium options, which is the point of the library.

The peer dependency is where the version coupling lives

The package manifest is where the constraints show, and the peer dependencies are the important part. The peer dependencies are cesium at 1.x, and react and react-dom at 18.2.0 or newer, and the engines field requires Node 20.19.0 or newer. Cesium is a peer dependency rather than a direct one, which means the application chooses which Cesium version to install and the library is tested against the 1.x line. That is the right arrangement for a library like this, because Cesium is large and the application usually has its own reasons for the version it uses. The React range matters in the same way, since the components rely on React 18 features and on the concurrent rendering behaviour. The package itself is published as a dual build, with a main entry at dist/resium.cjs, a module entry at dist/resium.js, types at dist/index.d.ts, and an exports map that points at the right file depending on whether you import or require.

Every release adds a new Cesium version

The release history is the clearest statement of how the project tracks upstream, and the release notes say it plainly. v1.27.0 is described as Cesium 1.146 support plus Buffer primitive picking, v1.26.0 as Cesium 1.145 support plus a Viewer crash fix, and v1.25.0 as Cesium 1.144 support plus a community fix. So the pattern is a new Cesium minor every release, roughly every four to six weeks over the summer of 2026, with a fix or a feature alongside it. The practical consequence for an adopter is that upgrading resium is usually also upgrading Cesium, and that the two have to be done together. The recent work also shows the shape of the bugs that get fixed at this level, since a Viewer crash and picking on a Buffer primitive are both the kind of issue that only shows up once you have integrated deeply enough to hit the edge case. The last push was on 2026-10-19.

A component library with a Storybook and visual regression tests

The repository treats itself as a component library, and the tooling reflects that. There is a .storybook directory, and the scripts include a storybook dev server on port 9001, a storybook build into the docs public examples folder, and a separate build target for the visual regression artefacts. The visual regression chain is unusually complete for a library of this size: a capture step that serves the static storybook on port 6006 and waits for it to come up before running the tests, a test step that runs test-storybook against that URL with a tag filter and a thirty second timeout, and a run step that feeds the results to reg-suit. The build script has a postbuild step that imports the compiled bundle and then runs a check-bundle script, so a packaging mistake fails the build rather than the consumer's app. The docs have their own generate step, a script that produces the API documentation, and the documentation site is built from the docs directory.

Four example projects, one per bundler

The examples directory holds four projects and the split tells you what the library is expected to work with. There is a Next.js example, a Vite example, and two webpack examples, numbered webpack and webpack2. The presence of two webpack examples suggests the older one is kept for reference while the second covers a newer configuration, and the practical point is that the library is expected to work in a modern server-rendered framework, in a plain Vite single page application, and in a classic webpack setup. The library's own build uses Vite, with tsc doing the type checking before the bundle, and the package marks itself as having no side effects, which is what allows a bundler to tree shake it. It also ships its source in the published files alongside the dist output, so a consumer that wants to inspect it can.

What the wrapper does not do for you

The honest limit of the library is that it is a component layer, not a replacement for knowing Cesium. The props on the components are the Cesium constructor options, so a component that takes a point with a pixel size is really a Cesium point graphic, and to use it well you still need to know what Cesium accepts and how it behaves, which means the component names are a convenience and a type layer rather than a new abstraction. The other limitation is the one that comes with the version coupling. Because a resium release is tied to a particular Cesium version, an application that needs a specific Cesium behaviour, or that is held back by a dependency on a different Cesium version elsewhere in its stack, may find the pairing awkward. The project addresses this by shipping releases for each new Cesium version rather than by decoupling, and the fix in each release is to move to the matching pair. The MIT licence applies to the library, and the maintainer is credited in the manifest as rot1024.

Editorial conclusion

resium suits a team building a Cesium application in React that wants the globe to be described in JSX rather than imperatively constructed, and that values type safety over the extra layer. It does not suit a project already built in plain Cesium with a thin framework layer, and it does not remove the need to understand Cesium itself, since the component props are the Cesium constructor options. Before you upgrade, read the changelog, because each release is tied to a specific Cesium version, and check that the React and ReactDOM versions you use are inside the peer dependency range.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. reearth/resium on GitHub
5. Releases