Skip to content

[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
merged 38 commits into from
Apr 30, 2025
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 Feb 26, 2025
3c99891
doc: update example collection with an updated vite+tailwind+mui impl…
CodeLeom Feb 26, 2025
73abccb
doc: modify the cra link to vite setup example
CodeLeom Feb 26, 2025
4e61c51
doc: remove cra explanation and replace with a Vite explanation
CodeLeom Feb 26, 2025
ab54075
doc: remove cra usage of babel to minimize bundle size. Vite explanat…
CodeLeom Feb 26, 2025
6076ee3
doc: remove migration to cra example
CodeLeom Feb 26, 2025
7e53859
doc: remove cra appearance
CodeLeom Feb 26, 2025
a930c0d
doc: add vite implementation of styled components and update the inte…
CodeLeom Feb 26, 2025
f4f8384
doc: update styled-component page with vite example links
CodeLeom Feb 26, 2025
1018d74
Merge branch 'master' into deprecated-react-removal
CodeLeom Mar 22, 2025
7279542
fix: suggestion included
CodeLeom Mar 22, 2025
1bbe9b5
fix: remove the appearance of CRA example files
CodeLeom Apr 12, 2025
b56932a
fix: add base url path
CodeLeom Apr 12, 2025
474016e
Merge remote-tracking branch 'upstream/master' into deprecated-react-…
CodeLeom Apr 12, 2025
6878c19
Merge branch 'master' into deprecated-react-removal
ZeeshanTamboli Apr 15, 2025
7bd121f
prettier
ZeeshanTamboli Apr 15, 2025
16f8a30
prettier and lint
ZeeshanTamboli Apr 15, 2025
726b10d
fix lint
ZeeshanTamboli Apr 15, 2025
c1b902d
fix docs
ZeeshanTamboli Apr 15, 2025
a19ede5
dev: add missing vite and ts example
CodeLeom Apr 28, 2025
8065eb2
dev: remove eslint file
CodeLeom Apr 28, 2025
4574845
doc: add missing syntax
CodeLeom Apr 28, 2025
aee9394
Merge remote-tracking branch 'upstream/master' into deprecated-react-…
CodeLeom Apr 29, 2025
ad4303d
dev: remove styled component from example codes and reference
CodeLeom Apr 29, 2025
7d2044a
Update examples/material-ui-vite-tailwind-ts/src/App.tsx
CodeLeom Apr 29, 2025
d715134
Update examples/material-ui-vite-ts/README.md
CodeLeom Apr 29, 2025
4c8a0b2
Update examples/material-ui-vite-ts/README.md
CodeLeom Apr 29, 2025
e86c84f
pnpm prettier
ZeeshanTamboli Apr 29, 2025
21df4a0
review changes
ZeeshanTamboli Apr 30, 2025
5b9b596
resolve conflicts
ZeeshanTamboli Apr 30, 2025
78e50b7
fix lint and docs link
ZeeshanTamboli Apr 30, 2025
d843d56
lint
ZeeshanTamboli Apr 30, 2025
2bce911
remove create-react-app fixture from bundling tests
ZeeshanTamboli Apr 30, 2025
ae57c15
Update minimizing-bundle-size.md
Janpot Apr 30, 2025
07dae62
Update minimizing-bundle-size.md
Janpot Apr 30, 2025
5fa2bfb
Merge branch 'master' into deprecated-react-removal
ZeeshanTamboli Apr 30, 2025
1ce1ad1
Merge branch 'deprecated-react-removal' of https://github.com/CodeLeo…
ZeeshanTamboli Apr 30, 2025
f8ab11f
Fix VS Code casing
ZeeshanTamboli Apr 30, 2025
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
2 changes: 1 addition & 1 deletion docs/data/material/components/icons/icons.md
Original file line number Diff line number Diff line change
@@ -65,7 +65,7 @@ Import icons using one of these two options:
```

The safest for bundle size is Option 1, but some developers prefer Option 2.
Make sure you follow the [minimizing bundle size guide](/material-ui/guides/minimizing-bundle-size/#option-two-use-a-babel-plugin) before using the second approach.
Make sure you read the [minimizing bundle size guide](/material-ui/guides/minimizing-bundle-size/) before using the second approach.

Each Material icon also has a "theme": Filled (default), Outlined, Rounded, Two-tone, and Sharp. To import the icon component with a theme other than the default, append the theme name to the icon name. For example `@mui/icons-material/Delete` icon with:

Original file line number Diff line number Diff line change
@@ -72,13 +72,10 @@ function App(props) {
}
```

### Create React App (CRA)
### CSP in Vite

According to the [Create React App Docs](https://create-react-app.dev/docs/advanced-configuration/), a Create React App will dynamically embed the runtime script into index.html during the production build by default.
This will require a new hash to be set in your CSP during each deployment.

To use a CSP with a project initialized as a Create React App, you will need to set the `INLINE_RUNTIME_CHUNK=false` variable in the `.env` file used for your production build.
This will import the runtime script as usual instead of embedding it, avoiding the need to set a new hash during each deployment.
When deploying a CSP using Vite, there are specific configurations you must set up due to Vite's internal handling of assets and modules.
See [Vite Features—Content Security Policy](https://vite.dev/guide/features.html#content-security-policy-csp) for complete details.

### Next.js Pages Router

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

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.We] Try to avoid using first-person plural like 'we'. Raw Output: {"message": "[Google.We] Try to avoid using first-person plural like 'we'.", "location": {"path": "docs/data/material/guides/minimizing-bundle-size/minimizing-bundle-size.md", "range": {"start": {"line": 7, "column": 211}}}, "severity": "WARNING"}

## 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

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Google.We] Try to avoid using first-person plural like 'our'. Raw Output: {"message": "[Google.We] Try to avoid using first-person plural like 'our'.", "location": {"path": "docs/data/material/guides/minimizing-bundle-size/minimizing-bundle-size.md", "range": {"start": {"line": 36, "column": 146}}}, "severity": "WARNING"}

## 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.
Original file line number Diff line number Diff line change
@@ -270,12 +270,7 @@ export default function GlobalCssSliderDeep() {
### Change the default styled engine

By default, Material UI components come with Emotion as their style engine.
If, however, you would like to use styled-components, you can configure your app by following the [styled-components guide](/material-ui/integrations/styled-components/) or starting with one of the example projects:

<!-- #target-branch-reference -->

- [Create React App with styled-components](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components)
- [Create React App with styled-components and TypeScript](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts)
If, however, you would like to use styled-components, you can configure your app by following the [styled-components guide](/material-ui/integrations/styled-components/).

Following this approach reduces the bundle size, and removes the need to configure the CSS injection order.

@@ -586,7 +581,7 @@ For Tailwind CSS v4, please refer to the [v4 integration guide](/material-ui/in

<!-- #target-branch-reference -->

If you are used to Tailwind CSS and want to use it together with the Material UI components, you can start by cloning the [Tailwind CSS](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-tailwind-ts) example project.
To use Tailwind CSS with Material UI components, you can start by cloning the [example project](https://github.com/mui/material-ui/tree/master/examples/material-ui-vite-tailwind-ts) built with Vite and TypeScript.
If you use a different framework, or already have set up your project, follow these steps:

1. Add Tailwind CSS to your project, following the instructions in https://tailwindcss.com/docs/installation/framework-guides.
@@ -600,14 +595,14 @@ If you use a different framework, or already have set up your project, follow th
};
```

3. Add the `important` option, using the id of your app wrapper. For example, `#__next` for Next.js and `"#root"` for CRA:
3. Add the `important` option, using the id of your app wrapper. For example, `#__next` for Next.js:

```diff title="tailwind.config.js"
module.exports = {
content: [
"./src/**/*.{js,jsx,ts,tsx}",
],
+ important: '#root',
+ important: '#__next',
theme: {
extend: {},
},
Original file line number Diff line number Diff line change
@@ -95,17 +95,3 @@ For TypeScript, you must also update the `tsconfig.json` as shown here:
:::info
**Versions compatibility**: To ensure compatibility, it's essential to align the major version of `@mui/styled-engine-sc` with that of the `styled-components` package you're using. For instance, if you opt for `styled-components` version 5, it's necessary to use `@mui/styled-engine-sc` version 5. Similarly, if your preference is `styled-components` version 6, you'll need to upgrade `@mui/styled-engine-sc` to its version 6, which is currently in an alpha state.
:::

## Ready-to-use examples

We provide boilerplate examples of Create React App with Material UI and styled-components in both JavaScript and TypeScript:

<!-- #target-branch-reference -->

- [Material UI + CRA + styled-components (JavaScript)](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components)
- [Material UI + CRA + styled-components (TypeScript)](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts)

:::warning
`@emotion/react`, `@emotion/styled`, and `styled-components` are optional peer dependencies of `@mui/material`, so you need to install them yourself.
See the [Installation guide](/material-ui/getting-started/installation/) for more info.
:::
Original file line number Diff line number Diff line change
@@ -392,7 +392,7 @@ See [this tss-react doc](https://docs.tss-react.dev/api/makestyles#naming-the-st

You may end up with eslint warnings [like this one](https://user-images.githubusercontent.com/6702424/148657837-eae48942-fb86-4516-abe4-5dc10f44f0be.png) if you deconstruct more than one item.

Don't hesitate to disable `eslint(prefer-const)`, [like this](https://github.com/thieryw/gitlanding/blob/b2b0c71d95cfd353979c86dfcfa1646ef1665043/.eslintrc.js#L17) in a regular project, or [like this](https://github.com/InseeFrLab/onyxia/blob/a264ec6a6a7110cb1a17b2e22cc0605901db6793/package.json#L133) in a CRA.
Don't hesitate to disable `eslint(prefer-const)`, [like this](https://github.com/thieryw/gitlanding/blob/b2b0c71d95cfd353979c86dfcfa1646ef1665043/.eslintrc.js#L17) in a regular project.

#### withStyles()

21 changes: 2 additions & 19 deletions docs/src/modules/components/MaterialUIExampleCollection.js
Original file line number Diff line number Diff line change
@@ -42,28 +42,11 @@ const examples = [
src: '/static/images/examples/remix.svg',
},
{
name: 'Create React App',
label: 'View JavaScript',
tsLabel: 'View TypeScript',
link: 'https://github.com/mui/material-ui/tree/master/examples/material-ui-cra',
tsLink: 'https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-ts',
src: '/static/images/examples/cra.svg',
},
{
name: 'Tailwind CSS + Create React App',
name: 'Tailwind CSS + Vite',
label: 'View TypeScript',
link: 'https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-tailwind-ts',
link: 'https://github.com/mui/material-ui/tree/master/examples/material-ui-vite-tailwind-ts',
src: '/static/images/examples/tailwindcss.svg',
},
{
name: 'styled-components',
label: 'View JavaScript',
tsLabel: 'View TypeScript',
link: 'https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components',
tsLink:
'https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts',
src: '/static/images/examples/styled.png',
},
{
name: 'Preact',
label: 'View JavaScript',
23 changes: 0 additions & 23 deletions examples/material-ui-cra-styled-components-ts/.gitignore

This file was deleted.

Loading