You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@echarts.apache.org by GitBox <gi...@apache.org> on 2020/12/28 08:49:22 UTC
[GitHub] [incubator-echarts] pissang opened a new pull request #13890: chore: improve minimal imports, option exports.
pissang opened a new pull request #13890:
URL: https://github.com/apache/incubator-echarts/pull/13890
<!-- Please fill in the following information to help us review your PR more efficiently. -->
## Brief Information
This pull request is about refactoring of exports so developers can have better API to get minimal imports.
Also, in this PR ts is upgraded ts to 4.1 to make sure exported types won't have problems in the higher ts version.
Related ZRender PR: https://github.com/ecomfe/zrender/pull/685
### Fixed issues
https://github.com/apache/incubator-echarts/issues/13764
https://github.com/apache/incubator-echarts/issues/13755
https://github.com/apache/incubator-echarts/issues/13763
https://github.com/apache/incubator-echarts/issues/13850
## Details
### Before: What was the problem?
We kept providing CommonJS modules in the earlier version because we want to make sure echarts can be compatible with environments as more as possible, like old Webpack and NodeJS.
So after rewriting our code with TypeScript. We still export two kinds of modules, CommonJS and ESM. CommonJS modules are in the `lib` folder, which is same with previous version and mainly used in NodeJS. ESM modules are in the `esm` folder, which will be used in the bundlers which target browser. This brings a serious issue, we were suggesting developers using the lib folder when import modules. Like `import * as echarts from 'echarts/lib/echarts'`. But now in most scenarios ESM module is much better because bundler can treeshake it and get a smaller bundle. This contradiction leads us to not know how to deal with the compatibility when still providing a best practice.
Even worse, because code of different extensions may both reference `lib` and `esm`. The bundle will have two namespaces. Which leads to a much larger bundle size and bugs like registered components can not be found.
### After: How is it fixed in this PR?
First of all, we remove CommonJS modules and export ESM format modules in the `lib` folder. I think very few bundlers don't support ESM module now. And for NodeJS we can provide the UMD format `dist/echarts.js`
Sencondly, we provide a higher level of exports for each components and each to avoid exposing our underlying folder structure and provide a `use` method to register the components
```js
import {LineChart} from 'echarts/charts';
import {GridComponent} from 'echarts/components';
import {CanvasRenderer} from 'echarts/renderers';
import {use} from 'echarts/core';
// Must import at least one renderer, SVGRenderer or CanvasRenderer.
use([LineChart, GridComponent, CanvasRenderer]);
```
For TypeScript, we also provide a better types when using the new minimal imports.
```ts
import {LineChart, LineSeriesOption} from 'echarts/charts';
import {GridComponent, GridComponentOption} from 'echarts/components';
import {use, ComposeOption} from 'echarts/core';
use([LineChart, GridComponent]);
type ECOption = ComposeOption<LineSeriesOption, GridComponentOption>;
const option: ECOption = {};
```
## Usage
### Are there any API changes?
- [x] The API has been changed.
### Related test cases or examples to use the new APIs
#### Import the whole package.
Importing of whole package is not changed.
```ts
import * as echarts from 'echarts';
const option: echarts.EChartsOption = {};
```
On top of that, we expose more types for case like https://github.com/apache/incubator-echarts/issues/13755
```ts
import * as echarts from 'echarts';
const lineOption: echarts.LineSeriesOption = {};
```
#### Minimal import.
```ts
import * as echarts from 'echarts/core';
import { GridComponent, GridComponentOption } from 'echarts/components';
import { LineChart, LineSeriesOption } from 'echarts/charts';
import { CanvasRenderer } from 'echarts/renderers';
// Must import at least one renderer.
// If you only want to render with SVG, just replace the CanvasRenderer with SVGRenderer.
// So the CanvasRenderer won't be included in the final bundle.
echarts.use([GridComponent, LineChart, CanvasRenderer]);
// A minimal types for option is useful for checking if any components are missing.
type EChartsOption = echarts.ComposeOption<GridComponentOption | LineSeriesOption>;
var option: EChartsOption = {...};
// If you want the full option.
import {EChartsOption} from 'echarts;
var option: EChartsOption = {...};
```
Then let the bundler do the tree-shaking and remove all unused components.
#### The legacy minimal import is still supported but not suggested.
```ts
// See https://github.com/apache/incubator-echarts/issues/13701
import * as echarts from 'echarts/index.blank';
import 'echarts/lib/chart/line';
import 'echarts/lib/component/grid';
```
Only use this kind of minimal importing when treeshaking can't work in the bundlers.
## Others
### Merging options
- [ ] Please squash the commits into a single one when merge.
### Other information
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org
[GitHub] [incubator-echarts] echarts-bot[bot] commented on pull request #13890: chore: improve minimal imports, option exports.
Posted by GitBox <gi...@apache.org>.
echarts-bot[bot] commented on pull request #13890:
URL: https://github.com/apache/incubator-echarts/pull/13890#issuecomment-751636182
Thanks for your contribution!
The community will review it ASAP. In the meanwhile, please checkout [the coding standard](https://echarts.apache.org/en/coding-standard.html) and Wiki about [How to make a pull request](https://github.com/apache/incubator-echarts/wiki/How-to-make-a-pull-request).
The pull request is marked to be `PR: author is committer` because you are a committer of this project.
Document changes are required in this PR. Please also make a PR to [apache/incubator-echarts-doc](https://github.com/apache/incubator-echarts-doc) for document changes. When the doc PR is merged, the maintainers will remove the `PR: awaiting doc` label.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org
[GitHub] [incubator-echarts] echarts-bot[bot] commented on pull request #13890: New minimal import API, improve exported option types.
Posted by GitBox <gi...@apache.org>.
echarts-bot[bot] commented on pull request #13890:
URL: https://github.com/apache/incubator-echarts/pull/13890#issuecomment-753632861
Congratulations! Your PR has been merged. Thanks for your contribution! 👍
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org
[GitHub] [incubator-echarts] pissang merged pull request #13890: New minimal import API, improve exported option types.
Posted by GitBox <gi...@apache.org>.
pissang merged pull request #13890:
URL: https://github.com/apache/incubator-echarts/pull/13890
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org
[GitHub] [incubator-echarts] plainheart commented on pull request #13890: New minimal import API, improve exported option types.
Posted by GitBox <gi...@apache.org>.
plainheart commented on pull request #13890:
URL: https://github.com/apache/incubator-echarts/pull/13890#issuecomment-751643216
Wow! Looks great!
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org
[GitHub] [incubator-echarts] ThomasBower commented on pull request #13890: New minimal import API, improve exported option types.
Posted by GitBox <gi...@apache.org>.
ThomasBower commented on pull request #13890:
URL: https://github.com/apache/incubator-echarts/pull/13890#issuecomment-754884327
Amazing work, thank you!
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org