Package Exports
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (esri-gl) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
esri-gl
A TypeScript library that bridges Esri ArcGIS REST services with MapLibre GL JS and Mapbox GL JS. It replicates Esri Leaflet's architecture patterns while being compatible with modern WebGL mapping libraries.
Note: This library is compatible with both MapLibre GL JS and Mapbox GL JS.
Features
Supported Services
- Dynamic Map Services - Server-rendered raster tiles from ArcGIS Map Services
- Tiled Map Services - Pre-cached tile services for optimal performance
- Image Services - Analytical raster data with server-side processing
- Vector Tile Services - Client-rendered vector tiles for fast styling
- Vector Basemap Styles - Esri's vector basemap styles with custom styling
- Feature Services - Vector data with smart vector tile detection and GeoJSON fallback
Advanced Features
- Smart Vector Tile Detection - Automatically detects vector tile endpoints with GeoJSON fallback
- Dynamic Layer Management - Add/remove layers dynamically with proper cleanup
- Identify Tasks - Query features and raster data at specific locations
- Bounding Box Filtering - Optimize performance with viewport-based data loading
- Layer Definitions - Filter data server-side using SQL-like expressions
- Time-aware Services - Support for temporal data visualization
- Attribution Management - Automatic service attribution handling
- TypeScript Support - Full type safety with comprehensive interfaces
Installation
Stable Release
npm install esri-glAlpha/Beta Releases
# Latest alpha release (current: v0.1.0-alpha.2)
npm install esri-gl@alpha
# Specific alpha version
npm install esri-gl@0.1.0-alpha.2
# Latest beta release
npm install esri-gl@betaGitHub Packages (Alternative Registry)
# Configure npm to use GitHub Packages for @muimsd scope
npm config set @muimsd:registry https://npm.pkg.github.com/
# Install from GitHub Packages
npm install @muimsd/esri-gl
# Or use the setup script
./scripts/github-packages.sh configure
./scripts/github-packages.sh installQuick Start
Basic Usage with MapLibre GL JS
import { Map } from 'maplibre-gl';
import { DynamicMapService, VectorTileService, FeatureService } from 'esri-gl';
const map = new Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json',
center: [-95, 37],
zoom: 4
});
map.on('load', () => {
// Add a dynamic map service
const dynamicService = new DynamicMapService('census-source', map, {
url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer'
});
map.addLayer({
id: 'census-layer',
type: 'raster',
source: 'census-source'
});
// Add a feature service with smart vector tile detection
const featureService = new FeatureService('parcels-source', map, {
url: 'https://services.arcgis.com/.../FeatureServer/0',
useVectorTiles: true, // Automatically detects and falls back to GeoJSON if needed
useBoundingBox: true, // Optimize with viewport filtering
where: "STATUS = 'Active'", // Server-side filtering
outFields: '*'
});
map.addLayer({
id: 'parcels-layer',
type: 'fill',
source: 'parcels-source',
paint: {
'fill-color': '#007cbf',
'fill-opacity': 0.5
}
});
});Using with Mapbox GL JS
import mapboxgl from 'mapbox-gl';
import { VectorBasemapStyle, ImageService } from 'esri-gl';
mapboxgl.accessToken = 'your-mapbox-token';
const map = new mapboxgl.Map({
container: 'map',
center: [-95, 37],
zoom: 4
});
map.on('load', () => {
// Add Esri vector basemap style
const basemapService = new VectorBasemapStyle('basemap-source', map, {
style: 'arcgis/streets'
});
// Add image service for analytical raster data
const imageService = new ImageService('elevation-source', map, {
url: 'https://sampleserver6.arcgisonline.com/arcgis/rest/services/Elevation/ImageServer',
renderingRule: {
rasterFunction: 'Hillshade'
}
});
map.addLayer({
id: 'elevation-layer',
type: 'raster',
source: 'elevation-source'
});
});Service Classes
DynamicMapService
Server-rendered raster tiles from ArcGIS Map Services.
const service = new DynamicMapService('source-id', map, {
url: 'https://example.com/arcgis/rest/services/MyService/MapServer',
layers: [0, 1, 2], // Specific layers to display
layerDefs: {
0: "POP2000 > 100000", // Filter layer 0
1: "STATE_NAME = 'California'" // Filter layer 1
},
transparent: true,
format: 'png32'
});TiledMapService
Pre-cached tile services for optimal performance.
const service = new TiledMapService('source-id', map, {
url: 'https://example.com/arcgis/rest/services/MyTiledService/MapServer'
});FeatureService
Vector data with intelligent vector tile detection and automatic GeoJSON fallback.
const service = new FeatureService('source-id', map, {
url: 'https://example.com/arcgis/rest/services/MyService/FeatureServer/0',
useVectorTiles: true, // Smart detection with fallback
useBoundingBox: true, // Viewport-based loading
where: '1=1',
outFields: '*',
maxRecordCount: 2000
});VectorTileService
Client-rendered vector tiles for fast styling and interaction.
const service = new VectorTileService('source-id', map, {
url: 'https://example.com/arcgis/rest/services/MyService/VectorTileServer'
});ImageService
Analytical raster data with server-side processing capabilities.
const service = new ImageService('source-id', map, {
url: 'https://example.com/arcgis/rest/services/MyImageService/ImageServer',
renderingRule: {
rasterFunction: 'Stretch',
rasterFunctionArguments: {
StretchType: 6,
NumberOfStandardDeviations: 2
}
},
mosaicRule: {
mosaicMethod: 'esriMosaicLockRaster',
lockRasterIds: [1, 2, 3]
}
});VectorBasemapStyle
Esri's vector basemap styles with customization options.
const service = new VectorBasemapStyle('source-id', map, {
style: 'arcgis/streets', // or 'arcgis/navigation', 'arcgis/topographic', etc.
language: 'en',
worldview: 'USA'
});Task-Based Operations
Modeled after Esri Leaflet's chainable task pattern for querying and identifying features.
IdentifyFeatures
Query vector features at specific locations.
import { IdentifyFeatures } from 'esri-gl';
const identifyService = new IdentifyFeatures({
url: 'https://example.com/arcgis/rest/services/MyService/MapServer'
});
// Identify features at a point
const results = await identifyService
.at({ lng: -95, lat: 37 })
.tolerance(5)
.layers('all')
.returnGeometry(true)
.run(map);
console.log('Identified features:', results);IdentifyImage
Query raster values from image services.
import { identifyImage } from 'esri-gl';
const results = await identifyImage({
url: 'https://example.com/arcgis/rest/services/Elevation/ImageServer'
}).at({ lng: -120, lat: 40 });
console.log('Elevation value:', results.value);Query
Advanced feature querying with spatial and attribute filters.
import { query } from 'esri-gl';
const results = await query({
url: 'https://example.com/arcgis/rest/services/MyService/FeatureServer/0'
})
.where("STATE_NAME = 'California'")
.intersects({
type: 'Point',
coordinates: [-118, 34]
})
.run();Advanced Features
Dynamic Layer Management
// Add layers dynamically
const service = new DynamicMapService('census-source', map, {
url: 'https://example.com/MapServer'
});
// Update visible layers
service.setLayers([0, 2, 5]);
// Update layer definitions
service.setLayerDefs({
0: "POP2000 > 50000",
2: "STATE_NAME IN ('California', 'Nevada')"
});
// Clean up
service.remove();Smart Vector Tile Detection
The FeatureService automatically detects vector tile availability:
const service = new FeatureService('smart-source', map, {
url: 'https://example.com/FeatureServer/0',
useVectorTiles: true // Will automatically:
// 1. Check for VectorTileServer endpoint
// 2. Test various URL patterns
// 3. Fall back to GeoJSON if vector tiles unavailable
// 4. Log the decision process to console
});Performance Optimization
const service = new FeatureService('optimized-source', map, {
url: 'https://example.com/FeatureServer/0',
useBoundingBox: true, // Only load features in current viewport
maxRecordCount: 1000, // Limit records per request
where: 'STATUS = "Active"', // Server-side filtering
outFields: ['OBJECTID', 'NAME', 'STATUS'] // Limit fields
});Development
Build System
- Library Build: Rollup with
@rollup/plugin-typescript(UMD + ESM outputs) - Type Declarations: Consolidated in
dist/types/directory - Demo Development: Vite dev server
- Documentation: Docusaurus build system
- Test Coverage: 92.94% with 651 focused test cases
Development Commands
# Start demo development server
npm run dev
# Build library (both UMD and ESM)
npm run build
# Watch mode for library development
npm run build:watch
# Type checking
npm run type-check
# Linting and formatting
npm run lint
npm run format
# Run tests
npm run test
npm run test:watch
npm run test:coverage
# Build documentation
npm run build-docs
npm run dev:docsProject Structure
src/
├── Services/ # Core service classes
│ ├── DynamicMapService.ts
│ ├── FeatureService.ts
│ ├── ImageService.ts
│ ├── TiledMapService.ts
│ ├── VectorTileService.ts
│ └── VectorBasemapStyle.ts
├── Tasks/ # Task-based operations
│ ├── Find.ts
│ ├── IdentifyFeatures.ts
│ ├── IdentifyImage.ts
│ └── Query.ts
├── demo/ # Demo React components
├── tests/ # Comprehensive test suite (92.94% coverage)
└── types.ts # TypeScript interfaces
dist/
├── types/ # Consolidated TypeScript declarations
├── esri-gl.js # UMD build
├── esri-gl.esm.js # ESM build
└── esri-gl.min.js # Minified UMD buildBrowser Support
- Modern Browsers: Chrome, Firefox, Safari, Edge (ES2018+)
- MapLibre GL JS: v2.0+ (recommended), v1.15+
- Mapbox GL JS: v2.0+ (recommended), v1.13+
TypeScript Support
esri-gl is written in TypeScript and provides full type definitions consolidated in a single directory:
import type {
DynamicMapServiceOptions,
FeatureServiceOptions,
IdentifyResult,
EsriGeoJSONFeatureCollection
} from 'esri-gl';
const options: FeatureServiceOptions = {
url: 'https://example.com/FeatureServer/0',
useVectorTiles: true,
where: '1=1'
};All type declarations are available in the dist/types/ directory after building.
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make changes and add tests
- Run validation:
npm run validate - Commit changes:
git commit -m 'Add new feature' - Push to branch:
git push origin feature/my-feature - Submit a pull request
License
MIT License - see LICENSE file for details.
Acknowledgements
- Esri Leaflet - Inspiration for API design and architectural patterns
- MapLibre GL JS & Mapbox GL JS - Incredible WebGL mapping libraries
- Esri ArcGIS Platform - Comprehensive GIS services and APIs
- mapbox-gl-esri-sources - Reference implementation for Esri service integration patterns