Skip to content

Commit

Permalink
feat(build): split ES bundle to leverage treeshaking
Browse files Browse the repository at this point in the history
fix #30
  • Loading branch information
LeBenLeBen committed Dec 1, 2020
1 parent a4163b7 commit 9d22cba
Show file tree
Hide file tree
Showing 9 changed files with 156 additions and 60 deletions.
2 changes: 1 addition & 1 deletion packages/chusho/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
"test:unit:dev": "vue-cli-service test:unit --watch"
},
"main": "dist/chusho.js",
"module": "dist/chusho.module.js",
"module": "dist/esm/chusho.js",
"files": [
"dist/"
],
Expand Down
38 changes: 29 additions & 9 deletions packages/chusho/rollup.config.js
Original file line number Diff line number Diff line change
@@ -1,43 +1,56 @@
import path from 'path';
import typescript from 'rollup-plugin-typescript2';
import resolve from 'rollup-plugin-node-resolve';
import { terser } from 'rollup-plugin-terser';
import replace from 'rollup-plugin-replace';

const builds = {
'cjs-dev': {
outFile: 'chusho.js',
output: {
file: './dist/chusho.js',
},
format: 'cjs',
mode: 'development',
},
'cjs-prod': {
outFile: 'chusho.min.js',
output: {
file: './dist/chusho.min.js',
},
format: 'cjs',
mode: 'production',
},
'umd-dev': {
outFile: 'chusho.umd.js',
output: {
file: './dist/chusho.umd.js',
},
format: 'umd',
mode: 'development',
},
'umd-prod': {
outFile: 'chusho.umd.min.js',
output: {
file: './dist/chusho.umd.min.js',
},
format: 'umd',
mode: 'production',
},
es: {
outFile: 'chusho.module.js',
output: {
dir: 'dist/esm',
preserveModules: true,
preserveModulesRoot: 'src',
},
format: 'es',
mode: 'development',
},
};

function genConfig({ outFile, format, mode }) {
function genConfig({ input, output, format, mode }) {
const isProd = mode === 'production';
input = input || './src/chusho.ts';

return {
input: './src/chusho.ts',
input,
output: {
file: path.join('./dist', outFile),
...output,
exports: 'named',
format: format,
globals: {
Expand All @@ -50,6 +63,13 @@ function genConfig({ outFile, format, mode }) {
resolve(),
typescript({
typescript: require('typescript'),
tsconfigOverride: {
compilerOptions: {
// ESM: transform most recent features such as optional chaining and nullish coalescing
// since those are currently erroring when using Webpack 4 if not being transpiled first
target: format === 'es' ? 'es2019' : 'es5',
},
},
}),
isProd &&
replace({
Expand Down
7 changes: 4 additions & 3 deletions packages/docs/.vuepress/assets/base/_table.scss
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.table {
table {
padding: 1px;
overflow-x: auto;

Expand Down Expand Up @@ -58,7 +58,8 @@
background-color: transparent;
}

tr, td {
tr,
td {
border-color: $gray-300;
}

Expand All @@ -76,4 +77,4 @@
text-transform: uppercase;
font-size: 0.875em;
}
}
}
7 changes: 6 additions & 1 deletion packages/docs/.vuepress/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,12 @@ module.exports = {
title: 'Getting Started',
path: '/guide/',
collapsable: false,
children: ['config', 'styling-components'],
children: [
'config',
'styling-components',
'using-components',
'builds',
],
},
{
title: 'Components',
Expand Down
41 changes: 0 additions & 41 deletions packages/docs/guide/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,44 +34,3 @@ app.use(Chusho, {
```

See the [configuration](/guide/config.html) for available options.

## Using components

You need to register Chūshō’s components you want to use either globally, for example in your main entry point:

```js
import Vue from 'vue';
import { CBtn, CIcon } from 'chusho';

Vue.component('CBtn', CBtn);
Vue.component('CIcon', CIcon);
```

Or locally in the components they are used:

```vue
<template>
<CToggle>
<CToggleBtn>...</CToggleBtn>
<CToggleContent>
<!-- ... -->
</CToggleContent>
</CToggle>
</template>
<script>
import { CToggle, CToggleBtn, CToggleContent } from 'chusho';
export default {
name: 'MyComponent',
components: {
CToggle,
CToggleBtn,
CToggleContent,
},
// ...
};
</script>
```
63 changes: 63 additions & 0 deletions packages/docs/guide/builds.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Builds

The [`dist` directory of the npm package](https://cdn.jsdelivr.net/npm/chusho/dist/) contains different builds:

| Filename | Module type | JavaScript version | Environment | Package.json field | About |
| ----------------- | ----------- | ------------------ | ----------- | ------------------ | ------------------------------------------------------- |
| chusho.js | CommonJS | ES5<sup>1</sup> | Development | main | Used by old bundlers: Webpack 1, Browserify, … |
| chusho.min.js | CommonJS | ES5<sup>1</sup> | Production | - | |
| chusho.umd.js | UMD | ES5<sup>1</sup> | Development | umd:main | To be used in the browser with a `<script />` tag |
| chusho.umd.min.js | UMD | ES5<sup>1</sup> | Production | - | |
| esm/chusho.js | ES Module | ES2019<sup>2</sup> | Development | module | Used by modern bundlers: Vue CLI, Webpack 2+, Rollup, … |

<sup>1</sup> ES5 is supported by all recent browsers and IE 11.

<sup>2</sup> ES2019 is supported only by the most recent browsers.

## Browsers support

If you’re using Vue CLI, Webpack 2+, Rollup or another modern bundler, it’s probably going to import the ES Module described above. This is great as it will automatically enable [tree-shaking](https://en.wikipedia.org/wiki/Tree_shaking) and remove unused code from your app bundle.

However this version targets modern browsers (supporting ES2019 features), therefor if you need to support older browsers, you’ll have to transpile Chūshō’s code.

### Vue CLI

To transpile for older browsers using Vue CLI, you need to add it to the `transpileDependencies` array in [`vue.config.js`](https://cli.vuejs.org/config/#vue-config-js):

```js{4}
// vue.config.js
module.exports = {
transpileDependencies: ['chusho']
}
```

### Webpack & Babel

To transpile for older browsers using a custom Webpack setup, you need to adapt your JavaScript loader configuration to include Chūshō. Usually it’s configured like this:

```js{10}
// webpack.config.js
module.exports = {
// ...
module: {
rules: [
{
test: /\.js$/,
loader: 'babel-loader',
exclude: /node_modules/,
},
],
},
// ...
};
```

Instead of excluding all `node_modules`, adapt the Regex to include Chūshō:

```js{5}
// ...
exclude: /node_modules\/(?!chusho)/,
// ...
```
8 changes: 4 additions & 4 deletions packages/docs/guide/config.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Configuration

To configure Chūshō’s, pass an object as the second argument of `app.use` when installing it:
Chūshō options can be set by passing an object as the second argument of `app.use` when installing it:

```js
```js{6-14}
import { createApp } from 'vue';
import Chusho from 'chusho';
Expand All @@ -11,9 +11,9 @@ const app = createApp(App);
app.use(Chusho, {
components: {
alert: {
// Alert component config
// Alert component options
},
// Other components config
// Other components options
},
// Other options…
});
Expand Down
2 changes: 1 addition & 1 deletion packages/docs/guide/styling-components.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
next: /guide/components/
next: /guide/using-components.html
---

# Styling components
Expand Down
48 changes: 48 additions & 0 deletions packages/docs/guide/using-components.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
next: /guide/components/
---

# Using components

Components aren’t registered automatically to take advantage of bundler’s [tree-shaking](https://en.wikipedia.org/wiki/Tree_shaking) optimizations by default.

You need to register Chūshō’s components you want to use either globally, for example in your main entry point:

```js{6-7}
import { createApp } from 'vue';
import { CBtn, CIcon } from 'chusho';
const app = createApp(App);
app.component('CBtn', CBtn);
app.component('CIcon', CIcon);
```

Or locally in the components they are used:

```vue{11,17-19}
<template>
<CToggle>
<CToggleBtn>...</CToggleBtn>
<CToggleContent>
<!-- ... -->
</CToggleContent>
</CToggle>
</template>
<script>
import { CToggle, CToggleBtn, CToggleContent } from 'chusho';
export default {
name: 'MyComponent',
components: {
CToggle,
CToggleBtn,
CToggleContent,
},
// ...
};
</script>
```

0 comments on commit 9d22cba

Please sign in to comment.