Getting Started

MapLibre ArcGIS provides full ArcGIS Enterprise, Server, and Portal integration for MapLibre GL JS. This guide will help you get up and running quickly.

💡 Prerequisites

You'll need Node.js 20+ for development, and a basic understanding of JavaScript/TypeScript. For the Python CLI, you'll need Python 3.9+.

Quick Start Options

Choose your preferred approach:

  • TypeScript Library - Full programmatic control with the npm package
  • YAML Configuration - No-code map definition with the Python CLI
  • React Components - Pre-built React wrappers for React applications

Installation

NPM Package

Terminal 
# Install the library
npm install maplibre-arcgis maplibre-gl

# Optional React support
npm install react react-dom

Python CLI

Terminal 
# From source
cd cli && pip install -e .

# Or when published
pip install maplibre-arcgis-cli

Authentication

MapLibre ArcGIS supports all major ArcGIS authentication methods. Choose the one that matches your deployment scenario.

OAuth2 / PKCE (Recommended)

Best for user-facing applications where users need to log in with their ArcGIS credentials.

TypeScript 
import { ArcGISAuthManager, ArcGISLoginControl } from 'maplibre-arcgis';

const auth = new ArcGISAuthManager({
  portalUrl: 'https://www.arcgis.com',
  authMethod: 'oauth2',
  clientId: 'YOUR_CLIENT_ID',
});

// Add login control to map
map.addControl(new ArcGISLoginControl({ auth }), 'top-right');

API Key

Best for public applications using ArcGIS Location Platform or Developer accounts.

TypeScript 
const auth = new ArcGISAuthManager({
  portalUrl: 'https://www.arcgis.com',
  authMethod: 'apikey',
  apiKey: 'YOUR_API_KEY',
});

generateToken

Best for legacy ArcGIS Server or Enterprise deployments.

TypeScript 
const auth = new ArcGISAuthManager({
  portalUrl: 'https://your-server.com/arcgis',
  authMethod: 'token',
  username: 'your_username',
  password: 'your_password',
});

App Credentials

Best for server-to-server scenarios without user context.

TypeScript 
const auth = new ArcGISAuthManager({
  portalUrl: 'https://www.arcgis.com',
  authMethod: 'app',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
});

Layer Controls

Add ArcGIS services to your map using the layer controls. Each control handles token injection automatically.

Feature Service

TypeScript 
import { EsriFeatureServiceControl } from 'maplibre-arcgis';

map.on('load', () => {
  map.addControl(new EsriFeatureServiceControl({
    id: 'parcels',
    url: 'https://services.arcgis.com/.../FeatureServer/0',
    auth,
    where: 'ACRES > 10',
    outFields: ['PARCEL_ID', 'OWNER', 'ACRES'],
  }), 'top-left');
});

Dynamic Map Service

TypeScript 
import { EsriDynamicMapServiceControl } from 'maplibre-arcgis';

map.addControl(new EsriDynamicMapServiceControl({
  id: 'zoning',
  url: 'https://server/arcgis/rest/services/Zoning/MapServer',
  auth,
  layers: [1, 2, 3],
  opacity: 0.7,
}), 'top-left');

Other Layer Types

  • EsriTiledMapServiceControl - Cached map tiles
  • EsriVectorTileServiceControl - Vector tile services
  • EsriImageServiceControl - Image services

WebMap Loading

Load existing ArcGIS WebMaps by item ID. The loader handles basemaps, operational layers, and initial extents automatically.

TypeScript 
import { WebMapControl } from 'maplibre-arcgis';

map.addControl(new WebMapControl({
  itemId: 'abc123def456',
  auth,
}), 'top-left');

COG Support

Cloud-Optimised GeoTIFF from S3

TypeScript 
import { CogS3Control } from 'maplibre-arcgis';

map.addControl(new CogS3Control({
  url: 's3://my-bucket/dem.tif',
  awsRegion: 'us-east-1',
  colormap: 'viridis',
  rescale: [0, 4000],
}), 'top-right');

COG Analytics with Pyodide

Run raster analytics on COGs directly in the browser.

TypeScript 
import { CogAnalyticsControl } from 'maplibre-arcgis';

map.addControl(new CogAnalyticsControl({
  url: 'https://example.com/landsat8.tif',
  formula: 'ndvi',
  bandMap: { red: 3, nir: 4, blue: 1, swir: 5 },
  colormap: 'rdylgn',
  opacity: 0.85,
}), 'top-right');

Supported Formulas: NDVI, EVI, SAVI, NBR, Hillshade, Custom Python

Supported Colormaps: rdylgn, viridis, spectral, rdbu, terrain, hot, grays

💡 Performance Note

First run loads Pyodide (~10s on fast connection). Subsequent runs are fast because the worker stays alive.

LiDAR Visualization

Visualize COPC, LAZ, and EPT point clouds directly in the browser.

TypeScript 
import { CopcLidarControl } from 'maplibre-arcgis';

map.addControl(new CopcLidarControl({
  url: 'https://example.com/cloud.copc.laz',
  colorScheme: 'elevation',
  pointSize: 2,
  opacity: 0.9,
}), 'top-right');

DuckDB Tools

Load GIS files in the browser with DuckDB WASM. No server required.

File Loading

TypeScript 
import { DuckDBLayerControl, DuckDBGISLoader } from 'maplibre-arcgis';

// Interactive control
map.addControl(new DuckDBLayerControl(), 'top-left');

// Programmatic API
const loader = await DuckDBGISLoader.create();
const fc = await loader.loadUrl('https://example.com/data.fgb');

Supported Formats: GeoJSON, Shapefile.zip, KML/KMZ, GPX, CSV/TSV, GeoParquet, FlatGeoBuf, GeoPackage

Geoprocessing

TypeScript 
import { DuckDBGeoprocessor } from 'maplibre-arcgis';

const gp = new DuckDBGeoprocessor(loader);

// Buffer
const buffered = await gp.buffer('parcels', {
  distanceMeters: 100,
  dissolve: true,
});

// Spatial Join
const joined = await gp.spatialJoin('parcels', 'zoning', {
  predicate: 'intersects',
});

Oriented Imagery

Display 360 panoramas and oblique imagery with spatial synchronization.

TypeScript 
import { OrientedImageryControl } from 'maplibre-arcgis';

map.addControl(new OrientedImageryControl({
  featureServiceUrl: 'https://services.arcgis.com/.../OrientedImagery/FeatureServer/0',
  auth,
  enableFootprints: true,
  enableLocationTool: true,
  enableEnhancements: true,
  enableGallery: true,
}), 'top-right');

Required Feature Service Fields:

  • ImagePath / ImageURL - URL to image file
  • CamHeading / Heading - Camera heading (degrees)
  • CamPitch / Pitch - Camera pitch (degrees)
  • CamRoll / Roll - Camera roll (degrees)
  • HFOV - Horizontal field of view (degrees)
  • VFOV - Vertical field of view (degrees)
  • ImageType - Image type: '360', 'oblique', 'nadir', 'inspection'

YAML Configuration

Define maps declaratively using YAML. Build static HTML with the Python CLI.

map.yaml 
version: 1
title: My Enterprise Map

auth:
  portal_url: https://my.portal.com
  method: oauth2
  client_id: abc123

view:
  center: [-98.5795, 39.8283]
  zoom: 4
  style: https://basemaps.cartocdn.com/gl/positron-gl-style/style.json

controls:
  login: true
  navigation: true
  scale: true
  duckdb_loader: true

layers:
  - id: counties
    type: feature_service
    url: https://services.arcgis.com/.../FeatureServer/0
    opacity: 0.7

  - id: elevation
    type: cog_s3
    url: s3://my-bucket/dem.tif
    colormap: viridis

Python CLI Reference

The Python CLI provides commands for creating, validating, building, and serving map configurations.

Initialize a New Project

Terminal 
maplibre-arcgis init
# Creates map.yaml with commented examples

Validate Configuration

Terminal 
maplibre-arcgis validate map.yaml
# Validates schema and optionally pings service URLs

Build Static HTML

Terminal 
maplibre-arcgis build map.yaml --output dist/index.html
# Generates self-contained HTML deployable anywhere

Development Server

Terminal 
maplibre-arcgis serve map.yaml --port 8080
# Serves with hot-reload and proper CORS headers for DuckDB

Convert Existing WebMaps

Terminal 
# Convert WebMap to YAML
maplibre-arcgis convert webmap ITEM_ID --portal https://www.arcgis.com --token TOKEN

# Convert WebScene to YAML (2D-extractable layers only)
maplibre-arcgis convert webscene ITEM_ID --portal https://www.arcgis.com --token TOKEN
✓ Next Steps

Ready to dive deeper? Check out the Developer Guide for architecture details and advanced usage, or the Deployment Guide for production deployment options.