Redraw

React opinionated bindings for Gleam. Because a lot of frameworks and products are using React in a day-to-day way, Redraw fills the gap by providing nice, simple API to work on a React codebase, Gleam-enhanced!

[!TIP]

Have you tried Lustre? Lustre requires almost no knowledge of JavaScript, no complicated runtimes to get like Node.js, few knowledge of HTML/CSS and other web technologies, less code interfaces to write than Redraw, and is supported by the entire Gleam community! Before launching into Redraw, you should take a look at Lustre, it provides a user-friendly, awesome experience right out-of-the-box for every gleamlins! Plus, Lustre is homomorphic, i.e. it can be used as well on client and on server with the same codebase! When using Redraw, you assume to have knowledge about frontend development.

Overview

Redraw is a package to help you use React in a frontend-only Gleam project. By leveraging on the entire JS ecosystem, Redraw help you interop with existing current React codebases, or allow you to build your custom codebase and cherry-picking the existing components you know and love! Redraw tries to keep everything at the lowest level possible, turning all the React niceties into Gleam niceties. Wherever possible, Redraw tries to stick with Lustre API, to help you create a codebase mixing the two frameworks. For instance, you could build libraries targeting both Lustre and Redraw, and using the same design system for all your products!

Prerequisites

Redraw assumes that you’re a fluent frontend developer and already understand how React works. If you don’t, it’s best to first learn React and the frontend ecosystem, and come back here later. Meanwhile, you could also take a look at Lustre to solve your problems.

Redraw assumes you have node.js as well as a decent package manager, i.e. npm, yarn or pnpm. Redraw also assumes you’re using Vite as a tooling, to build your application.

Getting started

Create the project, and add everything needed to make it work. Choose your prefered bundler to start. Create a Vite application, and choose to use JavaScript and React. Vite should bundle everything for you directly.

npm create vite@latest

yarn create vite

pnpm create vite

bun create vite

From the follow-on, yarn will be used to illustrate the commands, it’s up to you to see how to use your desired package manager. Then, it’s time to setup the project correctly.

cd [project-name]
yarn install

# Install the Vite Gleam plugin.
yarn add -D vite-gleam

# If you want to build the project on Vercel or Netlify.
yarn add -D @chouqueth/gleam

# Remove the files needed for `gleam new` to work.
rm README.md
mv .gitignore .gitignore.old

# Setup the project.
gleam new .
gleam add redraw redraw_dom

Now that everyting is setup, you have to add the vite-gleam plugin in vite.config.js. An example of a vite.config.js should look like this.

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import gleam from "vite-gleam"

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), gleam()],
})

You’re good to go!

Writing Redraw components

Writing Redraw components is the same as writing React component, with one small difference: wrap the component in use <- redraw.component()!

import redraw
import redraw/attribute
import redraw/html

pub fn gleam_is_awesome() {
  use <- redraw.component__("GleamIsAwesome")
  html.div([attribute.class("oh-yeah")], [
    html.text("Yeah, for sure")
  ])
}

While this could feels strange at first, you’ll get used to it quickly. To call the component, it’s needed to call the function first, before definining a new component.

import redraw
import redraw/attribute
import redraw/html
import redraw_dom/client

pub fn main() {
  let root = root()
  client.create_root("root")
  |> client.render(redraw.strict_mode([root()]))
}

fn root() {
  // Call `gleam_is_awesome` here, before component creation, otherwise a new
  // component will be created at each refresh.
  let gleam_is_awesome = gleam_is_awesome()
  use <- redraw.component__("Root")
  html.div([], [
    gleam_is_awesome()
  ])
}

fn gleam_is_awesome() {
  use <- redraw.component__("GleamIsAwesome")
  html.div([attribute.class("oh-yeah")], [
    html.text("Yeah, for sure")
  ])
}

And you know everything to create Redraw components!

What is the kind of components?

Components can have different kinds, accepting props, children, ref, or other things. To provide a simpler, usable API in Gleam, props components in Gleam can be List, Tuple or CustomTypes. It means you can totally define your component like this:

pub type CounterProps {
  CounterProps(
    count: Int,
    set_count: fn(fn(Int) -> Int) -> Nil,
  )
}

pub fn counter() {
  use props: CounterProps <- react.component_("Counter")
  html.button(
    [h.on_click(fn(_) { props.set_count(fn(count) { count + 1 }) })],
    [html.text("count is " <> int.to_string(props.count))],
  )
}

but also like this:

pub type CounterProps = #(Int, fn(fn(Int) -> Int) -> Nil)

pub fn counter() {
  use #(count, set_count): CounterProps <- react.component_("Counter")
  html.button(
    [h.on_click(fn(_) { set_count(fn(count) { count + 1 }) })],
    [html.text("count is " <> int.to_string(count))],
  )
}

Don’t worry about the translation of data from and to React, Redraw handles the hard task for you!

component-family functions

To define components, you should use component, component_ or component__. The difference between the three is the signature of the resulting component. component accepts props and children, component_ accepts only props, and component__ do not accept anything. See it as a way to create an empty component, used with contexts or internal state for instance.

forward_ref-family functions

Defining components sometimes involves to forward a ref to internal component. React uses the mechanism of forwardRef to push a ref, from the parent to a nested child. Redraw fully implements forwarded ref components! Use forward_ref or forward_ref_ to create a component with props, ref and children, or only with props and children!

Some reminders on hooks

Never use hooks outside of custom hooks (functions named use_[something]) or in components! It means you should never use something like use_effect or use_state outside of the body of component-related functions. If you break that rule, while it could seem to work, it’s actually breaking the runtime, and it can explode at any time. So keep that rule anytime: no hooks outside of custom hooks or component body.

Type-checking of hooks

You could see that hooks often use dependencies array, to determine if they have to rerun or not. This is totally supported by Redraw, and leverages on Gleam abilities! Always pass a tuple of dependencies to hooks. No type-checking are done at this stage, and probably none will be implemented later, exactly like it’s done with React currently. Be careful to provide the correct dependencies.

import gleam/io
import redraw
import redraw/attribute
import redraw/html

fn gleam_is_awesome() {
  use <- redraw.component__("GleamIsAwesome")
  redraw.use_effect(fn() {
    io.println("Hello from component!")
  }, #()) // Passing an empty tuple here is like passing [] in JavaScript.
  html.div([attribute.class("oh-yeah")], [
    html.text("Yeah, for sure")
  ])
}

Using external components

React is greatly used everywhere. It means a lot of components are already usable out-of-the-box. Happily, Redraw provides a way to interop directly with them! Use to_component and to_component_ to integrate a foreign function directly. Define the correct props, and your work is done! Don’t worry about snake_case and camelCase of props name, Redraw take care of the translation for you. Everytime you put an Option(a), Redraw will also translate it to a | null, because React use the convention to pass null everywhere instead of optionals.

import gleam/option.{type Option}
import redraw
import redraw/html

// This type will be converted to correct JS props.
pub type ExternalComponentProps {
  ExternalComponentProps(
    first_field: Bool,             // firstField: bool
    second_field: Bool,            // secondField: bool
    optional_field: Option(String) // optionalField: string | null
  )
}

@external(javascript, "external_module", "ExternalComponent")
fn external_component_ffi(props: a) -> redraw.Component

fn external_component() -> fn(ExternalComponentProps) -> redraw.Component {
  redraw.to_component_("ExternalComponent", external_component_ffi)
}

pub fn my_other_component() {
  let external_component = external_component()
  use <- redraw.component__("OtherComponent")
  html.div([], [
    external_component(
      ExternalComponentProps(
        first_field: True,
        second_field: False,
        optional_field: option.None,
      )
    )
  ])
}

Miscellaneous

Some questions, answers, and various informations.

What is the state of support for React Native, or any other React flavor?

React is an isolated packages, and renderers can be various. Redraw has successfully be used with Raycast. You can also easily add a redraw_native package, and provide an interface for native components. Everything can be done quickly and easily, because the entire package is written with as few JS as possible. Everything should work almost out-of-the box, because React is already working there. You should take inspiration at how is working redraw/html, and it could work in the exact same way. It’s only a matter of providing the correct Component to jsx.

Contributing

Do you love the package? You can contribute! Feel free to open a PR, or open an issue!

Why wrapping every components in use props <- component(name)?

If you’re used to React, you know a component is no more than a function, returning a ReactNode. Something like this:

function GleamIsAwesome(props) {
  return <div className="oh-yeah">Yeah, for sure</div>
}

Actually, because of JSX, React is a bit lying to all of us, and compiles it to:

import { jsx } from "react/runtime-jsx"

function GleamIsAwesome(props) {
  return jsx("div", { className: "oh-yeah", children: "Yeah, for sure" })
}

React injects a call to jsx before every JSX render. This allows for the runtime to determine if the function should be called once again with the new provided props. It’s also true for functions.

// That code
function ILoveBeam(props) {
  return <div>BEAM 💜</div>
}

function GleamIsAwesome(props) {
  return (
    <div className="oh-yeah">
      <ILoveBeam />
      Yeah, for sure
    </div>
  )
}

// Turns into
import { jsx, jsxs } from "react/runtime-jsx"

function ILoveBeam(props) {
  return jsx("div", { children: "BEAM 💜" })
}

function GleamIsAwesome(props) {
  return jsxs("div", {
    className: "oh-yeah",
    children: [jsx(ILoveBeam, {}), "Yeah, for sure"],
  })
}

Here, we got a problem: we cannot inject the jsx call before ILoveBeam in Gleam. What we could do is write a function that generate the jsx call with an other function with use, but anonymous functions cannot be used with React: React is doing referential equality for Functional Components. Every component should be defined once and for all.

To inject the jsx call properly, it would requires an additional compilation-step. Because we cannot do this, we pass by a generator function. That’s what use props <- component(name) is doing. To get the correct result, we go to a Component creator, a function that create a component once and for all from a render function. Everytime we create a component, we use a render function and turns it into a proper component to be used with React.