Get started

This page explains the different modules available in server-reason-react and how to use them.

It assumes a minimum understanding of:

• Reason
• reason-react (the react.js bindings)
• Melange (the JavaScript compiler)
• dune (the build system)

Installation

From opam's registry (recommended)

opam install server-reason-react

From source

To use the development version, install via opam pinning:

opam pin server-reason-react.dev "https://github.com/ml-in-barcelona/server-reason-react.git#main" -y

Setup

Add to your dune file:

(libraries (server-reason-react.react server-reason-react.reactDom))
(preprocess (pps server-reason-react.ppx))

Usage

server-reason-react provides React and ReactDOM modules with the same interface as reason-react, including JSX transformation via server-reason-react.ppx. Components follow the standard reason-react API as explained in their official documentation.

Here's a simple component:

module Greetings = {
  [@react.component]
  let make = (~name) => {
    <div>
      <h1> {React.string("Hello " ++ name)} </h1>
    </div>
  };
};

Components are functions that return a React.element and are annotated with @react.component. By convention, they are named `make`. When used in JSX, they can be written without the `make` prefix, using just the module name.

Here's a longer component with state:

module Counter = {
  [@react.component]
  let make = (~name) => {
    let (count, setCount) = React.useState(() => 0);
    <div>
      <p> {React.string(name ++ " " ++ Int.to_string(count))} </p>
      <button onClick={_ => setCount(_ => count + 1)}>
        {React.string("Click me")}
      </button>
    </div>
  };
};

Hooks like React.useState or React.useEffect are available but are no-ops when running on the server. Since components don't re-render on the server. Hooks like React.useCallback and React.useMemo have no memoization and return values just once.

Server-side Rendering

The main difference from reason-react is the ability to render on the server using ReactDOM. The module provides three rendering methods:

renderToString/renderToStaticMarkup

ReactDOM.renderToString renders a React tree as a HTML string:

let html = ReactDOM.renderToString(<App />);

ReactDOM.renderToStaticMarkup renders a non-interactive React tree (can't be hydrated on the client):

let html = ReactDOM.renderToStaticMarkup(<App />);

renderToStream

ReactDOM.renderToStream renders a React tree as a Lwt_stream of type Lwt_stream.t(string):

let%lwt (stream, abort) = ReactDOM.renderToStream(<App />);
stream |> Lwt_stream.iter_s((chunk => {
  let%lwt () = Dream.write(response_stream, chunk);
  Dream.flush(response_stream);
}));

Note: Lwt is required. See this issue for details.

React Server Components

React Server Components (RSC) is an architecture that allows you to render React components exclusively on the server, using server-side code (such as query the database or access the filesystem). It also, allows to differentiate server and client components (those components that require interactivity). Making sure that server ones are stripped from the JavaScript bundle sent to the client, while client components are loaded only when needed.

There's a entire area of improvements that RSC bring to the table, such as decreasing the bundle size by lazy loading client components, remove data fetching with useEffect hooks (by passing just promises), streaming the result of the server rendering of the page or stream the RSC payload, removes state by lifting it to the URL, to name the most notable ones.

This library supports it, but many pieces are being polished right now, check the demo folder for more information or the umbrella issue.