The Polymer library is in maintenance mode. For new development, we recommend Lit.

Create a polymer.json file in your top-level project folder to configure the behavior of Polymer CLI tools for your Polymer project. See the Polymer 3.0 Sample App for a working example.

Example

{
  "root": "~/projects/my-project",
  "entrypoint": "index.html",
  "shell": "src/my-project.js",
  "fragments": [
    "src/lazy-element.js"
  ],
  "sources": [
   "src/my-project.js",
   "manifest/**",
   "package.json"
  ],
  "extraDependencies": [
    "manifest.json",
    "node_modules/@webcomponents/webcomponentsjs/**"
  ],
  "moduleResolution": "node",
  "npm": true,
  "builds": [
    { 
      "name": "es5prod",
      "preset": "es5-bundled",
      "addServiceWorker": true
    },
    { 
      "name": "es6prod",
      "preset": "es6-unbundled",
      "addServiceWorker": true
    },
    { 
      "name": "dev",
      "addServiceWorker": false,
      "js": {"minify": false, "compile": false},
      "css": {"minify": false},
      "html": {"minify": false},
      "bundle": false,
      "addPushManifest": false
    }
  ]
}

This page defines the available configuration options for polymer.json, and describes how to set them.

  • root. Specify the path to the root project folder.
  • entrypoint. Specify the file that imports the app shell.
  • shell. Specify the app shell.
  • fragments. Specify your project's dynamic dependencies.
  • sources. Specify your app's source files and folders.
  • extraDependencies. Specify undiscoverable dependencies that won't be bundled.
  • builds. Configure one or more builds for your project.
  • autoBasePath. Set the base path for each build to its name.
  • lint. Configure lint warnings.
  • npm. Specify whether to use the node_modules folder as the componentDir option.
  • componentDir. Specify the folder in which web components are located.
  • moduleResolution. Use Node.js-style module resolution to convert package names to paths.

Optional string.

"root": "myfolder"
"root": "/full/path/to/myfolder"

The path to the root project folder. This can be an absolute path, or a path relative to the current working directory. Defaults to the current working directory.

Optional string.

"entrypoint": "index.html"

The main entrypoint to your app for all routes, often index.html. This file should import the app shell file specified in the shell property. It should be as small as possible since it’s served for all routes.

Required string.

"shell": "my-app.js"

The app shell. Contains the main code that boots the app and loads necessary resources. The shell usually includes the common UI for the app, and the router, which loads resources needed for the current route.

Optional array of strings.

"fragments": [
  "src/shop-list.js",
  "src/shop-detail.js",
  "src/shop-cart.js",
  "src/shop-checkout.js",
  "src/lazy-resources.js"
]

This property supports dynamic dependencies. It is an array of any JavaScript filenames that are not statically imported from the app shell.

If a fragment has static dependencies, provided the fragment is defined in this property, the Polymer build analyzer will find them. You only need to list the dynamic import.

In a Polymer app, the files listed in the fragments property usually contain one or more element definitions that may or may not be required during the user’s interaction with the app,and can thus be lazily loaded.

Optional array of strings. Defaults to ["src/**/*"].

"sources": [
  "data/**/*",
  "images/**/*",
  "src/**/*",
  "bower.json"
]

An optional array of globs matching your application source files. If left out, defaults to all files in your project src/ directory. You’ll need to set this if you store your source files in other locations.

Optional array of strings.

"extraDependencies": [
  "manifest.json",
  "node_modules/@webcomponentsjs/**"
],

Dependencies that the analyzer component of the Polymer build toolchain can’t discover, possibly because they're not statically imported, and that do not need to be bundled.

Optional array of build configuration objects.

Use the builds array to configure one or more builds to be generated by the polymer build command.

"builds": [
  {
    "preset": "es5-bundled",
    "name": "mybuildname",       
    "basePath": "somethingelse", 
    "browserCapabilities": ["es2015", "push"],
    "addServiceWorker": true, 
    "addPushManifest": true,  
    "swPrecacheConfig": "sw-precache-config.js", 
    "insertPrefetchLinks": true,
    "bundle": {             
      "exclude": ["path/to/file.js", "..." ], 
      "inlineCss": true,          
      "inlineScripts": true,      
      "rewriteUrlsInTemplates": true, 
      "sourcemaps": true,     
      "stripComments": true,    
    },
    "html": {            
      "minify": {        
        "exclude": ["path/to/file.html", "..." ]
      }
    },
    "css": {              
      "minify": {       
        "exclude": ["path/to/file.css", "..." ]
      }
    },
    "js": {              
      "minify": {         
        "exclude": ["path/to/file.js", "..." ]   
      },
      "compile": {        
        "exclude": ["path/to/file.js", "..." ]   
      }
    }
  },
  { 
    "name": "buildname",
     ... 
  }, 
  { 
    "name": "buildname",
     ... 
  }
]

Optional string.

"builds": [
  { "preset": "es5-bundled" }
]

Use build presets to easily create a build from a set of predefined options. We currently have presets for es5-bundled, es6-bundled and es6-unbundled builds.

The following example uses presets to generate two builds (es5-bundled and es6-bundled):

...
  "builds": [
    { "preset": "es5-bundled" }, 
    { "preset": "es6-unbundled" }
  ],
...

The presets are equivalent to the following build configurations:

es5-bundled

{
  "name": "es5-bundled",
  "js": {"minify": true, "compile": true},
  "css": {"minify": true},
  "html": {"minify": true},
  "bundle": true,
  "addServiceWorker": true,
  "addPushManifest": false,
}

es6-bundled

{
  "name": "es6-bundled",
  "browserCapabilities": ["es2015"],
  "js": {"minify": true, "compile": false},
  "css": {"minify": true},
  "html": {"minify": true},
  "bundle": true,
  "addServiceWorker": true,
  "addPushManifest": false,
}

es6-unbundled

{
  "name": "es6-unbundled",
  "browserCapabilities": ["es2015", "push"],
  "js": {"minify": true, "compile": false},
  "css": {"minify": true},
  "html": {"minify": true},
  "bundle": false,
  "addServiceWorker": true,
  "addPushManifest": true,
}

If you supply additional options for a build that inherits a preset, your options will override the preset's. For example, the following build configuration inherits all options from es5-bundled, but overrides addServiceWorker to false:

"builds": [{
  "preset": "es5-bundled",
  "addServiceWorker": false
}]
"builds": [{
  "name": "mybuildname",       
  "basePath": true,  
  "browserCapabilities": ["es2015", "push"]
}]

Optional string.

"name": "mybuildname"

An optional name for your build. If multiple builds are defined, the name property is required.

Optional string.

To set <base href="buildname">:

"basePath": true

To set <base href="some/other/path">:

"basePath": "some/other/path"

Update the entrypoint's <base> tag to support serving this build from a non-root path, such as when performing differential serving based on user agent. Requires that a <base> tag already exists.

If true, use the name property for the corresponding build configuration in the builds array. If a string, use that value. Leading and trailing slashes are optional.

Note that basePath must be set to true if using prpl-server.

You can automatically set basePath to true for all build configurations in the builds array by setting the top-level autoBasePath option to true.

Optional array of strings.

"browserCapabilities": ["es2015", "push", "serviceworker"]

Denotes the capabilities required for a browser to consume this build. Values are es2015, push and serviceworker. For more information, see the prpl-server-node README.

"builds": [{
  ...
  "addServiceWorker": true, 
  "addPushManifest": true,   
  "swPrecacheConfig": "sw-precache-config.js", 
  "insertPrefetchLinks": true
  ...
}]

Optional boolean.

"addServiceWorker": true

If true, generate a service worker for your application.

Optional boolean.

"addPushManifest": true

If true, generate an HTTP/2 Push Manifest for your application.

Optional string.

"swPrecacheConfig": "sw-precache-config.js"

An optional configuration file for the generated service worker. Defaults to sw-precache-config.js.

Optional boolean.

"insertPrefetchLinks": true,

If true, insert prefetch link elements into your fragments so that all dependencies are prefetched immediately.

Optional object.

"builds": [{
  ...
  "bundle": {             
    "exclude": ["path/to/file.js", "..." ], 
    "inlineCss": true,          
    "inlineScripts": true,       
    "rewriteUrlsInTemplates": true, 
    "sourcemaps": true,          
    "stripComments": true,   
  }
  ...
}]
  • exclude: A list of paths of files and/or folders that should not be inlined.

    "exclude": [ "path/to/file.js", "path" ]
    
  • inlineCss: If true, inline external CSS file contents into <style> tags.

    "inlineCss": true 
    
  • inlineScripts: If true, inline external Javascript file contents into <script> tags.

    "inlineScripts": true 
    
  • rewriteUrlsInTemplates: If true, rewrite URLs in element attributes and style tags inside templates when inlining html.

    "rewriteUrlsInTemplates": true 
    

    Defaults to false for Polymer 3.x and Polymer 2.x; for Polymer 1.x, or where the Polymer CLI can't identify the version you're using, rewriteUrlsInTemplates defaults to true.

    URLs in element attributes and style tags inside templates are not re-written in Polymer 3.x. URLs in attributes and styles inside element templates should be bound using importPath or rootPath where appropriate. See the documentation on URLs in DOM templates for more information.

  • sourcemaps: Create identity source maps for inline scripts.

    "sourcemaps": true 
    
  • stripComments: Remove all comments except those tagged @license, or starting with <!--! or <!--#.

    "stripComments": true 
    
"builds": [
  {
    ...
    "html": {            
      "minify": { 
        "exclude": ["path/to/file.html", "..." ] 
      }
    },
    "css": {              
      "minify": true
    },
    "js": {
      "minify": {         
        "exclude": ["path/to/file.js", "..." ]   
      },
      "compile": {      
        "exclude": ["path/to/file.js", "..." ]   
      }
    }
    ...
  }
]
  • html: An object containing a configuration option for HTML:

    • minify: If true, minify all HTML.
  • css: An object containing a configuration option for CSS:

    • minify: If true, minify all CSS.
  • js: An object containing configuration options for Javascript:

    • minify: If true, minify all JS.
    • compile: If true, use babel to compile all ES6 JS down to ES5.

Optional boolean.

"autoBasePath": true

Set the basePath property to true for all build configurations in the builds array.

Optional object.

"lint": {
  "rules": ["polymer-2"],
  "ignoreWarnings": []
}

Use the lint property to control the warnings you receive from polymer lint, and from polymer-lint when run from the command line or used by an IDE plugin.

Optional array of strings.

"lint": {
  "rules": ["polymer-2"]
}

rules is an array of linting rules and/or rule collections.

Most projects will use one of the following rule collections:

"lint": {
  "rules": ["polymer-2"]
}
"lint": {
  "rules": ["polymer-2-hybrid"]
}
"lint": {
  "rules": ["polymer-1"]
}

To receive warnings for specific instances of bad syntax, add the relevant rule to the rules array. For example, the following configuration warns for:

  • Data bindings that use undeclared properties, and
  • Callback overrides that fail to call the superclass callback.
"lint": {
  "rules": ["databind-with-unknown-property", "call-super-in-callbacks"]
}

For a full list of available rules and rule collections, run polymer help lint from the command line.

Optional array of strings.

To ignore a warning, add it to the ignoreWarnings array. For example, the following configuration warns for bad Polymer 2.x syntax, but ignores code that sets undeclared properties or attributes in HTML:

"lint": {
  "rules": ["polymer-2"],
  "ignoreWarnings": ["set-unknown-attribute"]
}

For a full list of available rules, run polymer help lint from the command line.

Optional boolean.

"npm": true

When true, tells the build process to look for components in node_modules.

Optional string.

"componentDir": "path/to/components"

The folder containing this project's components. When the npm option is set to true, this option is automatically set to the node_modules folder.

Optional string. Defaults to "none".

Defines how to resolve module specifiers in import and export statements when rewriting them to be web-compatible.

To disable module specifier rewriting:

"moduleResolution": "none"

To use Node.js resolution to find modules:

"moduleResolution": "node"