kobweb

0.24.0indexed

Opinionated framework for creating websites and web apps, leveraging Compose HTML. Features include live reloading, responsive design, static site exports, Markdown support, and server API routes.

JSJVM·varabyte/kobweb

2.2k

Stars

—

Used by

dependents

—

Health

/ 100

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  {
  Column(
    Modifier.fillMaxWidth().whiteSpace(WhiteSpace.PreWrap).textAlign(TextAlign.Center),
    horizontalAlignment = Alignment.CenterHorizontally
  ) {
     colorMode  ColorMode.currentState
    Button(
      onClick = { colorMode = colorMode.opposite },
      Modifier.borderRadius(percent).padding(px).align(Alignment.End)
    ) {
      
       (colorMode.isLight) FaMoon()  FaSun()
    }
    H1 {
      Text()
    }
    Span {
      Text()
      Link(, )
      Text()
      Link(
        ,
        
      )
    }
  }
}

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.

Our goal is to provide:

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

You can also check out my talk at KotlinConf '25 for a high-level overview of Kobweb. The talk showcases what Kobweb can do, introduces Compose HTML (which it builds on top of), and touches on a 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

Nix

OS: Mac and Linux

Thanks a ton to Lilian Maulny (e_ψ_lon) for adding support for this target!

First, enable flakes. Create ~/.config/nix/nix.conf:

experimental-features = nix-command flakes

Then:

$ nix profile add github:varabyte/kobweb-cli-nix

[!TIP] For more options, as well as NixOS instructions, see the README at https://github.com/varabyte/kobweb-cli-nix.

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.23/kobweb-0.9.23.zip
$ unzip kobweb-0.9.23.zip

# ... or the tar file

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

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

$ PATH=$PATH:/path/to/applications/kobweb-0.9.23/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.23/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.

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 the Gradle command to the console. This is how you can discover the Gradle commands discussed in this section.

You can read all about IntelliJ's Gradle integration here. Or to just jump straight into how to create run configurations for any of the commands discussed above, read these instructions.

Running examples

Kobweb will provide a growing collection of samples for you to learn from. To see what's available, run:

$ kobweb list

You can create the following Kobweb projects by typing `kobweb create ...`

• app: A template for a minimal site that demonstrates the basic features of Kobweb
• examples/jb/counter: A very minimal site with just a counter (based on the Jetbrains tutorial)
• examples/todo: An example TODO app, showcasing client / server interactions

For example, kobweb create examples/todo will instantiate a TODO app locally.

Gradle configuration

Declaring repositories to fetch Kobweb artifacts

Kobweb publishes its libraries to Maven Central and its plugins to the Gradle Plugin Portal. Therefore, Kobweb recommends setting up your project's settings.gradle.kts like so:

pluginManagement {
    repositories {
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}

[!TIP] All Kobweb templates embrace this pattern, so if you start your own project by building on top of any of them, then this will already be done for you.

Dependencies on Maven Central and the Gradle Plugin Portal are so standard, it's hard to imagine a project that isn't already using them, so in most cases, you won't have to do anything.

Testing snapshots

Occasionally, especially if you file an issue for a bug fix or a feature request, our team may ask you if you're willing to try using a snapshot build (a dev build, essentially).

Snapshots are, by design, not supported in either Maven Central nor the Gradle Plugin Portal. Therefore, we host all plugin and library artifacts in a separate official snapshot repository (at https://central.sonatype.com/repository/maven-snapshots/). As a result, you will have to declare this repository for both plugin and library blocks.

An easy way to enable this is by adding the following block of code into your settings.gradle.kts file:

pluginManagement {
    repositories {
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}

+ // The following block registers dependencies to enable Kobweb snapshot support. It is safe to delete or comment out
+ // this block if you never plan to use them.
+ gradle.settingsEvaluated {
+     fun RepositoryHandler.kobwebSnapshots() {

[!CAUTION] The above code, adding repositories inside the settingsEvaluated block, is actually not Gradle idiomatic -- that approach would be to create a settings plugin or just copy/paste the repository declaration in all relevant places -- but at the moment we are suggesting this approach for its simplicity:

If we could have declared a top level method in the settings file that both blocks could have called, that would have been a nice option to recommend. However, the block is "magic" and you cannot share code with it. This approach lets us at least mimic that kind of solution.

Gradle version catalogs

The project templates created by Kobweb all embrace Gradle version catalogs.

If you're not aware of it, it's a file that exists at gradle/libs.versions.toml. If you find yourself wanting to tweak or add new versions to projects you originally created via kobweb create, that's where you'll find them.

For example, here's the libs.versions.toml we use for our own landing site.

To read more about the feature, please check out the official docs.

Upgrading Kobweb in your project

The latest available version of Kobweb is declared at the top of this README. If a new version has come out, you can update your own project by editing gradle/libs.version.toml and updating the kobweb version there.

[!IMPORTANT] You should double-check COMPATIBILITY.md to see if you also need to update your kotlin and jetbrains-compose versions as well.

[!CAUTION] It can be confusing, but Kobweb has two versions -- the version for the library itself (the one that is applicable in this situation), and the one for the command line tool.

Read the Guide

If you got this far, it is time to start reading the manual!

📚 https://kobweb.varabyte.com/docs

The guide walks you through all Kobweb concepts, organized into sections to make it easier to read as well as later continue where you left off.

[!IMPORTANT] All the documentation for Kobweb used to live in this README, but it was getting so long as to be unwieldy. You may have ended up at this section after following an old link found in the wild. We apologize for the inconvenience, but you should be able to find the relevant information by visiting the guide and using the search bar found in the top right of the page.

Miscellaneous topics

General purpose improvements on top of Compose HTML and Kotlin/JS

In the beginning, Kobweb was only intended to be a thin layer on top of Compose HTML, but the more we worked on it, the more we ran into features that were simply not yet implemented in Compose HTML. In other cases, we found ourselves reaching for utilities that we wished existed in Kotlin/JS browser APIs. As we began adding these features, we realized it would have been a shame to bury them deep inside our framework.

As a result, we created two modules:

compose-html-ext, where we put code that we would be more than happy for the Compose HTML team to fork and migrate over to Compose HTML someday.
browser-ext, a collection of general purpose utilities that we think could be useful to any Kotlin/JS project targeting the browser.

The features across these modules include (not comprehensive):

[!NOTE] Some users have mentioned we should have opened PRs for the Compose HTML team instead of maintaining a separate codebase. However, after observing that JetBrains was focusing more and more of its energy on Compose Multiplatform for Web, we decided to implement the features we needed in our own project. This way, we could maintain our velocity while allowing their team to pick and choose what they agreed with at some point in the future at their leisure. There's so much code here, especially around CSS APIs, that getting mired down in PR discussions would have ground our progress to a halt.

If you want to use Compose HTML but not Kobweb, or Kotlin/JS but not Compose HTML, you can still use and benefit from compose-html-ext or browser-ext in your own project. An example build script could look like this (here, for a non-Kobweb Compose HTML project):

// build.gradle.kts
plugins {
  kotlin("multiplatform") version "..."
}

repositories {
  mavenCentral()
  google()
}

kotlin {
  js().browser()
  sourceSets {
    jsMain.dependencies {
      implementation(compose.html.core)
      implementation(compose.runtime)
      implementation("com.varabyte.kobweb:compose-html-ext:...") // IMPORTANT!!!
    }
  }
}

[!NOTE] The compose-html-ext dependency automatically provides the browser-ext dependency.

And of course, if you use Kobweb, it provides both.

What about Compose Multiplatform for Web?

Jetbrains is working on the "Compose Multiplatform UI Framework", which allows developers to use the same codebase across Android, iOS, Desktop, and the Web. And it may seem like the Kobweb + Silk approach is obsoleted by it.

It's first worth understanding the core difference between the two approaches. With Compose Multiplatform, the framework owns its own rendering pipeline, drawing to a buffer. In contrast, Compose HTML modifies an HTML / CSS DOM tree and leaves it up to the browser to do the final rendering.

This has major implications on how similar the two APIs can get. For example, in Compose Multiplatform, the order you apply modifiers matters. However, in Compose HTML, this action simply sets html style properties under the hood, where order does not matter.

Due to its reputation, ditching HTML / CSS entirely at first can seem like a total win, but this approach has several limitations:

robots would lose the ability to crawl and index your site, hurting SEO.
your initial render may take longer (as nothing will be rendered until your site's logic is downloaded and run for one frame).
your site will need to allocate a large canvas buffer, which could be very expensive on high-res, wide-screen desktops.
your UI will be opaque to the powerful suite of devtools that come bundled with browsers.

It would also prevent a developer from making use of the rich ecosystem of Javascript libraries out there.

Finally, Kobweb is more than just Kotlin-ifying HTML / CSS. It also provides rich integration with powerful web technologies like web workers and websockets.

For now, I am making a bet that there will always be value in embracing the web, providing a framework that sticks to HTML / CSS but offers a growing suite of UI widgets, layouts, and other features that make it a more comfortable experience for the Kotlin developer.

For example, the flexbox layout is a very powerful concept, but it can be very tricky to use. In most cases, you'll find it's much easier to compose Rows and Columns together than trying to remember if you should be justifying your items or aligning your content, even if Rows and Columns are just configuring the correct HTML / CSS for you behind the scenes.

Ultimately, I believe there is room for both Compose Multiplatform and Kobweb. If you want to make an app experience that feels the same on Android, iOS, Desktop, and Web, then Compose Multiplatform could be the right choice for you. However, if you just want to make a traditional website but want to use Kotlin instead of TypeScript, Kobweb can provide an excellent development experience for that case.

Community

Testimonials

I'm pleased to mention that Kobweb has received feedback from some satisfied users. Here are a few:

"This is a pretty bloody amazing technology you've created here. I have been dreading upgrading [my] website for ages because I didn't want to go back to html and css 🫤 now I can stay with Kotlin 😀"
"Kobweb looks fantastic and I've been [trying] to use Kotlin in all parts of [my] hobby stuff and work, so I got real excited when I saw Kobweb, [even though] I hadn't been satisfied with a web framework in a long time. Incredible work."
"I started using Kobweb last week and I have to say this [...] reinvented web development for me. [...] I used to hate html css. After getting my hands on kobweb I’m in love with it."
"Finally got paid -- all thanks to kobweb 🎉💥"
"I didn't wanna learn any JS framework so when I first learned about kobweb it felt like a no-brainer; having built 2 Android apps with compose already and a backend with ktor. One could argue Android developers are the best target audience since the additional knowledge needed to move an app to the web with Kobweb is minimal. I love it! 🤩"

Connecting with us

Join my Discord!
GitHub Discussions for this project
The Kobweb channel on the Kotlin Slack
You can send direct queries to my email

If you're comfortable with it, using Discord is recommended, because there's a growing community of users in there who can offer help even when I'm not around.

Filing issues and leaving feedback

It is still early days, and while we believe we've proven the feasibility of this approach at this point, there's still plenty of work to do to get to a 1.0 launch! We are hungry for the community's feedback, so please don't hesitate to:

Open an issue
Contact us (using any of the ways mentioned above) telling us what features you want
Ask us for guidance, especially as there are no tutorials yet (your questions can help us know what to write first!)

Thank you for your support and interest in Kobweb!

Supporting the project

You should feel no obligation to pay anything to use Kobweb -- it is licensed liberally quite intentionally and given to the community without any strings attached.

However, if you like what we are doing and are determined to support our efforts financially, we would gratefully accept a donation at ko-fi.com/bitspittle. Money will go towards development fees and rewarding contributors.

Alternately, there are countless non-financial ways to support this project, such as:

Just use Kobweb and spread the word!
Consider tagging your website with a "Made with Kobweb" blurb in the footer.
Write articles about Kobweb / share your experience using it.
Send us feedback, be it appreciative or critical. Please don't be shy about letting us know if there are things you feel are missing. If you have ideas that you think can make Kobweb better, please share them.
Join our community on Discord and/or Slack and answer questions.
Pick up a bug or feature to work on.

Ultimately, I want Kobweb to be known for having a kind, patient, and welcoming community. As long as you are helping us accomplish that, then please consider yourself already supporting our efforts.

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

kilua★ 364

rjarosComposable web framework enabling modern web application development with declarative UI components, state management, server-side rendering, and support for WebAssembly and JavaScript targets.Shared: web, compose-html, compose

compose-shimmer★ 1.0k

valentinilkOffers shimmering animation for UI elements, integrated via a simple modifier. Includes customization options like theming and animation boundaries. Supports advanced usage scenarios and custom modifiers.Shared: web, compose

material3-windowsizeclass-multiplatform★ 361

chrisbanesFacilitates responsive UI design by implementing Material 3 window size classes across multiple platforms, ensuring layouts adapt to various screen sizes. Supports Android, iOS, desktop, and web environments.Shared: web, compose

compose-sonner★ 349

dokar3An opinionated toast component, replicates the features of a popular React library. Offers stacked, animated, and customizable toasts with support for various themes, positions, durations, and interactions.Shared: web, compose

summon★ 158

codeyousefPowerful type-safe frontend framework delivers reactive state management, component-based architecture, and comprehensive styling for building elegant, responsive applications with declarative syntax and enhanced UI capabilities.Shared: web, compose

HtmlConverterCompose★ 144

cbeylsSimple API converts HTML to AnnotatedString with styling for UI components, replacing traditional HTML parsers. Supports custom styling, hyperlink handling, and unstyled text conversion. Future goals include inline image display.Shared: web, compose

Homebrew	`brew update` `brew upgrade kobweb`
Nix	`nix profile upgrade kobweb-cli-nix` (or review the varabyte/kobweb-cli-nix README for more options).
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.