diff --git a/BUILDING.md b/BUILDING.md index 5e0a06efcc0..5f5e9299a86 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -1,6 +1,24 @@ -# Building plotly.js +# 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. -The easiest way to bundle plotly.js into your application is to use 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. +## Browserify example + +Given source file: +```js +// file: index.js +var Plotly = require('plotly.js-dist-min'); +// .... +``` + +then simply run + +```sh +browserify index.js > bundle.js +``` + + + +The sections below provide additional info in respect to alternative building frameworks. ## Webpack @@ -21,24 +39,6 @@ A repo that demonstrates how to build plotly.js with Webpack can be found [here] ... ``` -## Browserify - -Given source file: - -```js -// file: index.js - -var Plotly = require('plotly.js'); - -// .... -``` - -then simply run, - -``` -browserify index.js > bundle.js -``` - ## 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. diff --git a/README.md b/README.md index 7fa62ad4331..c171f68b5a6 100644 --- a/README.md +++ b/README.md @@ -19,29 +19,31 @@ Plotly.js can be used to produce dozens of chart types and visualizations, inclu ## Table of contents * [Quick start options](#quick-start-options) -* [Modules](#modules) -* [Building plotly.js](#building-plotlyjs) +* [Partial bundles](#partial-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) * [Contributing](#contributing) * [Community](#community) -* [Notable Contributors](#creators) +* [Versioning](#versioning) +* [Notable contributors](#creators) * [Copyright and license](#copyright-and-license) +--- ## Quick start options ### Install with npm ```sh -npm install plotly.js-dist +npm install plotly.js-dist-min ``` and import plotly.js as ```js -import Plotly from 'plotly.js-dist' +import Plotly from 'plotly.js-dist-min' // Or using require, -var Plotly = require('plotly.js-dist') +var Plotly = require('plotly.js-dist-min') ``` ### Use the plotly.js CDN hosted by Fastly @@ -70,6 +72,7 @@ and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly #### 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: @@ -77,7 +80,7 @@ There are two kinds of plotly.js partial bundles: 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. @@ -85,29 +88,29 @@ Please note that the `scatter` trace is currently included in all bundles and ca 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 ``` 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 \ @@ -115,18 +118,20 @@ npm run partial-bundle -- \ --transforms none ``` Or simply on one line: -``` +```sh npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none ``` -## Building plotly.js - -Building instructions using `webpack`, `browserify` and other build frameworks are in [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.md) +--- +## 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 Official plotly.js documentation is hosted at [https://plotly.com/javascript](https://plotly.com/javascript). @@ -134,10 +139,19 @@ 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. +--- ## Community * Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news. @@ -145,13 +159,15 @@ Please read through our [contributing guidelines](https://github.com/plotly/plot 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/). See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js. -## Notable Contributors +--- +## Notable contributors Plotly.js is at the core of a large and dynamic ecosystem with many contributors who file issues, reproduce bugs, suggest improvements, write code in this repo (and other upstream or downstream ones) and help users in the Plotly community forum. The following people deserve special recognition for their outsized contributions to this ecosystem: @@ -160,7 +176,7 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors |**Alex C. Johnson**| [@alexcjohnson](https://github.com/alexcjohnson) | | Active, Maintainer | |**Mojtaba Samimi** | [@archmoj](https://github.com/archmoj) | [@solarchvision](https://twitter.com/solarchvision) | Active, Maintainer | |**Antoine Roy-Gobeil** | [@antoinerg](https://github.com/antoinerg) | | Active, Maintainer | -|**Nicolas Kruchten** | [@nicolaskruchten](https://github.com/nicolaskruchten) | [@nicolaskruchten](https://twitter.com/nicolaskruchten) | Active | +|**Nicolas Kruchten** | [@nicolaskruchten](https://github.com/nicolaskruchten) | [@nicolaskruchten](https://twitter.com/nicolaskruchten) | Active, Maintainer | |**Jon Mease** | [@jonmmease](https://github.com/jonmmease) | [@jonmmease](https://twitter.com/jonmmease) | Active | |**Étienne Tétreault-Pinard**| [@etpinard](https://github.com/etpinard) | [@etpinard](https://twitter.com/etpinard) | Hall of Fame | |**Mikola Lysenko**| [@mikolalysenko](https://github.com/mikolalysenko) | [@MikolaLysenko](https://twitter.com/MikolaLysenko) | Hall of Fame | @@ -175,6 +191,7 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors |**Chris Parmer**| [@chriddyp](https://github.com/chriddyp) | | Hall of Fame | |**Alex Vados**| [@alexander-daniel](https://github.com/alexander-daniel) | | Hall of Fame | +--- ## Copyright and license Code and documentation copyright 2021 Plotly, Inc.