[Question] How to Simplify Tangram usage as an NPM Module?

[bfreeds]

Want to start by saying thank you to everyone who has worked to make this mapping library so awesome, and congratulations on becoming a Linux Foundation project 😁

I'd love to use Tangram as my default mapping library because of the advanced capabilities for custom map design (which you've demo'd brilliantly). One barrier for me is that it's complex to use as a module. It looks like others have experienced these hurdles, too: (#561 #559).

Current Complexity

Currently the learning resources / documentation for using Tangram as a bundled library are:

• NPM. This documentation is the README.md from this repo, and does not provide any NPM-specific usage information.
  
• This README.md links to the tangram-play's wiki page called Using Tangram with Bundlers & Frameworks
  
  • This wiki includes shims for Browserify and workarounds for Webpack. It seems like Browserify has fallen out of favor of native NPM modules. Webpack can be a wily beast if you have to do workarounds / custom config. Because of this, recent Webpack releases have become "configuration-free," and other bundlers that are more developer friendly have been created (Parcel).
• This links to an example app using Tangram with Webpack, which includes additional notes for Webpack usage, which ends by sending you back to the tangram-play wiki:
  

Question

I don't know enough about Tangram.js to understand why these complexities exist, but I'm wondering what it would take on the development side to make this feel more NPM/module native (Mapboxgl.js does this very smoothly). I'm also wondering how the documentation could be simplified so that there is an example to reference, but the NPM module itself (where many might first go to look for a Tangram module) provides sufficient information to get started.

I plan on continuing to research this as I learn Tangram.js, but I'm curious if anyone has thoughts on if this could be useful and if so thoughts on where to start to make this happen.

[bcamper]

You're right, it is time we revisit this! :)

TLDR: with some recent changes to using Rollup for bundling, I was now able to create simple, "no config" demos with both Parcel and Webpack 🎉 More work is needed to clean these up, but it looks to be in much better shape now than previously.

Honestly I can't articulate or even remember all of the historical issues we ran into with bundling, but generally they stemmed from the unusual (but not entirely unique) web worker architecture used in Tangram. The library needs to spawn multiple web worker threads, and in order to be packaged in a single file (both for inclusion as a script tag, or via npm module) needs to have access to the actual source code of the web worker (which is instantiated via a blob URL).

Initially, we used a bespoke method for capturing the web worker code during Browserify's bundling process. However, the default Uglify minification used by Webpack broke this by making assumptions about code it could optimize that crossed the main/worker thread boundary; these issues necessitated the noParse webpack config option.

More recently, we switched to Rollup, but continued to encounter a similar minification error. Researching this now, it appears to be a manifestation of an issue also faced by Mapbox GL. While a little more testing is needed, by applying the same fix they did, I was able to get a simple Webpack build (with no special config) to work. The relevant Mapbox issue & fix:

mapbox/mapbox-gl-js#4359
mapbox/mapbox-gl-js#6956

I will aim to update and streamline the Tangram Webpack demo, and also create a similar one for Parcel (so much nicer than Webpack!). I believe that @meetar may be able to do the same for updating our basic React usage as well; he may also be creating TypeScript type definitions, which will be of help to some users.

Any advice or assistance in documenting and managing these demos would be appreciated as well. In the past, we have kept them as separate repos. It may also be useful to include a bundling demo in the main repository? I'm open to suggestions for reaching the best and widest audience, most easily.

[bfreeds]

@bcamper Thank you for the detailed response and context on this, that was super helpful for understanding the challenges faced previously. I'd love to help out in any way needed.

I do think it would be helpful to users to have a bundling demo in the main repository. Personally, when I'm doing a project using npm packages the first place I look for docs is on the NPM page itself. That's usually my first step, where I'll try pulling it in and seeing if I can get it working before coming back to a fuller api documentation for details.

I can research other open source project's documentation strategy, particularly around packages that are served both as a CDN library and as an NPM package, and suggest some ways to streamline the user experience for getting started with Tangram. Then would be happy to help implement, if desired.

[bcamper]

@bfreeds great, appreciate the help and outside perspective. Just wanted to say that in the meantime, I have managed to update and simplify these two examples somewhat:

https://github.com/tangrams/webpack-tangram-boilerplate
https://github.com/tangrams/react-webpack-tangram-boilerplate

At least as far as I am aware, all of the old weird config stuff (noParse etc.) has been removed successfully.

[bfreeds]

@bcamper the boilerplate's look much simpler. They both worked for me without a problem. Do you think it would make sense to change the tangram-play wiki to just point toward those two demo's rather than being a separate place to maintain documentation on how to use bundled Tangram?

[meetar]

Works for me – those docs could use some updating regardless :)