Installation

Package installation

bash npm install @maplibre-yaml/core maplibre-gl

bash pnpm add @maplibre-yaml/core maplibre-gl

bash yarn add @maplibre-yaml/core maplibre-gl

Required CSS

MapLibre GL JS requires its CSS for proper rendering. Add it to your HTML or import it in your JavaScript:

HTML
JavaScript

<link
  href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css"
  rel="stylesheet"
/>

javascript import 'maplibre-gl/dist/maplibre-gl.css';

Browser usage (CDN)

For quick prototypes or simple pages, you can use maplibre-yaml directly from a CDN — no build tools needed. An import map tells the browser where to find maplibre-gl, which is kept external (not bundled):

<!DOCTYPE html>
<html>
  <head>
    <link
      href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css"
      rel="stylesheet"
    />
    <style>
      ml-map {
        display: block;
        height: 400px;
      }
    </style>
    <!-- Tell the browser where to find maplibre-gl -->
    <script type="importmap">
      { "imports": { "maplibre-gl": "https://esm.sh/maplibre-gl@^4" } }
    </script>
    <!-- Register the <ml-map> web component -->
    <script
      type="module"
      src="https://unpkg.com/@maplibre-yaml/core/register.js"
    ></script>
  </head>
  <body>
    <ml-map src="/map.yaml"></ml-map>
  </body>
</html>

To use the JavaScript API (YAMLParser, MapRenderer) from a CDN instead of the web component, import the package from esm.sh, which resolves its dependencies automatically:

<script type="module">
  import { YAMLParser, MapRenderer } from "https://esm.sh/@maplibre-yaml/core";

  // Your map code here
</script>

Web component registration

To use the <ml-map> web component, import the registration module:

import "@maplibre-yaml/core/register";

Then use it in your HTML:

<ml-map
  style="width: 100%; height: 400px;"
  config='{"type":"map","config":{"center":[-74,40],"zoom":10,"mapStyle":"https://demotiles.maplibre.org/style.json"},"layers":[]}'
>
</ml-map>

TypeScript

maplibre-yaml is written in TypeScript and includes type definitions. No additional @types packages are needed.

import { YAMLParser, MapRenderer } from "@maplibre-yaml/core";
import type { MapBlock } from "@maplibre-yaml/core";

// For a single `type: map` document:
const mapBlock: MapBlock = YAMLParser.parseMapBlock(yamlString);

Verify installation

Create a simple test to verify everything is working:

import { YAMLParser } from "@maplibre-yaml/core";

const yaml = `
type: map
id: test
config:
  center: [0, 0]
  zoom: 2
  mapStyle: "https://demotiles.maplibre.org/style.json"
layers: []
`;

const result = YAMLParser.safeParseMapBlock(yaml);

if (result.success) {
  console.log("✓ maplibre-yaml is working!");
  console.log("  Map ID:", result.data.id);
} else {
  for (const error of result.errors) {
    console.error(`✗ ${error.path}: ${error.message}`);
  }
}

Next steps

Now that you have maplibre-yaml installed, let’s create your first map.