CARTO for React

CARTO for React

Overview

CARTO for React is the best way to develop Location Intelligence (LI) Apps using the CARTO platform + React + deck.gl.

It is based on Create React App, the most popular toolchain, and it will allow you to start with a well designed structure following the best practices for modern frontend development and an integrated toolchain for testing, building, and deploying your application.

The code is open source and is available in the following repositories:

The NPM packages (latest version) are linked below:

  • Templates:
Package Version Downloads
@carto/cra-template-base-3 (CARTO 3 template) version downloads
@carto/cra-template-base-2 (CARTO 2 template) version downloads
@carto/cra-template-sample-app-2 (sample app template for CARTO 2) version downloads
  • Lib packages:
Package Version Downloads
@carto/react-api version downloads
@carto/react-auth version downloads
@carto/react-basemaps version downloads
@carto/react-core version downloads
@carto/react-redux version downloads
@carto/react-ui version downloads
@carto/react-widgets version downloads
@carto/react-workers version downloads

Architecture

architecture

CARTO for React is based on the following libraries:

  • CARTO for deck.gl as the library to visualize maps. For the basemaps you can use either Google Maps or CARTO basemaps.
  • React as the JavaScript library for building user interfaces and Redux for managing global state for the application. We use React-Redux for managing the interactions between the React components with the Redux store.
  • Material-UI: UI React components for faster and easier web development.
  • [@carto/react-*]: A set of packages created to make easy integration with CARTO platform and its APIs, geospatial widgets, and a custom theme for Material-UI.

Why React?

Location Intelligence Apps tend to be applications with a reduced number of pages, but with lots of functionalities at each page and many relations between them.

In the past, they were developed using imperative programming (with MVC patterns or similar), but it easily ends up in a messy application with a huge amount of dependencies between components. And each time you need to add something new, a new bug is also introduced.

The reactive programming paradigm (React and deck.gl) fixes this issue and makes your application easy to maintain, test, and scale. We are 100% sure that you can create something manageable even if your application is really complex and includes lots of features with multiple interactions.

Yes, it is a new paradigm, but once you learn it, you will love it.

Templates

CARTO for React includes three different Create React App templates for kickstarting your application:

  • The CARTO 3 template that creates a simple application with just a map using the CARTO 3 platform. This is the template you are usually going to choose when you are creating a new app.

  • The CARTO 2 template, similar to the CARTO 3 template. You are going to use it when you are creating a new app with the CARTO 2 platform.

  • The sample app template for CARTO 2 that creates a more complex application with several views, layers, and widgets. The purpose of this template is to demonstrate how you can implement common Location Intelligence functionalities in a CARTO for React app.

The command to create a new application is the following:

1
npx create-react-app [application_name] --template [template_name]
  • application_name is the name of the folder that will be created for your application
  • template_name is the name of the template to use: @carto/base-3 for the CARTO 3 template (default), @carto/base-2 for the CARTO 2 template or @carto/sample-app-2 for the sample app template for CARTO 2.

Library

In addition to the Create React App templates, we have created a library to:

  1. Provide an easy integration with the CARTO platform and its APIs.

  2. Provide a catalog of useful widgets for Location Intelligence Apps.

  3. Create a custom theme for Material-UI to reduce the design work of your team.

There is a full reference available.

The library includes a set of UI components ready to be used to create the best Location Intelligence Apps.

Frequently Asked Questions (FAQ)

Installing npm modules, learning React with Redux, learning Material-UI, it is just too much for my application, is there a simpler way?

If your application is not so complex and does not need the benefits added by this template, you can just use CARTO for deck.gl with the scripting API. Please check the examples.

I’m using Vue or Angular for building my applications, what are my options?

At this moment, we only provide a complete solution with templates and widgets for React. If you are building an application using Vue, Angular, or other JavaScript framework, you don’t have to worry, it is completely feasible and you just need to use the CARTO for deck.gl pure JavaScript flavor. Please check the examples and the CARTO + Vue.js and CARTO + Angular docs.

When should I use the CARTO 3 platform vs the CARTO 2 platform?

CARTO 3 is the next version of the CARTO Platform and is still in beta. The main difference is that it provides full cloud native support to Datawarehouses, pushing down queries. If you are starting a new application we recommend that you use the latest version of CARTO by requesting access. Or contact us if you have questions.

Can I use the library with my own Create React App template? Yes, the library can be used independently. You will need to ensure you have added the required dependencies and you won’t be able to use the code generator, but you can take advantage of the functionality offered by the library: user interface components, widgets, state management, interaction with the CARTO platform…