Como Construir e Usar Plugins no Vite

Criar plugins Vite personalizados permite estender seu processo de build além da configuração padrão—seja para transformar tipos de arquivo personalizados, injetar lógica em tempo de build ou adicionar middleware ao servidor de desenvolvimento. Se você atingiu os limites da configuração padrão do Vite, construir seu próprio plugin é o próximo passo natural.

Este guia aborda os conceitos essenciais: como funciona a API de Plugins do Vite, os principais hooks de ciclo de vida que você usará e exemplos práticos para começar. Você aprenderá a criar, testar e publicar plugins que resolvem problemas reais no seu fluxo de trabalho de desenvolvimento.

Entendendo os Plugins Vite e sua Relação com o Rollup

Plugins Vite são objetos JavaScript que se conectam a diferentes estágios do processo de desenvolvimento e build. Eles são construídos sobre o sistema de plugins do Rollup, com hooks adicionais específicos para o servidor de desenvolvimento do Vite.

O Vite usa duas ferramentas de build diferentes internamente: o esbuild alimenta o servidor de desenvolvimento extremamente rápido com módulos ES nativos, enquanto o Rollup cuida do empacotamento de produção para saída otimizada. Esta arquitetura dual significa que seus plugins podem ter como alvo ambientes específicos usando a opção apply:

function myPlugin(): Plugin {
  return {
    name: 'my-plugin',
    apply: 'serve', // Executa apenas durante o desenvolvimento
    // ... hooks
  }
}

A maioria dos plugins Rollup funciona no Vite sem modificação. No entanto, se você precisar de funcionalidade do servidor de desenvolvimento—como adicionar middleware ou modificar HTML durante o desenvolvimento—você precisará de hooks específicos do Vite.

Estrutura Básica e Configuração de Plugins

Todo plugin Vite deve ter uma propriedade name e pelo menos uma função hook:

import type { Plugin } from 'vite'

function myPlugin(options?: MyPluginOptions): Plugin {
  return {
    name: 'vite-plugin-example',
    enforce: 'pre', // Opcional: controla a ordem de execução dos plugins
    apply: 'build', // Opcional: 'serve' | 'build' | undefined
    
    // Funções hook vão aqui
    transform(code, id) {
      if (id.endsWith('.custom')) {
        return transformCustomFile(code)
      }
    }
  }
}

A API de Plugins fornece definições TypeScript para todos os hooks e opções. Importe o tipo Plugin de ‘vite’ para segurança de tipo completa e autocompletar.

Hooks Essenciais de Ciclo de Vida na API de Plugins

Diferentes hooks são disparados em diferentes estágios do processo de build. Aqui estão os mais comumente usados:

Hooks de Configuração

• config: Modifica a configuração do Vite antes de ser resolvida
• configResolved: Acessa a configuração final resolvida

Hooks de Transformação

• transform: Modifica o código-fonte de módulos individuais
• load: Lógica de carregamento personalizada para tipos de arquivo específicos
• resolveId: Resolução de módulo personalizada

{
  name: 'transform-plugin',
  transform(code, id) {
    if (!id.includes('node_modules') && id.endsWith('.js')) {
      return {
        code: addCustomHeader(code),
        map: null // Suporte a source map
      }
    }
  }
}

Hooks de Servidor e Build

• configureServer: Adiciona middleware personalizado ao servidor de desenvolvimento
• transformIndexHtml: Modifica arquivos HTML
• writeBundle: Executa após o bundle ser escrito no disco

Cada hook tem tipos de retorno específicos e tempo de execução. O hook transform é executado para cada módulo, então mantenha-o rápido. Use load para operações custosas em arquivos específicos.

Construindo seu Primeiro Plugin Vite: Exemplos Práticos

Vamos construir três plugins práticos que demonstram padrões comuns:

Exemplo 1: Modificação de HTML

function htmlPlugin(): Plugin {
  return {
    name: 'html-modifier',
    transformIndexHtml(html) {
      return html.replace(
        '</head>',
        '<script>console.log("Injetado!")</script></head>'
      )
    }
  }
}

Exemplo 2: Middleware do Servidor de Desenvolvimento

function analyticsPlugin(): Plugin {
  return {
    name: 'request-analytics',
    configureServer(server) {
      server.middlewares.use((req, res, next) => {
        console.log(`${req.method} ${req.url}`)
        next()
      })
    }
  }
}

Exemplo 3: Geração de Arquivo em Tempo de Build

import path from 'path'
import fs from 'fs'
import type { Plugin, ResolvedConfig } from 'vite'

function generateManifest(): Plugin {
  let config: ResolvedConfig
  
  return {
    name: 'generate-manifest',
    configResolved(resolvedConfig) {
      config = resolvedConfig
    },
    writeBundle() {
      const manifestPath = path.join(config.build.outDir, 'manifest.json')
      fs.writeFileSync(manifestPath, JSON.stringify({
        timestamp: Date.now(),
        version: process.env.npm_package_version
      }))
    }
  }
}

Para depuração, use console.log nos seus hooks para rastrear a execução. Os métodos this.warn() e this.error() fornecem melhor relatório de erros do que lançar exceções.

Padrões Avançados e Melhores Práticas de Plugins

Módulos Virtuais

Crie módulos que não existem no disco:

const virtualModuleId = 'virtual:my-module'
const resolvedVirtualModuleId = '\0' + virtualModuleId

export function virtualPlugin(): Plugin {
  return {
    name: 'virtual-plugin',
    resolveId(id) {
      if (id === virtualModuleId) {
        return resolvedVirtualModuleId
      }
    },
    load(id) {
      if (id === resolvedVirtualModuleId) {
        return `export const msg = "from virtual module"`
      }
    }
  }
}

Otimização de Performance

Faça cache de transformações custosas:

const cache = new Map<string, string>()

function cachedTransform(): Plugin {
  return {
    name: 'cached-transform',
    transform(code, id) {
      if (cache.has(id)) return cache.get(id)
      
      const result = expensiveOperation(code)
      cache.set(id, result)
      return result
    }
  }
}

Teste seus plugins Vite usando Vitest com a API createServer para verificar o comportamento dos hooks isoladamente.

Publicando e Compartilhando seu Plugin

Siga estas convenções ao publicar:

1. Nomeie seu pacote vite-plugin-[nome]
2. Inclua "vite-plugin" nas keywords do package.json
3. Documente por que ele é específico do Vite (se usar hooks exclusivos do Vite)
4. Adicione prefixos de framework se for específico de framework: vite-plugin-vue-[nome]

Crie um README claro com instruções de instalação, exemplos de configuração e documentação da API. Envie seu plugin para o awesome-vite para alcançar a comunidade.

Conclusão

Construir plugins Vite personalizados dá a você controle completo sobre seu processo de build. Comece com transformações simples usando hooks como transform ou transformIndexHtml, depois expanda para padrões mais complexos conforme necessário. A API de Plugins é poderosa e ao mesmo tempo acessível—a maioria dos plugins requer apenas alguns hooks para resolver problemas específicos.

Para exploração mais profunda, consulte a documentação oficial de plugins do Vite e estude plugins populares no ecossistema. Sua próxima otimização de build ou melhoria de fluxo de trabalho pode estar a apenas um plugin de distância.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.