1 | [![Build Status](https://travis-ci.org/Polymer/polymer-cli.svg?branch=master)](https://travis-ci.org/Polymer/polymer-cli)
|
2 | [![Build status](https://ci.appveyor.com/api/projects/status/3xc7rkapu39rw9fs/branch/master?svg=true)](https://ci.appveyor.com/project/justinfagnani/polymer-cli/branch/master)
|
3 | [![NPM version](http://img.shields.io/npm/v/polymer-cli.svg)](https://www.npmjs.com/package/polymer-cli)
|
4 |
|
5 | # Polymer CLI
|
6 |
|
7 | The command-line tool for Polymer projects and Web Components.
|
8 |
|
9 | ## Features
|
10 |
|
11 | - **init** - Create a new Polymer project from pre-configured starter templates
|
12 | - **install** - Install dependencies and [dependency variants](https://www.polymer-project.org/2.0/docs/glossary#dependency-variants) via Bower
|
13 | - **serve** - Serve elements and applications during development
|
14 | - **lint** - Lint a project to find and diagnose errors quickly
|
15 | - **test** - Test your project with [`web-component-tester`](https://github.com/Polymer/web-component-tester/)
|
16 | - **build** - Build an application optimized for production
|
17 | - **analyze** - Generate an analyzed JSON representation of your element or application
|
18 |
|
19 | > **For a detailed overview of the CLI, how it works and when to use it, check out the official
|
20 | [Polymer CLI guide](https://www.polymer-project.org/2.0/docs/tools/polymer-cli).**
|
21 | > This README will focus on the individual CLI commands and how to run them.
|
22 |
|
23 |
|
24 | ## Installation
|
25 |
|
26 | ```bash
|
27 | $ yarn global add polymer-cli
|
28 | # or...
|
29 | $ npm install -g polymer-cli
|
30 | ```
|
31 |
|
32 | For best results and a faster installation, we recommend installing with [yarn](https://yarnpkg.com/en/).
|
33 |
|
34 | ## Configuration
|
35 |
|
36 | No configuration is required to use the Polymer CLI to develop a standalone element.
|
37 |
|
38 | When developing a web application, defining some configuration is recommended. Simple applications may work with the CLI's default settings, but following the [Application Shell Architecture](https://developers.google.com/web/updates/2015/11/app-shell) for your app and manually defining an application shell and fragments will give you the best performance in production.
|
39 |
|
40 | Here's a brief summary of the configuration options you can use to describe your web application structure:
|
41 |
|
42 | - [`entrypoint`](https://www.polymer-project.org/2.0/docs/tools/polymer-json#entrypoint) (Defaults to `index.html`): The main entrypoint to your app.
|
43 | - [`shell`](https://www.polymer-project.org/2.0/docs/tools/polymer-json#shell) (Optional): The app shell.
|
44 | - [`fragments`](https://www.polymer-project.org/2.0/docs/tools/polymer-json#fragments) (Optional): A list of other entrypoints into your application.
|
45 | - `root` (Defaults to current working directory): The web root of your application, can be a subfolder of your project directory.
|
46 | - `sources` (Defaults to `src/**/*`): The source files in your application.
|
47 |
|
48 | Configuration can be passed to all commands via global CLI flags: `--entrypoint`, `--shell`, etc. However we recommend saving your configuration to a `polymer.json` configuration file in your project. This guarantees a single shared configuration that will be read automatically for every command. Other project settings, like build and lint rules, can also be defined here.
|
49 |
|
50 | Read the [polymer.json spec](https://www.polymer-project.org/2.0/docs/tools/polymer-json) for a full list of all supported fields with examples.
|
51 |
|
52 |
|
53 | ## Command Overview
|
54 |
|
55 | ### `polymer help [COMMAND]`
|
56 |
|
57 | Run `polymer help` to get a helpful list of supported commands. Pass it a command name (ex: `polymer help serve`) to get detailed information about that command and the options it supports.
|
58 |
|
59 |
|
60 | ### `polymer init [TEMPLATE]`
|
61 |
|
62 | Initializes a Polymer project from one of several templates. Pre-bundled templates range from just bare-bones to fully featured applications like the [Polymer Starter Kit](https://github.com/Polymer/polymer-starter-kit).
|
63 |
|
64 | You can download and run templates built by our community as well. [Search npm](https://www.npmjs.com/search?q=generator-polymer-init) for a template you'd like to use. Then install it and the CLI will pick it up automatically.
|
65 |
|
66 | Run `polymer init` to choose a template from a list of all installed templates. Or, if you know the template name before hand, you can provide it as a command argument to select it automatically.
|
67 |
|
68 |
|
69 | ### `polymer install [--variants]`
|
70 |
|
71 | Installs your dependencies from Bower or npm.
|
72 |
|
73 | If the `--variants` option is provided, the command will also search your project's `bower.json` for a `"variants"` property and install any dependency variants listed there. [Dependency variants](https://www.polymer-project.org/2.0/docs/glossary#dependency-variants) describe alternative sets of dependencies to install alongside your normal `bower_components/` folder. Other CLI commands like `polymer test` and `polymer serve` are able to read these alternative dependency sets and test/serve them in parallel. This is especially useful if you need to test your elements against multiple versions of Polymer and/or other dependencies.
|
74 |
|
75 | By default, `polymer install` installs dependencies from Bower, similar to running `bower install`. If the `--npm` option is provided or `"npm": true` is specified in your `polymer.json`, then this command is equivalent to running `npm install`.
|
76 |
|
77 |
|
78 | ### `polymer serve [options...]`
|
79 |
|
80 | Start a development server designed for serving Polymer & Web Component projects. Applications are served as-is, while elements are served from a special route where it can properly reference its dependencies.
|
81 |
|
82 | By default, the server will automatically use [Babel](https://babeljs.io) to transpile any ES6 code down to ES5 for browsers that don't have native support for important ES6 features like classes. This behavior can be explicitly turned on/off for all browsers via the `--compile` option.
|
83 |
|
84 | Run `polymer help serve` for the full list of available options.
|
85 |
|
86 |
|
87 | ### `polymer lint [--rules RULE_SET] [options...]`
|
88 |
|
89 | Lint your project for common errors. Specify a set of linting rules via the `--rules` command option or your `polymer.json` configuration. To make sure you always use the correct rule set, we recommend adding a "lint" section to your polymer.json like so:
|
90 |
|
91 | ```json
|
92 | "lint": {
|
93 | "rules": [
|
94 | "polymer-2-hybrid"
|
95 | ]
|
96 | },
|
97 | ```
|
98 |
|
99 | Run `polymer help lint` for the full list of available options and rule sets.
|
100 |
|
101 |
|
102 | ### `polymer test [options...]`
|
103 |
|
104 | Run your element or application tests with [`web-component-tester`](https://github.com/Polymer/web-component-tester/).
|
105 |
|
106 | Run `polymer help test` for the full list of available options.
|
107 |
|
108 |
|
109 | ### `polymer build [options...]`
|
110 |
|
111 | Build a Polymer application for production. This includes support for optimizations like code bundling, minification, and ES6 compilation to run on older browsers.
|
112 |
|
113 | Most optimizations are disabled by default. To make sure the correct build enhancements are always used, you can provide a set of build configurations via the ["builds"](https://www.polymer-project.org/2.0/docs/tools/polymer-json#builds) field of your `polymer.json` file:
|
114 |
|
115 | ```json
|
116 | "builds": [{
|
117 | "bundle": true,
|
118 | "js": {"minify": true},
|
119 | "css": {"minify": true},
|
120 | "html": {"minify": true}
|
121 | }],
|
122 | ```
|
123 |
|
124 | Run `polymer help build` for the full list of available options & optimizations.
|
125 |
|
126 | If you need support for something that is missing from the CLI, check out the [polymer-build](https://github.com/Polymer/polymer-build) library. Is the JS library that powers the CLI, and calling it directly gives you much greater control than the CLI can provide. Visit the repo for usage information and examples.
|
127 |
|
128 |
|
129 | ### `polymer analyze [files...]`
|
130 |
|
131 | Generates an analyzed JSON representation of your element or project. This can be useful if you are working with other tooling that requires a cached analysis of your project.
|
132 |
|
133 | Run `polymer help analyze` for the full list of available options.
|
134 |
|
135 |
|
136 | ## Supported Node.js Versions
|
137 |
|
138 | Polymer CLI supports the [current & active LTS versions](https://github.com/nodejs/LTS) of Node.js and later. See the [Polymer Tools Node.js Support Policy](https://www.polymer-project.org/2.0/docs/tools/node-support) for more information.
|
139 |
|
140 | ## Compiling from Source
|
141 |
|
142 | You can compile and run the CLI from source by cloning the repo from Github and then running `npm run build`. But make sure you have already run `npm install` before building.
|
143 |
|
144 | ```bash
|
145 | # clone the repo from github
|
146 | yarn install
|
147 | yarn run build
|
148 | yarn link # link your local copy of the CLI to your terminal path
|
149 | ```
|
150 |
|
151 |
|