Yeoman generator for Polymer projects
Introduction
Polymer is a library of polyfills and sugar which enable the use of Web Components in modern browsers. The project allows developers to build apps using the platform of tomorrow and inform the W3C of places where in-flight specifications can be further improved.
generator-polymer provides Polymer scaffolding using Yeoman (a scaffolding tool for the web), letting you easily create and customize Polymer (custom) elements via the command-line and import them using HTML Imports. This saves you time writing boilerplate code so you can start writing up the logic to your components straight away.
Features
- A Polymer app scaffold built with HTML5 Boilerplate
- Sub-generator to create Polymer elements for your app
- Boilerplate to create reusable Polymer elements
- Quick deploy to GitHub pages
- All the goodness of
seed-element(docs & landing page for your element) - Support for SASS/SCSS and Autoprefixer
- PageSpeed Insights for performance tuning
- web-component-tester support
Installation
Install the generator
npm install -g generator-polymer
Make a new directory and cd into it
mkdir -p my-project && cd $_
Scaffold a new Polymer project:
yo polymer
Generators
Available generators:
Note: Generators are to be run from the root of your app
App
Sets up a new Polymer app, generating all the boilerplate you need to get started.
Example:
yo polymerElement (alias: El)
Generates a polymer element in app/elements and appends an import to app/elements/elements.html.
Example:
yo polymer:element my-element
# or use the alias
yo polymer:el my-elementNote: You must pass in an element name, and the name must contain a dash "-"
One can also include element dependencies to be imported. For instance, if you're creating a fancy-menu element which needs to import core-menu and core-icon-button as dependencies, you can generate the file like so:
yo polymer:el fancy-menu core-menu core-icon-buttonSeed
Generates a reusable polymer element based on the seed-element workflow. This should only be used if you're creating a standalone element repo that you intend to share with others via bower. If you're just building a Polymer app, stick to the Element generator.
The seed-element generator will construct a new element and its directory for you. Be aware: all bower dependencies will be installed as siblings of the newly generated element. Make sure that you generate the seed element within a directory that is intended to contain multiple components!
Example:
mkdir -p components && cd $_
yo polymer:seed x-fooGh
Generates a Github pages branch for your seed-element.
If your documentation or demo pages have dependencies declared as devDependencies in bower.json, they will be included in your GitHub pages branch.
Example:
cd components/x-foo
yo polymer:ghIf, for some reason, you don't want the devDependencies, use the --nodevdeps option.
Testing
The project generated by yo polymer contains support for web-component-tester. The following commands are included:
Run local tests (in terminal):
grunt|gulp test:localRun remote tests with SauceLabs:
grunt|gulp test:remoteSee the web-component-tester readme for configuration options.
Gotchas
The elements.html file
The app generator will produce an elements.html file where you can place your imports. This file will be vulcanized when you run the default grunt or gulp tasks. You'll want to make sure that elements.html is the only import in your index.html file, otherwise there's a good chance you'll accidentally load Polymer twice and break the app.
Autoprefixer and style elements
The Autoprefixer task will not work with style elements mixed into HTML files (it breaks). Meaning, if you drop a style tag inside of your Polymer element, it will not be processed by Autoprefixer. Only external CSS files can/will be processed by Autoprefixer.
Contribute
See the contributing docs
When submitting an issue, please follow the guidelines. Especially important is to make sure Yeoman is up-to-date, and providing the command or commands that cause the issue.