Atualizando o Vite no Laravel: do inotify do kernel ao manifest.json

Atualizando o Vite no Laravel: do inotify do kernel ao manifest.json#

Atualizar ferramentas de front-end em projetos Laravel frequentemente parece apenas uma troca de versões no package.json. No entanto, em ambientes de produção, servidores compartilhados ou containers, o processo envolve chamadas de sistema (syscalls), sincronização de portas no HMR e a resolução de arquivos de manifesto pelo PHP em tempo de execução.

Abaixo, documento o passo a passo da atualização do Vite, os gargalos de kernel mapeados e as soluções práticas para evitar quebras em produção.

1. As três camadas da integração#

O ecossistema do Vite no Laravel é composto por três peças integradas:

1. Vite Core (vite): O motor de build baseado em Rollup e Esbuild.
2. Laravel Vite Plugin (laravel-vite-plugin): A ponte que gerencia o servidor HMR (Hot Module Replacement) e orquestra a geração de assets.
3. Laravel Framework (laravel/framework): A camada PHP que interpreta as diretivas @vite no Blade a partir de public/build/manifest.json ou do arquivo temporário hot.

Se houver descompasso de versões entre essas partes, a aplicação pode quebrar durante o build ou falhar ao carregar scripts e estilos no navegador.

2. Procedimento de atualização no terminal#

Para garantir uma árvore de dependências limpa e sem artefatos legados:

# 1. Backup do arquivo de dependências
cp package.json package.json.bak

# 2. Atualizar os pacotes principais
npm install vite@latest laravel-vite-plugin@latest --save-dev

# 3. Limpar dependências antigas e reinstalar
rm -rf node_modules package-lock.json
npm install

3. Gargalos de kernel e chamadas de sistema no Linux#

Durante a subida de versões do Vite, alguns comportamentos do Node.js impactam diretamente o kernel do Linux:

A. Esgotamento de observadores do inotify (fs.inotify.max_user_watches)#

O Vite utiliza bibliotecas como o chokidar para observar mudanças em arquivos. Em ambientes com muitos arquivos, o limite padrão de instâncias de inotify do kernel pode ser atingido.

• Sintoma: O comando npm run dev roda normalmente, mas as alterações nos arquivos .blade.php ou .vue não atualizam o navegador via HMR.
• Checagem do limite atual:

cat /proc/sys/fs/inotify/max_user_watches

• Ajuste temporário e permanente:

sudo sysctl -w fs.inotify.max_user_watches=524288
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf

B. Conflito de resolução ipv6 no HMR#

A partir do Node.js 17+, o método dns.lookup prioriza endereços IPv6 (::1). Se o PHP-FPM estiver escutando estritamente em IPv4 (127.0.0.1), a diretiva @vite pode falhar ao consultar o servidor HMR.

• Solução: Force o host explícito em 127.0.0.1 no vite.config.js.

4. Configuração ajustada do vite.config.js#

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true, // Recarrega o navegador automaticamente em alterações no Blade
        }),
    ],
    server: {
        host: '127.0.0.1',
        // Em ambientes virtualizados ou containers Docker, habilite polling:
        watch: {
            usePolling: true,
        },
    },
});

5. Rastreamento e diagnóstico em baixo nível#

Se o build falhar ou os arquivos compilados não forem carregados, você pode auditar o comportamento real do processo:

Diagnóstico de permissões e paths com strace#

strace -f -e trace=openat,write npm run build 2>&1 | grep -E "EACCES|ENOENT"

Validação do ciclo do manifest.json#

O Laravel resolve assets lendo public/build/manifest.json. Se o framework retornar Vite manifest not found:

1. Certifique-se de que o comando npm run build gerou o arquivo no diretório public/build/.
2. Em caso de dúvidas sobre qual caminho o PHP está acessando, inspecione os descritores de arquivo abertos:

lsof -p <PID_DO_PHP>

Teste do socket do servidor HMR#

Para checar se a porta do servidor de desenvolvimento está aberta localmente:

netstat -tulpn | grep 5173

6. Casos de borda em ambientes de produção#

1. OOM Killer do Linux: A etapa de bundling com Esbuild consome picos agressivos de memória RAM. Em servidores com limites rígidos, o processo pode ser finalizado silenciosamente pelo kernel. Verifique com dmesg | grep -i oom.
2. Symlinks na pasta pública: Se a pasta pública for um link simbólico (ex: public_html -> public), certifique-se de que caminhos relativos no Vite apontem para a raiz correta do projeto.
3. Versão do Node.js: O Vite moderno exige Node.js 18+ ou 20+. Use o nvm para evitar que scripts executem uma versão legada do sistema operacional.

Boas práticas ao atualizar o Vite no Laravel#

1. Monitore o manifest.json: Nunca envie alterações para produção sem verificar se o arquivo public/build/manifest.json foi gerado e comitado adequadamente.
2. Ajuste o inotify preventivamente: Aumentar max_user_watches evita comportamentos intermitentes de recarregamento em desenvolvimento.
3. Defina o host IPv4 explicitamente: Configurar host: '127.0.0.1' no servidor de desenvolvimento elimina incompatibilidades entre a resolução do Node.js e o backend PHP.

Veja também

Desenvolvimento Bun, Node.js e PM2 em produção: quando usar, quando evitar e trade-offs arquiteturais

Desenvolvimento Como integrar o IndexNow: indexação instantânea para sites, SaaS e APIs

Desenvolvimento Como diagnosticar o erro 'no LS client available for routing key' no Linux

Este post está licenciado sob CC BY-NC.