v0.15.3

[bitspittle]

This release brings some extra functionality to Kobweb's export feature.

Planning to upgrade? Review instructions in the README.

---

Export

• The export block has moved from kobweb.export to kobweb.app.export, a long overdue migration.
• You can now use kobweb.app.export.filter to filter some routes out of being exported, which can save a lot of time in case you have some routes that don't need to be cached for SEO purposes.
• You can now use kobweb.app.export.enableTraces to collect snapshots of your pages' progress which you can use to visualize what was happening when they were being visited at export time.
• You can configure the timeout used when exporting by setting the kobweb.app.export.timeout property, for example timeout.set(1.minute).
  • The default timeout is 30 seconds.

Backend

• The ApiContext and InitApiContext classes now expose a property which tells you if your server is running in dev or prod mode; for example, ctx.env.isDev.
  • You can use this information to decide if you should create development versions of services, like a database populated with fake data.

Frontend

• Added convenience size(width, height), minSize(width, height), and maxSize(width, height) modifiers.
• Added new CSS*NumericValue types for all relevant CSS units.
  • Compose HTML provides non-Numeric versions, e.g. CSSLengthValue, CSSPercentageValue, etc.. Kobweb now provides numeric versions, e.g. CSSLengthNumericValue, CSSPercentageNumericValue, etc.
  • Updated all Kobweb APIs to use these new types.
  • Read more about this change in the README.

---

Notes

The export block has moved

The export feature is about as old as features in this framework get. As a result, it's no surprise that the export block location is outdated!

The new location lives under the app block (since only application modules should be influencing it):

// site/build.gradle.kts

// Old location
kobweb {
   export {
      includeSourceMap.set(false)
   }
}

// New location
kobweb {
   app {
      export {
         includeSourceMap.set(false)
      }
   }
}

It's trivial to move, but Gradle / IntelliJ unfortunately doesn't surface deprecation warnings directly (i.e. it would have been nice if the export name was crossed out in the IDE if in the old location), so instead you will get a warning at export time.

Filtering routes

Here's a quick example where we filter out exporting all admin pages from our site, since those will always require auth anyway and shouldn't be cached for SEO purposes. The filter scope includes a route property you can use to test the current route being exported:

// site/build.gradle.kts

kobweb {
   app {
      export {
         filter { !route.startsWith("/admin/") }
      }
   }
}

Enabling export traces

Let's say you have a page on your site that is taking 10 seconds to export, when all your other pages only take 1. What is happening?

Thanks to a feature provided by Playwright (the framework by Microsoft we use for taking browser snapshots), enabling traces is easy:

// site/build.gradle.kts

kobweb {
   app {
      export {
         enableTraces()
      }
   }
}

You can look at the docs for enableTraces to see how to configure it, but by default, when traces are enabled, Kobweb will drop trace.zip files under your .kobweb/export-traces folder, one per page exported.

You can then drag and drop those files into the page at https://playwright.dev/docs/trace-viewer to investigate its details.

Between trace snapshots and server logs, you should be able to diagnose what's going on.

---

Full Changelog: v0.15.2...v0.15.3

---

This discussion was created from the release v0.15.3.