[@mapbox/static-apis] [feature] Provide modules with reference without docs and examples

[ahocevar]

This pull request adds the flow-stripped source code of the @mapbox/mapbox-gl-style-spec package to the dist/ folder and adds them as exports to package.json. The latest reference imports a minified version of the v8 reference, without docs and examples.

The goal of the separate modules is to allow third-party applications to create smaller builds, and the motivation was that the ol-mapbox-style library currently has a full build with a size of 638 kB. When using the modules and minified reference from this pull request, the build size can be reduced to 534 kB.

The @mapbox/mapbox-gl-style-spec package now exports separate modules in addition to the ESM and CJS bundles. The difference between the bundles and the modules is that the latter use a minified version of the latest style refererence, which does not contain any doc and example fields. See the exports section of package.json for available modules.

Launch Checklist

• briefly describe the changes in this PR (see above)
• include before/after visuals or gifs if this PR includes visual changes (n/a)
• write tests for all new functionality (n/a)
• document any changes to public APIs (no changes)
• post benchmark scores (n/a)
• manually test the debug page
• tagged @mapbox/map-design-team @mapbox/static-apis if this PR includes style spec API or visual changes
• tagged @mapbox/gl-native if this PR includes shader changes or needs a native port (none)
• apply changelog label ('bug', 'feature', 'docs', etc) or use the label 'skip changelog'
• add an entry inside this element for inclusion in the mapbox-gl-js changelog: <changelog></changelog>

[CLAassistant]

All committers have signed the CLA.

[ahocevar]

This is now ready for review.

[mourner]

The difference between the bundles and the modules is that the latter use a minified version of the latest style refererence, which does not contain any doc and example fields.

Sorry for a delay with response. If this is the root of the issue, perhaps a more reliable solution would be to fix it directly — e.g. by exporting both minified and full v8 references in the ESM bundle? Or is that difficult due to the way minification happens in Rollup?

[ahocevar]

Thanks for the feedback, @mourner. The goal of the removal of the doc and example fields was to reduce the build size, and the reason why I did not do it in the ESM bundle is because I assume that consumers of @mapbox/mapbox-gl-style-spec may rely on the information in these fields.

It would be easy to export both minified and full v8 references in the ESM bundle, but would it meet the goal to reduce the build size of applications or libraries that depend on @mapbox/mapbox-gl-style-spec? If I'm not mistaken, bundlers only tree-shake on the module level. If that's correct, then your suggested solution would increase the build size instead of reducing it, because the full v8 reference would be carried around without actually being used.

Another solution I could think of is to include both minified and full spec as modules, but continue letting modules import the minified one. The full spec could be added e.g. as v8-full.json. Would that be an acceptable improvement to this pull request?

What exactly are your concerns regarding reliability of my proposed solution?

[mourner]

If I'm not mistaken, bundlers only tree-shake on the module level. If that's correct, then your suggested solution would increase the build size instead of reducing it, because the full v8 reference would be carried around without actually being used.

I don't think that's the case — the whole point of tree shaking is to only include what's used and discard the rest, module boundary or not. The only case when it's limited to module boundary is when the bundler pulls in CJS, or when ESM exports an object rather than a set of named exports, but it shouldn't be the case here.

So to sum up, let's explore adding a minified spec in the ESM exports.

[ahocevar]

Ok, let's try that. Looking at the code, I would assume that all code which depends on the reference works without docs and examples. Only the validate utility benefits from the full spec, because it will produce more useful output then.

[ahocevar]

@mourner I created #11661 implementing what you suggested. It was a bit more complicated because i did not want to modify the build process of mapbox-gl-js, so I added a replacer in rollup.config.js that actually replaces the build tool/configuration agnostic min export with the one that the rollup config creates.