This section shows you how to start an element project.
Create a directory for your element project. For projects with a single element, it's common to name the project directory to match the element name.
mkdir my-el && cd my-el
my-elis the name of the element you're creating.
Initialize your element. Polymer CLI asks you a few questions as it sets up your element project.
Enter a name for your element.
The custom elements specification requires the element name to contain a dash.
Enter a description of the element.
At this point, Polymer CLI generates files and directories for your element, and installs your project's dependencies.
Element project layout
After the initialization process Polymer CLI generates the following files and directories.
bower.json. Configuration file for Bower.
bower_components/. Project dependencies. See Manage dependencies.
demo/index.html. Demo of
index.html. Automatically-generated API reference.
.html. Element source code.
_test.html. Unit tests for the element.
Manage dependencies and HTML imports
Use Bower to manage dependencies
Polymer CLI uses Bower for dependency management.
Dependencies are stored in the
bower_components directory. You should never manually alter the
contents of this directory.
Use the Bower CLI to manage dependencies.
To download a dependency to
--save flag saves the new
bower install --save PolymerElements/iron-ajax
To remove the dependency from
bower uninstall PolymerElements/iron-ajax
Import dependencies as relative URLs
When importing dependencies inside your element, you should always use a relative URL as if the dependency is a sibling of your project.
<!-- from a top-level 'some-element.html' --> <link rel="import" href="../polymer/polymer.html"> <link rel="import" href="../paper-elements/paper-button.html">
Why use relative URLs?
Suppose that you ran Polymer CLI to generate an element project. Your element is named
You look inside
my-el.html and see that Polymer has been imported like so:
<link rel="import" href="../polymer/polymer.html">
This path doesn't make sense. Relative to
my-el.html, Polymer is actually located at
bower_components/polymer/polymer.html. Whereas the HTML import above is referencing a location
outside of your element project. What's going on?
Bower installs dependencies in a flat dependency tree, like so:
bower_components/ polymer/ polymer.html my-el/ my-el.html other-el/ other-el.html
This works well on the application-level. All elements are siblings, so they can all reliably
import each other using relative paths like
../polymer/polymer.html. This is why Polymer CLI
uses relative paths when initializing your element project.
However, one problem with this approach is that this structure does not actually match the layout in your element project. Your element project is actually laid out like so:
bower_components/ polymer/ polymer.html my-el.html
Polymer CLI handles this by remapping paths. When you run
polymer serve, all elements in
bower_components are remapped to appear to be in sibling directories relative to
current element is served from the made-up path of
bower name is the
name field from your element project's