Skip to content

michael-simons/wro4j-spring-boot-starter

Repository files navigation

wro4j-spring-boot-starter

A Spring Boot starter and auto-configuration for wro4j:

Wro4j is a tool for analysis and optimization of web resources. It brings together almost all the modern web tools: JsHint, CssLint, JsMin, Google Closure compressor, YUI Compressor, UglifyJs, Dojo Shrinksafe, Css Variables Support, JSON Compression, Less, Sass, CoffeeScript and much more.

Build Status Test coverage Quality Gate Maven Central

NOTE Wro4j has been updated to the Jakarta Servlet API with Wro4j 2 and it does now require Java 17, similar to Spring Boot 3. This integration has been upgraded to support Wro4j 2 on Spring Boot 3 since release 0.12.1.

Introduction

This starter does the following auto configuration for you:

  • Creating the WroFilter and the WroModelFactory
  • Registering them as a ServletFilter through a Spring FilterRegistrationBean

Furthermore it provides a Spring Based caching strategy if a CacheManager is present (which is the case if you're Spring Boot Application is configured with @EnableCaching) and a cache name is configured.

The wro4j-spring-boot-starter expecteds the Wro4j model configuration in xml format. If you want the Groovy version you have to role your own WroModelFactory, which is recognized by the auto configuration.

This starter doesn't bring in the wro4j-extension artifact which are a lot of third party libraries. If you need them, you have to include this in your Maven or Gradle build file.

With the starter comes an additional resource processor removeSourceMaps which removes stale source maps from minified and concatenated files.

This starter is in production at euregjug.eu and in various ENERKO Informatik products.

Usage and configuration

Just include the starter in your pom.xml:

<dependency>
    <groupId>eu.michael-simons</groupId>
    <artifactId>wro4j-spring-boot-starter</artifactId>
    <version>0.14.1</version>
</dependency>

These versions have been tested together:

Spring Boot Wro4j Starter
2.0.x 0.4.2
2.1.x 0.5.3
2.2.x 0.6.3
2.3.x 0.7.2
2.4.x 0.8.x
2.5.x 0.9.x
2.6.x 0.10.x
2.7.x 0.11.x
3.1.x 0.12.x
3.2.x 0.13.x
3.3.x 0.14.x

Add a wro.xml to your resources:

<?xml version="1.0" encoding="UTF-8"?>
<groups xmlns="http://www.isdc.ro/wro">
</groups>

including your CSS and JS files, and you're pretty much good to go. Be aware that this file belongs to your resources (i.e. /src/main/resources) and not under your WEB-INF directory as without the starter. I prefer having those configurations in one place. Read more about the wro.xml format at the official Wro4j documentation.

To actually minify your resources, you have to configure some processors. The starter is used at euregjug.eu for example with the following configuration:

wro4j.managerFactory.preProcessors = removeSourceMaps, cssUrlRewriting, cssImport, cssMinJawr, semicolonAppender, jsMin

Have a look at the configuration of the JUGs site at the source here. If you're already looking for a solution to use Wro4j with Spring Boot and found this starter than i guess you already know about the runtime solution Wro4j provides for your CSS and JS resources.

You can use all processors as described here.

For further configuration you can use all properties described under Available Configuration Options under the namespace wro4j.*, the options for configuring the pre- and postprocessors are under the subnamespace wro4j.managerFactory.*, as wro4j.managerFactory.preProcessors and wro4j.managerFactory.postProcessors.

As an alternative, you can add processors via their fully qualified classname as wro4j.preProcessors and wro4j.postProcessors. Configuring the processors via name or fully qualified class are mutually exclusive.

Configuration of Pre- and PostProcessors

You can configure Pre- and PostProcessors at two different points:

If you use wro4j.managerFactory.preProcessors and wro4j.managerFactory.postProcessors you must use predefined aliases or register your own processor provider as described in the comments of issue #3.

You can however use "our" custom options wro4j.preProcessors and wro4j.postProcessors (note the difference: No manager factory in between!). Those options take a comma separated list of classes that must implement ResourcePreProcessor and ResourcePostProcessor respectively.

If you do this, the wro4j-spring-boot-starter first checks, if a bean of the given type exists in the application context. This way, you can manage your processors as normal Spring beans. The only thing you have to take care of is to make sure that those are present in the context before Wro4jAutoConfiguration runs. See the example Wro4jAutoConfigurationIntegrationTests.

Options not present in the original Wro4j version

Option Default Meaning
wro4j.model /wro.xml The resource containing the Wro4j model definition (will be looked up as a classloader resource, not inside WEB-INF)
wro4j.filterUrl /wro4j Url to which the filter is mapped. Will be expanded to value/*
wro4j.cacheName The name of a Spring Cache. If this property is set and a CacheManager is configured (for example through @EnableCaching), then a CacheStrategy based on Spring cache abstraction will be used.

Misc

Beans of the following types are recognized and added to wro4j

  • ResourceAuthorizationManager

Not configurable at the moment

The options uriLocators, namingStrategy and hashStrategy are not configurable at the moment through this starter. If you need those, you have to provide your own WroManagerFactory as a Spring Bean, configured to your needs. The starter will still configure the model and processors factories for you and pass them to your manager factory, though.

Acknowledgements

I've been using Wro4j as a runtime solution since 2012 on dailyfratze.de and it really worked well for me. Thanks Alex for your work.

As always, the Spring documentation is a valuable resource. Here's how to start your own auto-configuration or starter: Creating your own auto-configuration. Thanks to all the people involved.

There's another Wro4j starter by Simon Buettner from which I had the basic idea, but I didn't like the fact that it centers around the Groovy model and especially the whole wro4-extensions.

Examples

ENERKO Informatik GmbH is using Wro4j and this starter in several products as well.