Guide

MapLibre GL JS tutorial: rendering vector tiles without Mapbox

A practical tutorial for MapLibre GL JS — the open-source fork of Mapbox GL. Render vector tiles from PMTiles or a tile server with full customisation.

MapLibre GL JS tutorial: rendering vector tiles without Mapbox

Rendering vector tiles efficiently while ensuring a great user experience can be challenging, particularly for developers looking to avoid proprietary solutions like Mapbox. MapLibre GL JS, a popular open-source mapping library, offers a robust alternative for rendering vector tiles in web applications. By utilizing formats like PMTiles, developers can create fast, flexible maps without relying on expensive paid services. This guide dives into how to get started using MapLibre GL JS for rendering PMTiles, giving you the tools to build powerful geospatial applications.

Understanding MapLibre GL JS

MapLibre GL JS is a powerful library that enables developers to create interactive, customizable maps using vector tiles. Born from the open-source community’s split from the proprietary Mapbox GL JS, MapLibre continues to grow, supported by a vibrant ecosystem of contributors. Key advantages include:

  • Open-source nature: Free to use and modify under the terms of the BSD license.
  • Customization: Offers extensive styling options for layers and sources.
  • Performance: Optimized for speed and rendering efficiency across devices.

To leverage MapLibre effectively, it’s essential to understand how it interacts with vector tiles, specifically when using PMTiles.

Working with PMTiles

PMTiles is a format designed to serve vector tiles efficiently. It allows for fast loading and rendering of tiles, thanks to its single-file architecture that streamlines data retrieval. Using PMTiles can enhance performance, as the format is optimized for progressive loading and provides lower latency.

When setting up a mapping project with PMTiles, it's crucial to understand the workflow:

  1. Tile generation: Use tools like Tippecanoe to create PMTiles from your geospatial dataset.
  2. Serving tiles: PMTiles can be served from a simple HTTP server, making it easy to integrate into a variety of applications.
  3. Map rendering: Integrate with MapLibre GL JS to display the tiles seamlessly.

Here’s a simple example of how to integrate PMTiles with MapLibre GL JS to render a map:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>MapLibre GL JS with PMTiles</title>
    <link
      href="https://unpkg.com/maplibre-gl@2.2.0/dist/maplibre-gl.css"
      rel="stylesheet"
    />
    <style>
      body { margin: 0; height: 100vh; }
      #map { width: 100%; height: 100%; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script src="https://unpkg.com/maplibre-gl@2.2.0/dist/maplibre-gl.js"></script>
    <script>
      const map = new maplibregl.Map({
        container: 'map',
        style: {
          version: 8,
          sources: {
            'pmtiles-source': {
              type: 'vector',
              url: 'pmtiles://path/to/your/tiles.pmtiles' // Replace with your PMTiles URL
            }
          },
          layers: [
            {
              id: 'layer',
              type: 'fill',
              source: 'pmtiles-source',
              'source-layer': 'your_layer_name', // Replace with your layer name
              layout: {},
              paint: {
                'fill-color': '#888888',
                'fill-opacity': 0.8
              }
            }
          ]
        },
        center: [0, 0], // Set your desired center
        zoom: 2
      });

      map.on('load', () => {
        console.log('Map loaded successfully!');
      });
    </script>
  </body>
</html>

Key points in the example above:

  • Map Setup: The map is instantiated with a specific container and style adhering to the MapLibre GL JS specifications.
  • Source Definition: The PMTiles source is defined in the style, linking it to the pmtiles:// URL.
  • Layer Rendering: A fill layer is created to render a specific layer from the PMTiles dataset.

Advantages of using MapLibre GL JS and PMTiles

Using MapLibre GL JS combined with PMTiles presents several benefits:

  • Cost-Effective: Both MapLibre GL JS and PMTiles are open-source, minimizing operational costs compared to proprietary services.
  • Flexibility: Customize styles and projections to fit specific requirements without licensing constraints.
  • Community Support: Being open-source fosters a collaborative environment, leading to frequent updates and a rich set of plugins and extensions.

Summary table: MapLibre GL JS vs. Mapbox GL JS

Feature MapLibre GL JS Mapbox GL JS
License Open-source (BSD) Proprietary
Cost Free Paid (with a free tier)
Customization Highly customizable Highly customizable
Built-in vector rendering Yes Yes
Offline support Via PMTiles Yes, paid plan
Community support Strong Limited to customer base

Further options

In addition to using MapLibre GL JS and PMTiles, there are hosted alternatives for rendering vector tiles that developers might consider, such as MapTiler and HERE Maps.

Practical takeaways

As geospatial applications continue to rise in demand, understanding how to deploy open-source technologies like MapLibre GL JS and PMTiles can provide considerable advantages in building responsive, scalable maps. Start by experimenting with the example code above, and consider integrating it into your existing projects or new applications.

FAQ

See also

Start building with Mapsi — free

No credit card required. Free tier includes 10,000 requests/month.

Get your free API key Read the docs
Try it now
curl "https://api.mapsi.dev/geocode?q=Berlin&key=YOUR_KEY"
  • EU-hosted on Hetzner — GDPR compliant
  • Open-source core — Pelias + Valhalla
  • Store results forever — no lock-in