Skip to content

Latest commit

 

History

History
130 lines (116 loc) · 3.59 KB

README.md

File metadata and controls

130 lines (116 loc) · 3.59 KB
Raw

Polyfill Service Java API

Table of Content

Usage

Setup

Include dependency in pom.xml

<dependency>
    <groupId>org.polyfillservice</groupId>
    <artifactId>polyfill-service-api</artifactId>
    <version>${polyfillServiceVersion}</version>
</dependency>

First, import Spring configuration to let Spring bootstraps the API. This can be done inside any spring bean, preferably in a @Configuration class.

@Import(PolyfillApiConfig.class)

// bean to specify path to custom service configurations
// can specify which polyfills to serve, etc.
// see below for how to write this file
// You may also implement your own PolyfillServiceConfigLocation
@Bean
public PolyfillServiceConfigLocation serviceConfigLocation() {
    return new PolyfillServiceConfigLocation(new File("path/to/service-config.xml"));
}

Configurations

Polyfill Service provides some options to customize the behavior of loading and fetching polyfills.

  • minified (default: true)
    • whether to minify polyfills
  • gated (default: true)
    • whether to gate polyfill with if (polyfill exists)
    • can be global or specific to a polyfill
  • load-on-unknown-ua (default: true)
    • whether to load polyfills when user agent is unknown
  • debug-mode (default: false)
    • whether to prepend polyfills with debug info
  • polyfills
    • when specified, only these polyfills are loaded into memory for fetching, including their dependencies
      • these are also the polyfills to fetch when no Query object is supplied
    • can be alias group like es6 that contains multiple polyfills

e.g.

<?xml version="1.0" encoding="UTF-8"?>
<configurations>
    <gated>true</gated>
    <minify>true</minify>
    <load-on-unknown-ua>true</load-on-unknown-ua>
    <debug-mode>true</debug-mode>

    <polyfills>
        <polyfill>es6</polyfill>
        <polyfill>Element.prototype.classList</polyfill>
        <polyfill>Element.prototype.cloneNode</polyfill>
    </polyfills>
</configurations>

Fetching polyfills

@Autowired
PolyfillService polyfillService;
...
// fetch with a user agent string and an optional query config object
// without query object, it will load all the polyfills
// or the polyfills defined in service config
// filtered by the user agent string
String output = polyfillService.getPolyfillsSource(userAgentString);

Custom Polyfill Location

Polyfill Structure

resources
- custom_polyfills
    - MyPolyfill
        - meta.json
        - min.js
        - raw.js

meta.json Example

{
  "browsers": {
    "android": "* - 4.4",
    "bb": "* - 10",
    "chrome": "* - 31",
    "firefox": "6 - 28",
    "ie": "8 - 12",
    "ie_mob": "*",
    "ios_saf": "* - 7.1",
    "op_mini": "*",
    "opera": "* - 19",
    "safari": "* - 7",
    "firefox_mob": "6 - 28"
  },
  "dependencies": ["setImmediate", "Array.isArray", "Event"],
  "license": "MIT",
  "detectSource": "'Promise' in this",
  "baseDir": "Promise"
}

Polyfill Service Hook

@Bean
public PolyfillLocation location() {
    return PolyfillLocationString("custom_polyfills");
}

If custom polyfills already exist in Polyfill Service, it will be replaced by your polyfills. The existing aliases will also apply to your custom polyfills. However, note that we don't support custom alias as of now.