If you haven't heard, babel-plugin-macros "enables zero-config, importable babel plugins." A few months ago, I published a blog post about it on the official babel blog: "Zero-config code transformation with babel-plugin-macros".

Since then, there have been a few exciting developments:

1. You can use it with a create-react-app application (v2 beta) because it's now included by default in the beta version of babel-preset-react-app (which is what create-react-app v2 beta is using!)
2. It was added as an optional transform to astexplorer.net by @FWeinb

Up until now, only early adopters have tried to write a macro, though there are a fair amount of people using the growing list of existing macros. There are tons of awesome things you can do with babel-plugin-macros, and I want to dedicate this newsletter to showing you how to get started playing around with writing your own.

Let's start off with a contrived macro that can split a string of text and replace every space with 🐶. We'll call it gemmafy because my dog's name is "Gemma." Woof!

1. Go to astexplorer.net
2. Make sure the language is set to JavaScript
3. Make sure the parser is set to babylon7
4. Enable the transform and set it to babel-macros (or babel-plugin-macros as soon as this is merged)

Then copy/paste this in the source (top left) code panel:

import gemmafy from 'gemmafy.macro'

console.log(gemmafy('hello world'))

And copy/paste this in the transform (bottom left) code panel:

module.exports = createMacro(gemmafyMacro)

function gemmafyMacro({ references, state, babel }) {
	references.default.forEach((referencePath) => {
		const [firstArgumentPath] = referencePath.parentPath.get('arguments')
		const stringValue = firstArgumentPath.node.value
		const gemmafied = stringValue.split(' ').join(' 🐶 ')
		const gemmafyFunctionCallPath = firstArgumentPath.parentPath
		const gemmafiedStringLiteralNode = babel.types.stringLiteral(gemmafied)
		gemmafyFunctionCallPath.replaceWith(gemmafiedStringLiteralNode)
	})
}

Alternatively, you can open this

TADA 🎉! You've written your (probably) very first babel plugin via a macro!

Here's the output that you should be seeing (in the bottom right panel):

console.log('hello 🐶 world')

You'll notice that babel-plugin-macros will take care of removing the import at the top of the file for you, and our macro replaced the gemmafy call with the string.

So here's your challenge. Try to add this:

console.log(gemmafy('hello world', 'world goodbye'))

Right now that'll transpile to:

console.log('hello 🐶 world')

Your job is to make it do this instead:

console.log('hello 🐶 world', 'goodbye 🐶 world')

From there, you can play around with it and do a lot of fun things!

If you want to see more of the capabilities, then copy this in the source (top left):

import myMacro, { JSXMacro } from 'AnyNameThatEndsIn.macro'
// (note: in reality, the AnyNameThatEndsIn.macro should be the name of your package
// for example: `codegen.macro`)
const functionCall = myMacro('Awesome')
const jsx = <JSXMacro cool="right!?">Hi!</JSXMacro>
const templateLiteral = myMacro`hi ${'there'}`
literallyAnythingWorks(myMacro)

And copy/paste this in the transform (bottom left) code panel:

module.exports = createMacro(myMacro)

function myMacro({ references, state, babel }) {
	// `state` is the second argument you're passed to a visitor in a
	// normal babel plugin. `babel` is the `@babel/core` module.
	// do whatever you like to the AST paths you find in `references`.
	// open up the console to see what's logged and start playing around!

	// references.default refers to the default import (`myMacro` above)
	// references.JSXMacro refers to the named import of `JSXMacro`
	const { JSXMacro = [], default: defaultImport = [] } = references

	defaultImport.forEach((referencePath) => {
		if (referencePath.parentPath.type === 'TaggedTemplateExpression') {
			console.log(
				'template literal contents',
				referencePath.parentPath.get('quasi'),
			)
		} else if (referencePath.parentPath.type === 'CallExpression') {
			if (referencePath === referencePath.parentPath.get('callee')) {
				console.log(
					'function call arguments (as callee)',
					referencePath.parentPath.get('arguments'),
				)
			} else if (
				referencePath.parentPath.get('arguments').includes(referencePath)
			) {
				console.log(
					'function call arguments (as argument)',
					referencePath.parentPath.get('arguments'),
				)
			}
		} else {
			// throw a helpful error message or something :)
		}
	})

	JSXMacro.forEach((referencePath) => {
		if (referencePath.parentPath.type === 'JSXOpeningElement') {
			console.log('jsx props', {
				attributes: referencePath.parentPath.get('attributes'),
				children: referencePath.parentPath.parentPath.get('children'),
			})
		} else {
			// throw a helpful error message or something :)
		}
	})
}

Next, open up your developer console and check out the console logs. Have fun with that!

Alternatively, you can just go here

Conclusion

I think there are a LOT of really cool places we can go with this technology. I didn't spend any time in this newsletter talking about the why behind macros or giving you ideas. I'll link to some resources for ideas below. The basic idea is if there's a way that you can pre-compile some of your operations, then you can improve runtime performance/bundle size of your application. In addition, this allows you to do some things at build time when you have access to the file system. The possibilities are really endless and we're just getting started! Enjoy!