Document Babel macros support and common uses

[gaearon]

Need to keep track:

• Relay https://github.com/facebook/relay/pull/2171
• Apollo https://github.com/facebookincubator/create-react-app/issues/3856#issuecomment-358696916
• Css-in-js like Emotion
• Maybe some i18n libs?
• SVG https://github.com/facebookincubator/create-react-app/issues/3856#issuecomment-358696916
• Maybe make one for idx? https://github.com/dralletje/idx.macro

[gaearon]

cc @kentcdodds do you have a list somewhere/

[threepointone]

partial application with https://github.com/citycide/param.macro

[threepointone]

emotion https://github.com/emotion-js/emotion/tree/master/packages/babel-plugin-emotion#babel-macros (needs a better doc page ofc)

[kentcdodds]

I should note that some plugins have still not upgraded from babel-macros to babel-plugin-macros. In any case, the documentation of babel-plugin-macros indicates that people should use the keyword babel-plugin-macros in their package.json to facilitate finding available macros.

• babel-macros keyword
• babel-plugin-macros keyword

[threepointone]

idx! https://github.com/dralletje/idx.macro

[kentcdodds]

Also, I'll be giving a talk at a meetup in two weeks about using babel-plugin-macros with create-react-app. I'll make sure that's recorded and add a link to the docs :+1:

[kentcdodds]

I just added a macros.md file to the babel-plugin-macros docs. Feel free to direct people there!

[kentcdodds]

Here's the recording of my talk :smile:

[Downchuck]

A sterling example of a painful case of css plugin: https://github.com/ant-design/babel-plugin-import/issues/166

[lifeiscontent]

not sure if this is create-react-app related or webpack related as @kentcdodds pointed out, but the errors when something doesn't compile in babel-macros are very unhelpful. https://github.com/kentcdodds/babel-plugin-macros/issues/79

[kentcdodds]

I believe it has nothing to do with babel macros specifically and is more generally babel...

[lifeiscontent]

right, sorry for not clarifying that @kentcdodds

[caedmon]

Not sure if this is the right place to ask this, but is babel-plugin-macros supposed to be working with 2.0.0-next.a671462c? I've tried to use it but haven't been able to get more than the rather opaque 'Failed to compile.' when I try to use a macro.

[mxstbr]

styled-components v4 also has a Babel macro! :tada: https://www.styled-components.com/docs/tooling#babel-macro

[petetnt]

https://github.com/facebook/create-react-app/pull/5481 graphql-tag.macro documented in this one

[ForestJohnson]

I was looking at how to print a warning message regarding

import styled from 'styled-components/macro'

versus

import styled from 'styled-components'  

The problem is that users are going to be instructed to import styled from 'styled-components' for quite some time and they will have no idea why the displayName config (display Styled Component Names in the class name) is not working.

This is important so the DEV / QA person can tell whether a given element in the Browser Developer Tools is a TabularWhoosieWhatsitContainer or if it's a TabularWhoosieWhatsitFlexRow. Currently when they look at it they see something like <div class='sc-xHyW3'>and <div class='sc-JTy5as'>

When the users are not instructed to update to 'styled-components/macro', this issue is happening because the babel plugin for styled-components will never be loaded because it will never be included in the babel config that gets generated here https://github.com/facebook/create-react-app/blob/b8ff97be72c02128c0917437d98e1b672a25ceb4/packages/babel-preset-react-app/create.js#L67

I checked whats trivially possible to do in the styled-components repo by putting console.log in the very top of the file in various places:

node_modules/styled-components/dist/styled-components.browser.cjs.js
node_modules/styled-components/dist/styled-components.browser.esm.js
node_modules/styled-components/dist/styled-components.cjs.js
node_modules/styled-components/dist/styled-components.esm.js
node_modules/styled-components/dist/styled-components.js
node_modules/styled-components/dist/styled-components-macro.cjs.js
node_modules/styled-components/dist/styled-components-macro.esm.js
node_modules/styled-components/dist/styled-components.min.js

I found that when I import styled from 'styled-components' the logs from styled-components.browser show up in the browser.

When I import styled from 'styled-components/macro' the logs from styled-components-macro show up in the build output.

So there is no great way to warn users about this at build time from within the styled-components repo, that I am aware of.

It may be possible to warn the user from inside create-react-app, but its easier said than done. It's not as easy as checking what packages they have installed because styled-components and styled-components/macro are the same package.

The tool that issues the warning would potentially have to be a macro/linter itself, that would go through your code looking for styled-components imports. I don't know how to set that up.

The alternative would be to issue the warning in the browser. But that seems like it might be risky, ugly, bad practice etc.

I suppose the other-OTHER alternative would be to modify babel-preset-react-app so that it loads babel-plugin-styled-components when present, I have an example of that here:

https://github.com/ForestJohnson/create-react-app/pull/1/commits/ccfe22bd251f0e8346bbf7c9ad82c1eaae454d38

The above does work (node_modules/babel-plugin-styled-components/lib/index.js will be executed at build time, and the displayNames will show up correctly in browser with import styled from 'styled-components') but it requires you to bust the Webpack/Babel cache for the change to "take", and I have no freaking clue how to get that to happen reliably at the right time. As a relatively naive user the only reliable way I found to do that was to completely delete and re-create the whole project folder.

[Annie-Huang]

using https://styled-components.com/docs/tooling#babel-macro will failed all my snapshot unit test, errors complains: TypeError: macro_1.default. is not a function

Where XXX can be span, li, etc Does anyone got the same problem?