Moving forward (new package)

[josxha]

Dear maplibre flutter community,

I'm happy to announce my latest efforts, flutter-maplibre or maplibre on pub.dev!
There is a hosted demo app running here.

While I was integrating maplibre_gl into a production system, I had annoying issues with reliability and experienced different behaviors on different platforms. There is a growing amount of bug reports related to these topics, too. This made me take a closer look on what major changes could be made to have a more resilient and modern package for the maplibre SDKs.

Room for improvement

1. Using code generation

The method channel currently used for android and iOS in maplibre_gl makes heavy use of argument parsing that is not type safe. The maplibre package tries to improve on this by replacing it with pigeon code generation. This has been previously suggested in #465. This change has the potential for

• reduce bugs because of type safe platform bindings
• faster implementation of new features
• better parity between platforms

2. Get rid of legacy code and workarounds

The maplibre_gl package contains some old undocumented workarounds. Some of them are related to when JavaScript interoperability of Dart was still in the early days, for example the one removed in 525e49e. Moreover, because of new language features in Dart like null safety, the code base can get mordernized a bit.

3. WebAssembly compatebility

Dart interop with JavaScript has changed quite a bit with recent versions of Flutter to support WASM builds. This would require the web integration to be revised and at least partially get rewritten.

4. License compliance

31 files in maplibre_gl contain a copyright header mentioning "The Chromium Authors" with a "BSD-style license". However, the license isn't included in the LICENSE file. Looking at the git history reveals that they were merged in along with code years ago and the original repository no longer exists as far as I remember.

// Copyright 2018 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5. Simplify the architecture

flutter-maplibre-gl currently consists of three packages: the main maplibre_gl package, the web integration in maplibre_gl_web and the package maplibre_gl_platform_interface with mostly interface classes. This is a solution to comply with the avoid_web_libraries_in_flutter lint.
In my opinion, the benefit in versioning and updating them separatly is rarely used. Learning from maplibre_gl this multi-package architecture can bring a decent amount of challences and complexity (e.g. #476.). It makes the release cycle more complicated, spreads the dependencies over multiple packages and is challenging for new contributors.

6. Documentation

The public API of flutter-maplibre-gl lacks documentation of its public API and the example app is the only place to learn how to implement features. I created a pull request that adds a docs site in #461.
By using the public_member_api_docs lint, it is possible to enfore documentation for the public API and provide a documentation website with versioned docs.

7. Example app

The example app of the package has no responsive design and some examples don't work any more, link to tile servers that no longer exist or have different results on different platforms.

But why start a new package?

While it would have been possible to integrate all my mentioned changes into maplibre_gl, it would have been very time consuming to update and migrate the package bit by bit. The amount and quantity of the changes made me prefer to risk a fresh start.

Should I start using the maplibre package?

Probably not yet, or at least not without checking what features you require. While in my opinion the MapController already has better reliability and better feature parity on different platforms, the package has still bugs and only a fraction of the functionality of maplibre_gl.
However, if you already want to do some testing with the new package, please give it a try.

That's all from me for now. Of course, if you are interested in joining efforts and contribute or test the package, you are more than welcome to do so. Thanks for reading this post, I'm open for feedback or suggestions (:

[gabbopalma]

Will this new package be supported by the MapLibre organization?

[josxha]

This flutter-maplibre-gl repository is considered a hosted project. This means while the repository is hosted on the MapLibre GitHub organization, no resources are directed towards it.

Hosted Project

A project that the MapLibre Organization does not allocate any resources to. The project is hosted in the MapLibre GitHub organization to facilitate collaboration between the people who are interested in the project.

See the MapLibre Project Tiers for more information.

I'm open to have josxha/flutter-maplibre adoped by the MapLibre organization as successor of this package one day but it will be on my GitHub account for now.

[josxha]

I created an issue that tracks feature parity between both projects: josxha/flutter-maplibre#29

[matthiscock]

Appreciate your work and look forward to testing and helping feedback on things.