v0.19.2

This release is nearly identical to v0.19.1 but contains a fix for a logic error introduced there that affected scrolling to fragments on the same page.

For example, if your project had code like this:

Link("#conclusion", "Click here to jump to the conclusion")

clicking on that link would have no effect.

If you are using v0.19.1, you should consider upgrading to v0.19.2 at your earliest convenience.

Important

Planning to upgrade? Review instructions in the README.

---

⚠️ Smooth scrolling behavior has changed ⚠️

In addition to our fix, we also removed some opinionated smooth scrolling behavior we used when navigating to fragments that we probably shouldn't have added in the first place.

What this means is, after upgrading to 0.19.2, if you have any pages in your site with internal links, navigation to them will now be instant, snapping immediately to the target element when you click a link. This is the browser's (and many sites') default behavior.

(For example, try clicking around on the section links in the sidebar of this Wikipedia page to see instant navigation in action.)

If you'd like to go back to re-enabling smooth scrolling in your site, we recommend adding this somewhere in your site, for example in your AppEntry.kt file:

@InitSilk
fun enableSiteWideSmoothScrolling(ctx: InitSilkContext) = ctx.stylesheet.apply {
    registerStyle("html") {
        cssRule(CSSMediaQuery.MediaFeature("prefers-reduced-motion", StylePropertyValue("no-preference"))) {
            Modifier.scrollBehavior(ScrollBehavior.Smooth)
        }
    }
}

What the above code does is set the site's scroll behavior to "smooth" unless some accessibility setting has been set on that user's machine indicating they don't want it. This approach is an encouraged best practice for enabling smooth scrolling.

---

Full Changelog: v0.19.1...v0.19.2

v0.19.1

Warning

This release added a logic bug around navigating to link fragments which was resolved in v0.19.2 (which you are encouraged to update to instead).

---

This release adds a few miscellaneous features and bumps up the Kotlin target to 2.0.20.

Important

Planning to upgrade? Review instructions in the README.

The biggest feature introduced in this release is callouts.

Note

GitHub also has callouts (they call them Alerts) and this is an example of one them: a note! GitHub also has alerts for tips, cautionary points, warnings, and important messages.

Kobweb includes all the alerts that GitHub exposes plus a few others.

I updated the handful of articles in my blog site to use callouts. If you'd like to see them in action, you can find a few examples of them in this post about fullstack Kobweb for example.

This release also adds markdown support for Callouts. They're as easy to create in Kobweb Markdown as they are in GitHub Markdown.

More information about Callouts and their markdown support can be found in the README.

---

Changes

Frontend

• Fixed an issue where working with Modifier.displayIfAtLeast(Breakpoint) and that family of methods would still result in elements flickering when a page first loaded.
• Tweaked a handful of composable names to be more consistent with the official API Guidelines for Jetpack Compose.
  • For example, deferRender -> Deferred, and a few others.
  • It's not expected that the average user will even notice, but this may result in some deprecation notices for some users.
• Removed a timer-related hack which was used to scroll to page fragments.
  • At the very least, the code is clean now; at best, there may have been the occasional case where the scroll operation wouldn't work and it should be a lot more robust now.

Silk

• New Callout widget

Markdown

• Added support for creating callouts

Gradle

• Fix a handful of cases in lesser used tasks that were still not configuration cache compatible.

Thanks!

In this release, we'd like to extend our appreciation to @okarmazin, who has been nothing but kind to the project in the Kotlin slack and has been going through the new user experience, filing bugs, and helping us by cleaning up mistakes and gaps in our README. Thank you very much for the support!

---

Full Changelog: v0.19.0...v0.19.1

v0.19.0

This release is identical to 0.18.3 but enables K2 support for Kobweb. 🎉

Please review the Kobweb K2 migration docs to learn how to migrate any existing projects over.

Important

Planning to upgrade? Review instructions in the README.

---

For the first time in several releases, we are seeing a decrease in the size of exported binaries. This may even be a more significant drop for projects that can use the new "ES2015" compiler target (see the migration docs for more details).

Note

For my own site, pre-0.19.0, the exported size was 1.12MB. In 0.19.0, it dropped to 1.00MB. And with ES2015, it dropped further to 941K. In total, a 16% drop without any changes to my code. That's pretty nice!

Also with this release, both Kobweb and all Kotlin Gradle plugins from JetBrains are configuration-cache compatible. If enabled for your project, you can experience significant compilation time speed-ups. This is highly encouraged given Kobweb's live-reloading experience.

Thanks!

This change exists thanks to @DennisTsar's efforts.

• He regularly tested Kobweb against pre-release versions of K2
• He identified and reported an incremental compilation issue with 2.0.0 (before things went out to our users!)
• He wrote the migration Gradle task and migration documentation
• He ensured that Kobweb was configuration-cache compatible by the time K2 came out

For my part, I mostly stayed out of his way, and I poked JB occasionally about the status of our filed bug.

This is a really incredible release, one that will result in memory and performance improvements for almost (or even every?) Kobweb user, and that many people were waiting for. And all the legwork for it happened while I was distracted by other tasks. I am truly grateful.

Of course, thanks as well to the Kotlin team. K2 is shaping up to be quite an excellent iteration on the language.

---

Full Changelog: v0.18.3...v0.19.0

v0.18.3

This release is a collection of miscellaneous features and bug fixes. Enjoy!

Important

Planning to upgrade? Review instructions in the README.

Changes

Frontend

• Modifier support for the border-image CSS property.
• Added additional margin and padding-related CSS logical properties (like more overrides for scrollPadding, marginInline, etc.)
• Fixed a bug where Modifier.background(color) without any other parameters would ignore the color value.
• You can now programmatically query all routes in your site using the PageContext
  • e.g. ctx.router.routes.forEach { r -> console.log(r.path) }
• Add new type-safe API for working with local storage and session storage (Documentation)
• ⚠️ Legacy route support has been removed.
  • See the Notes section for more information.
• Fixed some edge cases where underscores really confused route generation logic.
  • ⚠️ Example_Route.kt used to generate example_route and now will generate example-route.

Markdown

• Fixed issue where putting triple quotes in code blocks would generate code that wouldn't compile.

Backend

• API endpoints now support dynamic routes
  • e.g. @Api("articles/{article}")
  • Access the value of article in the above case using ctx.params["article"]

Gradle

• Kobweb should now be compatible with the Gradle configuration cache.
  • Note that the Kotlin plugin itself is not until v2.0. Kobweb should have support for this version soon.

---

Notes

Legacy Route support removed

If you don't care that much about a bit of Kobweb history, then don't read the rest of this section. Just go into your build.gradle.kts and remove the line:

kobweb {
  app {
    // ↓↓↓↓↓↓↓
    legacyRouteRedirectStrategy.set(DISALLOW) // DELETE ME!
    // ↑↑↑↑↑↑↑
  }
}

Caution

If you have this set to WARN or ALLOW, please read here.

However, if you'd like to learn more about this, read on!

Legacy route history

In the beginning, I wrote some logic to convert a Kotlin @Page filename (Example.kt) into a URL route (/example). My initial algorithm simply lowercased everything, and while I did not realize it at the time, this made the default behavior generate names that did not conform to Google's SEO recommendations, which is to use hyphens to separate words.

In 0.16.0, we updated this! So ExampleRoute.kt would now generate /example-route and not /exampleroute.

This long overdue change which, unfortunately, could break old sites if released directly.

Therefore, we did a bunch of work to intercept routes and handle legacy formats and new formats at the same time. In other words, a site with legacy route support would work if you visited either /examperoute OR /example-route.

However, it was always the plan to remove it sooner than later. It was a lot of ugly code we had to maintain, and the issue wasn't likely to affect that many users. Therefore, we gave users 6 months to migrate any offending cases over.

And that brings us to today! Legacy routes are finally out.

In order to not break compilation, we are leaving the legacyRouteRedirectStrategy property in Gradle for now, but it doesn't do anything anymore (except print out a warning if you've set it). You have 6 months to delete this one-liner from your project...

Thanks!

We had a first time contribution from @FromWau who noticed some misformatted documentation and fixed it. These kinds of cleanups are truly appreciated! Thanks for helping keep Kobweb tidy.

And a serious shoutout to @DennisTsar who did all the hard work to fix my crappy Gradle code in order to make it configuration cache friendly.

---

Full Changelog: v0.18.2...v0.18.3

v0.18.2

This is a minor release mostly to fix an accidental API ambiguity error we introduced for some users in v0.18.1. We also picked up a few misc. additions along the way.

If v0.18.1 is working fine for you, there is no urgency to upgrade.

Important

Planning to upgrade? Review instructions in the README.

Changes

Frontend

• Fixed ambiguity error for people calling Modifier.background(color) without any other parameters.
• Fixed an exception that would get fired if you used a design breakpoint inside a ctx.stylesheet.registerStyle block.
• Added mixBlendMode modifier

Gradle

• Refactored our Gradle code more compatible with configuration caching.

Full Changelog: v0.18.1...v0.18.2

v0.18.1

This release is a grab bag of miscellaneous features, including the addition of the long requested spacedBy arrangement method for Row and Column layouts (which comes thanks to a contribution from the community via @rafaeltonholo!). This release also features a handful of Markdown and CSS API fixes.

Important

Planning to upgrade? Review instructions in the README.

Note

Users are asking us when K2 support is going to land, but we are currently blocked due to a pretty major incremental compilation issue. You can learn more here and here. We are keeping a close eye on it and will support K2 as soon as we can!

Changes

Frontend

• New spacedBy arrangement support
  • See notes below for more information
• The boxShadow modifier can now take multiple shadow values
• Add transformBox, transformOrigin, and transformStyle modifiers
• Add overscrollBehavior modifier.

Silk

• Support for CSS layers

  • Read more about the feature in the README
  • Support for CSS layers was actually quietly introduced in 0.18.0 but not officially announced, since we wanted a bit of time to battle test the API first

• You can now pass in a callback letting you configure the look and feel of TOC header links

• Added new descendants and children utility methods for use inside CssStyle

  • For example, CssStyle { children("div", "span") { /* ... */ } } which is more expressive and easier to remember than cssRule(" > :is(div,span)")

• Link and Anchor widgets now accept an optional updateHistoryMode parameter

  • This is useful if you want a link to replace the current page rather than visit it (in other words, if you want to change the behavior when you press the "back" button)

• ⚠️ Renamed onTextChanged to onTextChange and onValueChanged to onValueChange for relevant Silk widgest

  • This brings our naming in line with how Jetpack Compose names its callbacks. Apologies for catching it so late.

Markdown

• You can now nest Kobweb Call blocks, supporting Kobweb code calling Kobweb code.
• Fixed logic issue in markdown that was preventing markdown context from being created in certain situations.
• Fixed a case where multiline markdown text had newlines getting swallowed

Backend

• Cleaned up logic around detecting routes that represent routes vs. files
  • For example, we no longer erroneously detect 1.0.0 in https://site.com/path/to/1.0.0 as a file with a .0 extension.

Notes

spacedBy

In HTML / CSS, the normal way to put space between elements in a row, column, or table layout is using the gap CSS style, which we have actually recommended for the last two years. However, with spacedBy, you can now use that instead:

// Using gap
Row(Modifier.columnGap(2.cssRem)) { /* ... */ }

// Using spacedBy
Row(horizontalArrangement = Arrangement.spacedBy(2.cssRem)) { /* ... */ }

The spacedBy method can also take optional alignment parameters. Read the official Jetpack Compose documentation for more information about these new APIs.

Constructing Background, Transition, and Animation CSS style properties

Over the past year, we have been building up a consistent vocabularly for how we want our CSS style classes to behave.

A very common pattern that has emerged is the CssStyleClass.of(...) helper method, which is a useful way to construct many CSS style classes that have complex parameters.

For Background, Transition, and Animation classes, however, since those classes already had (incomplete) definitions inside Compose HTML, we extended them by introducing our own CSSBackground, CSSTransition, and CSSAnimation data classes.

We have since come to the conclusion that this is pretty inconsistent and confusing, so in this release, Kobweb has introduces its own Background, Transition, and Animation classes. Constructing them is now consistent with all other CSS styles.

This may result in you getting deprecation warnings to migrate code over. Fixing it should be relatively straightforward, as in the following code:

-import com.varabyte.kobweb.compose.css.CSSTransition
+import com.varabyte.kobweb.compose.css.Transition

-CSSTransition("color", 50.ms))
+Transition.of("color", 50.ms))

Gradle

We have been hard at work getting Kobweb tasks to play nicer with the Gradle configuration cache. Our changes so far have all been implementation fixes that will be invisible to users, but we may need to deprecate / migrate some APIs in near future releases.

Thanks

This release we enjoyed first-time submissions from user @rafaeltonholo 🎉

They provided excellent PRs for the boxShadow and spacedBy changes. They also helped us identify inconsistencies in our codebase that we spent time tightening up.

Thank you Rafael for your contributions!

---

Full Changelog: v0.18.0...v0.18.1

v0.18.0

This release introduces the new CssStyle concept, which supersedes and obsoletes the previous ComponentStyle concept.

Important

Planning to upgrade? Review instructions in the README.

This release is one of the most significant changes we've made since we've started Kobweb development. These changes have been in discussion and development in the background for over eight months(!!!).

Caution

This release will likely introduce many deprecation warnings to your project. Please don't skip over the next section!

⚠️ Migrating your project

As authors of the framework, we're very excited about this release (and relieved to be finally getting it out there), but users should be prepared to hit anywhere from a handful to a bunch of warnings after upgrading. We've done everything we could to make the migration process as easy for users to do as possible, but we want to minimize surprise, which is why we're mentioning this up front.

If you are in the middle of a large change to your site, you probably want to hold off on upgrading until you can get your changes in.

After upgrading to Kobweb 0.18.0, users are encouraged to run ./gradlew kobwebMigrateToCssStyle in a clean git branch.

For most projects, the automigration task should just work; in rare cases, some projects using more advanced features may run into errors which should be easily resolvable.

Users can read the full story about Cssstyle here, including detailed migration support at the end of it.

A brief CssStyle overview

The short version is, this old pattern:

val ExampleStyle by ComponentStyle {
   /* ... */
}

has been replaced with

val ExampleStyle = CssStyle {
   /* ... */
}

"That's it?" you might be thinking. "You're so excited about a name change?"

Well, getting rid of the by keyword (a source of confusion for many new users) is already a nice win. But more importantly, we wrangled with a feature that organically grew out the constraints of its original design and fixed some of the longstanding issues with it.

Originally, ComponentStyle was meant to be a mechanism just for Silk to use internally when defining widgets, but it became the common and recommended approach for Kobweb users everywhere to create styles, even if the styles they were creating had nothing to do with any specific component. (For example, Silk even did this itself! It provides the SmoothColorStyle for smooth background color transitions; that's not really something that should be called a "component" style).

Note

In the context of Kobweb Silk, a style is Kotlin code that ultimately gets converted into / registered as a CSS stylesheet entry. Not too familiar with CSS stylesheet entries or why you should care about them? You can review the README section about them.

Moving forward, Kobweb now supports three broad categories of styles that we've identified across many users' projects: general styles, component styles, restricted styles.

General Styles

General styles are the most common type, and if you've been using ComponentStyle in your codebase, probably 95-100% of those declarations fall into this category. This case is just a block of related, open-ended, useful style values.

val HeaderTextStyle = CssStyle.base {
   Modifier.fontSize(32.px).fontWeight(FontWeight.Bold)
}

Starting in 0.18.0, you can now extend styles, which generate a new style that wraps its source style:

val TextStyle = CssStyle.base { Modifier.fontFamily("customfont") }

val HeaderTextStyle = TextStyle.extendedByBase {
   Modifier.fontSize(32.px).fontWeight(FontWeight.Bold)
}

val LoudHeaderTextStyle = HeaderTextStyle.extendedByBase {
   Modifier.color(Colors.Red).backgroundColor(Colors.Yellow)
}

With the above declared, LoudHeaderTextStyle.toModifier() would apply itself and its dependent styles, setting font family, font size, and colors all in a single invocation.

Component Styles

Component styles are the ones we originally designed -- styles with a niche purpose to back some widget and allow users to generates variants (i.e. style tweaks) on top of them.

As a bonus, starting in 0.18.0, they are now typed, so that you can no longer use a variant created by one of these styles with another style.

sealed interface ProgressKind : ComponentKind
val ProgressStyle = CssStyle<ProgressKind> { /* ... */ }
val IndeterminiteProgressVariant = ProgressStyle.addVariant { /* ... */ }

@Composable
fun Progress(
   modifier: Modifier = Modifier
   variant: CssStyleVariant<ProgressKind>? = null
) {
   val finalModifier = ProgressStyle.toModifier(variant).then(modifier)
   Box(finalModifier) { /* ... */ }
}

Restricted Styles

Restricted styles, the final category, are a way to create a class that exposes a limited set of constructor parameters, generating a style behind the scenes. We call it restricted because, unlike the other types of style declarations which are totally open-ended, these styles are constrained by the handful of constructor parameters that the class owner exposes.

class ProgressSize(size: CSSLengthNumericValue) :
   CssStyle.Restricted.Base(Modifier.size(size)) {
   companion object {
      val SM = ProgressSize(0.5.cssRem)
      val MD = ProgressSize(1.cssRem)
      val LG = ProgressSize(1.5.cssRem)
   }
}

CssStyle document

This concludes a brief overview of the new feature, but to see more details, read this document.

---

Thanks

I'd like to take a moment to express an incalculable amount of thanks to @DennisTsar, without whom this feature wouldn't exist. He did a ton of foundational exploration and work, but more than that, he identifyied and raised concerns about ComponentStyle in the first place.

I hope everyone working in open source is lucky enough to get to work with a core contributor of his generosity, good sense, and ability.

---

A final note

As library authors, we'd in general like very much not to make drastic changes like this, because we understand how disruptive it can be to our users who are just trying to get their work done.

Of course, it has been thanks to exposure from two years of some of the amazing projects that our users have created that has helped us improve our understanding of the domain. Normally, we can make incremental fixes here and there, but in this case, there was no way around ripping out the floor and installing a new one.

Still, we wanted to thank our users for their patience and understanding. We hope moving forward that people find CssStyle more convenient to use, due to its shorter name (easier to type!), improved type-safety, and extended feature set.

---

Full Changelog: v0.17.3...v0.18.0

v0.17.3

This small release fixes two regression with routes introduced in v0.17.2 -- one subtle dealing with trailing slashes, and another significant one that broke dynamic routes.

Important

Planning to upgrade? Review instructions in the README.

The release also adds a handful of misc. features that are coming along for the ride.

Changes

Frontend

• Fixed regression where dynamic routes stopped capturing values correctly
  • For example, the dynamic route "/{folder}/{page}" should match "/example/route" providing params["folder"] == "example" and params["page"] == "route"
• Fixed regression where missing slashes wouldn't get auto-appended.
  • For example, if you've registered the route "/a/b/" and the user visits "/a/b" (no trailing slash), Kobweb will automatically suffix the "/" for you at the end.
• Added tests for route logic so that we don't break subtle route features again...
• Added :focus-within psuedo-class
• Updated FA icons to v6.5.2, which adds about a dozen or two new icons, including FaThreads for Meta's "Threads" logo.

Markdown

• Added support for surfacing the optional title of an image link, e.g. ![example](/some-image.png 'This is a title')

---

Full Changelog: v0.17.2...v0.17.3

v0.17.2

This release adds a few features and has also migrated its dependencies to target Compose 1.6.2. (Projects using 1.6.1 should still work).

Important

Planning to upgrade? Review instructions in the README.

The biggest change is support for specifying route redirects, which you can read more about here.

server:
  redirects:
    - from: "/socials/facebook/([^/]+)"
      to: "/socials/meta/$1"

---

Changes

Frontend

• Navigation logic updated to take redirects into account.
• Users can now configure their site's lang setting, e.g. kobweb { app { index { lang.set("fr") } } } in your build script
  • If not set, defaults to "en"
  • You can use lang.set("") if you want to clear the language setting entirely.

Silk

• Fixed an issue with the checkbox implementation that could occasionally mess up scrolling vertical layouts.
• Modifier.backdropFilter now works on Safari targets

Backend

• Added routing support for redirects. Visiting an old URL will now return a 301 redirect code.

---

Full Changelog: v0.17.1...v0.17.2

v0.17.1

This is a small release which adds a new feature to Kobweb Workers and has also migrated its dependencies to target Compose 1.6.1 and Kotlin 1.9.23.

Important

Planning to upgrade? Review instructions in the README.

---

Changes

Workers

• Kobweb workers now support transferable objects
  • Transferable objects are a web solution to passing very large objects between an application and its workers
  • You can read more about them in the README
  • ⚠️ Backwards incompatible Unfortunately, this change will cause a compile error for anyone who is already using workers. The fix is easy, however. See the Notes section for more information.

---

Notes

The WorkerFactory interface has changed and will cause compile errors

In order to support transferable objects, the WorkerFactory interface has changed from using a lambda:

interface WorkerFactory<I, O> {
   fun createStrategy(postOutput: (O) -> Unit): WorkerStrategy<I>
}

to using a new class called OutputDispatcher:

interface WorkerFactory<I, O> {
   fun createStrategy(postOutput: OutputDispatcher<O>): WorkerStrategy<I>
}

Please update any implementations accordingly. Once the signature has been updated, your code should compile again as before.

For example, here is the diff in the empty template:

internal class EchoWorkerFactory : WorkerFactory<String, String> {
-  override fun createStrategy(postOutput: (String) -> Unit) = WorkerStrategy<String> { input ->
+  override fun createStrategy(postOutput: OutputDispatcher<String>) = WorkerStrategy<String> { input ->
      postOutput(input) // Add real worker logic here
   }
}

Deprecated code

We occasionally audit the codebase for deprecated code older than 6 months. In this case, we removed a lot. Hopefully, this won't affect you, if you already moved away from such code.

You can review this commit to see if a compile error you're getting was due to such a method

---

Full Changelog: v0.17.0...v0.17.1