Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Improve wording of bundle size guide #19768

Merged
merged 1 commit into from
Feb 19, 2020
Merged

[docs] Improve wording of bundle size guide #19768

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions docs/src/pages/guides/minimizing-bundle-size/minimizing-bundle-size.md
View file
Open in desktop
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