NPM pkg for dist bundles #2670

etpinard · 2018-05-25T21:03:10Z

resolves #2400

A new sync_pacakges.js script assembles "sub plotly.js packages" in the git-ignored build/ folder that include a minimal package.json and README.md as well as one single "bundle" file. Along with the main dist/plotly.js bundle, each partial bundle has it own "sub plotly.js package".

After running, node tasks/sync_pacakges.js, we get:

A sample package.json looks like:

and a sample README.md looks like:

Some questions left to answer:

Should we add the minified bundles to each sub package? Answer: no.
Should we add dist/topojson/ to all sub packages?
What to do with dist/extras/mathjax/? Should we include it too?

@nicolaskruchten what do you think?

- these sub-pkg are made in build/ - they all include a (minimal) README and package.json - at the moment, they include only one un-minified bundle file

etpinard · 2018-05-25T21:13:44Z

TODO:

we'll need to patch tasks/stats.js to make dist/README.md know about these npm "sub" packages
patch up the root README too.
update dev-docs about new npm publish behavior

nicolaskruchten · 2018-05-28T13:52:23Z

IMO no need to add minified versions. The main advantage I see for these packages is for people to import plotly.js in a more friendly way into their build systems like webpack and friends. In my experience, it's unhelpful to load minified files into such systems as it messes with their downstream minification.

nicolaskruchten · 2018-05-28T13:52:44Z

More generally I'm a huge fan of this PR :)

alexcjohnson · 2018-05-29T17:06:34Z

Slick! As to the questions about topojson and MathJax - these are both outside of the build, so seems to me the question is what would be the most useful thing we could do for folks who want to use local versions of topojson and MathJax, that wouldn't inconvenience folks content to use the CDN versions of these (or ignore them entirely)? Feels to me like we may want to include topojson anyway since otherwise they'd have to include the full plotly.js anyway just to get that, right? But maybe not MathJax, which they can get from npm now.

Incidentally, I was just chatting with @etpinard about our 4-year-old mathjax version - we're using 2.3, they're up to 2.7.4. Presumably a drop-in replacement since it's still 2.x, though we may change how we package it due to the npm package. We could make a separate issue for this, but perhaps the upgrade should be this PR, regardless of whether it's going to be included in the dist packages or not... if it is included people may start to wonder why it's so old, if not they'll be including the current version anyway (or at least one they can get from npm, which started at 2.5.1) so we'd better make sure it works!

etpinard · 2018-05-29T17:37:28Z

Feels to me like we may want to include topojson anyway since otherwise they'd have to include the full plotly.js anyway just to get that, right?

We could alternatively add a plotly.js-topojson npm package.

cpsievert · 2018-05-29T19:31:53Z

I would vote in favor of minified bundles if it's not too much overhead. It'd be much easier for me to leverage partial bundles in the R package that way.

nicolaskruchten · 2018-05-29T19:34:41Z

(no objections to minified bundles if it's helpful for the R world!)

etpinard · 2018-05-29T19:39:10Z

Just curious @cpsievert, why would an npm package be easier for you than downloading the min.js file from https://cdn.plot.ly/plotly-latest.min.js ?

cpsievert · 2018-05-29T20:27:22Z

@etpinard do we publish minified partials to the cdn (e.g., https://cdn.plot.ly/plotly-basic.min.js doesn't exist)?

I don't currently leverage partial builds in R, and I could do it via github releases, but it'd be nice to have a lighter-weight approach. I also recently created this R package to make it easy to leverage unpkg from R https://github.com/cpsievert/runpkg

etpinard · 2018-05-29T20:35:10Z

do we publish minified partials to the cdn (e.g., https://cdn.plot.ly/plotly-basic.min.js doesn't exist)?

yes -> https://cdn.plot.ly/plotly-basic-latest.min.js or https://cdn.plot.ly/plotly-basic-1.38.1.min.js

etpinard · 2018-05-29T20:36:20Z

All you want to know about partial bundles is here -> https://github.com/plotly/plotly.js/tree/master/dist#plotlyjs-basic

cpsievert · 2018-05-29T20:43:57Z

Ahhh, ok, I'll use the CDN then, sorry for the noise!

- factor up findModuleList from stats.js, to list which trace modules are included - fixup cb when build/* exist - add DRYRUN env var, to skip `npm publish`

... and refactor "Quick start options" section. List CDN first, plotly.js-dist 2nd and github release 3rd

etpinard · 2018-05-30T15:08:37Z

Reviewers, if you'll like to see what tasks/stats.js and tasks/sync_packages.js output, I made https://github.com/etpinard/plotly.js/tree/npm-pkgs-for-dist-bundles-build, where you can review:

https://github.com/etpinard/plotly.js/blob/npm-pkgs-for-dist-bundles-build/dist/README.md (updated only when we make new releases)
https://github.com/etpinard/plotly.js/tree/npm-pkgs-for-dist-bundles-build/build (git-ignored)

alexcjohnson · 2018-05-30T16:32:48Z

BUILDING.md

@@ -1,5 +1,7 @@
 # Building plotly.js

+The easiest way to bundle plotly.js into your application is to use the one of the distributed plotly.js packages on npm. These distributed packages should just work with **any** build framework. That said, if you're looking to save a few bytes, read the section below corresponding to your building framework.


use ~~the~~ one of the distributed...

Do you want to include a link that points to a list of these modules on npm? I guess we can add that later once it actually exists ;)

nicolaskruchten · 2018-05-30T18:25:17Z

README.md


 #### Install with `npm`

 ```bash
-npm install plotly.js
+npm install plotly.js-dist


Can we please move this up above the CDN option?

Personally, using the CDN is still the "quickest" way to start using plotly.js (hence its first spot in the "Quick start options" section), but ok.

nicolaskruchten · 2018-05-30T18:27:02Z

README.md


-If you would like to manually pick which plotly.js modules to include, you can create a *custom* bundle by using `plotly.js/lib/core`, and loading only the trace types that you need (e.g. `pie` or `choropleth`). The recommended way to do this is by creating a *bundling file*:
+If you would like to manually pick which plotly.js modules to include, you'll first need to run `npm install plotly.js` and then create a *custom* bundle by using `plotly.js/lib/core`, and loading only the trace types that you need (e.g. `pie` or `choropleth`). The recommended way to do this is by creating a *bundling file*. For example, in CommonJS:


I might prefix this with something like "If none of the distributed NPM packages meet your needs, and you would like to..." to encourage people to go with the flow :)

I think we should encourage people that want to save bytes to save bytes, but ok.

nicolaskruchten · 2018-05-30T18:31:38Z

What will the NPM module page look like for these new modules? they'll just inherit the same readme, github URL and homepage URL as the main module right? so basically the npmjs.org pages will look the same as the current one except for the callouts here?

etpinard · 2018-05-30T18:45:36Z

What will the NPM module page look like for these new modules?

Like their READMEs e.g.:

https://github.com/etpinard/plotly.js/blob/npm-pkgs-for-dist-bundles-build/build/plotly.js-cartesian-dist/README.md

nicolaskruchten · 2018-05-31T14:07:27Z

Re the README how are you telling NPM that it should use that readme instead of the main one? AFAIK it just grabs the readme from the repository field in package.json .. ?

etpinard · 2018-05-31T14:12:16Z

AFAIK it just grabs the readme from the repository field in package.json .. ?

Oh really? I thought it grabbed the package.json from where we run npm publish. Let me double-check.

etpinard · 2018-05-31T14:20:41Z

Thanks for bringing this up @nicolaskruchten !

We have to list the files manually in this case, like react's mono-repo does e.g. for react-dom.

josemarluedke · 2018-07-02T19:47:26Z

Are there any plans to get this merged in and released?

alexcjohnson · 2018-07-02T20:00:26Z

Are there any plans to get this merged in and released?

Yes, it's ready to go but because it will result in substantial changes to the documentation we want to merge it immediately before releasing v1.39.0. That should happen within the next week.

etpinard added 2 commits May 25, 2018 16:54

add 'sync packages' tasks that create pkg

e20dbbd

- these sub-pkg are made in build/ - they all include a (minimal) README and package.json - at the moment, they include only one un-minified bundle file

run 'sync packages' tasks as postpublish step

b3480f7

etpinard added feature something new status: discussion needed labels May 25, 2018

etpinard added this to the v1.39.0 milestone May 25, 2018

etpinard added 5 commits May 30, 2018 10:09

touch up sync_packages.js

a1238e7

- factor up findModuleList from stats.js, to list which trace modules are included - fixup cb when build/* exist - add DRYRUN env var, to skip `npm publish`

adapt README and BUILDING for 'sub' npm pacakges

e40b369

... and refactor "Quick start options" section. List CDN first, plotly.js-dist 2nd and github release 3rd

adapt item about build/ in CONTRIBUTING

c731350

adapt dist/README.md for npm sub packages

0a5cca2

add installation & usage section to each sub package README

c90bfbf

etpinard added a commit to etpinard/plotly.js that referenced this pull request May 30, 2018

[do not merge this] "build" commit for PR plotly#2670

07c724e

alexcjohnson reviewed May 30, 2018

View reviewed changes

nicolaskruchten reviewed May 30, 2018

View reviewed changes

etpinard added 6 commits May 31, 2018 11:38

fix typos + add \n in sub pkgs package.json

f9ee7ee

add link to npmjs page

ab2b5cd

clean bundle info tables

b1f32e3

add LICENSE to sub pkgs

3903e6d

list pkg files (to make sure npm doesn't grab them from repo root)

f6a19f9

nicolaskruchten-proof README

2bdce23

etpinard added status: reviewable and removed status: discussion needed labels Jul 3, 2018

etpinard merged commit 5de384c into plotly:master Jul 5, 2018

etpinard deleted the npm-pkgs-for-dist-bundles branch July 5, 2018 15:03

etpinard mentioned this pull request Jul 5, 2018

Fix typo in postpublish script #2784

Merged

This was referenced Sep 14, 2018

Should we expose a high-level bundler module / CLI ? #768

Closed

Package broken when installing in JSPM #22

Closed

etpinard mentioned this pull request Oct 10, 2018

Please publish locales on NPM #3083

Closed

etpinard mentioned this pull request Nov 7, 2018

Publish plotly.js-locales to npm #3223

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

NPM pkg for dist bundles #2670

NPM pkg for dist bundles #2670

etpinard commented May 25, 2018 •

edited

Loading

etpinard commented May 25, 2018 •

edited

Loading

nicolaskruchten commented May 28, 2018

nicolaskruchten commented May 28, 2018

alexcjohnson commented May 29, 2018

etpinard commented May 29, 2018 •

edited

Loading

cpsievert commented May 29, 2018

nicolaskruchten commented May 29, 2018

etpinard commented May 29, 2018

cpsievert commented May 29, 2018 •

edited

Loading

etpinard commented May 29, 2018

etpinard commented May 29, 2018 •

edited

Loading

cpsievert commented May 29, 2018 •

edited

Loading

etpinard commented May 30, 2018 •

edited

Loading

alexcjohnson May 30, 2018

nicolaskruchten May 30, 2018

etpinard May 30, 2018

nicolaskruchten May 30, 2018

etpinard May 30, 2018 •

edited

Loading

nicolaskruchten commented May 30, 2018 •

edited

Loading

etpinard commented May 30, 2018

nicolaskruchten commented May 31, 2018

etpinard commented May 31, 2018

etpinard commented May 31, 2018

josemarluedke commented Jul 2, 2018

alexcjohnson commented Jul 2, 2018

		@@ -1,5 +1,7 @@
		# Building plotly.js

		The easiest way to bundle plotly.js into your application is to use the one of the distributed plotly.js packages on npm. These distributed packages should just work with any build framework. That said, if you're looking to save a few bytes, read the section below corresponding to your building framework.


		If you would like to manually pick which plotly.js modules to include, you can create a custom bundle by using `plotly.js/lib/core`, and loading only the trace types that you need (e.g. `pie` or `choropleth`). The recommended way to do this is by creating a bundling file:
		If you would like to manually pick which plotly.js modules to include, you'll first need to run `npm install plotly.js` and then create a custom bundle by using `plotly.js/lib/core`, and loading only the trace types that you need (e.g. `pie` or `choropleth`). The recommended way to do this is by creating a bundling file. For example, in CommonJS:

NPM pkg for dist bundles #2670

NPM pkg for dist bundles #2670

Conversation

etpinard commented May 25, 2018 • edited Loading

etpinard commented May 25, 2018 • edited Loading

nicolaskruchten commented May 28, 2018

nicolaskruchten commented May 28, 2018

alexcjohnson commented May 29, 2018

etpinard commented May 29, 2018 • edited Loading

cpsievert commented May 29, 2018

nicolaskruchten commented May 29, 2018

etpinard commented May 29, 2018

cpsievert commented May 29, 2018 • edited Loading

etpinard commented May 29, 2018

etpinard commented May 29, 2018 • edited Loading

cpsievert commented May 29, 2018 • edited Loading

etpinard commented May 30, 2018 • edited Loading

alexcjohnson May 30, 2018

Choose a reason for hiding this comment

nicolaskruchten May 30, 2018

Choose a reason for hiding this comment

etpinard May 30, 2018

Choose a reason for hiding this comment

nicolaskruchten May 30, 2018

Choose a reason for hiding this comment

etpinard May 30, 2018 • edited Loading

Choose a reason for hiding this comment

nicolaskruchten commented May 30, 2018 • edited Loading

etpinard commented May 30, 2018

nicolaskruchten commented May 31, 2018

etpinard commented May 31, 2018

etpinard commented May 31, 2018

josemarluedke commented Jul 2, 2018

alexcjohnson commented Jul 2, 2018

etpinard commented May 25, 2018 •

edited

Loading

etpinard commented May 25, 2018 •

edited

Loading

etpinard commented May 29, 2018 •

edited

Loading

cpsievert commented May 29, 2018 •

edited

Loading

etpinard commented May 29, 2018 •

edited

Loading

cpsievert commented May 29, 2018 •

edited

Loading

etpinard commented May 30, 2018 •

edited

Loading

etpinard May 30, 2018 •

edited

Loading

nicolaskruchten commented May 30, 2018 •

edited

Loading