Documentation

Instructions for Play 2.6 (Sample Source)

WebJars can be added as dependencies to an app by simply adding them to the build.sbt file like:

libraryDependencies += "org.webjars" % "bootstrap" % "3.1.1-2"

Play automatically extracts the WebJar contents and makes them available via the Assets controller. So, if you have a route like:

GET         /assets/*file           controllers.Assets.at(path="/public", file)

Then a WebJar file like bootstrap.css is available at:

/assets/lib/bootstrap/css/bootstrap.css

There is also a helper library named webjars-play that makes it easy to reference WebJar assets. Here is an example build.sbt file with webjars-play and the bootstrap WebJar as dependencies:

libraryDependencies ++= Seq(
  "org.webjars" %% "webjars-play" % "2.6.3",
  "org.webjars" % "bootstrap" % "3.1.1-2"
)

After changing the dependencies you will need to restart Play.

The webjars-play helper library has a wrapper around the Play Static Asset Controller that can locate and serve WebJar assets. A new route import needs to be added to the conf/routes file:

->          /webjars                webjars.Routes

The org.webjars.play.WebJarsUtil class has a number of helpful methods for locating and loading assets. Check out the JavaDoc. To use it you need to inject an instance of WebJarsUtil - usually into a template. For example:

@this(webJarsUtil: org.webjars.play.WebJarsUtil)

... HTML page ...

@webJarsUtil.locate("bootstrap.min.css").css()
@webJarsUtil.locate("bootstrap.min.js").script()

WebJars have out-of-the-box support for RequireJS. To use it in a template, call the webJarsUtil.requireJs method with a reverse route to the main JavaScript app:

@webJarsUtil.requireJs(routes.Assets.versioned("javascripts/index.js"))

If you need to override the default RequireJS config you can use a lower-level RequireJS API to setup the config, for example:

<script>
  var require = {
    callback: function() {
      // default requirejs configs
      @for(webJarJson <- org.webjars.RequireJS.getSetupJson(routes.WebJarAssets.at("").url).values()) {
        @if(webJarJson != null) {
          requirejs.config(@Html(webJarJson.toString));
        }
      }

      // example custom requirejs config
      requirejs.config({
        paths: {
          jquery: "//code.jquery.com/jquery-1.11.1.min"
        },
        shim: {
          bootstrap: []
        }
      });
    }
  };
</script>
@webJarsUtil.locate("requirejs", "require.min.js").script(Map("data-main" -> routes.Assets.versioned("javascripts/index.js").url))

You can load WebJar assets from a CDN by setting the following config:

webjars.use-cdn=true
play.filters.headers.contentSecurityPolicy = "default-src 'self' https://cdn.jsdelivr.net"

Instructions for Xitrum

Xitrum from 3.13 has built-in support for WebJars. If you have a dependency like this:

libraryDependencies += "org.webjars" % "underscorejs" % "1.6.0-3"

In you Scalate view template file, you can write like this (the below examples use Jade syntax):

script(src={webJarsUrl("underscorejs/1.6.0", "underscore.js", "underscore-min.js")})

Xitrum will automatically use underscore.js for development environment and underscore-min.js for production environment.

The result will look like this:

<script src="/webjars/underscorejs/1.6.0/underscore.js?XOKgP8_KIpqz9yUqZ1aVzw"></script>

If you want to use the same file for both environments:

script(src={webJarsUrl("underscorejs/1.6.0/underscore.js")})

For examples, see xitrum-new and xitrum-demos (online).

Instructions for Servlet 3

With any Servlet 3 compatible container, the WebJars that are in the WEB-INF/lib directory are automatically made available as static resources. This works because anything in a META-INF/resources directory in a JAR in WEB-INF/lib is automatically exposed as a static resource. Please note that in case of Tomcat the JarScanner should not be configured to skip the WebJars (e.g. when jarsToSkip is set to * add the WebJars to jarsToScan).

Maven Example (example app)

First add a WebJar as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.1.0</version>
    </dependency>
</dependencies>

Then simply reference the resource like:

<link rel='stylesheet' href='webjars/bootstrap/3.1.0/css/bootstrap.min.css'>

Making dependencies version agnostic

Use the WebjarsServlet to make dependencies version agnostic, see Servlet 2.

Instructions for Servlet 2

WebjarsServlet allows Webjars resources to be referenced in legacy apps that are still running on Servlet containers that are not compliant with the Servlet 3 specification (e.g. Tomcat 6). It can also be used to make dependencies version agnostic in both Servlet 2 and Servlet 3 compatible containers.

Usage

1. Register our webjars-servlet-2.x Maven dependency in your web application:

   <dependency>
       <groupId>org.webjars</groupId>
       <artifactId>webjars-servlet-2.x</artifactId>
       <version>1.1</version>
   </dependency>

2. Register WebjarsServlet in your web.xml:

   <!--Webjars Servlet-->
   <servlet>
       <servlet-name>WebjarsServlet</servlet-name>
       <servlet-class>org.webjars.servlet.WebjarsServlet</servlet-class>
       <load-on-startup>2</load-on-startup>
   </servlet>
   <servlet-mapping>
       <servlet-name>WebjarsServlet</servlet-name>
       <url-pattern>/webjars/*</url-pattern>
   </servlet-mapping>

By default the Webjars resources will be cached by your browser. If for whatever reason you need to disable the cache, you can do so by using the disableCache configuration property like this:

<!--Webjars Servlet-->
<servlet>
    <servlet-name>WebjarsServlet</servlet-name>
    <servlet-class>org.webjars.servlet.WebjarsServlet</servlet-class>
    <init-param>
        <param-name>disableCache</param-name>
        <param-value>true</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

It is off course also possible to instantiate the WebjarsServlet programmatically (e.g. with Spring Boot's ServletRegistrationBean).

Making dependencies version agnostic

When using WebjarsServlet version 1.6 or higher, it will automatically detect the webjars-locator-core library on the classpath and use it to automatically resolve the version of any WebJar assets for you. In order to enable this feature, you will need to add the webjars-locator-core library as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>webjars-locator-core</artifactId>
        <version>0.48</version>
    </dependency>
</dependencies>

Then you may reference a WebJar asset in your template like this:

<link rel='stylesheet' href='/webjars/bootstrap/css/bootstrap.min.css'>

Instructions for JSF

With JSF, the WebJars that are in the WEB-INF/lib directory are automatically made available as resource libraries. This works because WebJars are compatible with the JSF resource identifier format. More Information about JSF resources.

Maven Example (example app)

First add a WebJar as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.1.0</version>
    </dependency>
</dependencies>

Then simply reference the resource like:

<h:outputStylesheet library="webjars" name="bootstrap/3.1.0/css/bootstrap.min-jsf.css" />
<h:outputScript library="webjars" name="jquery/1.11.2/jquery.js" />

Instructions for Grails (example app)

Grails manages static resources (such as javascript and css files) with the resources plugin. The resources plugin manages static resources via modules, like the Jquery Module, that define via a config file which static resources a module requires. For a more details explanation see the Grails docs on using Static Resource .

The Grails Modules Manager plugin allows dependencies on web libraries to be declared in the Grails build configuration file, BuildConfig.groovy. It resolves theses dependencies and creates modules that can be used by the resources plugin. It does this by downloading the jar files from webjars.org and extracting the web libraries from the jar files. It then creates grails specific resource modules from these web libraries.

Steps for using the plugin:

• Clone the modules manager plugin from

  https://github.com/groovydev/modules-manager-grails-plugin.git

• Build the plugin:

  grails package-plugin

• Install the plugin into your grails project from the file system - this assumes the plugin is in the same parent directory as the project:

  grails install-plugin ../modules-manager-grails-plugin/grails-modules-manager-0.2.1.zip

• Define the javascript and css dependencies. In grails-app/config/BuildConfig.groovy add:

  dependencies {
      compile 'org.webjars:bootstrap:3.1.0'
  }
  

• Run the refresh modules command which will download the necessary javascript and css dependencies:

  grails refresh-modules

• Notice how the plugin added the file conf/ModulesBootstrapResources.groovy. This module config file is used by the resources plugin to define the module dependencies and static resources.
• Add the module dependencies to the web page (see the example in views/index.gsp ). This is done by adding the require tag to the html page to include the static resource modules. Also note that it is necessary to add the layoutResources tag twice to the page. In the head tag add:

  <head>
  <r:require modules="jquery, bootstrap"/>
  <r:layoutResources/>
  

  And then at the bottom of the page right before the body add:

  <r:layoutResources/>
  </body>
  

• The resource manager then optimizes when the javascript is load by when it is need in the page and by default includes the javascript at the bottom of the page. For this reason it is necessary to put the javascript in a <r:script> tag so that the necessary dependencies will be included when the layoutResources tag is called. For example to use a jquery initialization function add the following to the page:

  <r:script>
  $(function (){ ... } 

Instructions for Dropwizard (example app)

With Dropwizard you can easily expose WebJars through the AssetsBundle. In your startup service's constructor setup the AssetsBundle to map static asset requests in a /META-INF/resources/webjars directory in JARs on the CLASSPATH to the /webjars URL, for example:

package org.webjars;

import com.yammer.dropwizard.Service;
import com.yammer.dropwizard.bundles.AssetsBundle;
import com.yammer.dropwizard.config.Configuration;
import com.yammer.dropwizard.config.Environment;

public class MainService extends Service {

    public static void main(String[] args) throws Exception {
        new MainService().run(args);
    }

    private MainService() {
        super("sample-dropwizard");
        addBundle(new AssetsBundle("/META-INF/resources/webjars", 0, "/webjars"));
    }

}

Now you can reference a WebJar asset like:

<link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'>

Instructions for Spring Boot (example app)

Spring Boot automatically configures Spring to map requests for /webjars to the /META-INF/resources/webjars directory of all the JARs in the CLASSPATH.

Maven Example

First add a WebJar as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.1.0</version>
    </dependency>
</dependencies>

Then reference a WebJar asset like:

<link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'>

Making dependencies version agnostic

When using Spring Boot, it will automatically detect the webjars-locator-core library on the classpath and use it to automatically resolve the version of any WebJar assets for you. In order to enable this feature, you will need to add the webjars-locator-core library as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>webjars-locator-core</artifactId>
        <version>0.48</version>
    </dependency>
</dependencies>

(Spring Boot manages the version if you use its BOM feature.) Then you may reference a WebJar asset in your template like this:

<link rel='stylesheet' href='/webjars/bootstrap/css/bootstrap.min.css'>

Enhanced support for RequireJS

RequireJS is a popular implementation of the AMD specification - a means by which JavaScript applications can be modularised. The easiest way of thinking about AMD is that it is JavaScript's equivalent of package and import statements (or namespace and include statements depending on your preferences!). These instructions assume basic knowledge of RequireJS.

The webjars-locator library has built-in support for RequireJS. To setup RequireJS use the webjars-locator library like this:

@ResponseBody
@RequestMapping(value = "/webjarsjs", produces = "application/javascript")
public String webjarjs() {
    return RequireJS.getSetupJavaScript("/webjars/");
}

This RequestMapping returns the setup code for your webjars and requirejs. It has to be included in your template before loading RequireJS. A basic setup looks like this:

<script src="/webjarsjs"></script>
<script data-main="/js/app" src="/webjars/requirejs/require.min.js"></script>

This loads the WebJars RequireJS configuration from webjars-locator and the RequireJS with a main JavaScript of js/app.

Underneath the covers each WebJar can have a RequireJS configuration file that sets up the modules, shims, exports, etc. These files is named webjars-requirejs.js and are automatically added to the page via the RequireJS.setup helper.

Some of the WebJars may not be updated to the new WebJars RequireJS syntax so if you experience problems please file issues on the WebJars you are using.

Instructions for Spring MVC

Spring MVC makes it easy to expose static assets in JAR files using ResourceHandlers.

Maven Example (example app)

First add a WebJar as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.1.0</version>
    </dependency>
</dependencies>

Then configure Spring to map requests for /webjars to the /META-INF/resources/webjars directory of all the JARs in the CLASSPATH. This can be done either via XML config:

<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

<mvc:resources mapping="/webjars/**" location="/webjars/"/>

Or Java config:

@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {

  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
  }

}

registry.addResourceHandler("/webjars/**").addResourceLocations("/webjars/");

Then reference a WebJar asset like:

<link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'>

Making dependencies version agnostic

When using Spring Framework version 4.2 or higher, it will automatically detect the webjars-locator-core library on the classpath and use it to automatically resolve the version of any WebJar assets for you. In order to enable this feature, you will need to add the webjars-locator-core library as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>webjars-locator-core</artifactId>
        <version>0.30</version>
    </dependency>
</dependencies>

And extend your XML config with a resource-chain element:

<mvc:resources mapping="/webjars/**" location="/webjars/">
    <mvc:resource-chain resource-cache="true"/>
</mvc:resources>

Or in case of Java config add the resourceChain() method and the WebJarsResourceResolver:

registry.addResourceHandler("/webjars/**").addResourceLocations("/webjars/").setCachePeriod(CACHE_PERIOD).resourceChain(true).addResolver(new WebJarsResourceResolver());

Then you may reference a WebJar asset in your template like this:

<link rel='stylesheet' href='/webjars/bootstrap/css/bootstrap.min.css'>

Enhanced support for RequireJS

RequireJS is a popular implementation of the AMD specification - a means by which JavaScript applications can be modularised. The easiest way of thinking about AMD is that it is JavaScript's equivalent of package and import statements (or namespace and include statements depending on your preferences!). These instructions assume basic knowledge of RequireJS.

The webjars-locator library has built-in support for RequireJS. To setup RequireJS use the webjars-locator library like this:

@ResponseBody
@RequestMapping(value = "/webjarsjs", produces = "application/javascript")
public String webjarjs() {
    return RequireJS.getSetupJavaScript("/webjars/");
}

This RequestMapping returns the setup code for your webjars and requirejs. It has to be included in your template before loading RequireJS. A basic setup looks like this:

<script src="/webjarsjs"></script>
<script data-main="/js/app" src="/webjars/requirejs/require.min.js"></script>

This loads the WebJars RequireJS configuration from webjars-locator and the RequireJS with a main JavaScript of js/app.

Underneath the covers each WebJar can have a RequireJS configuration file that sets up the modules, shims, exports, etc. These files is named webjars-requirejs.js and are automatically added to the page via the RequireJS.setup helper.

Some of the WebJars may not be updated to the new WebJars RequireJS syntax so if you experience problems please file issues on the WebJars you are using.

Instructions for Apache Tapestry

Apache Tapestry makes it easy to expose static assets in JAR files using contributeClasspathAssetAliasManager.

Maven Example (example app)

First add a WebJar as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.1.0</version>
    </dependency>
</dependencies>

Then configure the contributeClasspathAssetAliasManager in your AppModule to look for assets in META-INF/resources/webjars directories:

public class AppModule {
    public static void contributeClasspathAssetAliasManager(MappedConfiguration configuration) {
        configuration.add("webjars", "META-INF/resources/webjars");
    }
}

Then simply reference WebJars assets in your Tapestry templates like:

<link rel='stylesheet' media='screen'
    href='${asset:classpath:/META-INF/resources/webjars/bootstrap/3.1.0/css/bootstrap.min.css}'></link>
<script type='text/javascript'
    src='${asset:classpath:/META-INF/resources/webjars/jquery/1.9.0/jquery.min.js}'></script>

Instructions for Apache Wicket

The Wicket integration of Webjars uses a special IResourceFinder implementation to map Webjars resources.

Maven Example (example app)

First you have to add wicket-webjars as dependency to your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>de.agilecoders.wicket.webjars</groupId>
        <artifactId>wicket-webjars</artifactId>
        <version>0.3.4</version>
    </dependency>
</dependencies>

And a WebJar dependency like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>jquery</artifactId>
        <version>1.11.0</version>
    </dependency>
</dependencies>

Then configure your wicket application to map requests for /webjars and instances of IWebjarsResourceReference to the /META-INF/resources/webjars directory of all the JARs in the CLASSPATH. This can be done in Application.init:

/**
* @see org.apache.wicket.Application#init()
*/
@Override
public void init() {
   super.init();
   WicketWebjars.install(this);
}

Then simply reference the resource like:

<link rel='stylesheet' href='/webjars/jquery/1.11.0/jquery.js'>

Or add a Webjars*ResourceReference to your component:

@Override
public void renderHead(IHeaderResponse response) {
    super.renderHead(response);
    response.render(JavaScriptHeaderItem.forReference(
            new WebjarsJavaScriptResourceReference("jquery/1.11.0/jquery.js")));
}

To always use the most recent version of a WebJar asset, simply replace the version in path with the "current" string. When a resource name is resolved this string will be replaced with the most recent available version in classpath:

@Override
public void renderHead(IHeaderResponse response) {
    super.renderHead(response);

    // current will be replaced with "1.11.0"
    response.render(JavaScriptHeaderItem.forReference(
                    new WebjarsJavaScriptResourceReference("jquery/current/jquery.js")));
}

Instructions for Pippo

The Pippo integration of Webjars is pretty straightforward.

Maven Example (example app)

You should first add the dependecies to the webjars in Maven description file like this:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>jquery</artifactId>
        <version>2.1.4</version>
    </dependency>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.3.4</version>
    </dependency>
</dependencies>

Afterwards you have to let Pippo know you are using webjars. This can be done in Application.onInit method:

public class AjaxApplication extends Application {

    @Override
    protected void onInit() {
        addWebjarsResourceRoute();
        //business code here
    }
}

Then simply reference the resource for css:

<link href="${webjarsAt('bootstrap/3.3.1/css/bootstrap.min.css')}" rel="stylesheet">

or for js:

<script src="${webjarsAt('intercooler-js/0.4.10/src/intercooler.js')}"></script>

For examples on using webjars in several template language for Pippo you can check out this link here

Instructions for Ring (example app)

Ring makes it easy to expose WebJars through the wrap-resource function.

First add a Webjar as dependency to your application in the project.clj file, like:

:dependencies [[org.webjars/bootstrap "3.1.0"]]

Then change your wrapper sequence to setup wrap-resource to look for assets in /META-INF/resources directories in JARs on the CLASSPATH:

(def app
  (-> handler
    (wrap-resource "/META-INF/resources")))

(defn -main []
  (run-jetty app {:port (Integer/parseInt (or (System/getenv "PORT") "8080"))}))

Now you can reference a WebJar asset like:

<link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'>

Using clj-webjars

Alternatively you can use clj-webjars to simplify assets integration. By relying on wrap-webjars ring middleware you can reference a WebJar asset like:

<link rel='stylesheet' href='assets/css/bootstrap.min.css'>

The right asset will be transparently accessed and served with proper HTTP caching behavior.

Instructions for Dandelion

When writing bundles, you can configure assets to be fetched from multiple locations: webapp, classpath and more.

Dandelion also provides a WebJars integration via a dedicated locator for WebJars.

First, you have to add dandelion-webjars as dependency to your application in the pom.xml file:

<dependencies>
    <dependency>
        <groupId>com.github.dandelion</groupId>
        <artifactId>dandelion-webjars</artifactId>
        <version>1.1.0</version>
    </dependency>
</dependencies>

And a WebJar dependency like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>jquery</artifactId>
        <version>1.11.3</version>
    </dependency>
</dependencies>

Then, in your bundle definition, configure the asset as follows:

{
    "assets": [
        {
            "version": "1.11.3",
            "locations": {
                "webjar": "jquery.js"
            }
        }
    ]
}

Dandelion will finally generate the following client-side HTML markup:

<script src="/[contextPath]/webjars/jquery/1.11.3/jquery.js"></script>

A sample application is available here .

Instructions for Vert.x Web

The Vert.x Web StaticHandler can resolve file paths from both the filesystem and the classpath. Therefore, it requires very little configuration to serve assets packaged in a WebJar.

Maven Example

First add a WebJar as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.1.0</version>
    </dependency>
</dependencies>

In your code, create a StaticHandler and assign it to a Route:

Router router = Router.router(vertx);
router.route("/assets/lib/*").handler(StaticHandler.create("META-INF/resources/webjars"));

Then simply reference the resource like:

<link rel='stylesheet' href='assets/lib/bootstrap/3.1.0/css/bootstrap.min.css'>

Instructions for Quarkus

Quarkus support the use of WebJars by default and also adds a WebJar Locator to reference WebJars without the version.

Maven Example

First add a WebJar as a dependency of your application in the pom.xml file, like:

<dependencies>
    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>bootstrap</artifactId>
        <version>3.1.0</version>
    </dependency>
</dependencies>

Then simply reference the resource like:

<link rel='stylesheet' href='/webjars/bootstrap/3.1.0/css/bootstrap.min.css'>

Maven Example with locator

If you also want to use the locator, also add this to your pom.xml file:

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-webjars-locator</artifactId>>
    </dependency>
</dependencies>

Now you can reference the resource without the version:

<link rel='stylesheet' href='/webjars/bootstrap/css/bootstrap.min.css'>

Instructions for Ktor (Sample Source)

Add the webjars-locator-lite dependency, i.e. in Gradle:

implementation("org.webjars:webjars-locator-lite:0.0.4")

Add your WebJars, i.e. in Gradle:

runtimeOnly("org.webjars:bootstrap:5.3.2")

Define a routing path, an extension function that handles route resolution with the locator, create a shared / singleton instance of the locator, and configure the routing:

val WEBJARS_PATH = "/webjars"
fun WebJarVersionLocator.route(webJar: String, path: String) = run {
    path(webJar, path)?.let {
        "$WEBJARS_PATH/$it"
    }
}
val server = embeddedServer(CIO, port = 8080) {
    val webJarVersionLocator = WebJarVersionLocator()
    install(CallLogging)
    routing {
        staticResources(WEBJARS_PATH, "META-INF/resources/webjars")
        // other routes
    }
}

Use the webjarVersionLocator i.e. in kotlinx.html:

link(webJarVersionLocator.route("bootstrap", "css/bootstrap.min.css"), rel = "stylesheet")