fable-compiler / fable-compiler.github.io

Fable web site
https://fable.io
23 stars 63 forks source link

Document how to interop with JavaScript code/libraries #181

Closed mattgallagher92 closed 6 months ago

mattgallagher92 commented 6 months ago

I don't think this is in the Fable docs; it would be very useful to have!

When writing custom bindings for JavaScript libraries, I often refer to https://medium.com/@zaid.naom/f-interop-with-javascript-in-fable-the-complete-guide-ccc5b896a59f. There are a few reasons why this isn't ideal:

A page in the docs would be easier to find, provide more confidence that it's up to date and could be more focused.

MangelMaxime commented 6 months ago

Reading through the article it feels like most of the informations are already presents in Fable documentation with the difference of not being applied to a specific library.

What do you feel is missing?

Personally, I would say perhaps a more applied (macro level) example of how to mix everything together? We could for example take a specific library like dayjs which covers a lot common cases and write a similar step by step, conversion process explaining the decision taken?

As an additional potential ressource, there is also Glutinum specs which can be useful to know how a specific TypeScript syntax should/could be transformed into F#. This is not as friendly as a blog post, will be more exhaustive over time as Glutinum will supports more syntax.

MangelMaxime commented 6 months ago

To answer your points more specificitly:

It's not as easy to find as it would be if it were in the Fable docs. Newcomers likely don't know it exists.

True

It was written in 2017. I don't know whether there have been later changes to Fable which add more alternatives with different tradeoffs.

Indeed, Fable provides alternatives especially around POJO most importantly [<ParamObject>] which I tried to explains the why, and tradeoff / backward compatibility.

I also remember that the Interop guide, guide people in a direction to create more like a library on top of the binding instead of a raw binding which exposes an equivalent API as in JavaScript.

It's more verbose than I'd like for a reference (which makes sense - its purpose is to teach, not to be a reference).

Fable documentations contains a TOC which I hoped to be used as a reference table to quickly go to the section that matters for the users.

If you have feedbacks regarding the pages or feels like something is missing feel free to tell me via an issue or PR.

mattgallagher92 commented 6 months ago

Thanks for the quick reply Maxime! And thanks in particular for pointing out the Glutinum specs and [<ParamObject>] :slightly_smiling_face:

Sorry, you're right; I didn't open the "Features" page. I guess, for reasons that I can't explain, I didn't think that the documentation I wanted would be on that page. Perhaps because it had a different name like "calling JS from F#" in an old version of the docs, and I was looking for that.

I think the docs are good as they are :slightly_smiling_face: sorry for wasting your time :disappointed:

There could be some value in the things that you suggested, such as the applied example, but I don't think it's necessary for now.

MangelMaxime commented 6 months ago

Sorry, you're right; I didn't open the "Features" page. I guess, for reasons that I can't explain, I didn't think that the documentation I wanted would be on that page. Perhaps because it had a different name like "calling JS from F#" in an old version of the docs, and I was looking for that.

Yes, when doing the rewrite I renamed the page and Features is not a perfect name but allows us to have the same structure for all the targets. Which was a requirement for the rewrite of the documentation.

No worries, always happy to help :)