CARTO for React
CARTO for React is an application template to speed up the development of Location Intelligence (LI) Apps using the CARTO platform + React + deck.gl.
To quickly start a project locally, it's enough with:
npx create-react-app my-app --template @carto/base-3
CARTO 3 Sample App
It is based on Create React App, and it will allow you to start with a well designed structure and an integrated toolchain for testing, building, and deploying your application.
The code is open source and is available in the following repositories:
About Carto Platform Versions
In this documentation we use the term “CARTO 3†to refer to the latest version of the CARTO platform launched on October 2021, and “CARTO 2†to refer to the previous version. Note that each platform version has its own set of account credentials.
The latest CARTO for React version is 2.x. This version series is paired with MUI5. Regarding React support, from 2.0.4 both React 18 and React 17 are supported. In version 2.x only templates for CARTO 3 are available.
To work with previous version of Material UI (v4.x) and/or CARTO 2 version, user must use CARTO for React 1.x version series. The last stable release for MUI 4.x is 1.5 and there won't be any more active development on it, therefore migration to v2.x is recommended for all users.
The NPM packages (latest version) are linked below:
- Templates:
Package | Version | Downloads | Supported in |
|---|---|---|---|
@carto/cra-template-base-3 (CARTO 3 template) | v1.5 and v2.0 | ||
@carto/cra-template-base-3-typescript (CARTO 3 template for TypeScript) | v1.5 and v2.0 | ||
@carto/cra-template-sample-app-3 (CARTO 3 template) | v1.5 and v2.0 | ||
@carto/cra-template-base-2 (CARTO 2 template) | only v1.5 | ||
@carto/cra-template-sample-app-2 (sample app template for CARTO 2) | only v1.5 |
- Lib packages:
Package | Version | Downloads |
|---|---|---|
@carto/react-api | ||
@carto/react-auth | ||
@carto/react-basemaps | ||
@carto/react-core | ||
@carto/react-redux | ||
@carto/react-ui | ||
@carto/react-widgets | ||
@carto/react-workers |
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.
- [@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) helps with this issue and makes your application easy to maintain, test, and scale. We are very confident you can create something easily manageable even if your application is really complex and includes many features with multiple diverse interactions.
Yes, it is a new paradigm, but once you learn it, you will love it.
CARTO for React includes the following 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 using JavaScript.
- The CARTO 3 template for TypeScript 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 using TypeScript.
- 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 templates for CARTO 2 and CARTO 3 that create a more complex application with several views, layers, and widgets. The purpose of these templates is to demonstrate how you can implement common Location Intelligence functionalities in a CARTO for React app.
The command to create a new application depends on the package manager we are using.
If using npm as the package manager:
npx create-react-app [application_name] --template [template_name]
If using yarn:
yarn create react-app [application_name] --template [template_name]
application_nameis the name of the folder that will be created for your applicationtemplate_nameis the name of the template to use:@carto/base-3for the CARTO 3 template@carto/base-3-typescriptfor the CARTO 3 template for TypeScript@carto/sample-app-3for the sample app template for CARTO 3.@carto/base-2for the CARTO 2 template@carto/sample-app-2for the sample app template for CARTO 2.
- As said before,
base-2&sample-app-2are not supported anymore in CARTO for React 2.x
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.
The library includes a set of UI components ready to be used to create the best Location Intelligence Apps.
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. The main difference is that it provides full native support for cloud data warehouses and platforms, pushing down queries. If you are starting a new application, we recommend you to use the latest version of CARTO by requesting access. Or contact us if you have questions.
Can I use the library within my own React application? 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…
Last modified 4d ago