Melhores extensões de formatação de Lua para VS Code

Lua não tem um padrão de estilo imposto. O parser da linguagem aceita qualquer indentação válida, qualquer espaçamento de operadores e qualquer disposição de blocos - o que significa que cada programador recorre aos seus próprios hábitos. Num projeto a solo, tudo bem. Numa base de código partilhada, um mod de jogo ou um repositório de scripts de equipa, a formatação inconsistente cria ruído em cada diff, atrasa a revisão de código e torna a depuração mais difícil do que precisa ser.

O custo de um estilo Lua inconsistente

Quando duas pessoas escrevem Lua de forma diferente - uma usa indentação de quatro espaços, outra usa tabs; uma espaça os operadores, a outra não - cada commit contém mudanças de formatação misturadas com mudanças de lógica. Os revisores gastam tempo a ler diffs de estilo em vez de diffs de lógica. Os conflitos de fusão disparam. Um formatador resolve isto normalizando cada ficheiro para o mesmo estilo ao salvar, tornando os diffs limpos e revistáveis.

• Indentação consistente - blocos `do`/`end`, `if`/`end`, `function`/`end` indentam sempre da mesma forma
• Espaçamento uniforme - espaços à volta de `=`, `+`, `-`, `..` e outros operadores aplicam-se de forma consistente
• Disciplina de linhas em branco - linhas em branco extra entre funções e dentro de ciclos são normalizadas automaticamente
• Tratamento legível de strings - concatenações longas e strings multilinha são dispostas de forma previsível
• Imposição em toda a equipa - um `.luarc.json` ou `stylua.toml` partilhado no controlo de versões garante que todos usam as mesmas regras

O Marketplace do VS Code tem várias extensões de Lua, mas apenas um punhado está ativamente mantido e oferece formatação fiável. Aqui estão as três que vale a pena conhecer em 2026, por ordem de recomendação.

1. Lua Language Server (sumneko.lua) - recomendada

O Lua Language Server, publicado como `sumneko.lua` no Marketplace do VS Code, é a ferramenta de desenvolvimento de Lua mais completa disponível para VS Code. Instala uma implementação completa do Language Server Protocol (LSP) que fornece diagnósticos, inferência de tipos, ir para definição, documentação ao passar o rato, pesquisa de referências em todo o workspace e um formatador integrado - tudo numa única extensão.

• Editor: sumneko (Tang Liu)
• ID no Marketplace: `sumneko.lua`
• Instalações ativas: 1M+ (em 2026)
• Versões de Lua suportadas: 5.1, 5.2, 5.3, 5.4, LuaJIT
• Formatador: Integrado, configurado via `.luarc.json`
• Formatação ao salvar: Suportada nativamente
• Ideal para: A maioria dos fluxos de trabalho de Lua - scripting de jogos, ferramentas autónomas, sistemas embebidos

2. StyLua (jq-steuersoftware.stylua) - alternativa opinativa

StyLua é um formatador de código Lua opinativo, escrito em Rust e inspirado no Prettier. A extensão do VS Code envolve o binário do StyLua e integra-o como formatador de documentos. Ao contrário do Lua Language Server, o StyLua é apenas um formatador - não fornece diagnósticos, documentação ao passar o rato nem conclusão de código. O que fornece é um estilo determinista e sem debate: concorda com o estilo e compromete-se com ele, da mesma forma que o Prettier funciona para JavaScript.

• Editor: jq-steuersoftware
• ID no Marketplace: `jq-steuersoftware.stylua`
• Versões de Lua suportadas: 5.1, 5.2, 5.3, 5.4, LuaJIT, Luau (Roblox)
• Ficheiro de config: `stylua.toml` (opcional - funciona bem com os padrões)
• Formatação ao salvar: Suportada nativamente
• Ideal para: Projetos novos, equipas que querem formatação sem config à maneira do Prettier, desenvolvimento Luau Roblox

3. LuaFormatter (Koihik.vscode-lua-format) - opção legada configurável

LuaFormatter é uma extensão mais antiga que envolve a ferramenta de linha de comandos `lua-format`. Fornece configuração extensa - pode ajustar individualmente a largura de indentação, comprimento máximo de linha, espaçamento de operadores, indentação de continuação e muitas outras regras. Esse nível de controlo torna-a útil ao migrar uma base de código existente que já tem uma convenção de estilo estabelecida que o formatador deve respeitar. Contudo, o desenvolvimento abrandou desde o surgimento do StyLua, e o binário `lua-format` requer um passo de instalação separado em algumas plataformas.

• Editor: Koihik
• ID no Marketplace: `Koihik.vscode-lua-format`
• Ficheiro de config: `.lua-format` (formato YAML)
• Ideal para: Bases de código existentes com requisitos de estilo complexos, controlo granular por regra
• Ressalva: Requer o binário `lua-format` instalado separadamente em Linux/Mac

Instalar o Lua Language Server leva menos de dois minutos. Aqui está o caminho de configuração completo de uma instalação fresca do VS Code até à formatação ao salvar a funcionar.

{
  "Lua.runtime.version": "Lua 5.4",
  "Lua.diagnostics.globals": ["myGlobal", "anotherGlobal"],
  "Lua.format.enable": true,
  "Lua.format.defaultConfig": {
    "indent_style": "space",
    "indent_size": "4",
    "max_line_length": "120",
    "trailing_table_separator": "smart"
  }
}

{
  "editor.formatOnSave": true,
  "[lua]": {
    "editor.defaultFormatter": "sumneko.lua"
  }
}

A formatação ao salvar é a definição individual de maior impacto que pode ativar para o desenvolvimento de Lua no VS Code. Uma vez ativa, nunca aciona o formatador manualmente - corre sempre que prime Ctrl+S. Eis como configurá-la corretamente para diferentes cenários de equipa.

Definições de utilizador vs. de espaço de trabalho

O VS Code tem dois níveis de definições: ao nível do utilizador (aplicam-se a todos os projetos) e ao nível do espaço de trabalho (aplicam-se apenas ao projeto atual). Para formatação, o nível do espaço de trabalho é quase sempre a escolha certa - garante que cada colaborador do projeto usa o mesmo formatador, independentemente das preferências pessoais. As definições de espaço de trabalho vivem em `.vscode/settings.json` na raiz do projeto e devem ser commitadas ao controlo de versões.

Formatação ao salvar com StyLua

A extensão do StyLua para VS Code usa o mesmo mecanismo de formatação ao salvar. Defina o formatador padrão como `jq-steuersoftware.stylua` nas definições do espaço de trabalho. O StyLua lê um ficheiro de config `stylua.toml` se existir - é aí que define column_width, indent_type, indent_width e quote_style. Sem `stylua.toml`, o StyLua aplica as suas regras padrão (indentação de dois espaços, linhas de 120 caracteres, aspas duplas).

column_width = 120
line_endings = "Unix"
indent_type = "Spaces"
indent_width = 4
quote_style = "AutoPreferDouble"
call_parentheses = "Always"

Excluir ficheiros da formatação

Alguns ficheiros Lua não devem ser reformatados - bibliotecas de terceiros, código gerado ou scripts minificados. No StyLua, adicione um ficheiro `.styluaignore` (mesma sintaxe do `.gitignore`) para excluir caminhos. No Lua Language Server, pode delimitar o formatador a diretórios específicos com a definição `Lua.workspace.ignoreDir` no `.luarc.json`.

Os dois formatadores de Lua mais discutidos são o LuaFormatter e o StyLua. Adotam filosofias de formatação fundamentalmente diferentes, e a escolha certa depende do contexto do seu projeto. Aqui está uma comparação direta.

Se está a começar um projeto novo, escolha o StyLua e faça commit da config. Se herdou uma base de código com estilo existente, configure o LuaFormatter para o respeitar. Nunca misture ambos os formatadores na mesma base de código.

Lua Language Server vs. StyLua: podem coexistir?

O Lua Language Server e o StyLua servem propósitos principais diferentes - o Lua LS é um language server completo para diagnósticos e intellisense, o StyLua é apenas um formatador. Podem coexistir na mesma configuração do VS Code: instale o Lua LS para diagnósticos e inteligência de código e defina o StyLua como formatador padrão para formatação de documentos. Esta combinação dá-lhe o melhor das duas ferramentas. Configure-o no .vscode/settings.json definindo o defaultFormatter de [lua] como jq-steuersoftware.stylua mantendo o Lua LS instalado pelas funcionalidades LSP.

Formatador integrado do Lua LS: quando chega

Para a maioria dos programadores, o formatador integrado do Lua Language Server é suficiente e elimina a necessidade de instalar uma segunda extensão. Cobre todas as tarefas de formatação padrão e integra-se limamente com `.luarc.json`. A razão principal para adicionar o StyLua por cima é se a sua equipa quiser uma imposição de estilo mais forte (p. ex. impor estilo de aspas ou convenções de parênteses em chamadas) que o formatador do Lua LS não suporta atualmente.

As extensões do VS Code são a solução certa para o desenvolvimento do dia a dia. Mas há cenários em que precisa de formatar código Lua sem instalar nada de todo - e é aí que uma ferramenta baseada em navegador preenche a lacuna com limpeza.

Quando não pode instalar extensões

• Máquinas partilhadas ou bloqueadas - estações corporativas, computadores de laboratório ou ambientes de CI onde não pode instalar extensões do VS Code
• Limpeza pontual - um colega envia-lhe um excerto de Lua para rever e quer formatá-lo sem mudar de contexto
• Revisão de código sem ambiente de dev - rever um pull request numa máquina onde a sua configuração completa de Lua não está configurada
• Verificações de integração - confirmar que um ficheiro parece bem formatado antes do commit sem esperar que toda a toolchain instale
• Inspeção de código minificado - tem uma saída do minificador de Lua e quer reformatá-la para leitura

O Formatador de Lua da Aback Tools cobre todos estes casos. Cole o seu código Lua no editor e o formatador aplica indentação consistente, normaliza o espaçamento de operadores e limpa linhas em branco no seu navegador - sem registo, sem instalação e sem dados a saírem do seu dispositivo.

Ferramentas Lua online complementares

A formatação é um passo num fluxo completo de qualidade de código Lua. Várias outras ferramentas de navegador cobrem tarefas adjacentes que precisará regularmente junto com a formatação:

• **Lua Beautifier** - foca-se em melhorar a disposição visual de código sintaticamente correto mas difícil de ler
• **Validador de sintaxe de Lua** - verifica o código em busca de erros ao nível do parser com diagnósticos por linha antes de o executar
• **Minificador de Lua** - remove comentários, espaços e linhas em branco para deployment em produção e reduzir o tamanho do script
• **Ofuscador de Lua** - renomeia variáveis e codifica strings para proteger scripts de jogo de engenharia inversa casual
• **Ajudante de desofuscação de Lua** - melhora a legibilidade de scripts ofuscados para fluxos de depuração e análise

Um formatador trata dos espaços em branco, mas a boa qualidade de código Lua vai mais longe. Estas práticas trabalham junto com o seu formatador para manter bases de código Lua consistentes, legíveis e sustentáveis a qualquer escala.

Faça commit da config do formatador ao controlo de versões

Um `.luarc.json` para o Lua LS, `stylua.toml` para o StyLua ou `.lua-format` para o LuaFormatter devem viver na raiz do projeto e ser commitados ao seu repositório. Isto garante que cada colaborador - e cada execução de CI - usa regras de formatação idênticas. Sem uma config commitada, cada programador recorre às definições da sua própria extensão e a divergência de formatação volta a insinuar-se ao longo do tempo.

Adicione uma verificação de formatação em CI

A formatação ao salvar no VS Code só ajuda quem usa VS Code com a extensão instalada. Uma verificação em CI deteta o que escapar - colaboradores com outros editores, ficheiros rapidamente corrigidos ou código Lua gerado. A flag `--check` do StyLua sai com código diferente de zero se algum ficheiro não estiver corretamente formatado, tornando fácil falhar um job do GitHub Actions ou GitLab CI por violações de estilo.

Separe commits de formatação de commits de lógica

Se está a introduzir um formatador numa base de código existente pela primeira vez, corra o formatador sobre todos os ficheiros num único commit dedicado sem outras mudanças. Etiquete-o com clareza (p. ex. `chore: apply lua formatter to all files`). Isto mantém o ruído de formatação num commit para que todos os commits seguintes contenham apenas mudanças de lógica - e o `git blame` continua útil em cada linha.

Use nomenclatura consistente para variáveis locais

Os formatadores não renomeiam variáveis - essa é a sua responsabilidade. A comunidade Lua segue amplamente `snake_case` para variáveis e funções e `PascalCase` para tabelas ao nível de módulo e construções de tipo classe. Concorde uma convenção com a sua equipa e documente-a no `CONTRIBUTING.md` do seu projeto. Se trabalha com Roblox Luau, o guia de estilo do Roblox especifica `PascalCase` para instâncias e serviços e `camelCase` para variáveis locais - tenha consciência da distinção antes de aplicar convenções da comunidade Lua às cegas.