babel-plugin-macros
babel-plugin-macros 🎣
Allows you to build simple compile-time libraries
The problem
Check out this guest post on the Babel.js blog for a complete write up on the problem, motivation, and solution.
Currently, each babel plugin in the babel ecosystem requires that you configure it individually. This is fine for things like language features, but can be frustrating overhead for libraries that allow for compile-time code transformation as an optimization.
This solution
babel-plugin-macros defines a standard interface for libraries that want to use compile-time code transformation without requiring the user to add a babel plugin to their build system (other than babel-plugin-macros
, which is ideally already in place).
Table of Contents
Installation
This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies
:
Usage
You may like to watch this YouTube video to get an idea of what macros is and how it can be used.
User docs
Are you trying to use babel-plugin-macros
? Go to other/docs/user.md
.
Author docs
Are you trying to make your own macros that works with babel-plugin-macros
? Go to other/docs/author.md
. (you should probably read the user docs too).
Caveats
Babel cache problem
Note: This issue is not present when used in Create React App.
Most of the time you'll probably be using this with the babel cache enabled in webpack to rebuild faster. If your macro function is not pure which gets different output with same code (e.g., IO side effects) it will cause recompile mechanism fail. Unfortunately you'll also experience this problem while developing your macro as well. If there's not a change to the source code that's being transpiled, then babel will use the cache rather than running your macro again.
For now, to force recompile the code you can simply add a cache busting comment in the file:
This problem is still being worked on and is not unique to babel-plugin-macros
. For more details and workarounds, please check related issues below:
babel-plugin-preval: How to force recompile? #19
graphql.macro: Recompile problem (babel cache) #6
FAQ
How do I find available macros?
You can write your own without publishing them to npm
, but if you'd like to see existing macros you can add to your project, then take a look at the Awesome babel macros repository.
Please add any you don't see listed!
What's the difference between babel plugins and macros?
Let's use babel-plugin-console
as an example.
If we used babel-plugin-console
, it would look like this:
Add
babel-plugin-console
to.babelrc
Use it in a code:
When that code is run, the scope
function does some pretty nifty things:
Browser:
Node:
Instead, let's use the macro it's shipped with like this:
Add
babel-plugin-macros
to.babelrc
(only once for all macros)Use it in a code:
The result is exactly the same, but this approach has a few advantages:
Advantages:
requires only one entry in
.babelrc
for all macros used in project. Add that once and you can use all the macros you wanttoolkits (like create-react-app) may already support
babel-plugin-macros
, so no configuration is needed at allit's explicit. With
console.scope
people may be fooled that it's just a normalconsole
API when there's really a babel transpilation going on. When you importscope
, it's obvious that it's macro and does something with the code at compile time. Some ESLint rules may also have issues with plugins that look for "global" variablesmacros are safer and easier to write, because they receive exactly the AST node to process
If you misconfigure
babel-plugin-console
you wont find out until you run the code. If you misconfigurebabel-plugin-macros
you'll get a compile-time error.
Drawbacks:
Cannot (should not) be used for implicit transpilations (like syntax plugins)
Explicitness is more verbose. Which some people might consider a drawback...
In what order are macros executed?
This is another advantage of babel-plugin-macros
over regular plugins. The user of the macro is in control of the ordering! The order of execution is the same order as imported. The order of execution is clear, explicit and in full control of the user:
This differs from the current situation with babel plugins where it's prohibitively difficult to control the order plugins run in a particular file.
Does it work with function calls only?
No! Any AST node type is supported.
It can be tagged template literal:
A function:
JSX Element:
Really, anything...
See the testing snapshot for more examples.
How about implicit optimizations at compile time?
All examples above were explicit - a macro was imported and then evaluated with a specific AST node.
Completely different story are implicit babel plugins, like transform-react-constant-elements, which process whole AST tree.
Explicit is often a better pattern than implicit because it requires others to understand how things are globally configured. This is in this spirit are babel-plugin-macros
designed. However, some things do need to be implicit, and those kinds of babel plugins can't be turned into macros.
Should macros be dependencies or devDependencies?
Macros are processed at build-time and not required at runtime. They should be devDependencies.
Inspiration
Thank you to @phpnode for donating the npm package babel-plugin-macros
.
Other Solutions
Contributors
Thanks goes to these people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
LICENSE
MIT
Last updated