What does the comment /** @jsx jsx */ do in the Emotion CSS-in-JS library?

Question

This seems to be a best practice, since it is used almost everywhere. However, nowhere is it clearly explained what exactly it does ...

I did find a comment in the docs that said: "This comment tells babel to convert jsx to calls to a function called jsx instead of React.createElement". Does this simply mean it replaces standard React functionality with Emotion's? Are there any consequences from leaving out the /** @jsx jsx */ comment?

Answer 1

This is a custom pragma that tells the jsx transformer, in this case babel-plugin-transform-react what function to use to transform your jsx into plain javascript.

From the React Website:

A React component using jsx that looks like this:

class Hello extends React.Component {
  render() {
    return <div>Hello {this.props.toWhat}</div>;
  }
}

Will be transformed into this:

class Hello extends React.Component {
  render() {
    return React.createElement('div', null, `Hello ${this.props.toWhat}`);
  }
}

But by using that custom pragma, the compiled js might look like this:

class Hello extends React.Component {
  render() {
    return jsx('div', null, `Hello ${this.props.toWhat}`);
  }
}

This is useful because the jsx function might in some way enable the functionality of the library you're using by modifying or otherwise using the props or other data passed in from the jsx.

So therefor the answer to this question:

Are there any consequences from leaving out the /** @jsx jsx */

is yes. It will probably break the functionality of the library.

EDIT

This is mentioned in emotion's docs here: https://emotion.sh/docs/css-prop#jsx-pragma