Skip to content

Add ESM module support#166

Open
w8r wants to merge 3 commits intomasterfrom
esm-support
Open

Add ESM module support#166
w8r wants to merge 3 commits intomasterfrom
esm-support

Conversation

@w8r
Copy link
Collaborator

@w8r w8r commented Mar 6, 2026

Summary

This PR modernizes the package to support ES Modules (ESM) alongside the existing UMD format, enabling better tree-shaking and native module support in modern bundlers and Node.js.

Changes

  • New ESM source file (src/leaflet-mapbox-gl.js) with native import/export syntax
  • Rollup build pipeline producing both ESM and UMD bundles in dist/
  • Package.json updates:
    • Added "type": "module" for native ESM
    • Added "module" field pointing to ESM build
    • Added "exports" field with conditional exports for ESM/CJS resolution
    • Added "types" field for TypeScript support
    • Added build scripts (npm run build, prepublishOnly)
  • TypeScript definitions (dist/leaflet-mapbox-gl.d.ts)
  • JSHint configuration (.jshintrc) updated for ES6+

Usage

ESM (modern bundlers/Node.js):

import { mapboxGL } from 'mapbox-gl-leaflet';
// or
import mapboxGL from 'mapbox-gl-leaflet';

CommonJS:

const { mapboxGL } = require('mapbox-gl-leaflet');

Browser (unchanged):

<script src="dist/leaflet-mapbox-gl.js"></script>
<script>
  L.mapboxGL({ style: '...' }).addTo(map);
</script>

Backwards Compatibility

  • Original leaflet-mapbox-gl.js is kept in the package for users referencing it directly
  • UMD bundle maintains the same L.mapboxGL / L.MapboxGL globals
  • No breaking changes for existing users

Test plan

  • npm run lint passes
  • npm run build produces both ESM and UMD bundles
  • Manual testing with ESM import in a bundler (Vite/webpack)
  • Manual testing with script tag in browser

- Add ESM source in src/leaflet-mapbox-gl.js with import/export syntax
- Set up Rollup to build both ESM and UMD bundles to dist/
- Add package.json exports field for conditional ESM/CJS resolution
- Add "module" field pointing to ESM build
- Add TypeScript type definitions
- Configure JSHint for ES6+ with .jshintrc
- Keep original leaflet-mapbox-gl.js for backwards compatibility

Usage:
- ESM: import { mapboxGL } from 'mapbox-gl-leaflet'
- CJS: const { mapboxGL } = require('mapbox-gl-leaflet')
- Browser: <script src="dist/leaflet-mapbox-gl.js">
@w8r w8r self-assigned this Mar 6, 2026
@w8r w8r requested review from Copilot and jgravois March 6, 2026 17:36
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds an ES Module (ESM) build alongside the existing UMD distribution, aiming to improve compatibility with modern bundlers/Node ESM while preserving browser/global usage.

Changes:

  • Added an ESM source entry (src/leaflet-mapbox-gl.js) with import/export and named/default exports.
  • Introduced a Rollup build producing dist/leaflet-mapbox-gl.esm.js (ESM) and dist/leaflet-mapbox-gl.js (UMD).
  • Updated package metadata/scripts and added TypeScript declarations.

Reviewed changes

Copilot reviewed 4 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
src/leaflet-mapbox-gl.js New ESM entrypoint that exports MapboxGL / mapboxGL and also mutates L for compatibility.
rollup.config.js Rollup config to emit ESM + UMD builds.
package.json Adds conditional exports, sets type: module, and adds build/lint scripts.
package-lock.json Updates lockfile to include Rollup dependencies and lockfile v3 format.
dist/leaflet-mapbox-gl.d.ts Adds TypeScript typings and Leaflet module augmentation.
.jshintrc Enables ES module linting and modern ECMAScript settings.
.gitignore Ignores generated dist/*.js and sourcemaps while keeping .d.ts tracked.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

w8r and others added 2 commits March 6, 2026 18:48
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
- Rename CJS output to .cjs extension for explicit module type
- Add separate UMD build (.umd.js) for browsers
- Add "browser" field pointing to UMD build
- Update exports to use .cjs for require()
@w8r w8r requested review from mourner and stepankuzmin March 9, 2026 09:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants