Skip to content

RaynalHugo/react-cesium-fiber

Repository files navigation

react-cesium-fiber

npm version

react-cesium-fiber is a React renderer for CesiumJs on the web.

What is it?

react-cesium-fiber is a custom React renderer which lets you create cesium components.

With react-cesium-fiber, you can easily create a 3D globe of the Earth and add custom imagery or terrain providers, add 3D geometries, labels or even point-clouds.

Every feature proposed by CesiumJs is available in react-cesium-fiber. See the details of what you can do with CesiumJs on their website.

Why do you need it?

By default, CesiumJs has an imperative API. react-cesium-fiber transforms this in a declarative API. You simply specify what you want and react-cesium-fiber deals with the creation, updates and deletion of your components.

With react-cesium-fiber, you can profit from all the features React and its ecosystem bring, such as encapsulating and reusing logic in components. Your CesiumJs app now reacts easily to state changes, abstracting all the tedious work of maintaining your state and CesiumJs up to-date.

Getting started

1. Create your react app and add basic cesium configuration.

You can follow craco-cesium really nice tutorial. But note that you don't need to add resium.

2. Add react-cesium-fiber with your favorite provider.

npm install react-cesium-fiber

or

yarn add react-cesium-fiber

3. Add a Viewer in your app

import React from "react";
import { Viewer } from "react-cesium-fiber";

export const App = () => <Viewer />;

4. Add more components in your Viewer

import React from "react";
import { Color } from "cesium";
import { Viewer } from "react-cesium-fiber";

export const App = () => (
  <Viewer>
    <entity>
      <cartesian3
        attach="position"
        constructFrom="fromDegrees"
        args={[-114.0, 30.0, 300000.0]}
      />
      <boxGraphics attach="box" material={Color.RED}>
        <cartesian3 attach="dimensions" args={[400000.0, 300000.0, 500000.0]} />
      </boxGraphics>
    </entity>
  </Viewer>
);

Note that you don't need to import entity, cartesian3 or boxGraphics. That's the magic of the react-reconciler.

Core concepts

  • 📖 You need some basic knowledge of CesiumJs. react-cesium-fiber has a few specificities, such as the args and attach props, but once you grab those basic concepts, it quickly falls back to vanilla CesiumJs.
  • 🧩 Every CesiumJs object can be instanced as a children of the Viewer. They don't need to have a Capitalized name as react-cesium-fiber recognize them as native components.
  • 🚪 react-cesium-fiber is built in a way that always let you fallback to vanilla CesiumJs if you need. Using React ref, you can access the CesiumJs objects and manually update them.
  • 🔍 TypeScript types and props autocomplete should help you to get started.

More details about the ➡️ API here ⬅️

A few notes

  • Greatly inspired by the amazing react-three-fiber package and this mind-blowing video of Sophie Alpert.
  • Based on the work of the Cesium team and the CesiumJS library.
  • react-cesium-fiber is a very young project. If you are looking for something more production-ready, you can have a look at resium (even if I think that react-cesium-fiber conception is way easier to maintain.)