diff --git a/articles/styling/advanced/npm-packages.adoc b/articles/styling/advanced/npm-packages.adoc index 547e3f97b5..70008351ce 100644 --- a/articles/styling/advanced/npm-packages.adoc +++ b/articles/styling/advanced/npm-packages.adoc @@ -108,4 +108,62 @@ The assets block supports multiple packages and multiple mappings per package. B } ---- +[since:com.vaadin:vaadin@V24.9] +[#fonts-and-images-from-npm-with-npmpackage-annotation] +== Loading Fonts and Images from npm Packages Using the NpmPackage annotation + +[annotationname]`NpmPackage` has the field `assets` that makes it possible to copy assets from npm packages without the need for a custom theme or the `theme.json` file. + +The difference between using the `theme.json` and annotation `assets` is the location. +Theme copies under the custom theme folder, but the annotation copies to the static folder. + +The syntax for [annotationname]`NpmPackage` is the same as used for `theme.json`, `"asset/glob/pattern:local/target/path"`. +Multiple assets can be given for a single package annotation. + +.Sample asset mapping with `NpmPackage` annotation +[source,java] +---- +@NpmPackage(value = "@fortawesome/fontawesome-free", version = "5.15.1", + assets = { + "svgs/regular/**:fontawesome/icons" + }) +@Tag("my-component") +public class MyComponent implements Component { + public MyComponent() { + add(new Image("VAADIN/static/fontawesome/icons/snowflake.svg", + "snowflake")); + } +} +---- + +[NOTE] +The assets from the [annotationname]`NpmPackage` annotation are copied to the static folder `VAADIN/static` instead of `VAADIN/static/themes/[themeName]/` + +In the sample case the `svgs/regular/snowflake.svg` file from the `fortawesome` package is copied to `VAADIN/static/fontawesome/icons/snowflake.svg` and you should reference it with that path in the application code, including CSS stylesheets. +This difference is due to the custom theme call having the `themes/[themeName]/` in the request letting us know it is a theme resource, making it possible to prepend the static part. + +== Loading Stylesheets from npm Packages Using the CssImport annotation + +To load stylesheets form npm packages it is possible to use [annotation]`CssImport` targeting the stylesheet in `node_modules`. +For example to load `all.min.css` from `@fortawesome/fontawesome-free` an endpoint needs to be annotated as `@CssImport("@fortawesome/fontawesome-free/css/all.min.css")` + +.Sample asset mapping with `NpmPackage` annotation +[source,java] +---- +@NpmPackage(value = "@fortawesome/fontawesome-free", version = "5.15.1") +@CssImport("@fortawesome/fontawesome-free/css/all.min.css") +public class AppShell implements AppShellConfigurator { +} + +@Tag("my-component") +public class MyComponent implements Component { + public MyComponent() { + Span userIcon = new Span(); + userIcon.addClassNames("fa-sharp", "fa-solid", "fa-user"); + userIcon.getStyle().set("font-family", "'Font Awesome 5 Free'"); + add(userIcon); + } +} +---- + [discussion-id]`3e46fe3b-00d6-4cf7-908c-342a364210db`