babel-macros - npm Package Compare versions

Comparing version 0.5.0 to 0.5.1

dist/index.js

@@ -88,3 +88,7 @@ 'use strict';
   }
-  var requirePath = p.join(p.dirname(filename), source);
+  var requirePath = source;
+  var isRelative = source.indexOf('.') === 0;
+  if (isRelative) {
+    requirePath = p.join(p.dirname(filename), source);
+  }
   // eslint-disable-next-line import/no-dynamic-require
@@ -91,0 +95,0 @@ var macros = require(requirePath);

package.json

 {
   "name": "babel-macros",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Enables zero-config, importable babel plugins",
@@ -5,0 +5,0 @@ "main": "dist/index.js",

README.md

@@ -127,6 +127,108 @@ <div align="center">
 
+## FAQ
+
+### What's the difference between babel plugins and macros?
+
+Suppose we have a plugin `node-eval`, which evaluates a node expression at compile time.
+
+If we used `babel-plugin-node-eval`, it would look like this:
+
+1. Add `babel-plugin-node-eval` to `.babelrc`
+2. Use it in a code:
+
+```js
+const val = nodeEval`fs.readDirSync('./fleet')`
+
+// ↓ ↓ ↓  compiles to  ↓ ↓ ↓
+
+const val = ['red_leader', 'blue_leader']
+```
+
+Instead, if there were a macro called `node-eval.macro`, we could use
+it like this:
+
+1. Add `babel-macros` to `.babelrc` (only once for all macros)
+2. Use it in a code:
+
+```js
+import nodeEval from 'node-eval.macro'
+const val = nodeEval`fs.readDirSync('./fleet')`
+
+// ↓ ↓ ↓  compiles to  ↓ ↓ ↓
+
+const val = ['red_leader', 'blue_leader']
+```
+
+Advantages:
+
+- requires only one entry in `.babelrc` for all macros used in project
+- boilerplates, like Create React App ([soon hopefully][cra-issue]), might already support `babel-macros`, so no configuration is needed
+- it's explicit, that `node-eval` is macro and does something with the code at compile time
+- macros are safer and easier to write, because they receive exactly the AST node to process
+
+> By the way, something like `node-eval` actually exists and it's called [babel-plugin-preval][preval].
+
+### In what order are macros executed?
+
+In the same order as imported. The order of execution is clear, explicit
+and in full control of the user:
+
+```js
+import nodeEval from 'node-eval.macro'
+import css from 'css-in-js.macro'
+
+# First are evaluated `node-eval` macros, then `css` macros
+```
+
+This differs from the current situation with babel plugins where
+it's prohibitvely difficult to control the order plugins run in
+a particular file.
+
+### Does it work with tagged template literals only?
+
+No! Any AST node type is supported.
+
+It can be tagged template literal:
+
+```js
+import eval from 'eval.macro'
+const val = eval`7 * 6`
+```
+
+A function:
+
+```js
+import eval from 'eval.macro'
+const val = eval('7 * 6')
+```
+
+JSX Element:
+
+```js
+import Eval from 'eval.macro'
+const val = <Eval>7 * 6</Eval>
+```
+
+Really, anything...
+
+See the [testing snapshot](https://github.com/kentcdodds/babel-macros/blob/master/src/__tests__/__snapshots__/index.js.snap) 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](https://babeljs.io/docs/plugins/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-macros` designed.
+However, some things _do_ need to be implicit, and those kinds of babel plugins can't be
+turned into macros.
+
 ## Inspiration
 
 - [threepointone/babel-macros](https://github.com/threepointone/babel-macros)
-- [facebookincubator/create-react-app#2730](https://github.com/facebookincubator/create-react-app/issues/2730)
+- [facebookincubator/create-react-app#2730][cra-issue]
 
@@ -185,1 +287,2 @@ ## Other Solutions
 [preval]: https://github.com/kentcdodds/babel-plugin-preval
+[cra-issue]: https://github.com/facebookincubator/create-react-app/issues/2730

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

17164

increased by21.45%

Lines of code

105

increased by3.96%

Number of lines in readme file

287

increased by55.98%

No dependency changes