search

varabyte / kobweb

A modern framework for full stack web apps in Kotlin, built upon Compose HTML
https://kobweb.varabyte.com
Apache License 2.0
1.59k stars 71 forks source link

List available modules in the README #598

Open okarmazin opened 2 months ago

okarmazin commented 2 months ago

README should feature an authoritative reference of all available Kobweb-related (kobweb, kobwebx, silk) modules with their Maven coordinates.

Currently the README contains a lot of information about the different Kobweb capabilities, but it doesn't actually tell you where to get them.

bitspittle commented 2 months ago

I'll consider this more as we get closer to 1.0. I wouldn't want to do anything too early because we may add or rename modules before the final release.

Are you aware of any other projects that do this? I'm almost tempted to say that the final source of truth will be maven itself. We will ultimately release Kobweb artifacts on maven, and at that point, people will be able to search for all Kobweb artifacts (with descriptions) there.

okarmazin commented 2 months ago

Are you aware of any other projects that do this?

I'm not sure what you're referring to. Every library lists its modules as the first thing in their README (or some other easily accessible place)

How do you declare dependencies in your projects? You read their README and it tells you the coordinates which you add to your gradle/libs.versions.toml file.

After all, where did you find the Maven coordinates of Kobweb's own dependencies? compose, jsoup, kotlinx.serialization, kotlinpoet. Probably in their READMEs or other similar documentations.

okarmazin commented 2 months ago

https://www.http4k.org/guide/reference/ - open any of the module pages, installation information is front and center.

bitspittle commented 2 months ago

Sounds like you're asking for two separate things here...

1) How to set up <your build system here> to use Kobweb 2) A list of all artifacts / modules Kobweb generates

Build setup instructions

I'm definitely not against 1) in general as I have prominent sections in Kotter and Truthish.

I definitely plan to add a section about this eventually, but it wasn't as much a priority because most new users should just use kobweb create app for now. I also want to wait for my artifacts to live in Maven Central / the Gradle plugin portal. This will happen much closer to the 1.0 release.

Artifact list

A project like http4k (and also, say, ktor) is designed as tiny modular pieces that you are supposed to choose a subset from in your own project, and every project will be a bit different.

Kobweb is a more standard project -- a vast majority of projects will probably all import Kobweb core and Silk. These in turn auto-import additional artifacts for the user behind the scenes.

I have actually implemented Kobweb to be more flexible than this standard monolithic experience might imply. But picking and choosing this or that piece is more advanced behavior, and names / locations may change before we hit 1.0, so I don't want to spend time locking down the documentation on that yet.

I probably won't add a page in the main guide flow like http4k does, but I will use something like dokka to generate a full listing of all methods, classes, etc., eventually, and I think I will lean on something like that as docs that are closer to the source of truth (i.e. the code).

I may also surface information like this (https://github.com/varabyte/kobweb/blob/main/frontend/silk-widgets/README.md) into the docs, since I think at a high level, using Silk without Kobweb could be a more and more common use-case. (Although in that case, I may add a new Silk Gradle plugin so people don't have to do this by hand).