How to use OneMap Singapore for free, with React and MapLibre.

A step-by-step guide to starting a new NextJS app, and displaying a map using MapLibre (an open source fork of Mapbox), and OneMap as a tile server.

TLDR;

Source code: https://github.com/gpng/onemap-react-maplibre-demo

Demo: https://onemap-react-maplibre-demo.vercel.app/

Why?

I’ve created a few webapps that are map based with Singapore related data, and Mapbox prices can be quite crazy when their free limit of 50,000 loads is exceeded. I had to find a cheaper alternative, and finally realised the OneMap Singapore provides a tile server, which allows us to host a Singapore map for free.

Start a new NextJS app

npx create-next-app@latest --ts

(Optional) Delete all files that are unnecessary for this demo.

cd <project root>
rm -rf pages/api/ public/ styles/

Install dependencies

yarn add react-map-gl maplibre-gl

1. react-map-gl is a React wrapper for Mapbox compatible libraries, and lets us easily display a map in your react application
2. maplibre-gl is an open source fork of Mapbox GL JS. Mapbox has started requiring payment for each load of their library after switching to a non open source model since December 2020, so this is a good free alternative.

Import stylesheet from maplibre-gl

In pages/_app.tsx , import the maplibre css file that is required to display the map properly.

I also added some global styles to remove the default body margin as I want to display the map across the entire screen.

pages/_app.tsx

Display the map on the index page

Now on to pages/index.tsx , we want to display an interactive map across the entire window.

1. To use MapLibre instead of the default Mapbox library that react-map-gl depends on, we have to import Map from react-map-gl/maplibere
2. We also want to use OneMap’s tileserver, instead of the default Mapbox tile server which requires an access key and account from Mapbox. In this case, we will use the OneMap Grey design, and more specifically, their Mapbox Style.
3. We also set the maxBounds prop to limit the map view to just Singapore only as OneMap does not provide tiles for outside Singapore.

At this step, you already have an interactive Singapore map. Run the server using yarn dev or npm run dev , and visit http://localhost:3000 to see the map.

pages/index.tsx

What it should look like

If you just want a basic map setup, this is the end of the demo. You can continue tweaking and building your application around this base map.

Adding some visualisations and interactions

When building a map based app, there are a few common things that we will usually use, such as markers, visualisations, panning the map automatically etc, so I will just add in this functionality just as a demo of how it can be done.

For this demo, I will just use a simple set of data with 2 coordinates

Visualising a line between 2 points

react-map-gl exposes Source and Layer components which wrap their respsective Mapbox functions, that allows us to insert data into the map using GeoJSON, and visualise it.

The props required for these components are directly taken from Mapbox, so you can read through the docs for sources and layers to get a better idea of how to use them.

Here is an example of using the above data to show a green line between the 2 points.

Displaying markers

Similar to sources and layers, react-map-gl also exposes a Marker component that wraps Mapbox markers, docs are here.

We can use markers to display custom html components built in react.

Accessing the map instance directly

In some cases, react-map-gl does not expose every function that Mapbox has. We can directly access the mapbox gl instance to call its methods if needed.

For example, the flyTo function used to pan the map view to a specific coordinate is not exposed.

To access the instance, we provide a ref to the ReactMapGL component, which is then assigned to the map instance. We can then use the flyTo function on the map.

In this case, we call the flyTo function when any of the markers are clicked, and the map will pan over and center on the marker

Result

Tadah! An interactive map of Singapore, and some basic visualisation and functionality. You can now expand on it and build some interesting map based web apps. OneMap also provides other designs if you don’t like the grey base map.