improving getting started instructions

[johnynek]

I have almost no frontend experience, but I wanted to try outwatch to make a basic UI.

It would be really nice to have the most basic possible hello world example with no skipped steps.

I have an existing project, so I wanted to make the minimal addition to my sbt build, but I didn't have problems there. The first problem I had was:

1. When starting the hello world example from here: https://outwatch.github.io/docs/readme.html I didn't see what the exact path to the .js file. I should use. Eventually, by looking at scalajs, I found that I should run fastLinkJS and then use the file that was printed, but that didn't work. The snabbdom library seems to be using a require function that doesn't work on browsers.
2. I saw that I needed to add the bundler plugin but I didn't see that I had to do anything extra. The next thing I had to figure out was that I need to run fastOptJS::webpack to solve this issue.
3. But on my M1 mac, brew has installed for me Node 21.6.1 today. So the next issue I hit was this: error:0308010C:digital envelope routines::unsupported around a Hash instantiation. In order to solve that, I exited sbt and at the shell did export NODE_OPTIONS=--openssl-legacy-provider and then restarted sbt. Then the build command worked.

I know it's a challenge to make a tutorial accessible to someone with as little knowledge as myself on the subject, but I spent about 2 hours setting up and solving the above issues, when it seems like we could have a set by step with no missing bit (e.g. the readme doesn't say what path to JS to put, or how to find it, nor does it tell you which sbt task to use).

Anyway, maybe this issue can be of help to other similiarly clueless folks as myself.

[cornerman]

First of all thank you very much for opening this issue and writing down the points of struggle!

It is definitely not super easy to set it up and there a few gotchas. I am on holiday right now, but will try to address these points when i come back next week.

There is also the question of using webpack (i.e. ScalaJSBundler) or vite for bundeling your javascript code and it dependencies. Currently all our tutorials point to the former - and i want to update that as well.

Please bear with me and let me know about any other issue you encounter.

[cornerman]

For the record, we now have an example using vite here: https://github.com/outwatch/example-mill-vite. The documentation section on the website mentions the new example. But I think, there are still a few more points to mention about the setup. Keeping this open for now.