What is JSX Pragma

If you’re looking into using Theme UI , you’ll come across some (potentially) unfamiliar looking syntax:

/** @jsx jsx */
import { jsx } from "theme-ui"

This is a JSX pragma. What the heck is a JSX pragma? I had heard the phrase, but not thought too much about it until it came up with Gatsby theming — and lots of other folks hadn’t either.

What is a pragma?

A pragma is a compiler directive. It tells the compiler how it should handle the contents of a file.

An example of this in JavaScript is 'use strict' mode. 'use strict' is a directive that enables JavaScript’s Strict Mode, which is a way to opt in to a more restricted variant of JavaScript. It denotes that the code should be processed in a specific way.

What is JSX pragma?

JSX syntax on its own isn’t readable by the browser. In order to ship something readable to the browser, JSX needs to be converted to plain JavaScript.

Most React-based frameworks (like Gatsby), come with tooling already set up to support this conversion (usually Babel). How does that tooling know how to transform JSX? By default, the Babel plugin will convert JSX into JavaScript that calls the React.createElement function.

Take the following JSX, for example:

const element = <h1 className="greeting">Hello, world!</h1>

That JSX syntax compiles to a call to React.createElement, like this:

const element = React.createElement(
  "h1",
  { className: "greeting" },
  "Hello, world!"
)

Using a custom JSX pragma

There are two ways to specify a custom function (and therefore replace React.createElement):

• Add an option to the Babel plugin
• Set a pragma comment at the beginning of a module

Add an option to the Babel plugin

Changing the function in the Babel plugin will transform all JSX in an application to use the specified function.

Babel Preset

This method will not work with Create React App or other projects that do not allow custom babel configurations. Use the JSX Pragma method instead.

.babelrc

{
  "presets": ["@emotion/babel-preset-css-prop"]
}

Set a pragma comment

Using a pragma comment will limit the change to the modules the comment is added to. Therefore, you can use React.createElement by default, and opt in to the custom function only where needed. This is the approach taken in Theme UI.