Hi there! I’m a developer with a lot of backend experience with functional languages, and frontend experience with Elm/ClojureScript.
Part of what’s been great with Elm and ClojureScript (when set up with new tooling) is that the source code → JS-output for the browser is contained in one, maybe two tools. Additionally, the tooling provides fast reloads of CSS and changes in the source code, meaning that for a programmer new to frontend, it’s easy to set up. And if you want to do something out of the ordinary, the documentation is good enough to understand how to change it for your needs.
For example: I’m working on a multi-page application using the pure browser Web API (i.e. no React), and how to set up a project like that isn’t common in ClojureScript, but you can figure out how with the user guide.
However, the documentation over at ReScript Installation doesn’t help me much here, and I think the primary problem for me is that I’m told to run npx create-rescript-app. This effectively lets me decide between Vite/React/Tailwind or Next.js/Tailwind, neither of which I want in the first place.
Well… the create-rescript-app isn’t a problem per say – I’d assume it’s quite nice if you know what’s happening – but the fact that I have no step-by-step walkthrough from scratch makes it hard for me to know exactly what rescript is doing and what other tools must be set up (and what they do). I presume this is understandable for JS/TS-users well versed in the ecosystem, but at least for me, it’s hard to know how to set things up manually.
Is there a tutorial somewhere on how to create a ReScript project from scratch, which also explains how the different tools interact with each other?
You raise great points, and I’m working on writing up some tutorials and improving the getting started docs.
You said a single page app without React, so just vanilla JS? Are you just loading in an HTML file, or are you hoping for some type of dev server with hot reloading that will also bundle the site?
You said a single page app without React, so just vanilla JS? Are you just loading in an HTML file, or are you hoping for some type of dev server with hot reloading that will also bundle the site?
Heh, I actually wrote multi-page application In my case, my goal is to have an interactive tutorial for data structures and algorithms, kinda like what Red Blob games do. So concretely, I aim to have something like this:
A single, shared .js bundle that contains dependencies and shared logic
One .js file per page
The HTML page (either hand-crafted or generated by something else) have a couple of divs with IDs that the application hooks into and replaces
I’d like to have hot reloads of at least the CSS, though I think just normal automatic reloads of the others is what I can get with ReScript – …but perhaps there’s some way to distinguish state and rendering logic inside a ReScript app that means I can, at dev time, only reload the rendering logic?
That’s very particular for my problem though. What I’d like is more of a general tutorial that can help me on my way to get to such a setup, or make me realise if this is not recommended at the moment. I’ve seen Getting started | Experimental WebAPI which says “Experimental”, so maybe I’m a bit early to the party.
The “experimental” part just means it isn’t done or part of the compiler yet. It’s actually great if you try and use it and provide feedback. We want to make sure it’s easily adoptable to newcomers, so you’re the perfect target!
I’ve been poking at this trying to come up with some ideas, and I have a few follow up questions and thoughts.
Do you want a single HTML file that just loads in JS? You could do this with Parcel and get hot reloading when ReScript compiles or for changes to CSS and HTML. You could do lazy loading to break up the code into smaller files and import when needed. This is a very manual approach and navigation and routing would be tricky.
Do you want to just be able to deploy static files, or would you be OK with a server? HTMX might be a a good option.
It loads in an HTML file with CSS and JS and does hot reloading on file changes, and it does a good job of bundling including code splitting.
Since I’m not using a framework, I set up a main index.res file that loads in and uses pattern matching on location.pathname and depending on the path it lazy imports a different modules render function. That function replaces the html inside of #main with that page.
It’s pretty basic, but it does use the new experimental webapis and might be an interesting starting point if you want to poke around at a really basic app that doesn’t have a framework.
this is a very interesting question and I think it boils down to the philosophy of the project compared to Elm/ClojureScript. The latter are meant to be battery included, fully integrated, while ReScript is seen as a drop-in replacement of JS, a compiler that generates regular JS and that is meant to Just Work TM with the rest of the JS ecosystem. So if you’re trying to do something with ReScript, you’re basically supposed to try to make it work with JS and then just bring ReScript and you should be good to go.
There’s actually a manual setup guide if you don’t like create-rescript-app.
I understand this can be an issue for newcomers in the web ecosystem because you then have to learn two things, the web and ReScript while you can just learn Elm/ClojureScript. But it also makes gradual migration and reusing existing JS tooling much easier.
This is the great part about ReScript, and it also means that before you start using ReScript you currently have to have some knowledge about how JS and the ecosytem works. We probably have some room to add in more tutorials about how to get going for those who are not familiar with JS.
A good example is this note for the ReScript React docs:
This documentation assumes basic knowledge about ReactJS.
Please note that even though we will cover many basic React concepts, it might still be necessary to have a look at the official ReactJS resources, especially if you are a complete beginner with React.
We aren’t teaching or documenting how to use React, just how to use ReScript with React.
I think we need to get some docs/blog posts on the site about how to get started using frameworks that are built using ReScript for ReScript, such as res-x or rescript-rest. These would be good starting points for people who have not worked in the JS ecosystem and are coming to ReScript from other languages and stacks.
As I tried to explain above, the intent is really to have one codebase for a multi-page application (i.e. one shared bundle and one js file per page. Not an issue having manual work to add another page), and using low-level/self-designed tools to render visualisations and animations in either SVG, canvas, or maybe even WebGL (though I’m miles away from the last one) that the code finds by doing .getElementById when it’s loaded in.
I understand the ReScript idea of just having a .res/.resi → .js converter that works with the entire JS ecosystem out of the box. It’s great, because ReScript can just leverage the existing tools out there, which is super nice.
But let me be clear on something: I’ll be more than happy to just have a link to a tutorial for all the common tools, and how they interact with JavaScript-code. Then, if there’s some gotchas that needs to be addressed that can come after that link – though I assume that’s not really the case if you can run rescript -w in another terminal window, and the tools pick up .js changes. I don’t expect you to make a tutorial for the JS tooling itself (and neither do I think it’s sensible, unless there are enough caveats in the setup)
This looks very promising. It’s not exactly what I’m looking for, but it’s far less work to explore how to make multiple js-files with parcel than to tackle the entire JS tooling setup. I’m a little busy the coming days, but I’ll fork it later and see if I can get it to emit multiple files.
What you’re looking for is a “Multi Page” application. A lot of the tooling out there focuses on either a single entry file (Single Page App) or Server Side Renderring, but a Multi Page app generates a different JS file for each page (plus some optimizations for shared code)
I haven’t used it myself but vite supports multiple page apps and is really popular right now: Building for Production | Vite
With rescript, you’d usually have two terminals open, one with rescript (npm run dev:res) and then one with vite (npm start)
In my case, my goal is to have an interactive tutorial for data structures and algorithms, kinda like what 