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.
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!
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.
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 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!
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!
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.
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!
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.
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")
])
}
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,
)
)
])
}
Some questions, answers, and various informations.
React is an isolated packages, and renderers can be various. Redraw has
successfully been 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
.
Do you love the package? You can contribute! Feel free to open a PR, or open an issue!
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.