melange-re / melange-re.github.io Goto Github PK

So we can track visitors over time, pages that receive more visits...

umami has a free plan, looks like it'd be enough.

• v2 only compatible with OCaml 5.1
• Adding melange.ppx is now in 99% cases a must, as it has to be added in multiple cases where it was not needed before
• Some warnings have been turned to alerts, so they might be visible even if using vendored_dirs
• Js_foo modules need to be replaced with Js.Foo (same for Belt_* modules)
• Belt_MapInt is now Belt.Map.Int
• The payload of deriving now has different type, { jsConverter = newType } becomes jsConverter { newType } (see below)
• bs.deriving is replaced with deriving
• All @bs attrs are replaced with @mel
• Except [@bs] which is replaced by [@u]
• @bs.val is deprecated (can be removed)
• Effect handlers will be turned off
• Adding melange.dom and melange.node to libraries is required when using those modules.
• tbc...

Can include things like:

• Open source application examples
• Blog posts, tutorials
• Videos and podcasts
• Libraries
• Templates
• Built with Melange (prod apps)

I don't think we link to https://github.com/melange-re/melange anywhere on the site at the moment 😅

The unstable version of Melange has a couple of breaking changes:

• does not support bs.deriving anymore, it's been replaced with deriving
• fields using bs.optional should have type <something> optional

We should update the docs to reflect that.

ref: melange-re/melange#583

See melange-re/melange#722.

Should line 858 in communicate-with-javascript.md have two % signs for the Reason syntax as the text describes, or is this section (lines 847 to 860 specific to OCaml syntax and should be hidden when the reader selects the Reason syntax?

Now that opam-check-npm-deps is published in opam, we should update the docs to document how to use it, for both bindings authors and users.

In build system section.

          The `reactjs-jsx-ppx` might be renamed soon, we will have to remember to update the docs here.

Originally posted by @jchavarri in #83 (comment)

This attribute has been replaced by deriving in the latest Melange version.

Should there be a section in the website for the react-ppx bindings since those are distributed as a package on the Ocaml package site?

I imagine the existing reason-react site might get out of date at some point.

Is this something that an outside contributor(like myself) could submit as a PR?

Multiple pages in the Dune docs are moving in the latest version, e.g.

https://dune.readthedocs.io/en/latest/reference/preprocessing-spec.html

vs

https://dune.readthedocs.io/en/stable/concepts.html#preprocessing-specification

Once 3.8 is merged, we should revisit all links in the docs to make sure they work.

@anmonteiro do you think is is necessary to document the melc command? I was thinking, it is the closest that could exist as a repl today (not sure if the output from melc can be piped into a node command), and at the very least, it allows to see the generated code. Some people might find that useful for learning how the compiler works? 🤔

From @anmonteiro:

we should consider publishing the docs to a path like /stable so that we can keep newer branches as we document stuff for dev features

Right now the process is manual.

For ReScript users, for OCaml users, for TypeScript/JavaScript users.

All snippets should be shown on either OCaml syntax or Reason syntax. We can write both manually if needed (it's not too much work), but some kind of switch should be added in the frontend.

For BuckleScript original site, @rusty-key implemented the switch originally back in 2018: rescript-lang/bucklescript.github.io#50

Rescript es6 version of stdlib included a package.json with "type": "module"

https://github.com/rescript-lang/rescript-compiler/blob/77b6a3bcd63989d2fb015c8a2543d87f3cb45007/lib/es6/package.json

This comes useful when running nodejs apps with es6 bundling, as otherwise one has to resort to workarounds like custom node loaders, using mjs extensions and such.

There is a workaround using dune rules:

(subdir
 target
 (subdir
  node_modules
  (subdir
   melange
   (rule
    (alias my_melange_alias)
    (action
     (with-stdout-to
      package.json
      (run echo "{\"type\": \"module\"}")))))
  (subdir
   melange.belt
   (rule
    (alias my_melange_alias)
    (action
     (with-stdout-to
      package.json
      (run echo "{\"type\": \"module\"}")))))
  (subdir
   melange.runtime
   (rule
    (alias my_melange_alias)
    (action
     (with-stdout-to
      package.json
      (run echo "{\"type\": \"module\"}")))))))

But it has to be defined for the 3 libraries exposed by Melange, and also replicated for every melange.emit stanza used.

I wonder if Melange could include package.json files similarly. The problem applies to any library really, so there might be some generic solution out there. Most probably it needs some coordination with Dune? 🤔

cc @denis-ok

In this section the docs talk about using @bs.uncurry when you have a lot of annotations with @bs and that they can become cumbersome; however, ReasonML uses . instead of @bs, which is readable and not that cumbersome, so does the described use of @bs.uncurry only really apply to OCaml?

It would be nice to have some script to run the code snippets through the most recent versions of melc to make sure they remain in good state.

Ultimately, this script could be added to some CI workflow.

As more libraries get migrated and published in opam, this will become easier. But we should document how the transition happens.

Summary:

• the lib has no dune file: consume with npm, add dune config through Dune's subdir node_modules, use vendored_dirs to silence warnings
• the lib has dune, dune-project and opam file but is not published in opam official repo: consume with opam, use opam pin to point to repository
• the lib is published in opam repository: normal OCaml workflow

• Bundle stdlib / runtime .cmt files
• Generate .cmt from OCaml / ReasonML compilation

https://twitter.com/ceramichacker/status/1666586535108509697

• Runtime code examples; how Js.* compares to the jsoo ppx syntax.
• brief snippets in creating and using bindings to other libraries
• differences in setup, if it's anything more than the mode stanza
• elaboration as to how Melange provides a smoother development experience

I am trying to go through the example in the 'Build system' section of the docs, but when I do dune build @melange it fails with:

File "dune-project", line 1, characters 11-14:
1 | (lang dune 3.8)
               ^^^
Error: Version 3.8 of the dune language is not supported.
Supported versions of this extension in version 3.8 of the dune language:
- 1.0 to 1.12
- 2.0 to 2.9
- 3.0 to 3.7

(I'm on MacOS (ARM processor))

it'd be nice to have a section where we credit the projects / companies relying on Melange for their production use cases, as well as folks who financially back the project.

As discussed in #3 (comment), would be nice to have a link to see all the docs in a single page, or download a pdf.

Currently, the Getting Started docs highlight the [template]( template, which is definitely the easiest way for most people to jump in, but personally I like to set up new projects by hand because I feel like it helps me get more familiar with how the ecosystem's tools fit together. Especially as someone coming from Bucklescript, I'm less familiar with how the opam and dune pieces fit together, and I'd like more hands-on experience getting a project set up with those tools.

Some specific things I'm confused about:

• opam installs dune, then I can use dune init to create a project... which will likely have its own opam switch? Do I first need to create an opam switch with the version of dune I want to use inside the new project?

...wait, maybe that's the only thing I'm confused about. 😆 I'll keep working through this and let you know if there's anything else that confuses me.

For learning / teaching purposes, it'd be interesting to allow having a set of Melange snippets under the same playground link.

From a author point of view, I should be able to:

• Create a new group (let's call it a "lesson")
• Add new snippet to the lesson

From a reader point of view, I should be able to:

• Open a link to a lesson
• Navigate the snippets in the lesson

One of the main upsides of this approach is that if one of the snippets in the lesson fails to compile, the other snippets would be unaffected.

For implementation purposes, the layout / ui of this new feature could be something similar to what already exists with the examples, except that users can create or modify the group of snippets to their will:

We should check if there are issues in generated Reason by running dune build @re, which diffs against in-source and generated.

Should we have section where we document how OCaml syntax is supported by default, but Reason is also available? This section would include the steps to have Reason installed, and maybe mention the things that work and those that are not there yet (like error types being shown in Reason syntax).

We should support dune, reason and ocaml at least. Maybe opam too.

Dune has some support for Dune and opam files: https://github.com/jchavarri/dune/tree/c28b2c6b051d20646df3ca708df3de23b63600f3/doc/exts

The docs use @bs.splice for variadic functions but there is no mention of it in the list of attributes and extension nodes. ReScript has deprecated @bs.splice in favour of @bs.variadic - is it the same for Melange and should @bs.splice be replaced with @bs.variadic in the docs?

Recently helped some Discord user where was struggling with a compile error, and turns out he missed the reactjs-jsx-ppx, (wrapped false) and other sneaky pieces.

We made the process 90 times in Ahrefs and would be a nice tutorial to help others contribute to melange-community.

• Go to https://melange.re/unstable/playground/?language=OCaml&code=bGV0IHJlYyByYW5nZSBhIGIgPQogIGlmIGEgPiBiIHRoZW4gW10KICBlbHNlIGEgOjogcmFuZ2UgKGEgKyAxKSBi&live=off
• Remove the b at the end of line 3, it will show an (expected) compiling error
• Add b back

It shows an error Melange_compiler_libs__Warnings.Errors when it should compile just fine.

Happens on both unstable and v1.

See related melange-re/melange#538

#81 (comment)

Should @bs.config and --preamble have some documentation, especially since NextJS and RSC will require things like [@bs.config {flags: [|"--preamble", "\"use client\";"|]}];