varabyte/kobweb v0.20.1

on GitHub

This is a fairly meaty release with a handful of miscellaneous features addressing different requests made by various users, so it is hard to summarize easily! Please find details in the changes below.

Also, starting with this version, Kobweb will start releasing its artifacts on Maven Central and the Gradle Plugin Portal. More information about this in the Notes section below, but in general, this should open up Kobweb development to people working at companies that might restrict access to random maven repository URLs, which is nice.

Finally, this version of Kobweb updates Compose to 1.7.3 and Ktor to 3.0.3.

Changes

Frontend

• Catch-all dynamic routes (README link)
  • e.g. @Page("/a/b/c/...slug") would capture the value "d/e/f" in the URL "/a/b/c/d/e/f"
• Add modifier support for transition-behavior
• Add modifier support for color-scheme
• Add support for passing in the redirect parameter into all the Kobweb HTTP APIs (e.g. window.http.get(redirect = MANUAL))

Silk

• Add CanvasGl2 which lets you create a Canvas that wraps a WebGL2 context
• Add ColorMode.systemPreference
  • e.g. in an @InitSilk block: ctx.theme.initialColorMode = ColorMode.systemPreference
• Add ColorMode.saveToLocalStorage / ColorMode.loadFromLocalStorage convenience methods, which Kobweb sites commonly do to store a user's color mode preferences across multiple browser sessions.
  • Run kobweb create app for an example project that uses these methods.
• ⚠️ Renamed ColorScheme class to ColorPalette due to naming conflict with the CSS color-scheme property, which could be confusing.
  • Old code should still compile but this may generate deprecation warnings. See the Notes section for more details.

Backend

• You can now disable backend logging either to file and/or stdout/stderr destinations via the enableFileLogging and enableConsoleLogging properties in the Kobweb server configs
• API interceptors (README link)
  • Intercept all incoming network requests / outgoing responses, allowing you to mutate / redirect requests and responses.
  • A useful place to set global logic that should run before multiple API routes, redirect legacy APIs to new ones, and add authentication logic for protected routes, for example.
• Fixed a bug where if you had a resource and folder with the same name, attempting to access the resource would 404
  • e.g. if you registered both "store/product" and "store/product/item", then a Kobweb server would error if you tried to visit "store/product" directly.

Markdown

• Fixed a markdown cast exception that could occur in a markdown blockquote.

Gradle

• The Application plugin attempts to configure the Compose Compiler plugin in ways that may improve the site performance / size
  • ⚠️ See the Notes section for more details.
• New helper utility importCss method.
  • Before: unsafe { raw("@import url(\"somestyle.css\" layer(somestyle)") }
  • After: importCss("somestyle.css", layerName = "sometime")
• Preparations for publishing Kobweb artifacts to the Gradle Plugin Portal and Maven Central.

Notes

Maven central and the Gradle Portal Plugin

Starting in 0.20.1, Kobweb artifacts are now published to maven central and the Gradle Plugin Portal.

This means, essentially, that you can delete all maven repos from your build scripts that point to "https://us-central1-maven.pkg.dev/varabyte-repos/public" if you'd like.

// root settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
-       maven("https://us-central1-maven.pkg.dev/varabyte-repos/public")
    }
}

// root build.gradle.kts
subprojects {
    repositories {
        mavenCentral()
        google()
-       maven("https://us-central1-maven.pkg.dev/varabyte-repos/public")
    }
}

Snapshots

Occasionally, when people report issues with Kobweb, we may ask them to try using a snapshot version, which will have our latest code. Snapshots, which so far have only lived on the varabyte repository, are now published to an official snapshot maven repository as well ("https://s01.oss.sonatype.org/content/repositories/snapshots/"). If you remove the varabyte repo declarations as recommended earlier, you may wish to drop this code somewhere into your settings.gradle.kts file which will add references to the snapshot repository in their place:

// root settings.gradle.kts

// 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() {
        maven("https://s01.oss.sonatype.org/content/repositories/snapshots/") {
            mavenContent { 
                includeGroupByRegex("com\\.varabyte\\.kobweb.*")
                mavenContent { snapshotsOnly() }
            }
        }
    }
    pluginManagement.repositories { kobwebSnapshots() }
    dependencyResolutionManagement.repositories { kobwebSnapshots() }
}

Compose Compiler warning

After upgrading to 0.20.1, you may get this warning:

The Kobweb plugin failed to configure the compose compiler plugin. This prevents it from applying settings which may improve the size / performance of your site. To fix this, ensure that the plugin org.jetbrains.kotlin.plugin.compose is loaded at the same level as the Kobweb plugin. For example, if you load the Kobweb plugin in the project root with alias(libs.plugins.kobweb.application) apply false, you should also load the compose plugin there (e.g. with alias(libs.plugins.compose.compiler) apply false). To disable Kobweb's configuration of the compose compiler plugin, add kobweb.configureComposeCompiler=false to your project's gradle.properties file.

This warning may look complex, but in general, it just means you should make sure to always apply the compose compiler plugin at the same time you apply the Kobweb plugin. Most projects probably do this already, but yours may not if you declare your kobweb dependency in the root build script but only declare the compose compiler dependency in the site build script.

Here's an example fix (taken from the kobweb create examples/chat template, which gave us this warning when we upgraded it to 0.20.1):

// root build.gradle.kts
plugins {
   alias(libs.plugins.kotlin.multiplatform) apply false
+  alias(libs.plugins.compose.compiler) apply false
   alias(libs.plugins.kobweb.application) apply false
   alias(libs.plugins.kobweb.library) apply false
   alias(libs.plugins.kobwebx.markdown) apply false
}

ColorScheme to ColorPalette migration

You may get some compile warnings when upgrading to 0.20.1. Fixing them is trivial!

Here's an example of how to migrate such code:

val ctx = rememberPageContext()
   Button(
      onClick = { /* ... */ }, 
-     colorScheme = ColorSchemes.Blue
+     colorPalette = ColorPalettes.Blue
   ) {
      Text("Click me!")
   }

Thanks!

We had lots of new interest in Kobweb over the Christmas break. We appreciate folks choosing to spend some of their vacation time to experiment with our software! If you ever create a live website using Kobweb, be sure to inform us via one of the channels mentioned in the README's Connecting With Us section, and we'd love to boost its signal.

Full Changelog: v0.20.0...v0.20.1