fxl 37aa67060c 08.01demo | 5 månader sedan | |
---|---|---|
.. | ||
dist | 5 månader sedan | |
CHANGELOG.md | 5 månader sedan | |
LICENSE | 5 månader sedan | |
README.md | 5 månader sedan | |
package.json | 5 månader sedan |
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.
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).
This module is distributed via npm which is bundled with node and
should be installed as one of your project's devDependencies
:
npm install --save-dev babel-plugin-macros
You may like to watch this YouTube video to get an idea of what macros is and how it can be used.
Are you trying to use babel-plugin-macros
? Go to
other/docs/user.md
.
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).
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:
import macro from 'non-pure.macro';
-// Do some changes of your code or
+// add a cache busting comment to force recompile.
macro('parameters');
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:
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!
Let's use
babel-plugin-console
as
an example.
If we used babel-plugin-console
, it would look like this:
babel-plugin-console
to .babelrc
Use it in a code:
function add100(a) {
const oneHundred = 100
console.scope('Add 100 to another number')
return add(a, oneHundred)
}
function add(a, b) {
return a + b
}
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:
babel-plugin-macros
to .babelrc
(only once for all macros)Use it in a code:
import scope from 'babel-plugin-console/scope.macro'
function add100(a) {
const oneHundred = 100
scope('Add 100 to another number')
return add(a, oneHundred)
}
function add(a, b) {
return a + b
}
The result is exactly the same, but this approach has a few advantages:
Advantages:
.babelrc
for all macros used in project. Add that
once and you can use all the macros you wantbabel-plugin-macros
, so no configuration is needed at allconsole.scope
people may be fooled that it's just a
normal console
API when there's really a babel transpilation going on. When
you import scope
, 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" variablesbabel-plugin-console
you wont find out until you run the
code. If you misconfigure babel-plugin-macros
you'll get a compile-time
error.Drawbacks:
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:
import preval from 'preval.macro'
import idx from 'idx.macro'
// preval macro is evaluated first, then idx
This differs from the current situation with babel plugins where it's prohibitively difficult to control the order plugins run in a particular file.
No! Any AST node type is supported.
It can be tagged template literal:
import eval from 'eval.macro'
const val = eval`7 * 6`
A function:
import eval from 'eval.macro'
const val = eval('7 * 6')
JSX Element:
import Eval from 'eval.macro'
const val = <Eval>7 * 6</Eval>
Really, anything...
See the testing snapshot for more examples.
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.
Macros are processed at build-time and not required at runtime. They should be devDependencies.
Thank you to @phpnode for donating the npm package
babel-plugin-macros
.
Thanks goes to these people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT