Lumo to Aura Migration

General
3

I am doing the same right now for one of my apps, who I also built with the starpass theme in V24.

The biggest pain is the replacement of LumoUtilities, as there is no real replacement, except for Tailwind, which works fine, but does not align with Vaadin/Aura styling variables at the moment, e.g. there is no dedicated class for --vaadin-padding-m - you either need to use the respective numeric tailwind classes ( p-2) or the custom-var-classes (p-(--vaadin-padding-m), which can lead to some unreadable code).

I did the following, so it may help you finding your own way:

  1. move the content of your themes folder to the respective new position under META-INF/resources (and maybe some subfolder like styles)
  2. remove the @Theme annotation and add the respective @Stylesheet annotation
    a. either add the aura import in your styles.css or as an extra annotation
  3. go through your css files and replace the --lumo properties with the respective --vaadin or --aura properties (see Vaadin themes and base styles for details). It is a bit more tedious to find the correct prefix, since now it is one of the both with --vaadin the more prominent one (at least for my code it was the case)
    a. you will see, that there are no “margin” variables anymore. I used the “padding” ones also for margins.
    b. there are also no “sizes” anymore (like --lumo-size-m). If you used them, you have to create them yourself.
  4. And now the potentially ugly part: if you have used LumoUtility (I did that a lot for instance), you have to decide, how to overcome them
    a. either by converting all the respective settings into css in stylesheets. I started with that first and it was very very tedious. But it keeps the Java code a bit cleaner, since you only have a single css class there.
    b. or by replacing them with Tailwind css classes. This is my current approach. It bloats the Java code a bit more with a lot of strings, especially since it is more powerful and there a no constants, but it speeds up the conversion process, since you do not have to create a lot of additional stylesheets. When that part is done, often used Tailwind classes can be converted into static Strings, that can be reused and are a bite more self explanatory.
    c. when using Tailwind, I would recommend to map the variable custom vars (like Padding.S, .M, etc) to the numeric tailwind classes (like p-2, p-3, …) - or, if you want to use p-(--vaadin-padding-m), convert them directly into String constants.
  5. Some components may look different, for instance the progress-bar IIRC looks a bit different in Startpass than in Aura. If that is the case, peek into the respective Starpass styles and pick styles you need for your app
  6. Check everything and fix potential issues.

Side notes:

  • Most important side note: depending on the amount of styles, it may take a while until the conversion is done. Don’t try to fix things, until you have converted everything. I did that cause I was to impatient and it lead to duplicate styles at some points.
  • Aura handles “primary” colors differently than lumo. There is not a “primary” color, but an accent color, that behaves differently. Depending on the accent color, that can have interesting side effects (my primary color was pink-ish, which did not fit well as accent color). So you may have to override the aura accent color property for dedicated parts or components of your app.
  • Light and dark themes are configured differently than in Lumo. Always use the -dark/-light variant of a custom property.
  • Be careful with the background color to pick. It affects a lot in Aura, more than in Starpass IIRC.

I hope I did not forget anything, but this is more or less a “log” of my doings and I took some turns before I found a way that worked fine for me.

1 Like