K🕸️bweb

Kobweb is an opinionated Kotlin framework for creating websites and web apps, built on top of Compose HTML and inspired by Next.js and Chakra UI.

@Page
@Composable
fun HomePage() {
  Column(
    Modifier.fillMaxWidth().whiteSpace(WhiteSpace.PreWrap).textAlign(TextAlign.Center),
    horizontalAlignment = Alignment.CenterHorizontally
  ) {
    var colorMode by ColorMode.currentState
    Button(
      onClick = { colorMode = colorMode.opposite },
      Modifier.borderRadius(50.percent).padding(0.px).align(Alignment.End)
    ) {
      // Includes support for Font Awesome icons
      if (colorMode.isLight) FaMoon() else FaSun()
    }
    H1 {
      Text("Welcome to Kobweb!")
    }
    Span {
      Text("Create rich, dynamic web apps with ease, leveraging ")
      Link("https://kotlinlang.org/", "Kotlin")
      Text(" and ")
      Link(
        "https://github.com/JetBrains/compose-multiplatform/#compose-html",
        "Compose HTML"
      )
    }
  }
}

While Kobweb is still pre-1.0, it has been usable for a while now. It provides escape hatches to lower-level APIs, so you can accomplish anything even if Kobweb doesn't support it yet. Please consider starring the project to indicate interest, so we know we're creating something the community wants. How ready is it?▼

Our goal is to provide:

an intuitive structure for organizing your Kotlin website or web app
automatic handling of routing between pages
a collection of useful batteries included widgets built on top of Compose HTML
an environment built from the ground up around live reloading
static site exports for improved SEO
support for responsive (i.e. mobile and desktop) design
out-of-the-box Markdown support
a way to easily define server API routes and persistent API streams
support for creating and using web workers
a growing collection of general purpose utilities added on top of Compose HTML and Kotlin/JS (learn more▼)
an open source foundation that the community can extend
and much, much more!

📚 You can find a detailed guide at https://kobweb.varabyte.com/docs

You can also check out my talk at Droidcon SF 24 for a high level overview of Kobweb. The talk showcases what Kobweb can do, introduces Compose HTML (which it builds on top of), and covers a wide range of frontend and backend functionality. It is light on code but heavy on understanding the structure and capabilities of the framework.

Here's a demo where we create a Compose HTML project from scratch with Markdown support and live reloading, in under 10 seconds:

https://user-images.githubusercontent.com/43705986/135570277-2d67033a-f647-4b04-aac0-88f8992145ef.mp4

Getting started

The first step is to get the Kobweb binary. You can install it, download it, and/or build it, so we'll include instructions for all these approaches.

Install the Kobweb binary

Major thanks to aalmiray and helpermethod to helping me get these installation options working. Check out JReleaser if you ever need to do this in your own project!

Homebrew

OS: Mac and Linux

$ brew install varabyte/tap/kobweb

Scoop

OS: Windows

# Note: Adding buckets only has to be done once.

# Feel free to skip java if you already have it
> scoop bucket add java
> scoop install java/openjdk

# Install kobweb
> scoop bucket add varabyte https://github.com/varabyte/scoop-varabyte.git
> scoop install varabyte/kobweb

SDKMAN!

OS: Windows, Mac, and *nix

$ sdk install kobweb

Arch Linux

Thanks a ton to aksh1618 for adding support for this target!

With an AUR helper, e.g.:

$ yay -S kobweb
$ paru -S kobweb
$ trizen -S kobweb
# etc.

Without an AUR helper:

$ git clone https://aur.archlinux.org/kobweb.git
$ cd kobweb
$ makepkg -si

Don't see your favorite package manager?

Please see: https://github.com/varabyte/kobweb-cli/issues/11 and consider leaving a comment!

Download the Kobweb binary

Our binary artifact is hosted on GitHub. To download the latest, you can either grab the zip or tar file from GitHub or you can fetch it from your terminal:

$ cd /path/to/applications

# You can either pull down the zip file

$ wget https://github.com/varabyte/kobweb-cli/releases/download/v0.9.21/kobweb-0.9.21.zip
$ unzip kobweb-0.9.21.zip

# ... or the tar file

$ wget https://github.com/varabyte/kobweb-cli/releases/download/v0.9.21/kobweb-0.9.21.tar
$ tar -xvf kobweb-0.9.21.tar

and I recommend adding it to your path, either directly:

$ PATH=$PATH:/path/to/applications/kobweb-0.9.21/bin
$ kobweb version # to check it's working

or via symbolic link:

$ cd /path/to/bin # some folder you've created that's in your PATH
$ ln -s /path/to/applications/kobweb-0.9.21/bin/kobweb kobweb

Build the Kobweb binary

Although we host Kobweb artifacts on GitHub, it's easy enough to build your own.

Building Kobweb requires JDK11 or newer. We'll first discuss how to add it.

Download a JDK

If you want full control over your JDK install, manually downloading is a good option.

Download a JDK for your OS
Unzip it somewhere
Update your JAVA_HOME variable to point at it.

JAVA_HOME=/path/to/jdks/corretto-11.0.12
# ... or whatever version or path you chose

Install a JDK with the IntelliJ IDE

For a more automated approach, you can request IntelliJ install a JDK for you.

Follow their instructions here: https://www.jetbrains.com/help/idea/sdk.html#set-up-jdk

Building the Kobweb CLI

The Kobweb CLI is actually maintained in a separate GitHub repo. Once you have the JDK set up, it should be easy to clone and build it:

$ cd /path/to/src/root # some folder you've created for storing src code
$ git clone https://github.com/varabyte/kobweb-cli
$ cd kobweb-cli
$ ./gradlew :kobweb:installDist

Finally, update your PATH:

$ PATH=$PATH:/path/to/src/root/kobweb-cli/kobweb/build/install/kobweb/bin
$ kobweb version # to check it's working

Update the Kobweb binary

If you previously installed Kobweb and are aware that a new version is available, the way you update it depends on how you installed it.

| Method | Instructions | |---------------------------|--------------------------------------------------------------------------------------------------------------------------------------| | Homebrew | brew update brew upgrade kobweb | | Scoop | scoop update kobweb | | SDKMAN! | sdk upgrade kobweb | | Arch Linux | Rerunning install steps should work. If using an AUR helper, you may need to review its manual. | | Downloaded from Github | Visit the latest release. You can find both a zip and tar file there. |

Create your first Kobweb site

$ cd /path/to/projects/
$ kobweb create app

You'll be asked a few questions required for setting up your project.

You don't need to create a root folder for your project ahead of time - the setup process will prompt you for one to create. For the remaining parts of this section, let's say you choose the folder "my-project" when asked.

When finished, you'll have a basic project with two pages - a home page and an about page (with the about page written in markdown) - and some components (which a

Kobweb

Install / Use

README