Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/kentcdodds/babel-plugin-macros

🎣 Allows you to build simple compile-time libraries
https://github.com/kentcdodds/babel-plugin-macros
babel babel-macros babel-plugin
Last synced: 7 days ago
JSON representation
🎣 Allows you to build simple compile-time libraries
Host: GitHub
URL: https://github.com/kentcdodds/babel-plugin-macros
Owner: kentcdodds
License: mit
Created: 2017-07-07T00:48:46.000Z (over 7 years ago)
Default Branch: main
Last Pushed: 2023-05-30T11:04:41.000Z (over 1 year ago)
Last Synced: 2024-05-23T10:24:18.872Z (6 months ago)
Topics: babel, babel-macros, babel-plugin
Language: JavaScript
Homepage: https://npm.im/babel-plugin-macros
Size: 354 KB
Stars: 2,608
Watchers: 17
Forks: 134
Open Issues: 10
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project

awesome-github-star - babel-plugin-macros - time libraries | kentcdodds | 2580 | (JavaScript)
awesome-list - babel-plugin-macros - time libraries | kentcdodds | 2307 | (JavaScript)
awesome-f2e-libs - **babel-plugin-macros** - 前端文件写 node 逻辑。 (babel / 非 JavaScript 编译工具)
awesome-fe - **babel-plugin-macros** - 前端文件写 node 逻辑。 (babel / 非 JavaScript 编译工具)
README

        


babel-plugin-macros 🎣


Allows you to build simple compile-time libraries



---

[![Build Status][build-badge]][build]

[![Code Coverage][coverage-badge]][coverage]

[![version][version-badge]][package]

[![downloads][downloads-badge]][npmtrends]

[![MIT License][license-badge]][license]

[![All Contributors][all-contributors-badge]](#contributors-)

[![PRs Welcome][prs-badge]][prs]

[![Code of Conduct][coc-badge]][coc]

## The problem

Check out

[this guest post](https://babeljs.io/blog/2017/09/11/zero-config-with-babel-macros)

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).

Expand for more details on the motivation

For instance, many css-in-js libraries have a css tagged template string

function:

```js

const styles = css`

  .red {

    color: red;

  }

`

```

The function compiles your css into (for example) an object with generated class

names for each of the classes you defined in your css:

```js

console.log(styles) // { red: "1f-d34j8rn43y587t" }

```

This class name can be generated at runtime (in the browser), but this has some

disadvantages:

- There is cpu usage/time overhead; the client needs to run the code to generate

  these classes every time the page loads

- There is code bundle size overhead; the client needs to receive a CSS parser

  in order to generate these class names, and shipping this makes the amount of

  js the client needs to parse larger.

To help solve those issues, many css-in-js libraries write their own babel

plugin that generates the class names at compile-time instead of runtime:

```js

// Before running through babel:

const styles = css`

  .red {

    color: red;

  }

`

// After running through babel, with the library-specific plugin:

const styles = {red: '1f-d34j8rn43y587t'}

```

If the css-in-js library supported babel-plugin-macros instead, then they

wouldn't need their own babel plugin to compile these out; they could instead

rely on babel-plugin-macros to do it for them. So if a user already had

`babel-plugin-macros` installed and configured with babel, then they wouldn't

need to change their babel configuration to get the compile-time benefits of the

library. This would be most useful if the boilerplate they were using came with

`babel-plugin-macros` out of the box, which is true for

[`create-react-app`][cra].

Although css-in-js is the most common example, there are lots of other things

you could use `babel-plugin-macros` for, like:

- Compiling GraphQL fragments into objects so that the client doesn't need a

  GraphQL parser

- Eval-ing out code at compile time that will be baked into the runtime code,

  for instance to get a list of directories in the filesystem (see

  [preval][preval])

## Table of Contents

- [Installation](#installation)

- [Usage](#usage)

  - [User docs](#user-docs)

  - [Author docs](#author-docs)

  - [Caveats](#caveats)

- [FAQ](#faq)

  - [How do I find available macros?](#how-do-i-find-available-macros)

  - [What's the difference between babel plugins and macros?](#whats-the-difference-between-babel-plugins-and-macros)

  - [In what order are macros executed?](#in-what-order-are-macros-executed)

  - [Does it work with function calls only?](#does-it-work-with-function-calls-only)

  - [How about implicit optimizations at compile time?](#how-about-implicit-optimizations-at-compile-time)

- [Inspiration](#inspiration)

- [Other Solutions](#other-solutions)

- [Issues](#issues)

  - [🐛 Bugs](#-bugs)

  - [💡 Feature Requests](#-feature-requests)

- [Contributors ✨](#contributors-)

- [LICENSE](#license)

## Installation

This module is distributed via [npm][npm] which is bundled with [node][node] and

should be installed as one of your project's `devDependencies`:

```

npm install --save-dev babel-plugin-macros

```

## Usage

> You may like to watch

> [this YouTube video](https://www.youtube.com/watch?v=1queadQ0048&list=PLV5CVI1eNcJgCrPH_e6d57KRUTiDZgs0u)

> 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`](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`](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:

```diff

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:

- babel-plugin-preval:

  [How to force recompile? #19](https://github.com/kentcdodds/babel-plugin-preval/issues/19)

- graphql.macro:

  [Recompile problem (babel cache) #6](https://github.com/evenchange4/graphql.macro/issues/6)

- twin.macro: 

  [Can't change taliwind config #37](https://github.com/ben-rogerson/twin.macro/discussions/37)

## 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](https://github.com/jgierer12/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`](https://www.npmjs.com/package/babel-plugin-console) as

an example.

If we used `babel-plugin-console`, it would look like this:

1.  Add `babel-plugin-console` to `.babelrc`

2.  Use it in a code:

```js

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:**

![Browser console scoping add100](https://github.com/mattphillips/babel-plugin-console/raw/53536cba919d5be49d4f66d957769c07ca7a4207/assets/add100-chrome.gif)

**Node:**



Instead, let's use the macro it's shipped with like this:

1.  Add `babel-plugin-macros` to `.babelrc` (only once for all macros)

2.  Use it in a code:

```js

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:**

- requires only one entry in `.babelrc` for all macros used in project. Add that

  once and you can use all the macros you want

- toolkits (like [create-react-app][cra]) may already support

  `babel-plugin-macros`, so no configuration is needed at all

- it's explicit. With `console.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" variables

- macros 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 misconfigure `babel-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:

```js

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.

### Does it work with function calls 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 = 7 * 6

```

Really, anything...

See the [testing snapshot](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-plugin-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-plugin-macros](https://github.com/threepointone/babel-plugin-macros)

- [facebookincubator/create-react-app#2730][cra-issue]

Thank you to [@phpnode](https://github.com/phpnode) for donating the npm package

`babel-plugin-macros`.

## Other Solutions

- [sweetjs](http://sweetjs.org/)

## Issues

_Looking to contribute? Look for the [Good First Issue][good-first-issue]

label._

### 🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

[**See Bugs**][bugs]

### 💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding

a 👍. This helps maintainers prioritize what to work on.

[**See Feature Requests**][requests]

## Contributors ✨

Thanks goes to these people ([emoji key][emojis]):

  

    
_{Kent C. Dodds}
💻 📖 🚇 ⚠️

    
_{Sunil Pai}
🤔

    
_{Lily Scott}
💬 📖

    
_{Michiel Dral}
🤔

    
_{Kye Hohenberger}
🤔

    
_{Mitchell Hamilton}
💻 ⚠️

    
_{Justin Hall}
📖

  

  

    
_{Brian Pedersen}
💻 📖

    
_{Andrew Palm}
💻

    
_{Michael Hsu}
📖 🔌

    
_{Bo Lingen}
💻

    
_{Tyler Haas}
📖

    
_FWeinb
💻

    
_{Tomáš Ehrlich}
🐛 💻

  

  

    
_{Jonas Gierer}
📖

    
_{Loïc Padier}
💻

    
_{Paul Sherman}
💻

    
_{Conrad Buck}
💻 ⚠️ 📖

    
_InvictusMB
⚠️

    
_{Eric Berry}
🔍

    
_{Futago-za Ryuu}
💻 ⚠️

  

  

    
_Luc
💻

    
_{Victor Vincent}
💻

    
_{я котик пур-пур}
📖

    
_{Armando Sosa}
📖

    
_Matthias
💻

    
_{Jovi De Croock}
💻 ⚠️

    
_{Victor Arowo}
📖

  

  

    
_{Alex Chan}
📖

    
_{Evan Jacobs}
💻

  

This project follows the [all-contributors][all-contributors] specification.

Contributions of any kind welcome!

## LICENSE

MIT

[npm]: https://www.npmjs.com

[node]: https://nodejs.org

[build-badge]: https://img.shields.io/github/workflow/status/kentcdodds/babel-plugin-macros/validate?logo=github&style=flat-square

[build]: https://github.com/kentcdodds/babel-plugin-macros/actions?query=workflow%3Avalidate

[coverage-badge]: https://img.shields.io/codecov/c/github/kentcdodds/babel-plugin-macros.svg?style=flat-square

[coverage]: https://codecov.io/github/kentcdodds/babel-plugin-macros

[version-badge]: https://img.shields.io/npm/v/babel-plugin-macros.svg?style=flat-square

[package]: https://www.npmjs.com/package/babel-plugin-macros

[downloads-badge]: https://img.shields.io/npm/dm/babel-plugin-macros.svg?style=flat-square

[npmtrends]: http://www.npmtrends.com/babel-plugin-macros

[license-badge]: https://img.shields.io/npm/l/babel-plugin-macros.svg?style=flat-square

[license]: https://github.com/kentcdodds/babel-plugin-macros/blob/main/LICENSE

[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square

[prs]: http://makeapullrequest.com

[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square

[coc]: https://github.com/kentcdodds/babel-plugin-macros/blob/main/CODE_OF_CONDUCT.md

[emojis]: https://github.com/all-contributors/all-contributors#emoji-key

[all-contributors]: https://github.com/all-contributors/all-contributors

[all-contributors-badge]: https://img.shields.io/github/all-contributors/kentcdodds/babel-plugin-macros?color=orange&style=flat-square

[bugs]: https://github.com/kentcdodds/babel-plugin-macros/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Acreated-desc+label%3Abug

[requests]: https://github.com/kentcdodds/babel-plugin-macros/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement

[good-first-issue]: https://github.com/kentcdodds/babel-plugin-macros/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement+label%3A%22good+first+issue%22

[preval]: https://github.com/kentcdodds/babel-plugin-preval

[cra]: https://github.com/facebook/create-react-app

[cra-issue]: https://github.com/facebook/create-react-app/issues/2730