Skip to content

Commit

Permalink
Update documentation on tree-shaking
Browse files Browse the repository at this point in the history
Related issue: #19549
  • Loading branch information
larsenwork committed Feb 18, 2020
1 parent f2d74e9 commit ce766d9
Showing 1 changed file with 13 additions and 8 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,25 @@ on every commit for every package and critical parts of those packages ([view th
Combined with [dangerJS](https://danger.systems/js/) we can inspect
[detailed bundle size changes](https://github.com/mui-org/material-ui/pull/14638#issuecomment-466658459) on every Pull Request.

## How to reduce the bundle size?
## When and how to use tree-shaking?

For convenience, Material-UI exposes its full API on the top-level `material-ui` import.
If you're using ES6 modules and a bundler that supports tree-shaking ([`webpack` >= 2.x](https://webpack.js.org/guides/tree-shaking/), [`parcel` with a flag](https://en.parceljs.org/cli.html#enable-experimental-scope-hoisting/tree-shaking-support)) you can safely
use named imports and expect only a minimal set of Material-UI components in your bundle:
Tree-shaking of Material UI works out of the box in modern frameworks. Material UI exposes its full API on the top-level
`material-ui` import. If you're using ES6 modules and a bundler that supports tree-shaking
([`webpack` >= 2.x](https://webpack.js.org/guides/tree-shaking/),
[`parcel` with a flag](https://en.parceljs.org/cli.html#enable-experimental-scope-hoisting/tree-shaking-support)) you can safely
use named imports and still get an optimised bundle size automatically:

```js
import { Button, TextField } from '@material-ui/core';
```

⚠️ Be aware that tree-shaking is an optimization that is usually only applied to production
bundles. Development bundles will contain the full library which can lead to **slower
startup times**. This is especially noticeable if you import from `@material-ui/icons`.
Startup times can be approximately 6x slower than without named imports from the top-level API.
⚠️ The following instructions are only needed if you want to optimize your development startup times or if you are using an older bundler
that doesn't support tree-shaking.

## Development environment

Development bundles can contain the full library which can lead to **slower startup times**. This is especially noticeable if you
import from `@material-ui/icons`. Startup times can be approximately 6x slower than without named imports from the top-level API.

If this is an issue for you, you have various options:

Expand Down

0 comments on commit ce766d9

Please sign in to comment.