add CUSTOM_BUNDLE file, how to install deps, more edits

plotly · Jun 3, 2021 · d6b5498ba74636fea93a2da813413acdb270618f · d6b5498
1 parent a2bccfd
commit d6b5498ba74636fea93a2da813413acdb270618f
Showing with 64 additions and 49 deletions.

+6 −5 BUILDING.md

+56 −0 CUSTOM_BUNDLE.md

+1 −44 README.md

+1 −0 tasks/test_syntax.js
diff --git a/BUILDING.md b/BUILDING.md
@@ -1,5 +1,7 @@
 # Alternative ways to require or build plotly.js
-Depending on your needs, to bundle plotly.js into your application one of [the browserified distributed plotly.js packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) on npm could be used.
+Depending on your needs you may require/import one of [the distributed plotly.js packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) or [a plotly.js/lib index file](https://github.com/plotly/plotly.js/tree/master/lib) and integrate it into your application.
+
+The sections below provide additional info in respect to alternative building frameworks.
 
 ## Browserify example
 
@@ -16,10 +18,7 @@ then simply run
 browserify index.js > bundle.js
 ```
 
-
-
-The sections below provide additional info in respect to alternative building frameworks.
-
+---
 ## Webpack
 
 For plotly.js to build with Webpack you will need to install [ify-loader@v1.1.0+](https://github.com/hughsk/ify-loader) and add it to your `webpack.config.json`. This adds Browserify transform compatibility to Webpack which is necessary for some plotly.js dependencies.
@@ -39,6 +38,7 @@ A repo that demonstrates how to build plotly.js with Webpack can be found [here]
 ...
 ```
 
+---
 ## Angular CLI
 
 Since Angular uses webpack under the hood and doesn't allow easily to change it's webpack configuration, there is some work needed using a `custom-webpack` builder to get things going.
@@ -99,3 +99,4 @@ module.exports = {
 
 It's important to set `projects.x.architect.build.builder` and `projects.x.architect.build.options.customWebpackConfig`.
 If you have more projects in your `angular.json` make sure to adjust their settings accordingly.
+---
diff --git a/CUSTOM_BUNDLE.md b/CUSTOM_BUNDLE.md
@@ -0,0 +1,56 @@
+# Custom bundle
+You can simply make custom bundles yourself, if none of the [distributed packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) meet your needs, or you want to make a more optimized bundle file with/without specific traces and transforms.
+
+Install plotly.js, move to plotly.js folder then install plotly.js dependencies:
+```sh
+npm i plotly.js@2.0.0-rc.2
+cd node_modules/plotly.js
+npm i
+```
+
+By default all traces and transforms are included in the bundle if you simply run:
+```sh
+npm run partial-bundle
+```
+
+Use the `traces` option to include just the trace types you need.
+```sh
+npm run partial-bundle -- --traces scatter,scattergl,scatter3d
+```
+Please note that the `scatter` trace is currently included in all bundles and cannot be removed.
+[This behaviour may change in the future](https://github.com/plotly/plotly.js/pull/5535), so we recommend that you explicitly include `scatter` anyway if you need it in your bundle.
+
+Use the `transforms` option to specify which should be included.
+```sh
+npm run partial-bundle -- --transforms sort,filter
+```
+
+Or use `transforms none` to exclude them all.
+```sh
+npm run partial-bundle -- --transforms none
+```
+
+Use the `out` option to change the bundle filename (default `custom`).
+The new bundle will be created in the `dist/` directory and named `plotly-<out>.min.js` or `plotly-<out>.js` if unminified.
+```sh
+npm run partial-bundle -- --out myBundleName
+```
+
+Use the `unminified` option to disable compression.
+```sh
+npm run partial-bundle -- --unminified
+```
+
+# Example illustrating use of different options together
+To create an unminified custom bundle named `myScatters` including `scatter`, `scattergl` and `scatter3d` traces without any transforms:
+```sh
+npm run partial-bundle -- \
+    --unminified \
+    --out myScatters \
+    --traces scatter,scattergl,scatter3d \
+    --transforms none
+```
+Or simply on one line:
+```sh
+npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none
+```
diff --git a/README.md b/README.md
@@ -94,50 +94,7 @@ Load relevant MathJax (v2) files *Before* the plotly.js script tag:
 ## Bundles
 There are two kinds of plotly.js bundles:
 1. Complete and partial official bundles that are distributed to `npm` and the `CDN`, described in [the dist README](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
-2. Custom bundles you can create yourself, if none of the distributed packages meet your needs.
-
-Use the `traces` option to include just the trace types you need.
-```sh
-npm run partial-bundle -- --traces scatter,scattergl,scatter3d
-```
-Please note that the `scatter` trace is currently included in all bundles and cannot be removed.
-[This behaviour may change in the future](https://github.com/plotly/plotly.js/pull/5535), so we recommend that you explicitly include `scatter` anyway if you need it in your bundle.
-
-By default all transforms are included in the bundle.
-Use the `transforms` option to specify which should be included.
-```sh
-npm run partial-bundle -- --transforms sort,filter
-```
-
-Or use `transforms none` to exclude them all.
-```sh
-npm run partial-bundle -- --transforms none
-```
-
-Use the `out` option to change the bundle filename (default `custom`).
-The new bundle will be created in the `dist/` directory and named `plotly-<out>.min.js` or `plotly-<out>.js` if unminified.
-```sh
-npm run partial-bundle -- --out myBundleName
-```
-
-Use the `unminified` option to disable compression.
-```sh
-npm run partial-bundle -- --unminified
-```
-
-### Example illustrating use of different options together
-To create an unminified custom bundle named `myScatters` including `scatter`, `scattergl` and `scatter3d` traces without any transforms:
-```sh
-npm run partial-bundle -- \
-    --unminified \
-    --out myScatters \
-    --traces scatter,scattergl,scatter3d \
-    --transforms none
-```
-Or simply on one line:
-```sh
-npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none
-```
+2. Custom bundles you can create yourself to optimize the size of bundle depending on your needs. Please visit [CUSTOM_BUNDLE](https://github.com/plotly/plotly.js/blob/master/CUSTOM_BUNDLE.md) for more information.
 
 ---
 ## Alternative ways to require or build plotly.js

diff --git a/tasks/test_syntax.js b/tasks/test_syntax.js
@@ -227,6 +227,7 @@ function assertFileNames() {
                 base === 'CHANGELOG.md' ||
                 base === 'SECURITY.md' ||
                 base === 'BUILDING.md' ||
+                base === 'CUSTOM_BUNDLE.md' ||
                 file.indexOf('mathjax') !== -1
             ) return;