Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more motivation to the intro #60

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 82 additions & 10 deletions docs/intro/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,92 @@

This is a work in progress.

We'd love to hear your feedback! If you find any errors or have suggestions for
the book, please [file an
issue](https://github.com/ahrefs/melange-for-react-devs/issues) or ping @feihong
on the [#melange channel in the Reason Discord](https://discord.gg/reasonml).

:::

## Motivation
## What is Melange?

Melange is a collection of tools that bring the robustness of a mature,
statically-typed multi-paradigm programming language to the JavaScript
ecosystem. That language is OCaml, a language invented in the 1990s which has
been battle-tested by industry stalwarts. The heart of Melange is a compiler
that translates OCaml to human-readable JavaScript and built-in language
constructs for zero-cost interoperation with JavaScript.

## Why OCaml?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same discussion as ever, but "Why OCaml?" when you will write the book in reason is strange, confusing

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems to me that most of the benefits of Melange come from OCaml, and the book does teach OCaml (using Reason syntax).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh wait, do you mean Melange in the sense of the subset of OCaml language supported by Melange?


OCaml codebases scale well both in terms of quantity of lines and number of
contributors. The sound type system helps to prevent ambiguous behavior in your
program---if it compiles, it runs. OCaml and React (via
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "if it compiles, it runs" is a bit confusing because TypeScript also "runs if it compiles" 😄 What about

Suggested change
program---if it compiles, it runs. OCaml and React (via
program---if it compiles, it runs without runtime errors. OCaml and React (via

?

[ReasonReact][reasonreact]) are an effective, FP-friendly combination for
building frontend UIs using JSX syntax. If the backend is also written in OCaml,
you can share types between the frontend and backend, ensuring that they stay in
sync[^1]. In the near future, it will be possible to write [universal React
components](https://github.com/ml-in-barcelona/server-reason-react) that are
performantly rendered on the server using OCaml.
Comment on lines +31 to +33
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't say "I the near future", it's already possible. It's just not polished. I would explain within the previous sentence: you can write a full-stack application (sharing types, components rendered on the server, etc etc)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about:

If the backend is also written in OCaml,
you can share types between the frontend and backend, ensuring that they stay in
sync[^1]. It's even possible to write universal React
components
that are
rendered on the server with the performance of native code[^2].

The [^2] footnote will explain that it's not yet polished.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a better phrasing indeed


All that said, how does OCaml compare against other prominent compile-to-JS
languages?

**TypeScript** is a gradually-typed superset of JavaScript. It is easier to
learn and adopt, but is less type-safe than OCaml and all other langues on this
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
learn and adopt, but is less type-safe than OCaml and all other langues on this
learn and adopt, but is less type-safe than OCaml and all other languages on this

Comment on lines +38 to +39
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would try to be more expressive on comparing with TypeScript.

TypeScript is a gradually-typed superset of JavaScript. It's easier to
learn and adopt. His design, following closely JavaScript, brings a few footguns, like any, "as" casting, and ts-nocheck (to say a few) becoming less type-safe than OCaml.

list. TypeScript doesn't support pattern matching at the language level.

**ReScript** is very similar to OCaml, even at the syntax level. Its
RescriptReact library is roughly equivalent to our ReasonReact library. The main
Comment on lines +42 to +43
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**ReScript** is very similar to OCaml, even at the syntax level. Its
RescriptReact library is roughly equivalent to our ReasonReact library. The main
**ReScript** is very similar to OCaml, even at the syntax level. Its
rescript-react bindings are roughly equivalent to Melange reason-react bindings. The main

differences are that ReScript's only compilation target is JS, and it lacks the
metaprogramming features of OCaml, so you lose the ability to, say, [embed CSS
styles directly into your code](https://styled-ppx.vercel.app/).
Comment on lines +45 to +46
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Styled-ppx supports ReScript, so I would rather mention the ability to write universal components as the main benefit or Melange + ReasonReact.


**Elm** is similar to OCaml but leans much more strongly towards pure functional
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**Elm** is similar to OCaml but leans much more strongly towards pure functional
**Elm** is similar to OCaml. It leans strongly towards pure functional

programming. It cannot use React but comes with its own framework. It has many
fewer options for JS interop. Even though Elm compiles to JS, it can't be used
for backend development, even on Node.
Comment on lines +49 to +51
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
programming. It cannot use React but comes with its own framework. It has many
fewer options for JS interop. Even though Elm compiles to JS, it can't be used
for backend development, even on Node.
programming. It has fewer options for JS interop and cannot use React but comes with
its own framework. Elm can't be used for backend development, even on Node.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"It cannot use React but comes with its own framework".

It's more like: "Elm treats JavaScript as unsafe, with possibility to interact with it via ports. Integrations like React or Melange FFI aren't possible"


This is a project-based, guided introduction to Melange and its ecosystem.
**F#** is a fullstack language similar to OCaml and is strongly aligned with the
.NET ecosystem. F# has good support for functional programming and zero-cost
interop with C#. Feliz is an F# wrapper library for React that doesn't support
JSX.

**Kotlin** is a type-safe fullstack language strongly associated with the
Compose Multiplatform UI framework. Kotlin-react is a Kotlin wrapper library for
React which doesn't support JSX. Kotlin has some features in common with OCaml,
but doesn't have pattern matching.

**Dart** is a type-safe fullstack language strongly associated with the Flutter
UI framework, which supports compiling UI apps to mobile, desktop, and browser
environments. There's no Dart wrapper library for modern, functional React
components.

**OCaml** has another JS transpiler called js_of_ocaml. Unlike Melange,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's the Melange for X developers page that has a jsoo section, not sure if worth mentioning.

Also includes subsections about ReScript and TypeScript.

js_of_ocaml prioritizes OCaml compatibility over JavaScript interop.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd also mention that the story to use React is much more stable and tested in Melange than in jsoo.


Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Originally I had one paragraph for Rust here, but not sure if it's really in the same space as it compiles to WebAssembly and not normal JS. Should I bring it back?

As you can see, each compile-to-JS language has its own design goals, which
dictate its strengths and weaknesses relative to OCaml and Melange.
Comment on lines +35 to +72
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would move this into a separate section or even in the melange documentation

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The language comparison section was added in response to #58 and also another reader who responded to me via DM. But I agree it makes sense to add it to Melange docs as well.


## This book

This is a project-based, guided introduction to Melange and its ecosystem,
including ReasonReact, the dune build system, and various useful libraries.
Because Melange uses both OCaml and JavaScript ecosystems, there are quite a few
tools and concepts to learn. Therefore we try to make each chapter small and
digestible, not introducing too many things at once.
digestible, not introducing too many things at once. At the end of each chapter,
you'll find exercises with solutions.

## Audience

You should already know how to make frontend applications in JavaScript, in
particular with [React](https://react.dev/). You should be interested in
learning how to leverage your existing knowledge to build apps using
[ReasonReact](https://reasonml.github.io/reason-react/). You do not need to know
OCaml[^1]---we'll slowly introduce the basics of the language throughout the
tutorial. That said, a good complement to this guide is [OCaml Programming:
Correct + Efficient + Beautiful](https://cs3110.github.io/textbook/), which
teaches the language from the ground up and goes much deeper into its features.
[ReasonReact][reasonreact]. You do not need to know OCaml[^2]---we'll slowly
introduce the basics of the language throughout the tutorial. That said, a good
complement to this guide is [OCaml Programming: Correct + Efficient +
Beautiful](https://cs3110.github.io/textbook/), which teaches the language from
the ground up and goes much deeper into its features.

## Chapters and topics

Expand All @@ -46,8 +113,13 @@ teaches the language from the ground up and goes much deeper into its features.

...and much more to come!

[^1]:
Because of the focus on ReasonReact, we won't cover traditional OCaml
[reasonreact]: https://reasonml.github.io/reason-react/

[^1]: If the backend language isn't OCaml, you can still share types between
frontend and backend through a third-party tool like
[atd](https://github.com/ahrefs/atd).

[^2]: Because of the focus on ReasonReact, we won't cover traditional OCaml
syntax in this guide. Instead, we'll cover the [Reason
syntax](https://reasonml.github.io/) which works great with ReasonReact
because of its first-class support for JSX.