Installation

npm

npm install json-maps maplibre-gl

jsonmaps requires React 18+ as a peer dependency.

CSS

Import the MapLibre GL stylesheet in your app's entry point or layout:

import "maplibre-gl/dist/maplibre-gl.css";

Tailwind CSS

The component uses Tailwind classes internally for markers, legends, popups, and controls. Tell Tailwind to scan the package's dist files:

Tailwind v4 (CSS-based config):

/* globals.css */
@import "tailwindcss";
@source "../node_modules/json-maps/dist";

Tailwind v3 (JS config):

// tailwind.config.js
content: [
  "./node_modules/json-maps/dist/**/*.js",
  // ...your other paths
]

Next.js

If you're using Next.js with Turbopack, add transpilePackages to your config:

// next.config.ts
const nextConfig = {
  transpilePackages: ["json-maps"],
};
export default nextConfig;

Usage

"use client";

import { MapRenderer } from "json-maps";

const spec = {
  basemap: "streets",
  center: [-73.98, 40.75],
  zoom: 12,
};

export default function MyMap() {
  return <MapRenderer spec={spec} />;
}

No API keys required. Basemaps are served free by CARTO.

Dependencies

Icons are built-in (21 common map icons bundled as inline SVGs). No icon library needed.

From Source

To run the playground and docs locally:

git clone https://github.com/milind-soni/json-maps.git
cd json-maps
npm install
npm run dev

Open http://localhost:3000 for the landing page, or /playground to edit specs live.