Repository files navigation

A starting point for building web applications with Polymer 1.0

• Polymer,Paper,Iron andNeon elements
• Material Design layout
• Routing withPage.js
• Unit testing withWeb Component Tester
• Optional offline setup throughPlatinum Service Worker elements
• End-to-end Build Tooling (includingVulcanize)
• Recipes for ES2015 support, Polymer performance, using Chrome Dev Editor, Deploying to GitHub Pages, Deploying to Firebase, and Mobile Chrome Apps

See latest Polymer Starter Kit Demo (from master) athttps://polymerelements.github.io/polymer-starter-kit/

Check out the Polymer Starter Kit tutorials onpolymer-project.org:

• Set up the PSK
• Create a page
• Deploy the PSK to the web

To take advantage of Polymer Starter Kit you need to:

1. Get a copy of the code.
2. Install the dependencies if you don't already have them.
3. Modify the application to your liking.
4. Deploy your production code.

Download and extract Polymer Starter Kit to where you want to work. The project comes in two flavours - Light and Full.

Beginners: Try Polymer Starter Kit Light. This doesn't require any extra dependencies nor knowledge of modern front-end tooling. This option is good for prototyping if you haven't build a Polymer app before.

Intermediate - Advanced: Use the full version of Polymer Starter Kit. This comes with all the build tools you'll need for testing and productionising your app so it's nice and lean. You'll need to run a few extra commands to install the tools we recommend but it's worth it to make sure your final app is super optimised.

⚠️Important: Polymer Starter Kit, and Polymer Starter Kit Light, both contain dotfiles (files starting with a.). If you're copying the contents of the Starter Kit to a new location make sure you bring along these dotfiles as well! On Mac,enable showing hidden files, then try extracting/copying Polymer Starter Kit again. This time the dotfiles needed should be visible so you can copy them over without issues.

Rob Dodson has a fantasticPolyCast video available that walks through using Polymer Starter Kit. Anend-to-end with Polymer and Polymer Starter Kit talk is also available.

With Node.js installed, run the following one liner from the root of your Polymer Starter Kit download:

npm install -g gulp bower&& npm install&& bower install

The full starter kit requires the following major dependencies:

• Node.js, used to run JavaScript tools from the command line.
• npm, the node package manager, installed with Node.js and used to install Node.js packages.
• gulp, a Node.js-based build tool.
• bower, a Node.js-based package manager used to install front-end packages (like Polymer).

To install dependencies:

1. Check your Node.js version.

node --version

The version should be at or above 0.12.x.

2. If you don't have Node.js installed, or you have a lower version, go tonodejs.org and click on the big green Install button.

3. Installgulp andbower globally.

npm install -g gulp bower

This lets you rungulp andbower from the command line.

4. Install the starter kit's localnpm andbower dependencies.

cd polymer-starter-kit&& npm install&& bower install

This installs the element sets (Paper, Iron, Platinum) and tools the starter kit requires to build and serve apps.

gulp serve

This outputs an IP address you can use to locally test and another that can be used on devices connected to your network.

gulp test:local

This runs the unit tests defined in theapp/test directory throughweb-component-tester.

To run tests Java 7 or higher is required. To update Java go tohttp://www.oracle.com/technetwork/java/javase/downloads/index.html and downloadJDK and install it.

gulp

Build and optimize the current project, ready for deployment. This includes linting as well as vulcanization, image, script, stylesheet and HTML optimization and minification.

Polymer 1.0 introduces a shim for CSS custom properties. We take advantage of this inapp/styles/app-theme.html to provide theming for your application. You can also find our presets for Material Design breakpoints in this file.

Read more about CSS custom properties.

1. main.css - to define styles that can be applied outside of Polymer's custom CSS properties implementation. Some of the use-cases include defining styles that you want to be applied for a splash screen, styles for your application 'shell' before it gets upgraded using Polymer or critical style blocks that you want parsed before your elements are.
2. app-theme.html - to provide theming for your application. You can also find our presets for Material Design breakpoints in this file.
3. shared-styles.html - to share styles between elements and index.html.
4. element styles only - styles specific to element. These styles should be inside the<style></style> insidetemplate.

<dom-moduleid="my-list"><template><style>:host {        display: block;        background-color: yellow;      }</style><ul><templateis="dom-repeat"items="{{items}}"><li><spanclass="paper-font-body1">{{item}}</span></li></template></ul></template></dom-module>

These style files are located in thestyles folder.

Web apps built with Polymer Starter Kit come configured with support forWeb Component Tester - Polymer's preferred tool for authoring and running unit tests. This makes testing your element based applications a pleasant experience.

Read more about using Web Component tester.

Polymer usesBower for package management. This makes it easy to keep your elements up to date and versioned. For tooling, we use npm to manage Node.js-based dependencies.

Components installed by Bower live in theapp/bower_components directory. This location is specified by the.bowerrc file. Many projects which follow Yeoman conventions place thebower_components directory outside of theapp directory and then mount it using a server. This causes problems for tools likeVulcanize andweb-component-shards which rely on relative paths. We've chosen to simplify things and havebower_components live inside ofapp to resolve these issues.

1. Uncomment this line// app.baseUrl = '/polymer-starter-kit/'; in app.js near the top
2. Changeapp.baseUrl = '/polymer-starter-kit/'; toapp.baseUrl = '/your-pathname/'; (ex: if you repo isgithub.com/username/bobs-awesome-site you would change this tobobs-awesome-site)
3. Rungulp build-deploy-gh-pages from command line
4. To see changes wait 1-2 minutes then load Github pages for your app (ex:https://polymerelements.github.io/polymer-starter-kit/)

See more details

See detail recipe

Polymer Starter Kit offers an optional offline experience thanks to Service Worker and thePlatinum Service Worker elements. New to Service Worker? Read the followingintroduction to understand how it works.

Our optional offline setup should work well for relatively simple applications. For more complex apps, we recommend learning how Service Worker works so that you can make the most of the Platinum Service Worker element abstractions.

To enable Service Worker support for Polymer Starter Kit project use these 3 steps:

1. Uncomment Service Worker code in index.html

<!-- Uncomment next block to enable Service Worker support (1/2) --><!--<paper-toast             duration="6000"             text="Caching complete! This app will work offline."></paper-toast><platinum-sw-register auto-register                      clients-claim                      skip-waiting                      on-service-worker-installed="displayInstalledToast">  <platinum-sw-cache default-cache-strategy="networkFirst"                     cache-config-file="cache-config.json">  </platinum-sw-cache></platinum-sw-register>-->

2. Uncomment Service Worker code in elements.html

<!-- Uncomment next block to enable Service Worker Support (2/2) --><!--<link rel="import" href="../bower_components/platinum-sw/platinum-sw-cache.html"><link rel="import" href="../bower_components/platinum-sw/platinum-sw-register.html">-->

3. Uncomment 'cache-config' in therunSequence() section of the 'default' gulp task, like below:(gulpfile.js)

// Build Production Files, the Default Taskgulp.task('default',['clean'],function(cb){runSequence(['copy','styles'],'elements',['jshint','images','fonts','html'],'vulcanize','cache-config',cb);});

If you experience an issue with Service Worker support in your application, check the origin of the issue and use the appropriate issue tracker:

• sw-toolbox
• platinum-sw
• platinum-push-notifications-manager
• For all other issues, feel free to file themhere.

Service Workers are only available to "secure origins" (HTTPS sites, basically) in line with a policy to prefer secure origins for powerful new features. Howeverhttp://localhost is also considered a secure origin, so if you can, developing on localhost is an easy way to avoid this error. For production, your site will need to support HTTPS.

If you need to debug the event listener wire-up usechrome://serviceworker-internals.

This page shows your registered workers and provides some basic operations.

• Unregister: Unregisters the worker.
• Start: Starts the worker. This would happen automatically when you navigate to a page in the worker's scope.
• Stop: Stops the worker.
• Sync: Dispatches a 'sync' event to the worker. If you don't handle this event, nothing will happen.
• Push: Dispatches a 'push' event to the worker. If you don't handle this event, nothing will happen.
• Inspect: Opens the worker in the Inspector.

In order to guarantee that the latest version of your Service Worker script is being used, follow these instructions:

• After you made changes to your service worker script, close all but one of the tabs pointing to your web application
• Hit shift-reload to bypass the service worker as to ensure that the remaining tab isn't under the control of a service worker
• Hit reload to let the newer version of the Service Worker control the page.

If you find anything to still be stale, you can also try navigating tochrome:serviceworker-internals (in Chrome), finding the relevant Service Worker entry for your application and clicking 'Unregister' before refreshing your app. This will (of course) only clear it from the local development machine. If you have already deployed to production then further work will be necessary to remove it from your user's machines.

If for any reason you need to disable Service Worker support after previously enabling it, you can remove it from your Polymer Starter Kit project using these 4 steps:

1. Remove references to the platinum-sw elements from your applicationindex.
2. Remove the two Platinum Service Worker elements (platinum-sw/..) inapp/elements/elements.html
3. Remove 'precache' from the list in the 'default' gulp task (gulpfile.js)
4. Navigate tochrome://serviceworker-internals and unregister any Service Workers registered by Polymer Starter Kit for your app just in case there's a copy of it cached.

generator-polymer now includes support for Polymer Starter Kit out of the box.

Theming can be achieved usingCSS Custom properties viaapp/styles/app-theme.html.You can also useapp/styles/main.css for pure CSS stylesheets (e.g for global styles), however note that Custom properties will not work there under the shim.

APolycast is also available that walks through theming using Polymer 1.0.

This can be done viaapp/elements/routing.html. We use Page.js for routing and new routescan be defined in this import. We then toggle which<iron-pages> page to display based on theselected route.

<more-routing> (in our opinion) is good, but lacks imperative hooks for getting full controlover the routing in your application. This is one place where a pure JS router shines. We mayat some point switch back to a declarative router when our hook requirements are tackled. Thatsaid, it should be trivial to switch to<more-routing> or another declarative router in yourown local setup.

App layouts live in a separate repository calledapp-layout-templates.You can select a template and copy over the relevant parts you would like to reuse to Polymer Starter Kit.

You will probably need to change paths to where your Iron and Paper dependencies can be found to get everything working.This can be done by adding them to theelements.html import.

Our most commonly reported issue is around system permissions for installing Node.js dependencies.We recommend following thefixing npm permissionsguide to address any messages around administrator permissions being required. If you usesudoto work around these issues, this guide may also be useful for avoiding that.

If you run into an exception that mentions five optional dependencies failing (or anEEXIST error), youmay have run into an npmbug. We recommend updating to npm 2.11.0+to work around this. You can do this by opening a Command Prompt/terminal and runningnpm install npm@2.11.0 -g. If you are on Windows,Node.js (and npm) may have been installed intoC:\Program Files\. Updating npm by runningnpm install npm@2.11.0 -g will install npminto%AppData%\npm, but your system will still use the npm version. You can avoid this by deleting your older npm fromC:\Program Files\nodejsas describedhere.

If the issue is to do with a failure somewhere else, you might find that due to a network issuea dependency failed to correctly install. We recommend runningnpm cache clean and deleting thenode_modules directory followed bynpm install to see if this corrects the problem. If not, please check theissue tracker in casethere is a workaround or fix already posted.

Some Windows users have run into trouble with theelements.html file in theirdist foldernot being correctly vulcanized. This can happen if your project is in a folder with a name containing aspace. You can work around this issue by ensuring your path doesn't contain one.

There is also anin-flight issuewhere some are finding they need to disable theinlineCss option in our configuration for Vulcanizeto correctly build. We are still investigating this, however for the time-being use the workaround ifyou find your builds getting stuck here.

At the bottom ofapp/index.html, you will find a build block that can be used to include additionalscripts for your app. Build blocks are just normal script tags that are wrapped in a HTMLcomment that indicates where to concatenate and minify their final contents to.

Below, we've added inscript2.js andscript3.js to this block. The line<!-- build:js scripts/app.js --> specifies that these scripts will be squashed intoscripts/app.jsduring a build.

<!-- build:js scripts/app.js --><scriptsrc="scripts/app.js"></script><scriptsrc="scripts/script2.js"></script><scriptsrc="scripts/script3.js"></script><!-- endbuild-->

If you are not using the build-blocks, but still wish for additional files (e.g scripts or stylesheets) to be included in the finaldist directory, you will need to either copy these files as part of the gulpfile.js build process (see thecopy task for how to automate this) or manually copy the files.

Don't worry! We've got your covered. Polymer Starter Kit tries to offer everything you need to build and optimize your apps for production, which is why we include the tooling we do. We realise however that our tooling setup may not be for everyone.

If you find that you just want the simplest setup possible, we recommend using Polymer Starter Kit light, which is available from theReleases page. This takes next to no time to setup.

Like other Google projects, Polymer Starter Kit includes Google license headers at the top of several of our source files. Google's open-source licensing requires that this header be kept in place (sorry!), however we acknowledge that you may need to add your own licensing to files you modify. This can be done by appending your own extensions to these headers.

Polymer Starter Kit is a new project and is an ongoing effort by the Web Component community. We welcome your bug reports, PRs for improvements, docs and anything you think would improve the experience for other Polymer developers.