-
-
Notifications
You must be signed in to change notification settings - Fork 32.6k
[docs][examples] Remove create-react-app usages #45426
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.
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
Merged
ZeeshanTamboli
merged 38 commits into
mui:master
from
CodeLeom:deprecated-react-removal
Apr 30, 2025
+241
−1,813
Merged
Changes from all commits
Commits
Show all changes
38 commits
Select commit
Hold shift + click to select a range
fb44fba
doc: remove create create app from the official integration
CodeLeom 3c99891
doc: update example collection with an updated vite+tailwind+mui impl…
CodeLeom 73abccb
doc: modify the cra link to vite setup example
CodeLeom 4e61c51
doc: remove cra explanation and replace with a Vite explanation
CodeLeom ab54075
doc: remove cra usage of babel to minimize bundle size. Vite explanat…
CodeLeom 6076ee3
doc: remove migration to cra example
CodeLeom 7e53859
doc: remove cra appearance
CodeLeom a930c0d
doc: add vite implementation of styled components and update the inte…
CodeLeom f4f8384
doc: update styled-component page with vite example links
CodeLeom 1018d74
Merge branch 'master' into deprecated-react-removal
CodeLeom 7279542
fix: suggestion included
CodeLeom 1bbe9b5
fix: remove the appearance of CRA example files
CodeLeom b56932a
fix: add base url path
CodeLeom 474016e
Merge remote-tracking branch 'upstream/master' into deprecated-react-…
CodeLeom 6878c19
Merge branch 'master' into deprecated-react-removal
ZeeshanTamboli 7bd121f
prettier
ZeeshanTamboli 16f8a30
prettier and lint
ZeeshanTamboli 726b10d
fix lint
ZeeshanTamboli c1b902d
fix docs
ZeeshanTamboli a19ede5
dev: add missing vite and ts example
CodeLeom 8065eb2
dev: remove eslint file
CodeLeom 4574845
doc: add missing syntax
CodeLeom aee9394
Merge remote-tracking branch 'upstream/master' into deprecated-react-…
CodeLeom ad4303d
dev: remove styled component from example codes and reference
CodeLeom 7d2044a
Update examples/material-ui-vite-tailwind-ts/src/App.tsx
CodeLeom d715134
Update examples/material-ui-vite-ts/README.md
CodeLeom 4c8a0b2
Update examples/material-ui-vite-ts/README.md
CodeLeom e86c84f
pnpm prettier
ZeeshanTamboli 21df4a0
review changes
ZeeshanTamboli 5b9b596
resolve conflicts
ZeeshanTamboli 78e50b7
fix lint and docs link
ZeeshanTamboli d843d56
lint
ZeeshanTamboli 2bce911
remove create-react-app fixture from bundling tests
ZeeshanTamboli ae57c15
Update minimizing-bundle-size.md
Janpot 07dae62
Update minimizing-bundle-size.md
Janpot 5fa2bfb
Merge branch 'master' into deprecated-react-removal
ZeeshanTamboli 1ce1ad1
Merge branch 'deprecated-react-removal' of https://github.com/CodeLeo…
ZeeshanTamboli f8ab11f
Fix VS Code casing
ZeeshanTamboli File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
189 changes: 29 additions & 160 deletions
189
docs/data/material/guides/minimizing-bundle-size/minimizing-bundle-size.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,200 +1,69 @@ | ||
# Minimizing bundle size | ||
|
||
<p class="description">Learn more about the tools you can leverage to reduce the bundle size.</p> | ||
<p class="description">Learn how to reduce your bundle size and improve development performance by avoiding costly import patterns.</p> | ||
|
||
## Bundle size matters | ||
|
||
Material UI's maintainers take bundle size very seriously. Size snapshots are taken | ||
on every commit for every package and critical parts of those packages. | ||
Combined with [dangerJS](https://danger.systems/js/) we can inspect | ||
[detailed bundle size changes](https://github.com/mui/material-ui/pull/14638#issuecomment-466658459) on every Pull Request. | ||
Material UI's maintainers take bundle size very seriously. Size snapshots are taken on every commit for every package and critical parts of those packages. Combined with [dangerJS](https://danger.systems/js/), we can inspect [detailed bundle size changes](https://github.com/mui/material-ui/pull/14638#issuecomment-466658459) on every Pull Request. | ||
Check warning on line 7 in docs/data/material/guides/minimizing-bundle-size/minimizing-bundle-size.md
|
||
|
||
## When and how to use tree-shaking? | ||
## Avoid barrel imports | ||
|
||
Tree-shaking Material UI works out of the box in modern frameworks. | ||
Material UI exposes its full API on the top-level `@mui` imports. | ||
If you're using ES modules and a bundler that supports tree-shaking ([`webpack` >= 2.x](https://webpack.js.org/guides/tree-shaking/), parcel you can safely use named imports and still get an optimized bundle size automatically: | ||
Modern bundlers already tree-shake unused code in production builds, so you don't need to worry about it when using top-level imports. The real performance concern is during **development**, where **barrel imports** like `@mui/material` or `@mui/icons-material` can cause significantly **slower startup and rebuild times**. | ||
|
||
```js | ||
import { Button, TextField } from '@mui/material'; | ||
``` | ||
|
||
:::warning | ||
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 use named imports from `@mui/icons-material`, which can be up to six times slower than the default import. | ||
For example, between the following two imports, the first (named) can be significantly slower than the second (default): | ||
|
||
```js | ||
// 🐌 Named | ||
import { Delete } from '@mui/icons-material'; | ||
``` | ||
|
||
```js | ||
// 🚀 Default | ||
import Delete from '@mui/icons-material/Delete'; | ||
``` | ||
|
||
If this is an issue for you, you have two options: | ||
|
||
### Option one: use path imports | ||
|
||
You can use path imports to avoid pulling in unused modules. | ||
For instance, use: | ||
|
||
```js | ||
// 🚀 Fast | ||
// ✅ Preferred | ||
import Button from '@mui/material/Button'; | ||
import TextField from '@mui/material/TextField'; | ||
``` | ||
|
||
instead of top-level imports (without a Babel plugin): | ||
Instead of: | ||
|
||
```js | ||
// ❌ Slower in dev | ||
import { Button, TextField } from '@mui/material'; | ||
``` | ||
|
||
This is the option we document in all the demos since it requires no configuration. | ||
It is encouraged for library authors that are extending the components. | ||
Head to [Option 2](#option-two-use-a-babel-plugin) for the approach that yields the best DX and UX. | ||
|
||
While importing directly in this manner doesn't use the exports in [the main file of `@mui/material`](https://unpkg.com/@mui/material), this file can serve as a handy reference as to which modules are public. | ||
|
||
Be aware that we only support first and second-level imports. | ||
Anything deeper is considered private and can cause issues, such as module duplication in your bundle. | ||
This is especially true when using `@mui/icons-material`, where named imports can be up to six times slower than default path-based imports: | ||
|
||
```js | ||
// ✅ OK | ||
import { Add as AddIcon } from '@mui/icons-material'; | ||
import { Tabs } from '@mui/material'; | ||
// ^^^^^^^^ 1st or top-level | ||
|
||
// ✅ OK | ||
import AddIcon from '@mui/icons-material/Add'; | ||
import Tabs from '@mui/material/Tabs'; | ||
// ^^^^ 2nd level | ||
|
||
// ❌ NOT OK | ||
import TabIndicator from '@mui/material/Tabs/TabIndicator'; | ||
// ^^^^^^^^^^^^ 3rd level | ||
// 🐌 Slower in dev | ||
import { Delete } from '@mui/icons-material'; | ||
|
||
// 🚀 Faster in dev | ||
import Delete from '@mui/icons-material/Delete'; | ||
``` | ||
|
||
If you're using ESLint you can catch problematic imports with the [`no-restricted-imports` rule](https://eslint.org/docs/latest/rules/no-restricted-imports). The following `.eslintrc` configuration will highlight problematic imports from `@mui` packages: | ||
This approach avoids loading unnecessary parts of the package and does not require any special configuration. It is also the default used in all our official examples and demos. | ||
Check warning on line 36 in docs/data/material/guides/minimizing-bundle-size/minimizing-bundle-size.md
|
||
|
||
## Enforce best practices with ESLint | ||
|
||
To prevent accidental deep imports, you can use the `no-restricted-imports` rule in your ESLint configuration: | ||
|
||
```json | ||
// .eslintrc | ||
{ | ||
"rules": { | ||
"no-restricted-imports": [ | ||
"error", | ||
{ | ||
"patterns": ["@mui/*/*/*"] | ||
"patterns": [{ "regex": "^@mui/[^/]+$" }] | ||
} | ||
] | ||
} | ||
} | ||
``` | ||
|
||
### Option two: use a Babel plugin | ||
|
||
This option provides the best user experience and developer experience, except if you're using **Next.js 13.5 or greater**, where this optimization is automatically applied via the `optimizePackageImports` option in Next.js. In that case, using a Babel plugin is unnecessary. | ||
|
||
- UX: The Babel plugin enables top-level tree-shaking even if your bundler doesn't support it. | ||
- DX: The Babel plugin makes startup time in dev mode as fast as Option 1. | ||
- DX: This syntax reduces the duplication of code, requiring only a single import for multiple modules. | ||
Overall, the code is easier to read, and you are less likely to make a mistake when importing a new module. | ||
## Avoid VS Code auto-importing from barrel files | ||
|
||
```js | ||
import { Button, TextField } from '@mui/material'; | ||
``` | ||
To prevent VS Code from automatically importing from `@mui/material`, you can use the `typescript.autoImportSpecifierExcludeRegexes` in the VS Code project configuration: | ||
|
||
However, you need to apply the following steps correctly. | ||
|
||
#### 1. Configure Babel | ||
|
||
Use the [babel-plugin-import](https://github.com/umijs/babel-plugin-import) with the following configuration: | ||
|
||
`yarn add -D babel-plugin-import` | ||
|
||
Create a `.babelrc.js` file in the root directory of your project: | ||
|
||
```js | ||
const plugins = [ | ||
[ | ||
'babel-plugin-import', | ||
{ | ||
libraryName: '@mui/material', | ||
libraryDirectory: '', | ||
camel2DashComponentName: false, | ||
}, | ||
'core', | ||
], | ||
[ | ||
'babel-plugin-import', | ||
{ | ||
libraryName: '@mui/icons-material', | ||
libraryDirectory: '', | ||
camel2DashComponentName: false, | ||
}, | ||
'icons', | ||
], | ||
]; | ||
|
||
module.exports = { plugins }; | ||
``` | ||
|
||
:::error | ||
Avoid using [babel-plugin-direct-import](https://github.com/avocadowastaken/babel-plugin-direct-import) which transforms imports to: | ||
|
||
```js | ||
import Button from '@mui/material/Button/Button.js'; | ||
``` | ||
|
||
Future changes to the library's internal structure could break these paths. `babel-plugin-direct-import` allows for granular control over what gets imported, but it comes with the potential risk of relying on internal library paths. This may fail in future versions if the package is updated to use the `exports` field in `package.json`, which could block access to internal paths like this. | ||
::: | ||
|
||
If you are using Create React App, you will need to use a couple of projects that let you use `.babelrc` configuration, without ejecting. | ||
|
||
`yarn add -D react-app-rewired customize-cra` | ||
|
||
Create a `config-overrides.js` file in the root directory: | ||
|
||
```js | ||
/* config-overrides.js */ | ||
/* eslint-disable react-hooks/rules-of-hooks */ | ||
const { useBabelRc, override } = require('customize-cra'); | ||
|
||
module.exports = override(useBabelRc()); | ||
``` | ||
|
||
If you wish, `babel-plugin-import` can be configured through `config-overrides.js` instead of `.babelrc` by using this [configuration](https://github.com/arackaf/customize-cra/blob/master/api.md#fixbabelimportslibraryname-options). | ||
|
||
Modify your `package.json` commands: | ||
|
||
```diff | ||
"scripts": { | ||
- "start": "react-scripts start", | ||
- "build": "react-scripts build", | ||
- "test": "react-scripts test", | ||
+ "start": "react-app-rewired start", | ||
+ "build": "react-app-rewired build", | ||
+ "test": "react-app-rewired test", | ||
"eject": "react-scripts eject" | ||
} | ||
```json | ||
// .vscode/settings.json | ||
{ | ||
"typescript.preferences.autoImportSpecifierExcludeRegexes": ["^@mui/[^/]+$"] | ||
} | ||
``` | ||
|
||
Enjoy significantly faster start times. | ||
## Using Next.js 13.5 or later? | ||
|
||
#### 2. Convert all your imports | ||
|
||
Finally, you can convert your existing codebase to this option with this [top-level-imports codemod](https://www.npmjs.com/package/@mui/codemod#top-level-imports). | ||
It will perform the following diffs: | ||
|
||
```diff | ||
-import Button from '@mui/material/Button'; | ||
-import TextField from '@mui/material/TextField'; | ||
+import { Button, TextField } from '@mui/material'; | ||
``` | ||
If you're on **Next.js 13.5 or newer**, you're in good hands. These versions include automatic import optimization via the `optimizePackageImports` option. This removes the need for manual configuration or Babel plugins to optimize imports. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.