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

Polymer CLI supports initializing a project folder with one of several application templates.
The polymer-3-application template is the most basic starting point for a Polymer-based application. Other templates introduce more complex layout and application patterns.

This chapter teaches you more about the polymer-3-application template.
See Application templates for more details on other templates.

For a more full-featured progressive web app template, you can use the starter kit template (polymer-3-starter-kit). See the Polymer Starter Kit repo for more information.

Follow the steps below to get your basic app project set up.

  1. Create a directory for your app project.

    mkdir app
    cd app

    Where app is the name of your project directory.

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

    polymer init
  3. Select polymer-3-application.

  4. Enter a name for your app. Defaults to the name of the current directory.

  5. Enter a name for the main element in your project. The main element is the top-most, application-level element of your app. Defaults to the name of the current directory, followed by -app.

    The code samples throughout this doc use the example app element name my-app. When creating your app you'll want to replace any instance of my-app with the name of your main element.

  6. Enter a description for your app.

The Polymer CLI generates your app and installs its dependencies.

After creating your app, Polymer CLI generates the following files and directories:

  • Template README file.
  • index.html. Entrypoint page of the app.
  • manifest.json. App manifest. Provides information about your app to the browser.
  • node_modules/. Project dependencies. See Manage dependencies.
  • package-lock.json. Auto-generated file for npm.
  • package.json. Configuration file for npm.
  • polymer.json. Configuration file for Polymer CLI.
  • src/my-app/my-app.js. Source code for main element.
  • test/my-app/my-app_test.html. Tests for main element.

You may want to compose your main element out of smaller elements specific to your app. These application-specific elements should be defined in the src directory, at the same level as my-app.


To add another element to the project:

  1. Create a new folder under src.

    mkdir src/my-el
  2. Create a JavaScript module for the new element. You can use the existing app element as a starting point.

  3. To use the new element, you'll need to import it into your application element (for example, my-app.js) with an "import" statement:

    import 'my-el/my-el.js';

    Don't use polymer init to create an element project inside your app project.

Import your dependencies using module specifiers:

src/my-app/my-app.js {.caption}

import {PolymerElement} from '@polymer/polymer/polymer-element.js';
import '@polymer/paper-button/paper-button.js';
import '../my-el/my-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 my-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. Polymer CLI doesn't rewrite these specifiers.

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