Where is babel plugin syntax defined?

Question

I'm building a babel plugin and can find numerous examples of already written plugins in the Babel repo.

What I can't find is a definitive API documentation for writing such a plugin- especially for operations I can perform on the resulting AST.

I have checked

• babel itself (which is also what's linked from the ASTExplorer README
• Acorn documentation
• Googled "Babel transform API"
• The Babel Handbook
• Mozilla Parser API and the ESTree API linked therein

Just to list a few of the places. None of which have even defined the ubiquitous .get method I see called so often in existing plugins, to say nothing of other functions I can call on a path, node, scope, or binding.

Does a definitive source of documentation exist for Babel 7 transforms? If so, where is it?

Answer 1

I'm not a "babel" expert, but after a few hours, that is what I've found out. There is no documentation about API rather than the actual source code.

As an example, I've decided to use this plugin, called babel-plugin-transform-spread. Open those links as we go further.

The first stop is AST Spec. In the source code of the plugin above I see some CallExpression, which can easily be found in the spec. According to spec, this Type has a couple of properties (e.g. callee and arguments). And I can see a clear usage of them in the source code too. Nothing special at this point.

But you might want to ask: okay, but what about methods?

Let's have a look at ArrayExpression for example. There are no methods in the spec. But in the source code, there are a lot of them, like .replaceWith(). Where the heck did this come from? I found this API doc. Quite old, yes, but still helpful IMO. Try to find replaceWith on this page and you will see some hints like babel-core.traverse.NodePath.prototype.replaceWith.

Okay, the next step is to open babel's GitHub page and to find something about replaceWith in babel/packages/babel-traverse. That leads us to this line. And right here you can see other related methods.

As an exercise, you can open babel handbook and try to find something else. getPrevSibling for example. And again, open GitHub, open search, see the results, and here we go. Or findParent, or insertAfter, etc.

This method is not the easiest one, but without proper documentation, this is what we have to deal with. Unfortunately.