Create an element project with the Polymer CLI

This section shows you how to start an element project.

1. 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

   Where my-el is the name of the element you're creating.

2. Initialize your element. Polymer CLI asks you a few questions as it sets up your element project.

   polymer init
   

3. Select polymer-3-element.

4. Enter a name for your element.

   The custom elements specification requires the element name to contain a dash.

5. 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.

• README.md. Template for a README file.
• demo/index.html. Demo of my-el.html.
• index.html. Automatically-generated API reference.
• my-el.js. Element source code.
• node_modules/. Project dependencies. See Manage dependencies.
• package-lock.json. Automatically generated control file for npm.
• package.json. Configuration file for npm.
• polymer.json. Configuration file for Polymer CLI.
• test/my-el_test.html. Unit tests for the element.

Manage dependencies and JavaScript imports

Use npm to manage dependencies

Polymer CLI uses npm for dependency management.

Dependencies are stored in the node_modules directory. You should never manually alter the contents of this directory.

Use the npm command line tool to manage dependencies.

To download a dependency to node_modules/ (the --save flag saves the new dependency to package.json):

npm install --save @polymer/iron-ajax@next

To remove the dependency from node_modules and package.json:

npm uninstall @polymer/iron-ajax

Import dependencies using module specifiers

Import your dependencies using module specifiers:

src/my-el/my-el.js

import {PolymerElement} from '@polymer/polymer/polymer-element.js';
import '@polymer/paper-button/paper-button.js';
import '../child-el/child-el.js';

• When importing a dependency installed using npm, use the package name, followed by the path to the module.

  In the code above, for example, @polymer/paper-button is the name of a package containing the paper-button module, and paper-button.js is the path to the module inside the package. Polymer CLI rewrites these specifiers to paths when you build your app.

• When importing a local dependency (like child-el.js above), use either a relative path starting with ./ or ../, or an absolute path starting with ... Polymer CLI doesn't rewrite these specifiers.

• If you need to include a module from another site, such as a CDN, use a full URL (e.g. https://unpkg.com/thing@1.0.1/index.js). Polymer CLI doesn't rewrite these specifiers.

See Build for production for more information on how Polymer CLI resolves imports.