Padrões do Vite

Padrões de ferramenta de build e servidor de desenvolvimento para projetos Vite 8+. Abrange configuração, variáveis de ambiente, configuração de proxy, modo de biblioteca, pré-empacotamento de dependências e armadilhas comuns de produção.

Quando Usar

• Configurando vite.config.ts ou vite.config.js
• Configurando variáveis de ambiente ou arquivos .env
• Configurando proxy do servidor de desenvolvimento para backends de API
• Otimizando a saída do build (chunks, minificação, assets)
• Publicando bibliotecas com build.lib
• Solucionando problemas de pré-empacotamento de dependências ou interoperabilidade CJS/ESM
• Depurando erros de HMR, servidor de desenvolvimento ou build
• Escolhendo ou ordenando plugins do Vite

Como Funciona

• Modo de desenvolvimento serve arquivos de origem como ESM nativo — sem empacotamento. As transformações acontecem sob demanda por solicitação de módulo, é por isso que os inícios frios são rápidos e o HMR é preciso.
• Modo de build usa Rolldown (v7+) ou Rollup (v5–v6) para empacotar o aplicativo para produção com tree-shaking, code-splitting e minificação baseada em Oxc.
• Pré-empacotamento de dependências converte dependências CJS/UMD em ESM uma vez via esbuild e armazena o resultado em cache sob node_modules/.vite, para que inícios subsequentes pulem o trabalho.
• Plugins compartilham uma interface unificada entre desenvolvimento e build — o mesmo objeto de plugin funciona tanto para as transformações sob demanda do servidor de desenvolvimento quanto para o pipeline de produção.
• Variáveis de ambiente são inlined estaticamente no tempo de build. Variáveis prefixadas com VITE_ se tornam constantes públicas no bundle; tudo sem prefixo é invisível para o código do cliente.

Exemplos

Estrutura de Configuração

Configuração Básica

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { '@': new URL('./src', import.meta.url).pathname },
  },
})

Configuração Condicional

// vite.config.ts
import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig(({ command, mode }) => {
  const env = loadEnv(mode, process.cwd())   // VITE_ prefixed only (safe)

  return {
    plugins: [react()],
    server: command === 'serve' ? { port: 3000 } : undefined,
    define: {
      __API_URL__: JSON.stringify(env.VITE_API_URL),
    },
  }
})

Opções Chave de Configuração

Plugins

Plugins Essenciais

A maioria das necessidades de plugin são cobertas por um punhado de pacotes bem mantidos. Use-os antes de escrever os seus próprios.

Chamada crítica: vite build transpila, mas NÃO verifica tipos. Erros de tipo são enviados silenciosamente para produção, a menos que você adicione vite-plugin-checker ou execute tsc --noEmit em CI.

Criação de Plugins Personalizados

A criação é rara — a maioria das necessidades são cobertas por plugins existentes. Quando você precisar de um, comece inline em vite.config.ts e extraia apenas se for reutilizado.

// vite.config.ts — plugin inline mínimo
function myPlugin(): Plugin {
  return {
    name: 'my-plugin',                       // obrigatório, deve ser único
    enforce: 'pre',                           // 'pre' | 'post' (opcional)

…