diff --git a/BUILDING.md b/BUILDING.md index 5f5e9299a86..c609c64c123 100644 --- 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 new file mode 100644 index 00000000000..68569ce1165 --- /dev/null +++ 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-.min.js` or `plotly-.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 index c171f68b5a6..c30c2b8f014 100644 --- a/README.md +++ b/README.md @@ -18,21 +18,19 @@ Plotly.js can be used to produce dozens of chart types and visualizations, inclu ## Table of contents -* [Quick start options](#quick-start-options) -* [Partial bundles](#partial-bundles) +* [Load from npm (Node.js Package Manager)](#load-from-npm-nodejs-package-manager) +* [Load from Content Delivery Network (CDN)](#load-from-content-delivery-network-cdn) +* [Bundles](#bundles) * [Alternative ways to require or build plotly.js](#alternative-ways-to-require-or-build-plotlyjs) -* [Bugs and feature requests](#bugs-and-feature-requests) * [Documentation](#documentation) +* [Bugs and feature requests](#bugs-and-feature-requests) * [Contributing](#contributing) -* [Community](#community) -* [Versioning](#versioning) -* [Notable contributors](#creators) +* [Notable contributors](#notable-contributors) * [Copyright and license](#copyright-and-license) +* [Community](#community) --- -## Quick start options - -### Install with npm +## Load from npm (Node.js Package Manager) ```sh npm install plotly.js-dist-min @@ -42,95 +40,66 @@ and import plotly.js as ```js import Plotly from 'plotly.js-dist-min' -// Or using require, +``` +Or +```js var Plotly = require('plotly.js-dist-min') ``` -### Use the plotly.js CDN hosted by Fastly +--- +## Load from Content Delivery Network (CDN) +Fastly supports Plotly.js with free CDN service. Read more at . -#### A minified plotly.js X.Y.Z release +### Usage example ```html - + + + + +
+ + + ``` +In the example above `Plotly` object is added to the window scope by the script in the `head` section. +The `newPlot` method is then used to draw an interactive figure as described by `data` and `layout` into the desired `div` here named `gd`. +As demonstrated in the example above basic knowledge of `html` and [JSON](https://en.wikipedia.org/wiki/JSON) syntax is enough to get started i.e. with/without JavaScript! +To learn and build more with plotly.js please visit [plotly.js documentation](https://plotly.com/javascript). -#### An un-minified version is also available +### Un-minified versions are also available on CDN +While non-minified source files may contain characters outside UTF-8, it is recommended that you specify the `charset` when loading those bundles. ```html - -``` - -and use the `Plotly` object in the window scope. - -##### Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version. - -Fastly supports Plotly.js with free CDN service. Read more at - -### Download the latest release or a release candidate (rc) - -[Latest and rc releases on GitHub](https://github.com/plotly/plotly.js/releases/) - -and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md). - -#### Read the [Getting started page](https://plotly.com/javascript/getting-started/) for more examples. - ---- -## Partial bundles - -There are two kinds of plotly.js partial bundles: -1. The official partial 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-.min.js` or `plotly-.js` if unminified. -```sh -npm run partial-bundle -- --out myBundleName -``` +> Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version. -Use the `unminified` option to disable compression. -```sh -npm run partial-bundle -- --unminified +### To support MathJax +Load relevant MathJax (v2) files *Before* the plotly.js script tag: +```html + + ``` -### 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 -``` +## 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 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 If your library needs to bundle or directly require [plotly.js/lib/index.js](https://github.com/plotly/plotly.js/blob/master/lib/index.js) or parts of its modules similar to [index-basic](https://github.com/plotly/plotly.js/blob/master/lib/index-basic.js) in some other way than via an official or a custom bundle, or in case you want to tweak the default build configurations of `browserify` or `webpack`, etc. then please visit [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.md). ---- -## Bugs and feature requests - -Have a bug or a feature request? Please [open a Github issue](https://github.com/plotly/plotly.js/issues/new) keeping in mind the [issue guidelines](https://github.com/plotly/plotly.js/blob/master/.github/ISSUE_TEMPLATE.md). You may also want to read about [how changes get made to Plotly.js](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md) - --- ## Documentation @@ -139,32 +108,16 @@ Official plotly.js documentation is hosted at [https://plotly.com/javascript](ht These pages are generated by the Plotly [graphing-library-docs repo](https://github.com/plotly/graphing-library-docs) built with [Jekyll](https://jekyllrb.com/) and publicly hosted on GitHub Pages. For more info about contributing to Plotly documentation, please read through [contributing guidelines](https://github.com/plotly/graphing-library-docs/blob/master/README.md). -### To support MathJax -Load relevant MathJax (v2) files *Before* the plotly.js script tag: -```html - - -``` - --- -## Contributing - -Please read through our [contributing guidelines](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md). Included are directions for opening issues, using plotly.js in your project and notes on development. +## Bugs and feature requests ---- -## Community +Have a bug or a feature request? Please [open a Github issue](https://github.com/plotly/plotly.js/issues/new) keeping in mind the [issue guidelines](https://github.com/plotly/plotly.js/blob/master/.github/ISSUE_TEMPLATE.md). You may also want to read about [how changes get made to Plotly.js](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md) -* Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news. -* Implementation help may be found on community.plot.com (tagged [`plotly-js`](https://community.plotly.com/c/plotly-js)) or - on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)). -* Developers should use the keyword `plotly` on packages which modify or add to the functionality of plotly.js when distributing through [npm](https://www.npmjs.com/browse/keyword/plotly). --- -## Versioning - -This project is maintained under the [Semantic Versioning guidelines](https://semver.org/). +## Contributing -See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js. +Please read through our [contributing guidelines](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md). Included are directions for opening issues, using plotly.js in your project and notes on development. --- ## Notable contributors @@ -197,3 +150,17 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors Code and documentation copyright 2021 Plotly, Inc. Code released under the [MIT license](https://github.com/plotly/plotly.js/blob/master/LICENSE). + +### Versioning + +This project is maintained under the [Semantic Versioning guidelines](https://semver.org/). + +See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js. + +--- +## Community + +* Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news. +* Implementation help may be found on community.plot.com (tagged [`plotly-js`](https://community.plotly.com/c/plotly-js)) or + on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)). +* Developers should use the keyword `plotly` on packages which modify or add to the functionality of plotly.js when distributing through [npm](https://www.npmjs.com/browse/keyword/plotly). diff --git a/dist/README.md b/dist/README.md index 5e517f49beb..557f925f1ff 100644 --- a/dist/README.md +++ b/dist/README.md @@ -1,6 +1,6 @@ # Using distributed files -All plotly.js dist bundles inject an object `Plotly` into the global scope. +All plotly.js bundles inject an object `Plotly` into the global scope. Import plotly.js as: @@ -37,29 +37,34 @@ Plotly.newPlot(graphDiv, data, layout, {locale: 'de-CH'}) # Bundle information -The main plotly.js bundle includes all the official (non-beta) trace modules. +The main plotly.js bundle includes all trace modules. -It be can imported as minified javascript -- using dist file `dist/plotly.min.js` -- using CDN URL https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js - -or as raw javascript: -- using the `plotly.js-dist` npm package (starting in `v1.39.0`) -- using dist file `dist/plotly.js` -- using CDN URL https://cdn.plot.ly/plotly-2.0.0-rc.2.js -- using CommonJS with `require('plotly.js')` - -If you would like to have access to the attribute meta information (including attribute descriptions as on the [schema reference page](https://plotly.com/javascript/reference/)), use dist file `dist/plotly-with-meta.js` - -The main plotly.js bundle weights in at: +The main plotly.js bundles weight in at: | plotly.js | plotly.min.js | plotly.min.js + gzip | plotly-with-meta.js | |-----------|---------------|----------------------|---------------------| | 7.9 MB | 3.3 MB | 1015.1 kB | 8.2 MB | +#### CDN links +> https://cdn.plot.ly/plotly-2.0.0-rc.2.js + +> https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js + + +#### npm packages +> [plotly.js](https://www.npmjs.com/package/plotly.js) + +> [plotly.js-dist](https://www.npmjs.com/package/plotly.js-dist) + +> [plotly.js-dist-min](https://www.npmjs.com/package/plotly.js-dist-min) + +#### Meta information +> If you would like to have access to the attribute meta information (including attribute descriptions as on the [schema reference page](https://plotly.com/javascript/reference/)), use dist file `dist/plotly-with-meta.js` +--- + ## Partial bundles -Starting in `v1.15.0`, plotly.js also ships with several _partial_ bundles: +plotly.js also ships with several _partial_ bundles: - [basic](#plotlyjs-basic) - [cartesian](#plotlyjs-cartesian) @@ -70,13 +75,13 @@ Starting in `v1.15.0`, plotly.js also ships with several _partial_ bundles: - [finance](#plotlyjs-finance) - [strict](#plotlyjs-strict) -Starting in `v1.39.0`, each plotly.js partial bundle has a corresponding npm package with no dependencies. +> Each plotly.js partial bundle has a corresponding npm package with no dependencies. + +> The minified version of each partial bundle is also published to npm in a separate "dist-min" package. -Starting in `v1.50.0`, the minified version of each partial bundle is also published to npm in a separate "dist min" package. +> The strict partial bundle includes everything except the traces that require function constructors. Over time we hope to include more of the remaining trace types here, after which we intend to work on other strict CSP issues such as inline CSS that we may not be able to include in the main bundle. -Starting in `v2.0.0`, the strict partial bundle includes everything except the traces that require function constructors. -Over time we hope to include more of the remaining trace types here, after which we intend to work on other strict CSP issues -such as inline CSS that we may not be able to include in the main bundle. +--- ### plotly.js basic @@ -89,45 +94,17 @@ The `basic` partial bundle contains trace modules `bar`, `pie` and `scatter`. | 2.7 MB | 1003.6 kB | 325.9 kB | #### CDN links +> https://cdn.plot.ly/plotly-basic-2.0.0-rc.2.js -| Flavor | URL | -| ------ | --- | -| Tagged | https://cdn.plot.ly/plotly-basic-2.0.0-rc.2.js | -| Tagged minified | https://cdn.plot.ly/plotly-basic-2.0.0-rc.2.min.js | +> https://cdn.plot.ly/plotly-basic-2.0.0-rc.2.min.js -#### npm package (starting in `v1.39.0`) -Install [`plotly.js-basic-dist`](https://www.npmjs.com/package/plotly.js-basic-dist) with -``` -npm install plotly.js-basic-dist -``` +#### npm packages +> [plotly.js-basic-dist](https://www.npmjs.com/package/plotly.js-basic-dist) -ES6 module usage: -```js -import Plotly from 'plotly.js-basic-dist' -``` - -CommonJS usage: -```js -var Plotly = require('plotly.js-basic-dist'); -``` - -#### dist min npm package (starting in `v1.50.0`) - -Install [`plotly.js-basic-dist-min`](https://www.npmjs.com/package/plotly.js-basic-dist-min) with -``` -npm install plotly.js-basic-dist-min -``` - -#### Other plotly.js entry points - -| Flavor | Location | -|---------------|----------| -| dist bundle | `dist/plotly-basic.js` | -| dist bundle (minified) | `dist/plotly-basic.min.js` | -| ES6 module | `import Plotly from 'plotly.js/lib/index-basic'` | -| CommonJS | `require('plotly.js/lib/index-basic')` | +> [plotly.js-basic-dist-min](https://www.npmjs.com/package/plotly.js-basic-dist-min) +--- ### plotly.js cartesian @@ -140,45 +117,17 @@ The `cartesian` partial bundle contains trace modules `bar`, `box`, `contour`, ` | 3.3 MB | 1.2 MB | 397.1 kB | #### CDN links +> https://cdn.plot.ly/plotly-cartesian-2.0.0-rc.2.js -| Flavor | URL | -| ------ | --- | -| Tagged | https://cdn.plot.ly/plotly-cartesian-2.0.0-rc.2.js | -| Tagged minified | https://cdn.plot.ly/plotly-cartesian-2.0.0-rc.2.min.js | - -#### npm package (starting in `v1.39.0`) - -Install [`plotly.js-cartesian-dist`](https://www.npmjs.com/package/plotly.js-cartesian-dist) with -``` -npm install plotly.js-cartesian-dist -``` - -ES6 module usage: -```js -import Plotly from 'plotly.js-cartesian-dist' -``` - -CommonJS usage: -```js -var Plotly = require('plotly.js-cartesian-dist'); -``` +> https://cdn.plot.ly/plotly-cartesian-2.0.0-rc.2.min.js -#### dist min npm package (starting in `v1.50.0`) -Install [`plotly.js-cartesian-dist-min`](https://www.npmjs.com/package/plotly.js-cartesian-dist-min) with -``` -npm install plotly.js-cartesian-dist-min -``` +#### npm packages +> [plotly.js-cartesian-dist](https://www.npmjs.com/package/plotly.js-cartesian-dist) -#### Other plotly.js entry points - -| Flavor | Location | -|---------------|----------| -| dist bundle | `dist/plotly-cartesian.js` | -| dist bundle (minified) | `dist/plotly-cartesian.min.js` | -| ES6 module | `import Plotly from 'plotly.js/lib/index-cartesian'` | -| CommonJS | `require('plotly.js/lib/index-cartesian')` | +> [plotly.js-cartesian-dist-min](https://www.npmjs.com/package/plotly.js-cartesian-dist-min) +--- ### plotly.js geo @@ -191,45 +140,17 @@ The `geo` partial bundle contains trace modules `choropleth`, `scatter` and `sca | 2.8 MB | 1 MB | 335.7 kB | #### CDN links +> https://cdn.plot.ly/plotly-geo-2.0.0-rc.2.js -| Flavor | URL | -| ------ | --- | -| Tagged | https://cdn.plot.ly/plotly-geo-2.0.0-rc.2.js | -| Tagged minified | https://cdn.plot.ly/plotly-geo-2.0.0-rc.2.min.js | +> https://cdn.plot.ly/plotly-geo-2.0.0-rc.2.min.js -#### npm package (starting in `v1.39.0`) -Install [`plotly.js-geo-dist`](https://www.npmjs.com/package/plotly.js-geo-dist) with -``` -npm install plotly.js-geo-dist -``` +#### npm packages +> [plotly.js-geo-dist](https://www.npmjs.com/package/plotly.js-geo-dist) -ES6 module usage: -```js -import Plotly from 'plotly.js-geo-dist' -``` - -CommonJS usage: -```js -var Plotly = require('plotly.js-geo-dist'); -``` - -#### dist min npm package (starting in `v1.50.0`) - -Install [`plotly.js-geo-dist-min`](https://www.npmjs.com/package/plotly.js-geo-dist-min) with -``` -npm install plotly.js-geo-dist-min -``` - -#### Other plotly.js entry points - -| Flavor | Location | -|---------------|----------| -| dist bundle | `dist/plotly-geo.js` | -| dist bundle (minified) | `dist/plotly-geo.min.js` | -| ES6 module | `import Plotly from 'plotly.js/lib/index-geo'` | -| CommonJS | `require('plotly.js/lib/index-geo')` | +> [plotly.js-geo-dist-min](https://www.npmjs.com/package/plotly.js-geo-dist-min) +--- ### plotly.js gl3d @@ -242,45 +163,17 @@ The `gl3d` partial bundle contains trace modules `cone`, `isosurface`, `mesh3d`, | 3.8 MB | 1.5 MB | 481.3 kB | #### CDN links +> https://cdn.plot.ly/plotly-gl3d-2.0.0-rc.2.js -| Flavor | URL | -| ------ | --- | -| Tagged | https://cdn.plot.ly/plotly-gl3d-2.0.0-rc.2.js | -| Tagged minified | https://cdn.plot.ly/plotly-gl3d-2.0.0-rc.2.min.js | - -#### npm package (starting in `v1.39.0`) - -Install [`plotly.js-gl3d-dist`](https://www.npmjs.com/package/plotly.js-gl3d-dist) with -``` -npm install plotly.js-gl3d-dist -``` - -ES6 module usage: -```js -import Plotly from 'plotly.js-gl3d-dist' -``` - -CommonJS usage: -```js -var Plotly = require('plotly.js-gl3d-dist'); -``` - -#### dist min npm package (starting in `v1.50.0`) +> https://cdn.plot.ly/plotly-gl3d-2.0.0-rc.2.min.js -Install [`plotly.js-gl3d-dist-min`](https://www.npmjs.com/package/plotly.js-gl3d-dist-min) with -``` -npm install plotly.js-gl3d-dist-min -``` -#### Other plotly.js entry points +#### npm packages +> [plotly.js-gl3d-dist](https://www.npmjs.com/package/plotly.js-gl3d-dist) -| Flavor | Location | -|---------------|----------| -| dist bundle | `dist/plotly-gl3d.js` | -| dist bundle (minified) | `dist/plotly-gl3d.min.js` | -| ES6 module | `import Plotly from 'plotly.js/lib/index-gl3d'` | -| CommonJS | `require('plotly.js/lib/index-gl3d')` | +> [plotly.js-gl3d-dist-min](https://www.npmjs.com/package/plotly.js-gl3d-dist-min) +--- ### plotly.js gl2d @@ -293,45 +186,17 @@ The `gl2d` partial bundle contains trace modules `heatmapgl`, `parcoords`, `poin | 3.8 MB | 1.5 MB | 501.8 kB | #### CDN links +> https://cdn.plot.ly/plotly-gl2d-2.0.0-rc.2.js -| Flavor | URL | -| ------ | --- | -| Tagged | https://cdn.plot.ly/plotly-gl2d-2.0.0-rc.2.js | -| Tagged minified | https://cdn.plot.ly/plotly-gl2d-2.0.0-rc.2.min.js | +> https://cdn.plot.ly/plotly-gl2d-2.0.0-rc.2.min.js -#### npm package (starting in `v1.39.0`) -Install [`plotly.js-gl2d-dist`](https://www.npmjs.com/package/plotly.js-gl2d-dist) with -``` -npm install plotly.js-gl2d-dist -``` +#### npm packages +> [plotly.js-gl2d-dist](https://www.npmjs.com/package/plotly.js-gl2d-dist) -ES6 module usage: -```js -import Plotly from 'plotly.js-gl2d-dist' -``` - -CommonJS usage: -```js -var Plotly = require('plotly.js-gl2d-dist'); -``` - -#### dist min npm package (starting in `v1.50.0`) - -Install [`plotly.js-gl2d-dist-min`](https://www.npmjs.com/package/plotly.js-gl2d-dist-min) with -``` -npm install plotly.js-gl2d-dist-min -``` - -#### Other plotly.js entry points - -| Flavor | Location | -|---------------|----------| -| dist bundle | `dist/plotly-gl2d.js` | -| dist bundle (minified) | `dist/plotly-gl2d.min.js` | -| ES6 module | `import Plotly from 'plotly.js/lib/index-gl2d'` | -| CommonJS | `require('plotly.js/lib/index-gl2d')` | +> [plotly.js-gl2d-dist-min](https://www.npmjs.com/package/plotly.js-gl2d-dist-min) +--- ### plotly.js mapbox @@ -344,45 +209,17 @@ The `mapbox` partial bundle contains trace modules `choroplethmapbox`, `densitym | 4.3 MB | 1.7 MB | 523.4 kB | #### CDN links +> https://cdn.plot.ly/plotly-mapbox-2.0.0-rc.2.js -| Flavor | URL | -| ------ | --- | -| Tagged | https://cdn.plot.ly/plotly-mapbox-2.0.0-rc.2.js | -| Tagged minified | https://cdn.plot.ly/plotly-mapbox-2.0.0-rc.2.min.js | - -#### npm package (starting in `v1.39.0`) - -Install [`plotly.js-mapbox-dist`](https://www.npmjs.com/package/plotly.js-mapbox-dist) with -``` -npm install plotly.js-mapbox-dist -``` - -ES6 module usage: -```js -import Plotly from 'plotly.js-mapbox-dist' -``` - -CommonJS usage: -```js -var Plotly = require('plotly.js-mapbox-dist'); -``` - -#### dist min npm package (starting in `v1.50.0`) +> https://cdn.plot.ly/plotly-mapbox-2.0.0-rc.2.min.js -Install [`plotly.js-mapbox-dist-min`](https://www.npmjs.com/package/plotly.js-mapbox-dist-min) with -``` -npm install plotly.js-mapbox-dist-min -``` -#### Other plotly.js entry points +#### npm packages +> [plotly.js-mapbox-dist](https://www.npmjs.com/package/plotly.js-mapbox-dist) -| Flavor | Location | -|---------------|----------| -| dist bundle | `dist/plotly-mapbox.js` | -| dist bundle (minified) | `dist/plotly-mapbox.min.js` | -| ES6 module | `import Plotly from 'plotly.js/lib/index-mapbox'` | -| CommonJS | `require('plotly.js/lib/index-mapbox')` | +> [plotly.js-mapbox-dist-min](https://www.npmjs.com/package/plotly.js-mapbox-dist-min) +--- ### plotly.js finance @@ -395,45 +232,17 @@ The `finance` partial bundle contains trace modules `bar`, `candlestick`, `funne | 2.9 MB | 1.1 MB | 352 kB | #### CDN links +> https://cdn.plot.ly/plotly-finance-2.0.0-rc.2.js -| Flavor | URL | -| ------ | --- | -| Tagged | https://cdn.plot.ly/plotly-finance-2.0.0-rc.2.js | -| Tagged minified | https://cdn.plot.ly/plotly-finance-2.0.0-rc.2.min.js | - -#### npm package (starting in `v1.39.0`) +> https://cdn.plot.ly/plotly-finance-2.0.0-rc.2.min.js -Install [`plotly.js-finance-dist`](https://www.npmjs.com/package/plotly.js-finance-dist) with -``` -npm install plotly.js-finance-dist -``` -ES6 module usage: -```js -import Plotly from 'plotly.js-finance-dist' -``` - -CommonJS usage: -```js -var Plotly = require('plotly.js-finance-dist'); -``` - -#### dist min npm package (starting in `v1.50.0`) - -Install [`plotly.js-finance-dist-min`](https://www.npmjs.com/package/plotly.js-finance-dist-min) with -``` -npm install plotly.js-finance-dist-min -``` +#### npm packages +> [plotly.js-finance-dist](https://www.npmjs.com/package/plotly.js-finance-dist) -#### Other plotly.js entry points - -| Flavor | Location | -|---------------|----------| -| dist bundle | `dist/plotly-finance.js` | -| dist bundle (minified) | `dist/plotly-finance.min.js` | -| ES6 module | `import Plotly from 'plotly.js/lib/index-finance'` | -| CommonJS | `require('plotly.js/lib/index-finance')` | +> [plotly.js-finance-dist-min](https://www.npmjs.com/package/plotly.js-finance-dist-min) +--- ### plotly.js strict @@ -446,46 +255,17 @@ The `strict` partial bundle contains trace modules `bar`, `barpolar`, `box`, `ca | 6.6 MB | 2.8 MB | 835.8 kB | #### CDN links +> https://cdn.plot.ly/plotly-strict-2.0.0-rc.2.js -| Flavor | URL | -| ------ | --- | -| Tagged | https://cdn.plot.ly/plotly-strict-2.0.0-rc.2.js | -| Tagged minified | https://cdn.plot.ly/plotly-strict-2.0.0-rc.2.min.js | - -#### npm package (starting in `v1.39.0`) - -Install [`plotly.js-strict-dist`](https://www.npmjs.com/package/plotly.js-strict-dist) with -``` -npm install plotly.js-strict-dist -``` - -ES6 module usage: -```js -import Plotly from 'plotly.js-strict-dist' -``` - -CommonJS usage: -```js -var Plotly = require('plotly.js-strict-dist'); -``` +> https://cdn.plot.ly/plotly-strict-2.0.0-rc.2.min.js -#### dist min npm package (starting in `v1.50.0`) - -Install [`plotly.js-strict-dist-min`](https://www.npmjs.com/package/plotly.js-strict-dist-min) with -``` -npm install plotly.js-strict-dist-min -``` -#### Other plotly.js entry points +#### npm packages +> [plotly.js-strict-dist](https://www.npmjs.com/package/plotly.js-strict-dist) -| Flavor | Location | -|---------------|----------| -| dist bundle | `dist/plotly-strict.js` | -| dist bundle (minified) | `dist/plotly-strict.min.js` | -| ES6 module | `import Plotly from 'plotly.js/lib/index-strict'` | -| CommonJS | `require('plotly.js/lib/index-strict')` | +> [plotly.js-strict-dist-min](https://www.npmjs.com/package/plotly.js-strict-dist-min) +--- ----------------- _This file is auto-generated by `npm run stats`. Please do not edit this file directly._ \ No newline at end of file diff --git a/tasks/stats.js b/tasks/stats.js index cea205f45c2..0a65b42517a 100644 --- a/tasks/stats.js +++ b/tasks/stats.js @@ -34,7 +34,7 @@ function getInfoContent() { return [ '# Using distributed files', '', - 'All plotly.js dist bundles inject an object `Plotly` into the global scope.', + 'All plotly.js bundles inject an object `Plotly` into the global scope.', '', 'Import plotly.js as:', '', @@ -83,54 +83,64 @@ function getMainBundleInfo() { return [ '# Bundle information', '', - 'The main plotly.js bundle includes all the official (non-beta) trace modules.', + 'The main plotly.js bundle includes all trace modules.', '', - 'It be can imported as minified javascript', - '- using dist file `dist/plotly.min.js`', - '- using CDN URL ' + cdnRoot + pkgVersion + MINJS, - '', - 'or as raw javascript:', - '- using the `plotly.js-dist` npm package (starting in `v1.39.0`)', - '- using dist file `dist/plotly.js`', - '- using CDN URL ' + cdnRoot + pkgVersion + JS, - '- using CommonJS with `require(\'plotly.js\')`', - '', - 'If you would like to have access to the attribute meta information ' + - '(including attribute descriptions as on the [schema reference page](https://plotly.com/javascript/reference/)), ' + - 'use dist file `dist/plotly-with-meta.js`', - '', - 'The main plotly.js bundle weights in at:', + 'The main plotly.js bundles weight in at:', '', '| plotly.js | plotly.min.js | plotly.min.js + gzip | plotly-with-meta.js |', '|-----------|---------------|----------------------|---------------------|', '| ' + mainSizes.raw + ' | ' + mainSizes.minified + ' | ' + mainSizes.gzipped + ' | ' + mainSizes.withMeta + ' |', '', + '#### CDN links', + '> ' + cdnRoot + pkgVersion + JS, + '', + '> ' + cdnRoot + pkgVersion + MINJS, + '', + '', + '#### npm packages', + '> ' + createLink('https://www.npmjs.com/package/', 'plotly.js'), + '', + '> ' + createLink('https://www.npmjs.com/package/', 'plotly.js-dist'), + '', + '> ' + createLink('https://www.npmjs.com/package/', 'plotly.js-dist-min'), + '', + '#### Meta information', + [ + '> If you would like to have access to the attribute meta information', + '(including attribute descriptions as on the [schema reference page](https://plotly.com/javascript/reference/)),', + 'use dist file `dist/plotly-with-meta.js`' + ].join(' '), + '---', + '', '## Partial bundles', '', - 'Starting in `v1.15.0`, plotly.js also ships with several _partial_ bundles:', + 'plotly.js also ships with several _partial_ bundles:', '', partialBundlePaths.map(makeBundleHeaderInfo).join('\n'), '', - 'Starting in `v1.39.0`, each plotly.js partial bundle has a corresponding npm package with no dependencies.', + '> Each plotly.js partial bundle has a corresponding npm package with no dependencies.', '', - 'Starting in `v1.50.0`, the minified version of each partial bundle is also published to npm in a separate "dist min" package.', + '> The minified version of each partial bundle is also published to npm in a separate "dist-min" package.', '', - 'Starting in `v2.0.0`, the strict partial bundle includes everything except the traces that require function constructors.', - 'Over time we hope to include more of the remaining trace types here, after which we intend to work on other strict CSP issues ', - 'such as inline CSS that we may not be able to include in the main bundle.', + [ + '> The strict partial bundle includes everything except the traces that require function constructors.', + 'Over time we hope to include more of the remaining trace types here, after which we intend to work on other strict CSP issues', + 'such as inline CSS that we may not be able to include in the main bundle.', + ].join(' '), + '', + '---', '' ]; } // info about partial bundles function getPartialBundleInfo() { - return partialBundlePaths.map(makeBundleInfo); + return partialBundlePaths.map(distBundleInfo); } // footer info function getFooter() { return [ - '----------------', '', '_This file is auto-generated by `npm run stats`. ' + 'Please do not edit this file directly._' @@ -142,11 +152,16 @@ function makeBundleHeaderInfo(pathObj) { return '- [' + name + '](#plotlyjs-' + name + ')'; } -function makeBundleInfo(pathObj) { +function createLink(base, name) { + return '[' + name + '](' + base + name + ')'; +} + +function distBundleInfo(pathObj) { var name = pathObj.name; var sizes = findSizes(pathObj); var traceList = pathObj.traceList; - var pkgName = 'plotly.js-' + name + '-dist'; + var nameDist = 'plotly.js-' + name + '-dist'; + var nameVersion = name + '-' + pkgVersion; return [ '### plotly.js ' + name, @@ -160,45 +175,17 @@ function makeBundleInfo(pathObj) { '| ' + sizes.raw + ' | ' + sizes.minified + ' | ' + sizes.gzipped + ' |', '', '#### CDN links', + '> ' + cdnRoot + nameVersion + JS, '', - '| Flavor | URL |', - '| ------ | --- |', - '| Tagged | ' + cdnRoot + name + '-' + pkgVersion + JS + ' |', - '| Tagged minified | ' + cdnRoot + name + '-' + pkgVersion + MINJS + ' |', + '> ' + cdnRoot + nameVersion + MINJS, '', - '#### npm package (starting in `v1.39.0`)', - '', - 'Install [`' + pkgName + '`](https://www.npmjs.com/package/' + pkgName + ') with', - '```', - 'npm install ' + pkgName, - '```', - '', - 'ES6 module usage:', - '```js', - 'import Plotly from \'' + pkgName + '\'', - '```', - '', - 'CommonJS usage:', - '```js', - 'var Plotly = require(\'' + pkgName + '\');', - '```', - '', - '#### dist min npm package (starting in `v1.50.0`)', - '', - 'Install [`' + pkgName + '-min`](https://www.npmjs.com/package/' + pkgName + '-min) with', - '```', - 'npm install ' + pkgName + '-min', - '```', '', - '#### Other plotly.js entry points', + '#### npm packages', + '> ' + createLink('https://www.npmjs.com/package/', nameDist), '', - '| Flavor | Location |', - '|---------------|----------|', - '| dist bundle | ' + '`dist/plotly-' + name + JS + '` |', - '| dist bundle (minified) | ' + '`dist/plotly-' + name + MINJS + '` |', - '| ES6 module | ' + '`import Plotly from \'plotly.js/lib/' + 'index-' + name + '\'`' + ' |', - '| CommonJS | ' + '`require(\'plotly.js/lib/' + 'index-' + name + '\')`' + ' |', + '> ' + createLink('https://www.npmjs.com/package/', nameDist + '-min'), '', + '---', '' ].join('\n'); } diff --git a/tasks/test_syntax.js b/tasks/test_syntax.js index f6983905f30..f3eb68f7dcc 100644 --- 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;