Skip to content

Commit 5de384c

Browse files
etpinardetpinard
authored
Merge pull request #2670 from etpinard/npm-pkgs-for-dist-bundles
NPM pkg for dist bundles
2 parents 9698e78 + 2bdce23 commit 5de384c

File tree

7 files changed

+242
-82
lines changed

7 files changed

+242
-82
lines changed

‎BUILDING.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Building plotly.js
22

3+
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.
4+
35
## Webpack
46

57
For plotly.js to build with Webpack you will need to install [[email protected]+](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.

‎CONTRIBUTING.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -208,7 +208,7 @@ This will produce the following plot, and say you want to simulate a selection p
208208
- All tasks can be run using [`npm run-script`](https://docs.npmjs.com/cli/run-script)
209209
- Tests are `test/`, they are partitioned into `image` and `jasmine` tests
210210
- Test dashboard and image viewer code is in `devtools/`
211-
- Non-distributed, built files are in `build/` (most files in here are git-ignored, the css and font built files are exceptions)
211+
- Built files are in `build/` (most files in here are git-ignored, the css and font built files are exceptions)
212212

213213

214214
## Coding style

‎README.md

+17-20
Original file line numberDiff line numberDiff line change
@@ -32,28 +32,16 @@ and more.
3232

3333
## Quick start options
3434

35-
#### Download the latest release
36-
[Latest Release on Github](https://github.com/plotly/plotly.js/releases/)
37-
38-
and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
39-
40-
#### Clone the repo
35+
### Install with npm
4136

4237
```bash
43-
git clone https://github.com/plotly/plotly.js.git
38+
npm install plotly.js-dist
4439
```
4540

46-
and use the plotly.js `dist` file(s).
47-
48-
#### Install with `npm`
49-
50-
```bash
51-
npm install plotly.js
52-
```
41+
and import plotly.js as `import Plotly from 'plotly.js-dist';` or `var Plotly = require('plotly.js-dist');`.
5342

54-
and require plotly.js using CommonJS as `var Plotly = require('plotly.js');` or use the plotly.js `dist` file(s).
43+
### Use the plotly.js CDN hosted by Fastly
5544

56-
#### Use the plotly.js CDN hosted by Fastly
5745
```html
5846
<!-- Latest compiled and minified plotly.js JavaScript -->
5947
<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
@@ -62,18 +50,27 @@ and require plotly.js using CommonJS as `var Plotly = require('plotly.js');` or
6250
<script src="https://cdn.plot.ly/plotly-1.5.0.min.js"></script>
6351

6452
<!-- OR an un-minified version is also available -->
65-
<script src="https://cdn.plot.ly/plotly-latest.js"></script>
53+
<script src="https://cdn.plot.ly/plotly-latest.js" charset="utf-8"></script>
6654
```
6755

6856
and use the `Plotly` object in the window scope.
6957

70-
##### Read the [Getting started page](https://plot.ly/javascript/getting-started/) for more examples.
58+
### Download the latest release
59+
60+
[Latest Release on Github](https://github.com/plotly/plotly.js/releases/)
61+
62+
and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
63+
64+
#### Read the [Getting started page](https://plot.ly/javascript/getting-started/) for more examples.
65+
7166

7267
## Modules
7368

74-
Starting in `v1.15.0`, plotly.js also ships with several _partial_ bundles (more info [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md#partial-bundles)).
69+
Starting in `v1.15.0`, plotly.js ships with several _partial_ bundles (more info [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md#partial-bundles)).
70+
71+
Starting in `v1.39.0`, plotly.js publishes _distributed_ npm packages with no dependencies. For example, run `npm install plotly.js-geo-dist` and add `import Plotly from 'plotly.js-geo-dist';` to your code to start using the plotly.js geo package.
7572

76-
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*:
73+
If none of the distributed npm packages meet your needs, and 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:
7774

7875
```javascript
7976
// in custom-plotly.js

‎package.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,8 @@
4646
"baseline": "node tasks/baseline.js",
4747
"preversion": "check-node-version --node 8 --npm 5 && npm-link-check && npm ls --prod",
4848
"version": "npm run build && git add -A dist src build",
49-
"postversion": "node -e \"console.log('Version bumped and committed. If ok, run: git push && git push --tags')\""
49+
"postversion": "node -e \"console.log('Version bumped and committed. If ok, run: git push && git push --tags')\"",
50+
"postpublish": "node tasks/sync_package.js"
5051
},
5152
"browserify": {
5253
"transform": [

‎tasks/stats.js

+42-60
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
var path = require('path');
22
var fs = require('fs');
33

4-
var falafel = require('falafel');
54
var gzipSize = require('gzip-size');
65
var prettySize = require('prettysize');
76

@@ -11,7 +10,6 @@ var pkg = require('../package.json');
1110

1211
var pathDistREADME = path.join(constants.pathToDist, 'README.md');
1312
var cdnRoot = 'https://cdn.plot.ly/plotly-';
14-
var coreModules = ['scatter'];
1513

1614
var ENC = 'utf-8';
1715
var JS = '.js';
@@ -110,6 +108,7 @@ function getMainBundleInfo() {
110108
'- using CDN URL ' + cdnRoot + 'latest' + MINJS + ' OR ' + cdnRoot + pkg.version + MINJS,
111109
'',
112110
'or as raw javascript:',
111+
'- using the `plotly.js-dist` npm package (starting in `v1.39.0`)',
113112
'- using dist file `dist/plotly.js`',
114113
'- using CDN URL ' + cdnRoot + 'latest' + JS + ' OR ' + cdnRoot + pkg.version + JS,
115114
'- using CommonJS with `require(\'plotly.js\')`',
@@ -129,7 +128,8 @@ function getMainBundleInfo() {
129128
'Starting in `v1.15.0`, plotly.js also ships with several _partial_ bundles:',
130129
'',
131130
constants.partialBundlePaths.map(makeBundleHeaderInfo).join('\n'),
132-
''
131+
'',
132+
'Starting in `v1.39.0`, each plotly.js partial bundle has a corresponding npm package with no dependencies.'
133133
];
134134
}
135135

@@ -156,26 +156,55 @@ function makeBundleHeaderInfo(pathObj) {
156156
function makeBundleInfo(pathObj) {
157157
var name = pathObj.name;
158158
var sizes = findSizes(pathObj);
159-
var moduleList = coreModules.concat(scrapeContent(pathObj));
159+
var moduleList = common.findModuleList(pathObj.index);
160+
var pkgName = 'plotly.js-' + name + '-dist';
160161

161162
return [
162163
'### plotly.js ' + name,
163164
'',
164-
formatBundleInfo(name, moduleList),
165+
'The `' + name + '` partial bundle contains trace modules ' + common.formatEnumeration(moduleList) + '.',
166+
'',
167+
'#### Stats',
168+
'',
169+
'| Raw size | Minified size | Minified + gzip size |',
170+
'|------|-----------------|------------------------|',
171+
'| ' + sizes.raw + ' | ' + sizes.minified + ' | ' + sizes.gzipped + ' |',
172+
'',
173+
'#### CDN links',
174+
'',
175+
'| Flavor | URL |',
176+
'| ------ | --- |',
177+
'| Latest | ' + cdnRoot + name + '-latest' + JS + ' |',
178+
'| Latest minified | ' + cdnRoot + name + '-latest' + MINJS + ' |',
179+
'| Tagged | ' + cdnRoot + name + '-' + pkg.version + JS + ' |',
180+
'| Tagged minified | ' + cdnRoot + name + '-' + pkg.version + MINJS + ' |',
181+
'',
182+
'#### npm package (starting in `v1.39.0`)',
183+
'',
184+
'Install [`' + pkgName + '`](https://www.npmjs.com/package/' + pkgName + ') with',
185+
'```',
186+
'npm install ' + pkgName,
187+
'```',
188+
'',
189+
'ES6 module usage:',
190+
'```js',
191+
'import Plotly from \'' + pkgName + '\'',
192+
'```',
193+
'',
194+
'CommonJS usage:',
195+
'```js',
196+
'var Plotly = require(\'' + pkgName + '\');',
197+
'```',
165198
'',
166-
'| Way to import | Location |',
199+
'#### Other plotly.js entry points',
200+
'',
201+
'| Flavor | Location |',
167202
'|---------------|----------|',
168203
'| dist bundle | ' + '`dist/plotly-' + name + JS + '` |',
169204
'| dist bundle (minified) | ' + '`dist/plotly-' + name + MINJS + '` |',
170-
'| CDN URL (latest) | ' + cdnRoot + name + '-latest' + JS + ' |',
171-
'| CDN URL (latest minified) | ' + cdnRoot + name + '-latest' + MINJS + ' |',
172-
'| CDN URL (tagged) | ' + cdnRoot + name + '-' + pkg.version + JS + ' |',
173-
'| CDN URL (tagged minified) | ' + cdnRoot + name + '-' + pkg.version + MINJS + ' |',
205+
'| ES6 module | ' + '`import Plotly from \'plotly.js/lib/' + 'index-' + name + '\'`' + ' |',
174206
'| CommonJS | ' + '`require(\'plotly.js/lib/' + 'index-' + name + '\')`' + ' |',
175207
'',
176-
'| Raw size | Minified size | Minified + gzip size |',
177-
'|------|-----------------|------------------------|',
178-
'| ' + sizes.raw + ' | ' + sizes.minified + ' | ' + sizes.gzipped + ' |',
179208
''
180209
].join('\n');
181210
}
@@ -197,50 +226,3 @@ function findSizes(pathObj) {
197226

198227
return sizes;
199228
}
200-
201-
function scrapeContent(pathObj) {
202-
var code = fs.readFileSync(pathObj.index, ENC);
203-
var moduleList = [];
204-
205-
falafel(code, function(node) {
206-
if(isModuleNode(node)) {
207-
var moduleName = node.value.replace('./', '');
208-
moduleList.push(moduleName);
209-
}
210-
});
211-
212-
return moduleList;
213-
}
214-
215-
function isModuleNode(node) {
216-
return (
217-
node.type === 'Literal' &&
218-
node.parent &&
219-
node.parent.type === 'CallExpression' &&
220-
node.parent.callee &&
221-
node.parent.callee.type === 'Identifier' &&
222-
node.parent.callee.name === 'require' &&
223-
node.parent.parent &&
224-
node.parent.parent.type === 'ArrayExpression'
225-
);
226-
}
227-
228-
function formatBundleInfo(bundleName, moduleList) {
229-
var enumeration = moduleList.map(function(moduleName, i) {
230-
var len = moduleList.length,
231-
ending;
232-
233-
if(i === len - 2) ending = ' and';
234-
else if(i < len - 1) ending = ',';
235-
else ending = '';
236-
237-
return '`' + moduleName + '`' + ending;
238-
});
239-
240-
return [
241-
'The', '`' + bundleName + '`',
242-
'partial bundle contains the',
243-
enumeration.join(' '),
244-
'trace modules.'
245-
].join(' ');
246-
}

‎tasks/sync_packages.js

+139
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
var path = require('path');
2+
var fs = require('fs-extra');
3+
var exec = require('child_process').exec;
4+
var runSeries = require('run-series');
5+
6+
var common = require('./util/common');
7+
var constants = require('./util/constants');
8+
var pkg = require('../package.json');
9+
10+
var packagesSpecs = constants.partialBundlePaths
11+
.map(function(d) {
12+
return {
13+
name: 'plotly.js-' + d.name + '-dist',
14+
index: d.index,
15+
main: 'plotly-' + d.name + '.js',
16+
dist: d.dist,
17+
desc: 'Ready-to-use plotly.js ' + d.name + ' distributed bundle.',
18+
};
19+
})
20+
.concat([{
21+
name: 'plotly.js-dist',
22+
index: path.join(constants.pathToLib, 'index.js'),
23+
main: 'plotly.js',
24+
dist: constants.pathToPlotlyDist,
25+
desc: 'Ready-to-use plotly.js distributed bundle.',
26+
}]);
27+
28+
packagesSpecs.forEach(function(d) {
29+
var pkgPath = path.join(constants.pathToBuild, d.name);
30+
31+
function initDirectory(cb) {
32+
if(common.doesDirExist(pkgPath)) {
33+
cb();
34+
} else {
35+
fs.mkdir(pkgPath, cb);
36+
}
37+
}
38+
39+
function writePackageJSON(cb) {
40+
var cnt = {
41+
name: d.name,
42+
version: pkg.version,
43+
description: d.desc,
44+
license: pkg.license,
45+
main: d.main,
46+
repository: pkg.repository,
47+
bugs: pkg.bugs,
48+
author: pkg.author,
49+
keywords: pkg.keywords,
50+
files: [
51+
'LICENSE',
52+
'README.md',
53+
d.main
54+
]
55+
};
56+
57+
fs.writeFile(
58+
path.join(pkgPath, 'package.json'),
59+
JSON.stringify(cnt, null, 2) + '\n',
60+
cb
61+
);
62+
}
63+
64+
function writeREADME(cb) {
65+
var moduleList = common.findModuleList(d.index);
66+
67+
var cnt = [
68+
'# ' + d.name,
69+
'',
70+
d.desc,
71+
'',
72+
'Contains trace modules ' + common.formatEnumeration(moduleList) + '.',
73+
'',
74+
'For more info on plotly.js, go to https://github.com/plotly/plotly.js',
75+
'',
76+
'## Installation',
77+
'',
78+
'```',
79+
'npm install ' + d.name,
80+
'```',
81+
'## Usage',
82+
'',
83+
'```js',
84+
'// ES6 module',
85+
'import Plotly from \'' + d.name + '\';',
86+
'',
87+
'// CommonJS',
88+
'var Plotly = require(\'' + d.name + '\');',
89+
'```',
90+
'',
91+
'## Copyright and license',
92+
'',
93+
'Code and documentation copyright 2018 Plotly, Inc.',
94+
'',
95+
'Code released under the [MIT license](https://github.com/plotly/plotly.js/blob/master/LICENSE).',
96+
'',
97+
'Docs released under the [Creative Commons license](https://github.com/plotly/documentation/blob/source/LICENSE).',
98+
''
99+
];
100+
101+
fs.writeFile(
102+
path.join(pkgPath, 'README.md'),
103+
cnt.join('\n'),
104+
cb
105+
);
106+
}
107+
108+
function copyMain(cb) {
109+
fs.copy(d.dist, path.join(pkgPath, d.main), cb);
110+
}
111+
112+
function copyLicense(cb) {
113+
fs.copy(
114+
path.join(constants.pathToRoot, 'LICENSE'),
115+
path.join(pkgPath, 'LICENSE'),
116+
cb
117+
);
118+
}
119+
120+
function publishToNPM(cb) {
121+
if(process.env.DRYRUN) {
122+
console.log('dry run, did not publish ' + d.name);
123+
cb();
124+
return;
125+
}
126+
exec('npm publish', {cwd: pkgPath}, cb).stdout.pipe(process.stdout);
127+
}
128+
129+
runSeries([
130+
initDirectory,
131+
writePackageJSON,
132+
writeREADME,
133+
copyMain,
134+
copyLicense,
135+
publishToNPM
136+
], function(err) {
137+
if(err) throw err;
138+
});
139+
});

0 commit comments

Comments
 (0)