type declaration for typescript not working properly. about maptiler-sdk-js

[jonathanlurie]

Hello @danirdd92 ,
I am not super familiar with Svelte, so I used the Vanilla TS code sample from ViteJS (powered by Stackblitz) and I could create an example that works well. Please find it here: https://stackblitz.com/edit/maptiler-sdk-vite-vanilla-ts?file=readme.md

The issue was in the default tsconfig.json of the ViteJS project, they use a somewhat legacy/non-official "moduleResolution": "bundler", that I replaced with a more common "moduleResolution": "node",. This tells TS how to resolve the modules. It's a bit verbose but you can find more info about this here: https://www.typescriptlang.org/docs/handbook/module-resolution.html

The slash / character is generally not an issue and is often used as a way to create a logic of namespace within the NPM ecosystem. For example, at MapTiler, we try to publish all our official packages with the prefix @maptiler/. You can see this a lot with companies, but it's less frequent for non-affiliated individuals.

You're 100% correct, MapLibre GL, Mapbox GL, and MapTiler SDK do look very similar and that is for historical reasons. The project started 10 years ago and was originally created by Mapbox. After some years of development, they decided that after a certain version, their library will no longer be published as open source (even though the source is available on GitHub, the license of Mapbox GL JS is no longer open). At this moment, there was already a fairly large ecosystem of open-source developers that were using it and were creating all sorts of plugins for it, and they decided to join forces and fork the very last version of Mapbox GL JS that was published under an open source license, and they called this fork MapLibre GL JS. For some years now, MapLibre GL JS is being maintained by a very active community and is diverging more and more from Mapbox GL JS.

As per MapTiler SDK, this is not a fork of MapLibre GL JS, this is an extension, so it has exactly the same capabilities, and on top of this, we add a smoother compatibility layer with MapTiler Cloud, as well as some nice helper, functions to make the developer experience more enjoyable. For example, with MapTiler SDK, you don't really have to think about what is the URL of the raster tiles to add 3D terrain or how to configure it, this is done internally and you just have to construct your map instance with terrain: true. That's just an example.

I do understand the confusion and I will pass the message to our documentation team, I am sure we can improve this point!

[jonathanlurie]

Hello @danirdd92 ,
thanks for the feedback! I'll try to reproduce this with Vite. The svelte and vanilla-ts are the boilerplates you have used from Vite, is that correct?

[danirdd92]

Hi @jonathanlurie :)

Exactly, both coming with from the vite cli boilerplate.

I do have a suspicion regarding the cause which is the name of the package @maptiler/sdk
I believe the backslash doesn't register properly as a name alias but as path which breaks some existing preconceptions that either vs-code or typescript have regarding the location of the declaration files.

maybe a fix in rollup settings is needed?
I'm really not in the know for anything to actually give good advice thus no PR so feels bad. :(

Also, a bit off-topic, I'd like to understand the relationship between libre-gl, mapbox anf maptiler, these 3 SDKs look awefully similar to the point i sometimes find their name mentioned in another's source code or as advice for plugin usage to the point it's actually referenced in the docs to use another.

see the following example from using maptiler with react in the official docs pointing to libre-gl here.

[danirdd92]

Thank you very much @jonathanlurie !

Your help is much appreciated both with the ts issue and the history of all the mapping libs mentioned above.

kind regards,
Daniel.

[PolynomialTim]

I ran into something similar while writing a project using @maptiler/sdk also scaffolded with create vite (React/TS template).

Similar to what @jonathanlurie said, changing tsconfig.json:compilerOptions.moduleResolution from bundle to node also resolved the issues I was seeing locally.

While looking for answers about the errors I was seeing, I stumbled on some long discussions and a reference to arethetypeswrong.github.io for checking NPM package exported TS types. Their Github repo has additional documentation about common causes for each flagged type of error.

Outside my realm of expertise, but might be helpful in fixing the type exports in @maptiler/sdk so that others don't run into the same issue in the future.