1. Overview
This tutorial introduces WebJars and how to use them in a Java application.
Simply put, WebJars are client side dependencies packaged into JAR archive files. They work with most JVM containers and web frameworks.
Here’s a few popular WebJars: Twitter Bootstrap, jQuery, Angular JS, Chart.js etc; a full list is available on the official website.
2. Why Use WebJars?
This question has a very simple answer – because it’s easy.
Manually adding and managing client side dependencies often results in difficult to maintain codebases.
Also, most Java developers prefer to use Maven and Gradle as build and dependency management tools.
The main problem WebJars solves is making client side dependencies available on Maven Central and usable in any standard Maven project.
Here are a few interesting advantages of WebJars:
- We can explicitly and easily manage the client-side dependencies in JVM-based web applications
- We can use them with any commonly used build tool, eg: Maven, Gradle, etc
- WebJars behave like any other Maven dependency – which means that we get transitive dependencies as well
3. The Maven Dependency
Let’s jump right into it and add Twitter Bootstrap and jQuery to pom.xml:
<dependency>
<groupId>org.webjars</groupId>
<artifactId>bootstrap</artifactId>
<version>3.3.7-1</version>
</dependency>
<dependency>
<groupId>org.webjars</groupId>
<artifactId>jquery</artifactId>
<version>3.1.1</version>
</dependency>
Now Twitter Bootstrap and jQuery are available on the project classpath; we can simply reference them and use them in our application.
Note: You can check the latest version of the Twitter Bootstrap and the jQuery dependencies on Maven Central.
4. The Simple App
With these two WebJar dependencies defined, let’s now set up a simple Spring MVC project to be able to use the client-side dependencies.
Before we get to that however, it’s important to understand that WebJars have nothing to do with Spring, and we’re only using Spring here because it’s a very quick and simple way to set up an MVC project.
Here’s a good place to start to set up the Spring MVC and Spring Boot project.
And, with the simple projet set up, we’ll define a some mappings for our new client dependencies:
@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry
.addResourceHandler("/webjars/**")
.addResourceLocations("/webjars/");
}
}
We can of course do that via XML as well:
<mvc:resources mapping="/webjars/**" location="/webjars/"/>
5. Version-Agnostic Dependencies
When using Spring Framework version 4.2 or higher, it will automatically detect the webjars-locator library on the classpath and use it to automatically resolve the version of any WebJars assets.
In order to enable this feature, we’ll add the webjars-locator library as a dependency of the application:
<dependency>
<groupId>org.webjars</groupId>
<artifactId>webjars-locator</artifactId>
<version>0.30</version>
</dependency>
In this case, we can reference the WebJars assets without using the version; see next section for a couple actual examples.
6. WebJars on the Client
Let’s add a simple plain HTML welcome page to our application (this is index.html):
<html>
<head>
<title>WebJars Demo</title>
</head>
<body>
</body>
</html>
Now we can use Twitter Bootstrap and jQuery in the project – let’s use both in our welcome page, starting with Bootstrap:
<script th:src="@{/webjars/bootstrap/3.3.7-1/js/bootstrap.min.js}"></script>
For a version-agnostic approach:
<script th:src="@{/webjars/bootstrap/js/bootstrap.min.js}"></script>
Add jQuery:
<script th:src="@{/webjars/jquery/3.1.1/jquery.min.js}"></script>
And the version-agnostic approach:
<script th:src="@{/webjars/jquery/jquery.min.js}"></script>
7. Testing
Now that we’ve added Twitter Bootstrap and jQuery in our HTML page, let’s test them.
We’ll add a bootstrap alert into our page:
<div class="container"><br/>
<div class="alert alert-success">
<strong>Success!</strong> It is working as we expected.
</div>
</div>
Note that some basic understanding of Twitter Bootstrap is assumed here; here’s the getting started guides on the official.
This will show an alert as shown below, which means we have successfully added Twitter Bootstrap to our classpath.
Let’s use jQuery now. We’ll add a close button to this alert:
<a href="#" class="close" data-dismiss="alert" aria-label="close">×</a>
Now we need to add jQuery and bootstrap.min.js for the close button functionality, so add them inside body tag of index.html, as below:
<script th:src="@{/webjars/jquery/3.1.1/jquery.min.js}"></script>
<script th:src="@{/webjars/bootstrap/3.3.7-1/js/bootstrap.min.js}"></script>
Note: If you are using version-agnostic approach, be sure to remove only the version from the path, otherwise, relative imports may not work:
<script th:src="@{/webjars/jquery/jquery.min.js}"></script>
<script th:src="@{/webjars/bootstrap/js/bootstrap.min.js}"></script>
This is how our final welcome page should look like:
<html>
<head>
<script th:src="@{/webjars/jquery/3.1.1/jquery.min.js}"></script>
<script th:src="@{/webjars/bootstrap/3.3.7-1/js/bootstrap.min.js}"></script>
<title>WebJars Demo</title>
<link rel="stylesheet"
th:href="@{/webjars/bootstrap/3.3.7-1/css/bootstrap.min.css}" />
</head>
<body>
<div class="container"><br/>
<div class="alert alert-success">
<a href="#" class="close" data-dismiss="alert"
aria-label="close">×</a>
<strong>Success!</strong> It is working as we expected.
</div>
</div>
</body>
</html>
This is how the application should look like. (And the alert should disappear when clicking the close button.)
8. Conclusion
In this quick article, we focused on the basics of using WebJars in a JVM-based project, which makes development and maintenance a lot easier.
We implemented a Spring Boot backed project and used Twitter Bootstrap and jQuery in our project using WebJars.
The source code of the above-used example can be found in the Github project – this is a Maven project, so it should be easy to import and build.
