New formatter haxelib library

Does your code look old?
Has your code lost its shininess?
Is your whitespace all over the place?
Do you use tabs and/or spaces for indentation?
Have you messed up your curlys?
Do you use empty lines?
Do you like it when format happens in your code?

Then why not try haxelib run formatter -s folderWithDustyOldCode? (*)

Out now: formatter - available at your local haxelib store.

Check out our low low prices!

For a limited(**) time only: free VSCode integration!

(*) use backups; diff tool recommended
(**) for very very broad values of limited


For anyone interested in seeing what the default built-in hxformat.json configuration file looks like, here it is: haxe-formatter/default-hxformat.json at master · HaxeCheckstyle/haxe-formatter · GitHub (note: dev version differs from 1.0.0 release)

1 Like

Seems there is already a good amount of configuration option :+1:

Something that would be really awesome is an online tool (or a vscode extension) similar to clang-format configurator to create your own config easily.

Formatter has lots of options, but obviously we haven’t tested every combination of options, most unittests use built-in defaults, so there might be some side effects when configuring your personal code style.

A configuration tool would be really cool, e.g. it could be a HaxeUI based VSCode extension (maybe with multiple tabs for different types of configuration options), that has a split view showing a live preview of formatting results. All we need is a volunteer… :slight_smile:

For now we have auto-completion in VSCode through JSON schema.

For anyone not running VSCode, I have heard from someone using the command line version from within HaxeDevelop to format files on demand. I’m not using HaxeDevelop, so I don’t know how to set it up or how well you can integrate it with your workflow.
That might also work for other editors.

It helps to have NodeJS installed, since haxelib run formatter or neko <formatter>\run.n will try to run node run.js - the NodeJS version is a lot faster than the Neko version (a C++ version is only slightly faster compared to NodeJS).

Finally got a chance to use this - it’s amazing! Thanks so much, this was something I’ve learned to love in other languages that I really missed in Haxe.

1 Like

The latest vshaxe extension (2.4.1) brings haxe-formatter 1.1.0 to VSCode which offers additional emptyLines settings and the ability to wrap method chains (and a few other changes).

If you have a hxformat.json containing custom wrapping rules, you will have to adjust them from e.g.:

  "wrapping": {
    "anonType": [{"conditions": [{"cond": "itemCount <= n", "value": 3}], "type": "noWrap"}]


  "wrapping": {
    "anonType": {
      "defaultWrap": "noWrap",
      "rules": [{"conditions": [{"cond": "itemCount <= n", "value": 3}], "type": "noWrap"}]

I have released haxe-formatter 1.1.2 yesterday (for VSCode users: it’s already included with vshaxe 2.4.4).
It brings a few bugfixes, e.g. wrapping with “keep” should now work as intended, and indentation logic should give nicer results for cases where left curly is on “next” line instead of “same”.

I also added a small section to explaining how to start using formatter in your projects.


Skipping a post for haxe-formatter 1.2.0, because I released formatter 1.3.0 earlier (for those using VSCode, there is vshaxe 2.4.5 out now as well).

There are some breaking changes in that new version, if you were using custom values for

  • whitespace.openingParenPolicy
  • whitespace.closingParenPolicy
  • whitespace.openingBracePolicy
  • whitespace.closingBracePolicy
  • whitespace.objectOpeningBracePolicy
  • whitespace.objectClosingBracePolicy

you need to update your configuration and use the new whitespace.parenConfig and whitespace.bracesConfig options.
There is a full dump of all built-in default options under resources/default-hxformat.json inside your haxelib folder (you can also generate your own version by running haxelib run formatter --default-config <filename>).
Again VSCode users should see JSON schema support for hxformat.json files, giving them suggestions and autocomplete when editing formatter settings.

Also if people were having issues where formatter would “eat” or destroy their code, version 1.3.0 has a new safeguard that should detect and prevent such behaviour. Formatter should skip formatting a file before destroying your code (better no formatting than destructive formatting).
If you have samples where formatter fails to format or destroys code, please open an issue on github (GitHub - HaxeCheckstyle/haxe-formatter: Haxe code formatter based on tokentree).


haxe-formatter 1.4.0 is out now either standalone as haxelib or integrated into VSCode through vshaxe 2.5.1 (also released earlier).

Among many bugfixes formatter now has a new wrapping option for extends/implements (wrapping.implementsExtends) and two new empty lines settings for file header and between multiline comments (emptylines.afterFileHeaderComment and emptylines.betweenMultilineComments).

Defaults for wrapping.opBoolChain have changed slightly, wrapping should occur less frequent than before and it will now wrap before || and &&, e.g.:

dirty = dirty
        || (Tilemap.x != _prevTilemapX)
        || ((Tilemap.y != _prevTilemapY)
                || (Tilemap.scale.x != _prevTilemapScaleX)
                || (Tilemap.scale.x != _prevTilemapScaleX)
                || (Tilemap.scale.x != _prevTilemapScaleX))
        && (Tilemap.scale.x != _prevTilemapScaleX);

Version 1.5.1 has a ton of bugfixes and comes with a few additional settings, such as:

  • wrapping.opAddSubChain provides wrapping rules for +/- chains, e.g. string concatenation or large math equations
  • wrapping.metadataCallParameter wraps metadata parameter, e.g. when you have a large list of @:forward parameters
  • emptyLines.macroClassEmptyLines empty line options for macro class {}
  • emptyLines.lineCommentsBetweenTypes empty line option for line comments (//) before, after or between type definitions
  • emptyLines.lineCommentsBetweenFunctions empty line option for line comments (//) before, after or between function definitions
  • whitespace.addLineCommentSpace controls whether to add a space after // or not, (keep //TODO or convert it to // TODO), no change if there is whitespace after //

Formatter 1.5.1 is included with vshaxe 2.7.0 which was released to marketplace a few hours ago.


Version 1.7.0 is out now and it includes all goodies from version 1.6.0 (that I failed to post about) as well as some new features and numerous bugfixes, e.g.:

  • new --stdin CLI switch to allow (limited) pipe mode (limited to a single file)
  • new multi var wrapping:
var a:Float = 4 * (p1.x * p1.x + p1.y * p1.y),
    b:Float = 4 * (p1.x * p2.x + p1.y * p2.y),
    c:Float = p2.x * p2.x + p2.y * p2.y,
  • new curly line end options to set different policies for blocks, object literals, anonymous types or typedefs
  • new targets: compiles to Java, JVM and browser javascript
  • new indentation option indentComplexValueExpressions allows to switch between different indent styles for complex value expressions:
var a = if (val)                      var a = if (val)
                10;                           10;
        else                          else
                20;        vs.                20;
return if (val)                       return if (val)
                10;                           10;
        else                          else
                20;                           20;
  • new matrix array wrapping:
rotation = [
	 Math.cos(alpha), 0, Math.sin(alpha), 0,
	               0, 1,               0, 0,
	-Math.sin(alpha), 0, Math.cos(alpha), 0,
	               0, 0,               0, 1

There is also a new vshaxe version 2.11.0 which includes formatter 1.7.0 along with some other changes (visit their changelog).


I’ve released formatter version 1.8.0 yesterday which comes with the following changes:

  • redefined same line option returnBody to only apply to multiline, loop, switch, try or if expressions
  • added returnBodySingleLine as a new same line option to target simple return expressions, so you can have:
return 10;
return null;
     if (x < 0) "negative";
     else "non-negative";
  • added printing out which hxformat.json applies to what input file when using CLI in verbose mode (-v)
  • added indentCaseLabels to control indentation of case labels
     (true = default)            (false)
switch option {             switch option {
    case Some(v):           case Some(v):
        trace("Foo");  vs.      trace("Foo");
    default:                default:
        trace("Bar");           trace("Bar");
}                           }
  • added multiple existingBetweenFields empty lines settings, to keep or remove empty lines on field level
  • added untypedBody same line option, giving you control over where untyped appears when used as a body:
function foo() untyped {       function foo() 
    trace("");            vs.      untyped {
}                                      trace("");
  • and lots of small bugfixes

formatter 1.8.0 is also included with vshaxe extension 2.13.1.
Note: There was some packaging mishap in vshaxe 2.13.0, where it came with a formatter version inbetween 1.7.1 and 1.8.0, so if you are still on 2.13.0 please update!


You can test the formatter with this online tool Online haxe-formatter


formatter 1.9.1 came out today!

1.9.0 had a few new indentation options for conditional compilation sections, fixed null point exceptions when compiling to HL and fixed a few smaller bugs.
It also introduced a range formatting API (currently not available through CLI).

1.9.1 fixes some issues related to range formatting

Range formatting API is currently used in vshaxe 2.16.2 to bring you Format Selection command and format on paste (enabled via "editor.formatOnPaste": true)


Formatter 1.10.1 was just released!

It includes numerous bugfixes and a few new features:

  • formatter can now detect files with merge conflicts and will not try to format them
  • it added lineEnds.anonFunctionCurly so you can have different curly linebreak settings if they occur as a block of an anonymous function
  • with wrapping.casePattern you can define wrapping rules that deal with cases that hold a long list of patterns, e.g.
case Kwd(KwdIf) | Kwd(KwdElse) | Kwd(KwdTry) | Kwd(KwdCatch) 
        | Kwd(KwdDo) | Kwd(KwdWhile) | Kwd(KwdFor) | Kwd(KwdFunction)
        | Kwd(KwdSwitch) | Kwd(KwdReturn) | Kwd(KwdUntyped) | Arrow:
  • there is a new wrapping condition type called exceedsMaxLineLength which will match lines that are longer than maxLineLength setting (pre-wrapping)

As is tradition there is also a new vshaxe release (2.19.2) that includes all formatter related changes and bugfixes.
Formatter 1.10.1 brings a fix for those using formatOnPaste in VSCode, it should no longer add an extra space when your paste ends inside an identifier or string literal.

Fun side note: If you ever need to run an older version of Formatter you can just run haxelib run formatter:1.9.2 -s src (assuming you have a matching haxelib version installed)


@ablum you’re doing wonderful work with this. Thank you so much! This is all the more important as I’ve been preparing to do some serious evangelism around Haxe for a while now.

I’ve taken a break developing in Haxe but now I’m back to it and your extension is SUPER useful for me :).

If there’s one tiny comment I could make… I feel it would be useful to add more documentation :slight_smile: I’ve been digging and digging to find certain settings :smiley: . For example, popular things such as keeping braces on new lines are in “lineEnds.blockCurly.leftCurly”. Perhaps some of the popular ones can even be set from Preferences UI, or at least having the most popular options clearly specified in the What do you think?

Thanks for your feedback!

I do have some ideas on documenting formatter options outside of JSON schema, though I haven’t started experimenting with them to figure out what works and what’s doable.

Ok, I took some time to implement a documentation / demo site for formatter.

You can find it here: Formatter docs

It has a few samples with customisable config settings, a download button for hxformat.json and you can paste in your own code or edit sample code.
Formatting happens on change events, so you have to click outside textarea after a code change to rerun formatter.

It is still a work in progress and short on content, but it’s something :slight_smile:

Sources are available here: GitHub - HaxeCheckstyle/haxe-formatter-docs: demo / playground / documentation site for Haxe formatter
It uses a custom text based file format for sample pages and it’s written in Haxe.

If you have any suggestions, new samples or found a bug, feel free to open an issue or create a pull request.


Oh wow! That’s super nice! Online configuration tool. You’re a wiz! :smiley: