This is a work in progress. Please feel free to give any feedback.

This generalizes the JSX (v4) transform to not only work on React, but any module that can fulfill the interface needed for the JSX transform.

Configuration

You configure a generic JSX transform by putting any module name in the module config of JSX. This can be any valid module name. So you can define your own MyJsx.res locally if you wanted to, and it'd still work. Example part from rescript.json:

"jsx": {
  "module": "Preact"
 },

This will now put the Preact module in control of the generated JSX calls. The Preact module can be defined by anyone - locally in your project, or by a package. As long a it's available in the global scope. The JSX transform will delegate any JSX related code to Preact.

@react.component will still be available, and so is a generic @jsx.component notation. Both work the same way.

One thing is important to note - the generic JSX transform has no version or mode like the React JSX transform has. It's always JSX v4, and the mode is irrelevant (it's automatic internally for the generic JSX transform). This doesn't matter for the generic JSX module, it only needs one implementation, but it's good to know.

Usage example

Here's a quick usage example (the actual definition of Preact.res comes below):

First, configure rescript.json:

"jsx": {
  "module": "Preact"
 },

Now you can build Preact components:

// Name.res
@jsx.component // or @react.component if you want
let make = (~name) => Preact.string(`Hello ${name}!`)

And you can use them just like normal with JSX:

let name = <Name name="Test" />

File level configuration

You can configure what JSX transform is used at the file level via @@jsxConfig, just like before. Like:

@@jsxConfig({module_: "Preact"})

Implementing a generic JSX transform module

Below is a full list of everything you need in a generic JSX transform module, including code comments to clarify. It's an example implementation of a Preact transform, so when doing this for other frameworks you'd of course adapt what you import from, and so on.

// Preact.res
/* Below is a number of aliases to the common `Jsx` module */
type element = Jsx.element

type component<'props> = Jsx.component<'props>

type componentLike<'props, 'return> = Jsx.componentLike<'props, 'return>

@module("preact")
external jsx: (component<'props>, 'props) => element = "jsx"

@module("preact")
external jsxKeyed: (component<'props>, 'props, ~key: string=?, @ignore unit) => element = "jsx"

@module("preact")
external jsxs: (component<'props>, 'props) => element = "jsxs"

@module("preact")
external jsxsKeyed: (component<'props>, 'props, ~key: string=?, @ignore unit) => element = "jsxs"

/* These identity functions and static values below are optional, but lets you move things easily to the `element` type. The only required thing to define though is `array`, which the JSX transform will output. */
external array: array<element> => element = "%identity"
@val external null: element = "null"

external float: float => element = "%identity"
external int: int => element = "%identity"
external string: string => element = "%identity"

/* These are needed for Fragment (<> </>) support */
type fragmentProps = {children?: element}

@module("preact") external jsxFragment: component<fragmentProps> = "Fragment"

/* The Elements module is the equivalent to the ReactDOM module in React. This holds things relevant to _lowercase_ JSX elements. */
module Elements = {
  /* Here you can control what props lowercase JSX elements should have. A base that the React JSX transform uses is provided via JsxDOM.domProps, but you can make this anything. The editor tooling will support autocompletion etc for your specific type when this ships. */
  type props = JsxDOM.domProps

  @module("preact")
  external jsx: (string, props) => Jsx.element = "jsx"

  @module("preact")
  external div: (string, props) => Jsx.element = "jsx"

  @module("preact")
  external jsxKeyed: (string, props, ~key: string=?, @ignore unit) => Jsx.element = "jsx"

  @module("preact")
  external jsxs: (string, props) => Jsx.element = "jsxs"

  @module("preact")
  external jsxsKeyed: (string, props, ~key: string=?, @ignore unit) => Jsx.element = "jsxs"

  external someElement: element => option<element> = "%identity"
}

As you can see, most of the things you'll want to implement will be copy paste from the above. But do note that everything needs to be there unless explicitly noted or the transform will fail.

Technical implementation

The technical implementation tries to minimize actual changes (since the React integration is still 1st class and the most refined one). The generic JSX transform is roughly implemented like this:

• Rename relevant JSX transform parts to indicate that they're general rather than tied to React
• No breaking changes to the JSX configuration
• Minimal changes in how the JSX is run. It's all mostly the same as before

Outstanding questions

• Does Gentype need to be adjusted? If so, how?
• What do we do about React-specific things like ref, forwardRef and so on?
• Should all of the mechanisms around key be available to all generic transforms? Is it needed?

Future

• "Intrinsic elements" (read: The JSX module can define what lowercase elements are available, and what types each of those has). I have a few ideas here that I can detail later on.
• Safer way of mixing JSX transforms in the same project? Right now, everything still needs to be aliased to Jsx.element, which means that there's currently no true separation between different JSX at the type level. You could use React.string (because that returns a Jsx.element) interchangeably with Preact.string (because that also needs to return a Jsx.element). This isn't ideal, but is pretty niche, so it's something we can solve later on.

Wrapping up

Excited to hear your feedback on this! This will obviously need a bunch of documentation to be useful.

Personally, I'm excited to ship this even if it's in a reduced form because I believe it can unlock a bit of innovation in ReScript. One example is I'm building res-x that uses JSX on the server with ReScript as regular HTML templating. The JSX integration there will be much smoother and idiomatic with this generic JSX transform.