eslint-plugin-mui-v9

Plugin ESLint para migração e depreciações do MUI v9, com foco em capturar legado de v6/v7 que ainda quebra ou atrapalha projetos atuais.

Instalação

npm install -D eslint-plugin-mui-v9

Requisitos

• Node.js ^20.19.0 || ^22.13.0 || >=24.0.0
• ESLint >=10.0.0

O que este plugin cobre

• imports públicos vs deep imports
• Grid legado (GridLegacy, Grid2, Unstable_Grid2)
• props antigas de Grid
• migração de @mui/lab para @mui/material
• slots / slotProps
• TextField legado
• system props fora de sx
• Typography paragraph
• props legadas de Dialog e Modal
• APIs removidas do tema como MuiTouchRipple

Filosofia

• quebra real -> error
• orientação útil com baixo risco -> warn
• autofix só quando a transformação é segura
• validação por import/origem para reduzir falso positivo

Uso

Flat config

import muiV9 from "eslint-plugin-mui-v9"

export default [
  muiV9.configs.recommended,
]

Configuração manual

import muiV9 from "eslint-plugin-mui-v9"

export default [
  {
    plugins: {
      "mui-v9": muiV9,
    },
    rules: {
      "mui-v9/no-grid-legacy-props": "error",
      "mui-v9/prefer-slots-api": "warn",
    },
  },
]

Presets

| Preset | Descrição | |---|---| | recommended | Melhor equilíbrio para migração diária. Quebras em erro, sugestões em warning. | | strict | Tudo em erro para limpeza mais agressiva. | | flat/recommended | Alias do preset recomendado para flat config. | | flat/strict | Alias do preset estrito para flat config. |

Regras

Migrações e quebras

| Regra | O que detecta | Autofix | |---|---|---| | no-deep-imports | imports profundos e privados do MUI | ✅ | | no-legacy-icons | ícones Outline removidos, trocando por Outlined | ✅ | | no-grid-legacy-imports | GridLegacy, Grid2 e Unstable_Grid2 | ✅ | | no-grid-legacy-props | item, xs/sm/md/lg/xl e *Offset antigos | ✅ seguro | | lab-to-core-imports | componentes estáveis movidos de @mui/lab para @mui/material | ✅ | | no-listitem-button-prop | <ListItem button> legado | ❌ | | no-dialog-modal-legacy-props | onBackdropClick e disableEscapeKeyDown | ❌ | | no-system-props | system props fora de sx em componentes suportados | ✅ simples | | no-typography-paragraph | prop paragraph removida | ✅ simples | | no-muitouchripple-theme | MuiTouchRipple dentro de createTheme({ components }) | ❌ |

Sugestões de API

| Regra | O que detecta | Autofix | |---|---|---| | prefer-slots-api | components / componentsProps antigos | ✅ simples | | prefer-textfield-slot-props | InputProps, inputProps, SelectProps etc. no TextField | ✅ simples |

Exemplos rápidos

// antes
import Alert from "@mui/lab/Alert"

// depois
import Alert from "@mui/material/Alert"

// antes
<Typography paragraph>Texto</Typography>

// depois
<Typography sx={{ mb: 2 }}>Texto</Typography>

// antes
<Grid item xs={12} md={6} />

// depois
<Grid size={{ xs: 12, md: 6 }} />

// antes
<TextField InputProps={{ startAdornment: icon }} />

// depois
<TextField slotProps={{ input: { startAdornment: icon } }} />

Qualidade e validação

O pacote foi validado com:

• suíte Vitest + RuleTester
• npm run test
• npm run typecheck
• npm run build

Limites conhecidos

• autofix é conservador em casos com spread props
• cenários com sx ou slotProps já existentes podem exigir ajuste manual
• algumas migrações de lógica, como Dialog / Modal via onClose(_, reason), são apenas orientadas por mensagem

Licença

MIT