Breaking changes v2.0.0

[wipfli]

Version 2.0.0 of this library is coming soon. The migration to Typescript removes support for internet explorer and the public API does not expose the version anymore. See CHANGELOG.md of the typescript branch.

Breaking changes that most likely will follow are:

• Removal of accessToken support
• Removal of the Mapbox CSS classes

[wipfli]

While the access token probably has to go, I think it is still up for discussion if we also want to remove the Mapbox CSS classes, see #203.

[wipfli]

@p-j I am worried that if we remove the Mapbox CSS classes many plugins will break. But then if we keep them the plugins might still break since Mapbox and MapLibre will diverge over time.

[HarelM]

One of the things discussed in #41 is the idea of creating a plugin for mablibre to support this compatibility. I think this idea is a good middle ground - people who are interested in working with both maplibre and mapbox could contribute to this plugin. This will allow this project and repo to continue forward without the need for extra complexity of keeping backwards compatibility which is a big burden on development from my past experience. I think that creating a plugin like this and having the relevant css there and maybe other functions to facilitate smooth transition and compatibility is the right direction. Feel free to let me know if I'm missing something here and if this is not possible in any way.
I would like to focus on developing maplibre and less about maintaining support for mapbox when working on this project... :-)

[Pessimistress]

FWIW we are making a push in react-map-gl to be impartial about the map renderer in use. The latest react-map-gl@beta release lists mapbox-gl as a peer dependency instead of dependency. We have also removed all hard-coded mapbox-* class names from the entire code base. You can test it here: https://github.com/visgl/react-map-gl/tree/7.0-dev/examples/get-started/maplibre

The biggest compatibility risk for our upcoming release is that it heavily relies on @types/mapbox-gl, e.g. the react component prop types for Map, Marker etc. extend those that are imported from @types/mapbox-gl. If maplibre and mapbox-gl diverge further, TypeScript may start complaining. Please advise if you know of any best practices/solutions of "drop-in replacement" for typing.

[HarelM]

@Pessimistress thanks for this wonderful news! From version 2.x we are moving to use the typing straight from the code. This introduce breaking changes in the typings unfortunately, I'm not sure I know how to solve this easily.
You can test and see how this behaves by installing maplibre-gl@2.0.0-pre.6.
While maintaining ngx-maplire-gl I forked the ngx-mapbox-gl and it allowed me to easily support only maplibre, but if you manage to support both maplibre and mapbox using types that are not the same I would love to know how. :-)

[astridx]

I have tested https://github.com/visgl/react-map-gl/tree/7.0-dev/examples/get-started/maplibre

At first everything looked good.

But when I changed [mapStyle ](https://github.com/visgl/react- good.
I wrote too quickly. The other mapStyle were also displayed after I called npm run build again.

[joshuacrew]

I have tested https://github.com/visgl/react-map-gl/tree/7.0-dev/examples/get-started/maplibre

I found an issue with combining that example with the Controls example here. I have put an issue in the react-map-gl library, but it may be more applicable here.

[wipfli]

Updates from the steering committee meeting: MapLibre's priority is to make it easy for users to switch from Mapbox v1 to MapLibre v2. The release notes should document what steps are needed for such a switch. Avoiding fragmentation has beed and will continue to be of highest importance to this project and introducing breaking changes for symbolic reasons are not acceptable. Maintainers of this code base want to focus on new features and improvements. Keeping it compatible with Mapbox v2 is however not required.

[wipfli]

@marcelnormann @nyurik @HarelM @klokan were in today's meeting. Correct me if I misinterpreted something.

[stevage]

Thanks for the update, much appreciated.

[arichnad]

I've read the v2 pre release changelog, and it says ** Breaking Change ** removed all code related to accessToken and mapbox specific urls, but it doesn't say what to do about this? Having a one-liner about what needs to change or even a pointer on what needs to happen will be insanely useful to users upgrading to v2 or anyone trying to change from mapbox to maplibre.

Maybe something along the lines of, change "mapbox://...") to "style.json" where style.json has something specific in it?

The release notes should document what steps are needed for such a switch

@wipfli Where are these release notes? I don't see them here or in the maplibre-gl-js-docs. Linking from the changelog to this document might be useful, thanks!

[stevage]

Correct me if I'm wrong, but Mapbox servers are a public REST API, accessible broadly with an access token.

My understanding after a brief re-read:

• there is a vector tiles API which works like this, and is priced by tile request.
• there is Mapbox GL JS v2 which has additional terms (not relevant here) and charges per map load

I don't see any indication that there is anything problematic about using a third-party library (which MapLibre essentially is) to access Mapbox services, provided you have an API key etc.

Now, HarelM referenced the warning in this code, which I'll quote:

/***** START WARNING - IF YOU USE THIS CODE WITH MAPBOX MAPPING APIS, REMOVAL OR
* MODIFICATION OF THE FOLLOWING CODE VIOLATES THE MAPBOX TERMS OF SERVICE  ******
* The following code is used to access Mapbox's Mapping APIs. Removal or modification
* of this code when used with Mapbox's Mapping APIs can result in higher fees and/or
* termination of your account with Mapbox.
*
* Under the Mapbox Terms of Service, you may not use this code to access Mapbox
* Mapping APIs other than through Mapbox SDKs.
*
* The Mapping APIs documentation is available at https://docs.mapbox.com/api/maps/#maps
* and the Mapbox Terms of Service are available at https://www.mapbox.com/tos/
******************************************************************************/

I read this "warning" as what it is, a warning that modifying code here might be breaking terms defined elsewhere. It is not, itself, a licence or agreement. And the problem is, the Mapbox terms of service keep changing, so it's very hard to know what the terms were in effect at the time this was written, or even to know why it was written.

In particular, I can't find any justification for this statement in the current Mapbox Terms of Service:

Under the Mapbox Terms of Service, you may not use this code to access Mapbox Mapping APIs other than through Mapbox SDKs.

There isn't anything in the terms at all about SDKs. I'm not certain, but I suspect there were previously some much more restrictive terms that have been removed. Maybe one of these changes:

April 24, 2020: product terms removed and replaced with a reference to our standard service terms.

July 1, 2019: Removed the default restriction that Services have to be used in conjunction with a Mapbox map. Point of interest results from the Geocoding API and Enterprise Boundaries must still be used in conjunction with a Mapbox map.

May 22, 2019: Updates to reflect pricing changes; removal of commercial and private application restrictions; addition of late payment interest and attorneys’ fees; addition of audit right for non-geocoding services; updated tax language; and minor corrections and reorganizations for clarity.

So, in summary: I think it's most likely fine to access Mapbox services through MapLibre, although I don't entirely understand exactly what part of that file is needed anyway (since most of it seems to be about implementing the "Map loads" pricing which isn't relevant here).

And IMHO this:

The bottom line is: don't use mapbox with this library.

Is a very disappointing stance for a project maintainer to be taking. I really hope this does not reflect the direction of the project, because if it does, it will make it much less valuable.

[Pessimistress]

As of today the Mapbox hosted tiles can still be loaded by appending the access token as a query parameter. Users of maplibre can use a map style that references Mapbox servers in tandem with the transformRequest callback:

maplibre-gl-js/src/ui/map.ts

Line 245 in ac88200

* @param {RequestTransformFunction} [options.transformRequest=null] A callback run before the Map makes a request for an external URL. The callback can be used to modify the url, set headers, or set the credentials property for cross-origin requests.

I personally think it's perfectly fine for maplibre to include a code sample for this use case in its documentation, alongside a "read the Mapbox T&C before use" warning.

[wipfli]

Thanks everyone for the feedback. I am happy to review pulll requests which update the readme or changelog to clarify how one is supposed to use Mapbox services with MapLibre GL JS. All contributions are welcome!

[igal1c0de4n]

Has anyone been able to use the RequestTransformFunction approach to load a mapbox style?
If so, would love to see a sample

[AbelVM]

I'm quite interested in this issue too 😅

[nyurik]

My take on licensing (IANAL) is that this is outside of the MapLibre's scope to evaluate constantly changing terms of service of any data provider, let alone endorse or give any legal guarantees -- from BSD license -- THIS SOFTWARE IS PROVIDED ... "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES ... ARE DISCLAIMED.

That said, we always want to "play nice" and provide as much help and transparency as possible. MapBox usage is clearly a goal of many users, so we should have a dedicated section in our documentation/examples/.... The docs should:

• link to MB license/TOS
• document the removal of the mapbox-specific code and associated scary text, and explain the reasoning behind code removal
• reiterate that MapLibre libs are provider-neutral, and cannot endorse any data provider or do legal evaluation of their terms/give any legal guarantees
• provide MapLibre usage examples based on Mapbox API official docs, i.e. if the docs say that a token must be appended to a tile URL, show how to do it with MapLibre

We should also kindly ask Mapbox to clarify their position on 3rd party usage of their service by non-Mapbox authorized client libraries, including the seeming discrepancy with the "scary text" warning. Perhaps this should be done by a Mapbox customer who wants to use MapLibre while paying for Mapbox service.

P.S. Thanks everyone who is participating!

[stevage]

That seems very reasonable.

I have reached out to someone at Mapbox by email. Will keep you updated.

[sabres207]

So is it possible to use mapbox api with maplibre even with version 2?
I'm currently using maplibre version 1 only for that reason.

[aaguilardm]

Hi, has there been any update from Mapbox in regards to this?

[stevage]

No, I haven't heard any further word from them.

[acalcutt]

I was testing the MapLibre Terrain3d branch and I noticed it no longer worked with the maplibre-gl-inspect.min.js plugin I had modified from mapbox-gl-inspect.min.js.

After looking into it I think it is related to the removal of 'version', which the plugin used to make sure the library was a supported version. I was able to get it working again by removing that check
var e, n = null;

                window.maplibregl ? ((e = (e = window.maplibregl).version.split(".").map(parseFloat))[0] < 1 && e[1] < 29 && console.error("MaplibreInspect only supports Maplibre GL JS >= v0.29.0. Please upgrade your Maplibre GL JS version."), n = new window.maplibregl.Popup({
                    closeButton: !1,
                    closeOnClick: !1
                })

was changed to

                window.maplibregl ? ((n = new window.maplibregl.Popup({
                    closeButton: !1,
                    closeOnClick: !1
                }))

This should work for my use, but I'm wondering if 'version' is used in other plugins and/or still useful

[HarelM]

It's worth mentioning here that we are looking into named exports as part of this version"s breaking changes. The advantage is to allow tree shaking, the disadvantage is that it will split the ecosystem sooner than later.
See #623 for more technical info.
Thoughts are welcome :-)

[stevage]

This does not seem like a big deal to me. If I'm understanding right, it basically means changing:

import mapboxgl from 'mapbox-gl';

to

import * as mapboxgl from 'maplibre-gl';

or something similar.

Is it a bigger deal than that? This does not seem like something that "splits the ecosystem" to me.

[HarelM]

I'm not sure yet, it might be just that, and in this case, as you said, it's not that big of a deal, but it might be more complicated, I still need to research it and see what are the expected changes.
It might also be a candidate for 3.x in case we decide to release 2.x without it.
The more I read about it the more I'm inclined to change the output format from UMD to ESM, which might not be fully related to named exports but seems somehow connected... I'm not sure...

[astridx]

While the access token probably has to go, I think it is still up for discussion if we also want to remove the Mapbox CSS classes, see #203.

I'm not sure, but didn't we want to delete the classes in version 2?
If we don't do this, it's only possible for the next major version (3.0), right?