Configuração

O Oxfmt funciona logo de saída, mas a maioria das equipes versiona um arquivo de configuração para manter a formatação alinhada entre execuções locais, editores e CI.

Esta página cobre configuração de projeto: opções de formatação, padrões de ignorar e recursos experimentais.

Criar um arquivo de configuração

Para gerar uma config inicial no diretório atual:

oxfmt --init

O Oxfmt procura automaticamente estes arquivos a partir do diretório do arquivo formatado e sobe pela árvore:

• .oxfmtrc.json
• .oxfmtrc.jsonc
• oxfmt.config.ts

Próximo de cada arquivo formatado vence o arquivo de config mais próximo. Assim você pode colocar configurações diferentes em níveis distintos do projeto. Por exemplo, uma na raiz do repositório e outra dentro de um subdiretório:

my-repo/
├── oxfmt.config.ts         # padrão para o repositório inteiro
├── src/
│   └── app.ts              # usa a config da raiz
└── packages/
    └── fancy-app/
        ├── .oxfmtrc.json   # sobrescritas para este pacote
        └── index.ts        # usa packages/fancy-app/.oxfmtrc.json

Se não precisar de config aninhada, passe --disable-nested-config para buscar só a partir do diretório de trabalho atual. É mais rápido porque o Oxfmt resolve a config uma vez em vez de por arquivo.

Também dá para passar config explícita com -c, o que desativa a busca aninhada. Aceita qualquer formato suportado (.json, .jsonc, .ts, .mts, .cts, .js, .mjs, .cjs):

oxfmt -c path/to/yourconfig.json

Um JSON mínimo:

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80
}

Arquivos JS/TS usam export default. defineConfig é opcional, mas ajuda com tipos e autocomplete no editor:

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});

Formato do arquivo

O arquivo é um objeto JSON. Campos frequentes no nível superior:

• printWidth: largura máxima da linha (padrão: 100)
• tabWidth: espaços por nível de indentação (padrão: 2)
• useTabs: usar tabs em vez de espaços (padrão: false)
• semi: ponto e vírgula ao fim das declarações (padrão: true)
• singleQuote: aspas simples (padrão: false)
• trailingComma: vírgulas finais em estruturas multilinha (padrão: "all")
• ignorePatterns: globs para excluir da formatação
• sortImports: ordenação de imports (desligada por padrão)
• sortTailwindcss: ordenação de classes Tailwind (desligada por padrão)
• sortPackageJson: ordenação de package.json (ligada por padrão)

Lista completa em referência do arquivo de config.

Schema JSON

Inclua $schema para validação e autocomplete no editor:

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json"
}

.editorconfig

O Oxfmt lê estas propriedades do .editorconfig:

• end_of_line → endOfLine
• indent_style → useTabs
• indent_size → tabWidth
• max_line_length → printWidth
• insert_final_newline → insertFinalNewline

Suportadas seção raiz e sobrescrita por globs.

[*]
indent_size = 4

[*.{js,ts}]
indent_size = 2

Só conta o .editorconfig mais próximo do diretório atual:

• root = true não é honrado
• Arquivos .editorconfig aninhados não são mesclados

Sobrescrita (overrides)

Use overrides para opções diferentes em arquivos específicos:

.oxfmtrc.json

{
  "printWidth": 100,
  "overrides": [
    {
      "files": ["*.test.js", "*.spec.ts"],
      "options": {
        "printWidth": 120
      }
    },
    {
      "files": ["*.md", "*.html"],
      "excludeFiles": ["*.min.js"],
      "options": {
        "tabWidth": 4
      }
    }
  ]
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 100,
  overrides: [
    {
      files: ["*.test.js", "*.spec.ts"],
      options: {
        printWidth: 120,
      },
    },
    {
      files: ["*.md", "*.html"],
      excludeFiles: ["*.min.js"],
      options: {
        tabWidth: 4,
      },
    },
  ],
});

Cada entrada de override tem:

• files (obrigatório): globs que casam os arquivos
• excludeFiles (opcional): globs excluídos deste override
• options: opções de formatação a aplicar

Os globs são resolvidos em relação ao diretório do arquivo de config do Oxfmt.

Precedência

Ordem de aplicação (da menor para a maior prioridade):

1. Padrões embutidos
2. Raiz do arquivo de config
3. Opções dentro de overrides
4. Fallback para .editorconfig nos campos ainda indefinidos

Opções específicas do Oxfmt

insertFinalNewline

Define se uma nova linha final é adicionada aos arquivos formatados. Padrão: true.

É um recurso muito pedido ao Prettier: alguns ambientes (por exemplo Salesforce) removem nova linha no fim.

printWidth

O Oxfmt usa printWidth: 100 por padrão (o Prettier usa 80). Motivos:

• TypeScript tende a ser mais longo por causa das anotações de tipo
• Imports costumam ter muitos especificadores
• Telas são mais largas hoje em dia
• Menos quebras ⇒ menos tokens para LLMs

Para alinhar ao padrão do Prettier:

.oxfmtrc.json

{
  "printWidth": 80
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});

Próximos passos

• Ignorar arquivos: padrões, .gitignore e fluxo .prettierignore.
• Comentários de ignorar embutidos: supressões em linha.
• Referência do arquivo de config: schema completo.
• Referência do CLI: lista de flags.