Add more motivation to the intro #60
Conversation
| 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. |
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 | ||
| 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 | ||
| 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/). | ||
|
|
||
| **Elm** is similar to OCaml but leans much more 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. | ||
|
|
||
| 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, | ||
| js_of_ocaml prioritizes OCaml compatibility over JavaScript interop. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
I would move this into a separate section or even in the melange documentation
There was a problem hiding this comment.
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.
| that translates OCaml to human-readable JavaScript and built-in language | ||
| constructs for zero-cost interoperation with JavaScript. | ||
|
|
||
| ## Why OCaml? |
There was a problem hiding this comment.
Same discussion as ever, but "Why OCaml?" when you will write the book in reason is strange, confusing
There was a problem hiding this comment.
It seems to me that most of the benefits of Melange come from OCaml, and the book does teach OCaml (using Reason syntax).
There was a problem hiding this comment.
Oh wait, do you mean Melange in the sense of the subset of OCaml language supported by Melange?
| that translates OCaml to human-readable JavaScript and built-in language | ||
| constructs for zero-cost interoperation with JavaScript. | ||
|
|
||
| ## Why OCaml? |
There was a problem hiding this comment.
It seems to me that most of the benefits of Melange come from OCaml, and the book does teach OCaml (using Reason syntax).
| 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. |
There was a problem hiding this comment.
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.
|
|
||
| **OCaml** has another JS transpiler called js_of_ocaml. Unlike Melange, | ||
| js_of_ocaml prioritizes OCaml compatibility over JavaScript interop. | ||
|
|
There was a problem hiding this comment.
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?
| 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 | ||
| 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 | ||
| 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/). | ||
|
|
||
| **Elm** is similar to OCaml but leans much more 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. | ||
|
|
||
| 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, | ||
| js_of_ocaml prioritizes OCaml compatibility over JavaScript interop. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
It's looking great.
A note on the comparison section, it might sound a bit defensive, maybe some wording like usages of "but" ("TS is easier, but...", "Elm is similar, but..."), and also some extended usage of adjectives that can be vague ("much more strongly", "many fewer options"...) contribute to that?
Maybe this section should show alternatives and why one would pick them up (rather than focusing on what they're missing).
If the goal is to show what things they're missing (pattern matching, React integration, zero cost bindings, JSX) it might be better to create a table instead.
|
|
||
| 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 |
There was a problem hiding this comment.
The "if it compiles, it runs" is a bit confusing because TypeScript also "runs if it compiles" 😄 What about
| program---if it compiles, it runs. OCaml and React (via | |
| program---if it compiles, it runs without runtime errors. OCaml and React (via |
?
| 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 |
There was a problem hiding this comment.
| 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 |
| **ReScript** is very similar to OCaml, even at the syntax level. Its | ||
| RescriptReact library is roughly equivalent to our ReasonReact library. The main |
There was a problem hiding this comment.
| **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 |
| metaprogramming features of OCaml, so you lose the ability to, say, [embed CSS | ||
| styles directly into your code](https://styled-ppx.vercel.app/). |
There was a problem hiding this comment.
Styled-ppx supports ReScript, so I would rather mention the ability to write universal components as the main benefit or Melange + ReasonReact.
| environments. There's no Dart wrapper library for modern, functional React | ||
| components. | ||
|
|
||
| **OCaml** has another JS transpiler called js_of_ocaml. Unlike Melange, |
There was a problem hiding this comment.
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.
| components. | ||
|
|
||
| **OCaml** has another JS transpiler called js_of_ocaml. Unlike Melange, | ||
| js_of_ocaml prioritizes OCaml compatibility over JavaScript interop. |
There was a problem hiding this comment.
I'd also mention that the story to use React is much more stable and tested in Melange than in jsoo.
| metaprogramming features of OCaml, so you lose the ability to, say, [embed CSS | ||
| styles directly into your code](https://styled-ppx.vercel.app/). | ||
|
|
||
| **Elm** is similar to OCaml but leans much more strongly towards pure functional |
There was a problem hiding this comment.
| **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. |
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
"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"
| **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 |
There was a problem hiding this comment.
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.
Addresses #58