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 updatebrew 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 fromGithub	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 are collections of reusable, composable pieces). Your own directory structure should look something like this:

my-project
└── site/src/jsMain
    ├── kotlin.org.example.myproject
    │   ├── components
    │   │   ├── layouts
    │   │   │   ├── MarkdownLayout.kt
    │   │   │   └── PageLayout.kt
    │   │   ├── sections
    │   │   │   ├── Footer.kt
    │   │   │   └── NavHeader.kt
    │   │   └── widgets
    │   │       └── IconButton.kt
    │   ├── pages
    │   │   └── Index.kt
    │   └── AppEntry.kt
    └── resources/markdown
        └── About.md

Note that there's no index.html or routing logic anywhere! We generate that for you automatically when you run Kobweb. This brings us to the next section...

Run your Kobweb site

$ cd your-project/site
$ kobweb run

This command spins up a web server at http://localhost:8080. If you want to configure the port, you can do so by editing your project's .kobweb/conf.yaml file.

You can open your project in IntelliJ and start editing it. While Kobweb is running, it will detect changes, recompile, and deploy updates to your site automatically.

Using IntelliJ

If you don't want to keep a separate terminal window open beside your IDE window, you may prefer alternate solutions.

Terminal tool window

You can use the IntelliJ terminal tool window to run kobweb within it. If you run into a compile error, the stack trace lines will get decorated with links, making it easy to navigate to the relevant source.

Gradle commands

kobweb itself delegates to Gradle, but nothing is stopping you from calling the commands yourself. You can create Gradle run configurations for each of the Kobweb commands.

[!TIP] When you run a Kobweb CLI command that delegates to Gradle, it will log