Solução de problemas comuns no shadcn/ui: conflitos de estilo, componentes que não renderizam e erros de tipo

Você olha para o componente de botão na tela: ele deveria ser um belo botão azul, mas agora parece apenas um button HTML comum, sem sequer ter cantos arredondados.

Nos últimos três meses, encontrei mais armadilhas do que escrevi código. Conflitos de estilo, falhas na renderização de componentes, erros do TypeScript — esses problemas parecem ser uma “especialidade” do shadcn/ui, e todo projeto novo acaba encontrando alguns deles.

Hoje reuni esses problemas comuns e suas soluções. Espero que este guia ajude você a evitar alguns desvios.

Como diagnosticar conflitos de estilo

Conflitos de estilo são o problema mais comum e representam cerca de 40% de todos os casos. Há alguns motivos principais.

Conflitos entre variáveis CSS

O shadcn/ui usa variáveis CSS para gerenciar as cores do tema. Essas variáveis são definidas no globals.css:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 2%;
}

É aí que o problema pode começar. Se o projeto já tiver uma configuração de tema própria ou se você tiver alterado as cores do Tailwind antes de instalar o shadcn/ui, as duas configurações podem entrar em conflito.

Como diagnosticar?

Primeiro, abra o globals.css e confira se todas as variáveis CSS estão presentes. Depois, verifique a configuração colors do tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        border: "hsl(var(--border))",
        input: "hsl(var(--input))",
        ring: "hsl(var(--ring))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
      },
    },
  },
}

Os dois lados precisam corresponder. Se uma variável estiver ausente, o estilo associado a ela não será aplicado.

Minha experiência: antes de instalar o shadcn/ui, faça backup do tailwind.config.js e do globals.css. Quando a instalação terminar, compare os dois arquivos e restaure manualmente qualquer configuração que tenha sido sobrescrita.

Conflito entre Shadow DOM e Tailwind

Esse problema é curioso. O Shadow DOM foi criado para isolar estilos, mas as classes do Tailwind não atravessam seus limites.

O cenário mais típico envolve o componente Dialog. O DialogContent usa um Portal para renderizar em document.body, saindo do escopo do Shadow DOM — e todos os estilos desaparecem.

Há duas soluções:

A primeira é simplesmente não usar Shadow DOM:

const MyDialogWC = r2wc(MyDialog, {
  shadow: null  // Desativa o Shadow DOM
});

Assim, o Portal volta a funcionar normalmente, mas o isolamento de estilos deixa de existir. Você terá de gerenciar os estilos globais manualmente e tomar cuidado com conflitos entre nomes de classes.

A segunda é usar a Safelist para forçar a inclusão das classes:

// tailwind.config.js
module.exports = {
  safelist: [
    'bg-primary',
    'text-primary-foreground',
    'hover:bg-primary/90',
    'bg-red-500',
    'h-9',
    'h-10',
    'px-3',
    'px-4',
  ],
}

Essa abordagem garante que os estilos sejam gerados, mas a Safelist aumenta o tamanho do arquivo CSS. É preciso avaliar essa troca.

Convivência com outras bibliotecas de UI

Se o projeto já usa MUI (Material-UI) e você quer migrar para shadcn/ui, pode encontrar conflitos de estilo.

A origem do problema é o Preflight do Tailwind, que redefine todos os estilos padrão do navegador. Os estilos do MUI também podem ser afetados por essa redefinição, fazendo com que os componentes sejam exibidos de forma incorreta.

Uma tentativa comum:

Algumas pessoas desativam o Preflight:

module.exports = {
  corePlugins: {
    preflight: false,  // Desativa o Preflight
  },
}

Isso, porém, tem um efeito colateral: os estilos do Tailwind também são afetados. Alguns componentes podem deixar de ser exibidos corretamente.

Uma solução melhor:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Use o recurso prefix do Tailwind para adicionar um prefixo a todas as classes:

module.exports = {
  prefix: 'tw-',  // Todas as classes passam a ter nomes como tw-bg-blue-500
}

Assim, as classes do Tailwind não entram em conflito com as classes do MUI. Em compensação, você precisa adicionar tw- manualmente a cada nome de classe, o que dá um pouco mais de trabalho.

Minha sugestão: se o projeto já tem muitos componentes MUI, não tente migrar tudo de uma vez. Primeiro, use o prefixo para permitir a convivência das duas bibliotecas. Adote shadcn/ui nos componentes novos e migre os antigos gradualmente.

Configuração do Tailwind sobrescrita

Já caí nessa armadilha várias vezes.

Depois de executar npx shadcn-ui@latest init, o arquivo de configuração do Tailwind pode ser sobrescrito. O problema afeta especialmente o array plugins: se você já tinha configurado @tailwindcss/forms ou outro plugin, ele pode desaparecer.

Os sintomas são bem evidentes: os campos de formulário de repente ficam com uma aparência estranha ou alguns componentes perdem todos os estilos.

Etapas de diagnóstico:

1. Abra o backup do tailwind.config.js feito antes da instalação
2. Compare-o com o arquivo de configuração após a instalação
3. Restaure os plugins que desapareceram:

module.exports = {
  // ... Outras configurações
  plugins: [
    require("@tailwindcss/forms"),  // Restaura o plugin
    require("tailwindcss-animate"),
  ],
}

Medida preventiva: faça backup dos arquivos de configuração antes de instalar o shadcn/ui. Outra opção é usar um script específico de gerenciamento de configuração para registrar todos os plugins.

Como diagnosticar componentes que não renderizam

Os estilos parecem corretos, mas o componente simplesmente não aparece? Essa situação também é bastante comum.

Caminho incorreto em content

O Tailwind precisa saber quais arquivos usam suas classes para poder gerar o CSS correspondente. Isso é definido no campo content do tailwind.config.js.

Normalmente, o problema é que o diretório de componentes do shadcn/ui não foi incluído.

Verifique a configuração:

module.exports = {
  content: [
    './src/app/**/*.{ts,tsx}',
    './src/components/**/*.{ts,tsx}',  // Este caminho é obrigatório
    './app/**/*.{ts,tsx}',
    './pages/**/*.{ts,tsx}',
  ],
}

Se você colocou os componentes em uma biblioteca de UI dentro de node_modules, também será necessário adicionar:

content: [
  // ... Outros caminhos
  './node_modules/@your-ui-lib/**/*.{ts,tsx}',
]

Minha experiência: sempre que criar um novo diretório de componentes, lembre-se de adicionar o caminho à configuração content. Caso contrário, o Tailwind não examinará esses arquivos e as classes não serão geradas.

Problema no caminho do globals.css

O shadcn/ui precisa de um arquivo CSS para definir as variáveis do tema. O caminho desse arquivo fica configurado no components.json.

O problema mais comum é um caminho incorreto ou a existência de vários arquivos globals.css.

Como diagnosticar:

Primeiro, verifique o components.json:

{
  "style": "default",
  "css": "src/app/globals.css",  // Este caminho
}

Depois, confirme:

1. Esse arquivo realmente existe?
2. Há apenas um globals.css no projeto?
3. O globals.css foi importado corretamente no arquivo principal?

Se houver vários arquivos globals.css, remova os extras e mantenha apenas um.

Verifique a importação:

Em um projeto Next.js, o globals.css deve ser importado em app/layout.tsx ou pages/_app.tsx:

import '@/app/globals.css'  // Ou './globals.css'

Sem essa importação, as variáveis CSS não entram em vigor e todos os estilos dos componentes desaparecem.

Variáveis CSS não definidas

Às vezes, o arquivo globals.css existe, mas as variáveis não foram definidas.

O exemplo mais típico é o modo escuro. Você muda para dark mode e percebe que as cores dos componentes estão incorretas — possivelmente porque as variáveis CSS do modo escuro não foram configuradas.

Verifique o globals.css:

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 2%;
}

As variáveis sob a classe .dark precisam estar definidas. Caso contrário, os componentes não receberão os estilos do modo escuro.

Caso específico do Tailwind v4:

Se você usa Tailwind v4, a configuração é diferente:

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
}

Esse mapeamento com @theme inline é obrigatório. Sem ele, o Tailwind v4 não reconhece essas variáveis.

Uso incorreto de maiúsculas e minúsculas no caminho de importação

Já caí nessa armadilha duas vezes.

No Windows, os nomes de arquivos não diferenciam maiúsculas de minúsculas, enquanto no Linux e no Mac essa diferença é considerada. Por isso, o desenvolvimento local pode funcionar, mas a implantação em produção falha.

O sintoma típico é o componente renderizar localmente, mas o servidor não encontrar o módulo.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Erro típico:

// ❌ Incorreto: Button com B maiúsculo
import { Button } from "@/components/ui/Button"

// ✅ Correto: button com b minúsculo
import { Button } from "@/components/ui/button"

Os nomes dos arquivos de componentes do shadcn/ui usam letras minúsculas. O caminho de importação também precisa usar letras minúsculas.

Como diagnosticar:

Revise todas as instruções de importação dos componentes e confirme que cada caminho corresponde exatamente ao nome real do arquivo. Preste atenção especial às mensagens de erro do ambiente de produção.

Como diagnosticar erros de tipo do TypeScript

Erros do TypeScript aparecem com menos frequência, mas podem dar bastante trabalho.

Erro de tipo na propriedade variant

O componente Button do shadcn/ui tem uma propriedade variant, usada para alternar o estilo do botão (default, destructive, outline e outros).

A mensagem de erro costuma ser:

Type '{ variant: string }' is not assignable to type 'IntrinsicAttributes & ButtonProps'.
Property 'variant' does not exist on type 'IntrinsicAttributes & ButtonProps'.

Origem do problema:

A propriedade variant não foi exportada corretamente na definição de tipo do componente Button.

Como diagnosticar:

Abra components/ui/button.tsx e verifique a definição de tipo de variant:

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
      },
    },
  }
)

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  // VariantProps precisa estar presente aqui
}

Se VariantProps<typeof buttonVariants> estiver ausente, o tipo da propriedade variant também desaparecerá.

Minha experiência: ao encontrar esse erro, comece verificando a definição de tipo do componente. Confirme que VariantProps foi herdado corretamente.

Incompatibilidade entre versões do React

Se você usa React 19 e algumas dependências ainda não são compatíveis com essa versão, podem surgir erros de tipo.

A mensagem de erro costuma ser:

npm error ERESOLVE unable to resolve dependency tree
npm error Found: [email protected]

Há duas soluções:

A primeira é forçar a instalação:

npm install --legacy-peer-deps
# Ou
npm install --force

Isso ignora os requisitos de versão das peer dependencies, mas pode causar problemas de compatibilidade.

A segunda é fazer downgrade do React:

npm install react@18 react-dom@18

Use React 18 e espere as dependências serem atualizadas antes de fazer o upgrade.

Minha sugestão: React 18 é mais estável para projetos novos. Considere a atualização apenas quando shadcn/ui e as demais dependências forem compatíveis com React 19.

Problemas de tipo com React Hook Form

Ao usar o componente Form do shadcn/ui junto com React Hook Form e Zod, podem surgir problemas de mapeamento de tipos.

A mensagem de erro costuma ser:

Type 'info.${number}.fileName' is not assignable to type '"info" | "info.0" | "info.0.fileName"'

Esse é um problema de tipo em campos de formulário dinâmicos. O tipo do Zod Schema não corresponde ao tipo da propriedade name do FormField.

Solução:

Confirme que o tipo do Schema foi inferido corretamente:

const formSchema = z.object({
  email: z.string().email(),
  password: z.string(),
})

type FormValues = z.infer<typeof formSchema>  // Esta inferência de tipo é obrigatória

const form = useForm<FormValues>({
  resolver: zodResolver(formSchema),
})

A propriedade name do FormField passará a corresponder automaticamente aos nomes dos campos do Schema.

Minha experiência: formulários dinâmicos, como os que usam useFieldArray, têm tipos mais complexos. É preciso revisar com cuidado a definição do Zod Schema e a inferência de tipos do TypeScript.

Dependências de tipos ausentes

Às vezes, o TypeScript informa um erro porque @types/react ou @types/react-dom não está instalado.

A mensagem pode ser:

Could not find a declaration file for module 'react'

Solução:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

npm install -D @types/react @types/react-dom

Depois da instalação, reinicie o servidor do TypeScript. No VSCode, use Ctrl+Shift+P e digite “TypeScript: Restart TS Server”.

Medida preventiva: instale as dependências de tipos logo no início de um projeto novo. Não espere o erro aparecer para perceber que estão faltando.

Boas práticas e medidas preventivas

Depois de encontrar tantas armadilhas, reuni algumas formas de evitá-las.

Boas práticas de gerenciamento de configuração

Faça backup dos arquivos de configuração:

Antes de instalar o shadcn/ui ou alterar a configuração do Tailwind, faça um backup:

cp tailwind.config.js tailwind.config.js.backup
cp globals.css globals.css.backup

Depois da instalação, compare as diferenças e mescle as configurações manualmente.

Use um único arquivo de configuração:

Use apenas um tailwind.config.js e um globals.css por projeto. Não crie vários arquivos de configuração, pois isso facilita o surgimento de conflitos.

Configure todos os caminhos necessários:

A configuração content deve incluir todos os diretórios de componentes:

content: [
  './src/**/*.{ts,tsx}',        // O curinga cobre todos os diretórios
  './app/**/*.{ts,tsx}',
  './pages/**/*.{ts,tsx}',
  './components/**/*.{ts,tsx}',
]

Gerenciamento de versões das dependências

Verifique as peerDependencies:

Antes de instalar uma dependência nova, confira suas peerDependencies:

npm info <package> peerDependencies

Se a dependência exigir React 18, mas o projeto estiver usando React 19, será necessário avaliar a compatibilidade.

Atualize regularmente as dependências de tipos:

npm update @types/react @types/react-dom

Mantenha as declarações de tipo sincronizadas com a versão do React.

Estratégia de testes

Teste logo após a instalação:

Assim que terminar de instalar o shadcn/ui, teste os estilos:

1. Crie uma página simples com alguns componentes do shadcn/ui
2. Confira se os estilos são exibidos corretamente
3. Teste a alternância para o modo escuro
4. Execute a verificação de compilação do TypeScript

Teste no ambiente de produção:

Funcionar no ambiente local não significa que tudo também funcionará em produção:

npm run build
npm run preview

Gere o build e abra a prévia para conferir se os estilos e os tipos estão corretos.

Conclusão

Depois de tudo isso, os problemas mais comuns do shadcn/ui se concentram em três áreas:

1. Conflitos de estilo: arquivos de configuração sobrescritos, conflitos entre variáveis CSS e convivência com outras bibliotecas de UI
2. Componentes que não renderizam: caminhos incorretos em content, problemas no caminho do globals.css e diferenças entre maiúsculas e minúsculas nos caminhos de importação
3. Erros de tipo do TypeScript: ausência do tipo da propriedade variant, incompatibilidade entre versões do React e dependências de tipos ausentes

Quando surgir um problema, siga esta ordem de diagnóstico:

1. Primeiro, verifique os arquivos de configuração (tailwind.config.js e globals.css)
2. Depois, confira os caminhos (content e caminhos de importação)
3. Por fim, revise as definições de tipo (tipos dos componentes e versões das dependências)

Se você está começando a usar shadcn/ui, vale a pena testar todo o processo primeiro em um projeto vazio. Depois de conhecer a configuração e os problemas mais frequentes, adote a biblioteca em um projeto real.

O shadcn/ui é muito útil, mas sua configuração pode mesmo ser um pouco complexa. Quando você domina essas técnicas de diagnóstico, os problemas deixam de assustar.