Create Scala.js g8 template

[tgodzik]

Giter8 templates are used in a number of places and provides users with a simple way of starting a project within a selected framework. The templates can be used:

• via sbt:
  sbt new scalajs/scalajs.g8
• via coursier:

coursier install giter8
g8 scalajs/scalajs.g8

• and selected within Metals New Scala project command

All the available ScalaJS templates are rather old and certainly unofficial. I propose that we create a basic ScalaJS sbt project scalajs/scalajs.g8 with some basics that users (especially beginners) can use to get started. We could also setup Scala Steward for that repo and make sure that the template is in the default templates for Metals.

What are people's opinions on this? What should we add to the template if we decide to create one?

[keynmol]

Things that tripped me over personally:

1. %%% (so at least 1 dependency in the build definition with a comment would help a lot)
2. Testing (seeing https://github.com/scala-js/scala-js-env-jsdom-nodejs and then through trial and error getting it to work really helped)
3. A pre-baked index-dev.html which targets the output (hardcoded?) of fastOptJS so that one can open it immediately
4. A cross-compiled module for JVM and JS (core module tested on jvm and js, and a frontend module?)

Can't think of more things that would qualify for a minimal template.

I think the idea is fantastic :)

P.S.: keeping dependencies up-to-date is a big one. There were several complaints of broken sample projects and templates on Gitter, and SS can help with that

[nafg]

I think there should be a few:

• A standalone web (frontend only) project. (Could be a few flavors of development loop, IMO ideal would be scalajs-bundler updated to support snowpack...) Could include ScalablyTyped.
• A Node.js project
• Shared cross compiled, could have a Play version and an Http4s version

[nafg]

Random thought... maybe would be nice if in addition to Giter8 (templates for a new project) there were a scaffolding tool to add partial templates to existing projects. Not sure how it would work. But it would be nice if it could allow turning a server-only web project into a shared cross-compiled to scala.js project, or take a new scala.js subproject and add getting started boilerplate for scalajs-react, slinky, laminar, etc -- updating build.sbt and adding code files

[sjrd]

@keynmol That sounds like a reasonable set to me.

@nafg

I think there should be a few:

If several are needed, then other people should maintain them. I cannot promise to keep several templates up-to-date, especially if they use technologies that I don't know (for example, servers like Play or Http4s).

[keynmol]

Ah yeah, wanted to add another one:

• An example of accessing a JavaScript native function/class (through a facade)

With dependency being kept up-to-date by scala steward, if access pattern changes (like it did with globals), then template will be updated as well because the build should break.

I'm mentioning it because I think one of the docs on scalajs site is incorrect, and I tripped over that and didn't contribute (which is on me).

---

Agree with project-specific templates - I think the projects do a decent job of maintaining a list of examples by non-maintainers, and there's a lot more flux (i.e. I do want to convert my own http4s-laminar-fullstack template to Snowpack, but the "official" template should not be subject to such churn)

[tgodzik]

Let me know if you need any help with the template, I did play around with a couple and we had them setup for scalameta like for example: https://github.com/scalameta/mill-scala-seed.g8

I do agree that it should be one main template that we can put into the list of curated templates, so it's easy for the users to find and play around with.

[nafg]

I understand that the scala.js developers don't want to get involved with web frameworks. On the other hand personally I have next to no use for a scala.js-only giter8 template. That's what got me thinking that if we had a scaffolding tool, there could be a way of the scala.js team to maintain a "project fragment" that could somehow be scaffolded together with a web framework "project fragment," whatever that would mean. Bottom line, I guess I don't have any suggestion that's relevant to this thread and useful to me. Although, another thought -- what about a giter8 template that uses the web server built into recent JDKs as a JVM-only module? That way you have a barebones JVM+JS+shared template, without as much of a 3rd-party-library maintenance concern. Then if I want to use say http4s I just have to add a library and swap out the main class.

…

On Fri, Jan 22, 2021 at 7:40 AM Tomasz Godzik ***@***.***> wrote: Let me know if you need any help with the template, I did play around with a couple and we had them setup for scalameta like for example: https://github.com/scalameta/mill-scala-seed.g8 I do agree that it should be one main template that we can put into the list of curated templates, so it's easy for the users to find and play around with. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4390 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAYAUCHKRTAQKPBTNJ3GE3S3FW5TANCNFSM4WKQMF3Q> .

[sherpal]

I agree that a Scala-js only template is not that useful (or something very minimal automatically adding the plugin, enabling it and setting the main module intializer to true).

I would tend to think that a minimal useful template should have

• a cross project jvm/js
• an example of a shared model
• a js side with a little html manipulation (and a call to the backend for said model - the call could be made using fetch)
• a jvm side with a small http server (with a route serving dummy data for said model) (if I need to pick a name, it would be akka-http)
• an integration with any js packager (webpack/snowpack/vite), so that there is hot reload

Others might disagree but these are the things that I do all the time when starting a project, and they are quite annoying.

[Atry]

I maintain a template project for static Scala.js projects https://github.com/Atry/scalajs-all-in-one-template

[jetaggart]

Just chiming in that this would be amazing. I have my heart set on using scalajs, but I'm really struggling to get started. Every tutorial (i.e. scalajs docs) I find just says "add the plugin to sbt" when it's clearly not that simple and for a beginner, sbt is very hard to understand how to get started. Any example I find seems to be 4-5 years out of date so I don't trust them (once again, scalajs docs). It'd be awesome to be able to clone something and run it to get a feel for things. I also don't particularly like that the examples that seem to work/are up to date include backends with them. It makes me think it's coupled to that backend, and in several cases they are.

[sherpal]

Scala(.js) documentation follow the same principles as FP in general: orthogonality and composability. If you don't have any previous knowledge of sbt, it's true that it's very hard to get started. Perhaps you should go see a getting started of Scala in general, running a main method on the JVM, then switched back to Scala.js.

That said, I'm not sure how much people would you Scala.js alone, without a Scala backend. But, perhaps you are right that a simple g8 template with

• a simple npm packager
• a simple index.html file which calls the compiled scala js code
• a simple main method in scala js manipulating the dom a bit

could be interesting to getting started. In this case I feel like a maintained minimal repository to clone would be better.

[nafg]

I don't think there's any reason for documentation to be orthogonal (other than lack of time) or composable (how do you compose docs?) While docs in the Scala ecosystem are better than they used to be, overall they are still really, really, lacking. The question should not be whether this should be done, only when and by who.

…

On Mon, Dec 13, 2021, 7:16 AM Antoine Doeraene ***@***.***> wrote: Scala(.js) documentation follow the same principles as FP in general: orthogonality and composability. If you don't have any previous knowledge of sbt, it's true that it's very hard to get started. Perhaps you should go see a getting started of Scala in general, running a main method on the JVM, then switched back to Scala.js. That said, I'm not sure how much people would you Scala.js alone, without a Scala backend. But, perhaps you are right that a simple g8 template with - a simple npm packager - a simple index.html file which calls the compiled scala js code - a simple main method in scala js manipulating the dom a bit could be interesting to getting started. In this case I feel like a maintained minimal repository to clone would be better. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4390 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAYAUGKH2KCAX5VWEI3AITUQXPZBANCNFSM4WKQMF3Q> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[jetaggart]

The composability is what attracts me, that said, it's hard to know what to compose up front. I have run Scala and used Scala in production. But the tooling around scala.js (running webpack behind the scenes, how npm deps get pulled in, multiple plugins, scalablytyped?!) is very magical and uncomfortable when there's no best practices published and no expert's patterns to follow. What magical commands do I need to run to have the expected compile/hot reload cycle. For example, here's the command I ended up with: ;fastOptJS::startWebpackDevServer;~fastOptJS. That took hours to figure out and I'm not even sure it's the best way.

It doesn't instill confidence when several of the examples in the site are 5-6 years out of date (is this maintained? is anyone using this?). I know how to use webpack/js/the whole ecosystem and scala, but I am not sure how to stitch it all together in a good way.

Fwiw, I think the rust ecosystem has done an amazing job here. I can, as a newcomer, clone an example that's nearly present in every library/framework and type cargo run then start poking around. It's very approachable. The first step being "how do I construct/program an sbt project" is not.

I apologize for being negative, but just wanted to communicate why it's very hard to get going/convince others this is a good idea/use this as a solo dev. I really love what scala is doing, and I think scala/scalajs is the future, but the adoption is hard.

I've put together a very simple starter example with scala-js that may be of some help. I hesitate to put it out there for the reasons mentioned above. It feels like I kludged it together and probably has a bunch of bloat/mistakes.

https://github.com/jetaggart/scala-js-react-starter

Here's an example from kotlin that's represents what would help a ton: https://github.com/kotlin-hands-on/web-app-react-kotlin-js-gradle/tree/finished

[sherpal]

@nafg

I agree. I'm not saying it's a good thing. I'm saying that's the state of affairs, unfortunately.

Here scala.js assumes that the user knows sbt, and knows what node or JS in the browser is.

[fdietze]

For reference, we have a fairly minimal Outwatch template with hot reloading available: https://github.com/outwatch/seed.g8

There is also a scalajs full-stack template to deploy to AWS lambda: https://github.com/fun-stack/example

Lots of experience and personal best-practices went into these, so there's probably something to learn from.

In the fun-stack example, we even decided to remove g8 and make it a pure repo to be cloned (marked as github template).

g8 didn't have enough advantages to keep it, while having the disadvantage to have a more complicated CI and scala-steward setup.

Doing a git clone or a sbt new is not very different in usability.