Correct method for packaging CSS in component libraries

I have a question ever since i noticed that the @CssImport annotation is considered a legacy feature https://vaadin.com/docs/latest/styling/legacy/css-import

We have a a project that contains several jars to expose some Vaadin components that we re-use across several projects, similar to how vaadin components are made available

  • my-custom-button.jar
  • my-custom-grid.jar

These components come with custom css.
Before we could use the @CssImport annotation to package the css file (in the META-INF frontend folder of the component jar) and these would be picked up by the Vaadin build of the parent project where the component was included as a dependency.

What is the correct way to replicate this setup without using the CssImport annotation?

Because the legacy page refers to switching to themes https://vaadin.com/docs/latest/styling/application-theme, but I don’t see how we can achieve the same result?

  • @import the stylesheets from the jars in the master stylesheet of the application? But this seems like a very big QoL regression compared to before
  • parent themes? But as far as I understand the documentation there can only be a single theme parent
  • Some other way that I missed in the documentation?

I would appreciate some input on this, because for now it seems our best course of action is to keep using @CssImport but I would rather not rely on a legacy feature in new code we deliver.

Those projects / add-ons should still use those annotations. The usage is marked legacy directly in applications if I understand the intention correctly

My developer brain interprets legacy == deprecated

Which leads me to some reservation to keep using the feature in new code.
Since I’m woried support for the CssImport annotation might be dropped in some future Vaadin release

There is also @Stylesheet, which is a more generic way to load CSS. The main difference between that and @CssImport is that the latter adds the css to the frontend bundle, while the latter doesn’t. (Which may or may not be what you want.)

If we do deprecate @CssImport, I would expect there to be an option to bundle stylesheets loaded with @Stylesheet for those who prefer that.

And if that happens, the refactorization required in custom components should not be worse than changing one annotation to another.

The stylesheets need to be added to the bundle. So for now as I understand it we should keep using the @CssImport annotation. And should it become truly deprecated some alternative is probably going to be provided.
Is there someway this could be reflected in the documentation on styling and stylesheets on the site? Because to me it very much seemed like we should treat the CssImport annotation like a “deprecated” feature we should avoid using.

The thing that is discouraged is the theme-for since it injects the CSS into the shadow Dom. Now there is a standard way of doing this. The documentation should be updated to avoid the confusion. Currently the CSS import annotation is the way to style your component ( to be packaged as a jar) . Of course for an application you should use the theme.

In your case, you could use a theme that embeds all the components ( my-custom-button,… ). That’s simpler but you have less granularity.

Indeed, we should make the documentation more precise about this. I’ll make a ticket about it.

There https://github.com/vaadin/docs/issues/3069