Overview

This plugin integrates Autoprefixer with Spincast to easily add vendor prefixes to your CSS.

It allows you to serve CSS that has been tweaked so browsers support is enhanced. For example, you may use this plugin to be able to use CSS Grids with good support for IE11!

Requirements

As you will see in the Installation section, this plugin requires Node.js and three npm libraries to be installed on the environment(s) your Spincast application will run on.

In order to remove the need to install Node, we could have used hacks such as J2V8! But solutions like those always have more issues than "using the real thing" directly. Also, it seems J2V8 may even drop support for Node.js in the near future.

Usage

You inject and use the SpincastCssAutoprefixerManager component to transform your CSS.

Let's say you have a dynamic resource route that serves your CSS files dynamically:

router.dir("/publicdyn/css/*{relativePath}")
      .pathRelative("/publicdyn/css")
      .handle(publicResourcesController::dynCss);

In the "dynCss(...)" handler, you would get the raw content of the CSS file and tweak it using the SpincastCssAutoprefixerManager component before sending it:

File rawCssFile = //... get the raw CSS file

String cssContent = FileUtils.readFileToString(rawCssFile, "UTF-8");

JsonObject options = context.json().create();
options.set("grid", "autoplace");
String cssContentTweaked = getSpincastCssAutoprefixerManager().autoPrefix(cssContent, options);

context.response().sendCharacters(cssContentTweaked, "text/css");

Explanation :

  • 1 : We get the raw CSS file using the "relativePath" path parameter taken from the request. We make sure we validate this user input properly!
  • 3 : We get the raw CSS content.
  • 5-6 : In this example, we add an option in order to tell Autoprefixer that we want to enable support for CSS Grids.
  • 7 : We call the autoPrefix(...) method.
  • 9 : We send the tweaked CSS, using the proper content-type.

Under the hood, another plugin is used, Spincast Process Utils, in order to call the postcss-cli Node program, with Autoprefixer enabled.

SpincastCssAutoprefixerManager methods
The main methods provided by SpincastCssAutoprefixerManager are:
  • String autoPrefix(String cssContent, JsonObject options)

    Run Autoprefixer on the specified CSS content, as a String. Returns the modified CSS.

  • void autoPrefix(File cssFile, JsonObject options)

    Run Autoprefixer on the specified CSS file. The file will be modified and will contain the vendor prefixes.

  • boolean isValidAutoprefixerEnvironment()

    Validate if the current environment has been properly configured for this plugin to work as it should.

Configurations

Most of the possible options are passed inline, when you call autoPrefix(...). Those options are documented here.

There is only one global configuration:

  • String getPostcssExecutableName()

    Allows you to modify the name of the executable the plugin will call.

    By default, it will be "postcss" except on Windows where it will be "postcss.cmd".

    You can specify an absolute path here, but beware that the "autoprefixer" library must still be installed globally or the command run by the plugin will fail.

In your Guice module, you can bind a custom implementation of SpincastCssAutoprefixerConfig in order to change the configuration.

Dependencies

This plugin depends on the Spincast Process Utils plugin which is not provided by default by the spincast-default artifact.

This dependency will be automatically installed. Note that it is always a good idea to read the documentation of the automatically installed plugins.

Installation

1. Make sure Node.js is properly installed on the machine(s) your Spincast application will run on.

2. Install postcss, postcss-cli and autoprefixer, globally, using npm:


npm install -g postcss postcss-cli autoprefixer

3. Add this Maven artifact to your project:

<dependency>
    <groupId>org.spincast</groupId>
    <artifactId>spincast-plugins-css-autoprefixer</artifactId>
    <version>1.14.1</version>
</dependency>

4. Add an instance of the SpincastCssAutoprefixerPlugin plugin to your Spincast Bootstrapper:


Spincast.configure()
        .plugin(new SpincastCssAutoprefixerPlugin())
        // ...