A starting point for building web applications with Polymer 1.0
- Polymer, Paper, Iron and Neon elements
- Material Design layout
- Routing with Page.js
- Unit testing with Web Component Tester
- Optional offline setup through Platinum Service Worker elements
- End-to-end Build Tooling (including Vulcanize)
Polymer Starter Kitを利用するには次のようにする必要があります:
- コードを取得します。
- インストールされていない場合は、依存するライブラリをインストールします。
- アプリケーションを変更します。
- プロダクションコードをデプロイします。
こちら Download からダウンロードします。
スタンダードバージョンのPolymer Starter Kit はPolymerのアプリケーション開発をする際に非常に便利なツールが付属しています。新規にツールをインストールせずに始めたい場合は、Releases ページの Polymer Starter Kit Light を見てみてください。
Node.jsをインストールした状態で、Polymer Starter Kitのルートディレクトリで下記を実行します。
npm install -g gulp bower && npm install && bower installStarter Kitは下記のメジャーなソフトウェアが必要です:
- Node.js, コマンドラインからのJavaScriptツールの実行に使用されます。
- npm, Node.jsのパッケージマネージャーです。Node.jsと共にインストールされパッケージのインストールに使用されます。
- gulp, Node.jsベースのビルドツールです。
- bower, Node.jsベースのパッケージマネージャでPolymerのようなフロントエンドのパッケージインストールに使用されます。
依存のインストール:
- Node.jsのバージョンをチェックします。
node --versionバージョンは0.12.xかそれ以上である必要があります。
2 Node.jsがインストールされていない、または下位バージョンがインストールされている場合は, nodejs.orgへ行き、インストールボタンをクリックしてください。
gulpとbowerをグローバルインストールします。
npm install -g gulp bowerこれで、コマンドラインから gulp と bower が実行出来るようになります。
- Starter Kitの
npmとbower依存をインストールします。
cd polymer-starter-kit && npm install && bower installこれはPaper, Iron, Platinumのエレメントセットや、アプリケーションのビルドに必要なツールをインストールします。
gulp serveこれはローカルや、ネットワークに接続されたデバイス上でテストするためのIPアドレスを出力します。
gulp test:localweb-component-testerを利用し、app/test ディレクトリにあるユニットテストを実行します。
テストの事項には、Java 7かそれ以上のバージョンのJavaがインストールされている必要があります。 アップデートするには、http://www.oracle.com/technetwork/java/javase/downloads/index.htmlへ行き、 JDK をダウンロードしてインストールしてください。
gulp現在のプロジェクトをビルド、最適化し、デプロイの準備を行います。これはvulcanization(加硫)、画像、スクリプト、スタイルシートやHTMLの最適化や縮小などを含みます。
Polymer 1.0では、CSSのカスタムプロパティのためのシムがあります。アプリケーションのテーマのカスタマイズを、app/styles/app-theme.html で行っています。また、私たちのMaterial Designのプリセットを見ることが出来ます。
CSSのカスタムプロパティについての詳細は、こちらRead more
- main.css - PolymerのカスタムCSSプロパティの実装の外にも適用することができるスタイルを定義します。 ユースケースとしては、スプラッシュスクリーンやPolymerでアップグレードされる前のアプリケーション 'シェル' 、エレメントがパースされるまえのクリティカルなスタイルブロック等があります。
- app-theme.html - アプリケーション全体のテーマを設定できます。 また、私たちのMaterial Designのプリセットを見ることが出来ます。
- shared-styles.html - エレメントとindex.html間のスタイル共有のためのファイルです。
- element styles only - エレメントへのスタイルファイルです。スタイル設定は
templateの<style></style>タグの中に定義されている必要があります。
<dom-module id="my-list">
<template>
<style>
:host {
display: block;
background-color: yellow;
}
</style>
<ul>
<template is="dom-repeat" items="{{items}}">
<li><span class="paper-font-body1">{{item}}</span></li>
</template>
</ul>
</template>
</dom-module>これらのスタイルファイルは、 styles folder にあります。
Polymer Starter KitでビルドされたWebアプリケーションは Web Component Testerがサポートされています。 Web Component Testerは、オーサリングとユニットテスト実行のためのPolymer推奨のツールです。これはエレメントベースのアプリケーションのテストに良い経験となるでしょう。
Web Component testerについてはこちら Read more
Polymerはパッケージ管理に Bower を使用します。これによって簡単にエレメントを更新したり、バージョンを管理する事が可能です。ツールには、私たちはNode.jsベースの依存を管理するためにnpmを使用します。
Polymer Starter Kit offers an optional offline experience thanks to Service Worker and the Platinum Service Worker elements. New to Service Worker? Read the following introduction 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:
- Uncomment Service Worker code in index.html
<!-- Uncomment next block to enable Service Worker support (1/2) -->
<!--
<paper-toast id="caching-complete"
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"
precache-file="precache.json">
</platinum-sw-cache>
</platinum-sw-register>
-->- 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">
-->- Uncomment 'cache-config' in the
runSequence()section of the 'default' gulp task, like below: (gulpfile.js)
// Build Production Files, the Default Task
gulp.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 them here.
Service Workers are only available to "secure origins" (HTTPS sites, basically) in line with a policy to prefer secure origins for powerful new features. However http://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 use chrome://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 to chrome: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:
- Remove references to the platinum-sw elements from your application index.
- Remove the two Platinum Service Worker elements (platinum-sw/..) in app/elements/elements.html
- Remove 'precache' from the list in the 'default' gulp task (gulpfile.js)
- Navigate to
chrome://serviceworker-internalsand 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 using CSS Custom properties via app/styles/app-theme.html.
You can also use app/styles/main.css for pure CSS stylesheets (e.g for global styles), however note that Custom properties will not work there under the shim.
A Polycast is also available that walks through theming using Polymer 1.0.
This can be done via app/elements/routing.html. We use Page.js for routing and new routes
can be defined in this import. We then toggle which <iron-pages> page to display based on the selected route.
<more-routing> (in our opinion) is good, but lacks imperative hooks for getting full control
over the routing in your application. This is one place where a pure JS router shines. We may
at some point switch back to a declarative router when our hook requirements are tackled. That
said, it should be trivial to switch to <more-routing> or another declarative router in your
own local setup.
App layouts live in a separate repository called app-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 the elements.html import.
Our most commonly reported issue is around system permissions for installing Node.js dependencies.
We recommend following the fixing npm permissions
guide to address any messages around administrator permissions being required. If you use sudo
to 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 an EEXIST error), you
may have run into an npm bug. We recommend updating to npm 2.11.0+
to work around this. You can do this by opening a Command Prompt/terminal and running npm install npm@2.11.0 -g. If you are on Windows,
Node.js (and npm) may have been installed into C:\Program Files\. Updating npm by running npm install npm@2.11.0 -g will install npm
into %AppData%\npm, but your system will still use the npm version. You can avoid this by deleting your older npm from C:\Program Files\nodejs
as described here.
If the issue is to do with a failure somewhere else, you might find that due to a network issue
a dependency failed to correctly install. We recommend running npm cache clean and deleting the node_modules directory followed by
npm install to see if this corrects the problem. If not, please check the issue tracker in case
there is a workaround or fix already posted.
Some Windows users have run into trouble with the elements.vulcanized.html file in their dist folder
not being correctly vulcanized. This can happen if your project is in a folder with a name containing a
space. You can work around this issue by ensuring your path doesn't contain one.
There is also an in-flight issue
where some are finding they need to disable the inlineCss option in our configuration for Vulcanize
to correctly build. We are still investigating this, however for the time-being use the workaround if
you find your builds getting stuck here.
At the bottom of app/index.html, you will find a build block that can be used to include additional
scripts for your app. Build blocks are just normal script tags that are wrapped in a HTML
comment that indicates where to concatenate and minify their final contents to.
Below, we've added in script2.js and script3.js to this block. The line
<!-- build:js scripts/app.js --> specifies that these scripts will be squashed into scripts/app.js
during a build.
<!-- build:js scripts/app.js -->
<script src="scripts/app.js"></script>
<script src="scripts/script2.js"></script>
<script src="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 final dist directory, you will need to either copy these files as part of the gulpfile.js build process (see the copy 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 the Releases page. This takes next to no time to setup.
- Copy code below
- Then replace
gulp.task('vulcanize', function () {...entire gulp vulcanize task code ingulpfile.js
// Vulcanize granular configuration
gulp.task('vulcanize', function () {
var DEST_DIR = 'dist/elements';
return gulp.src('dist/elements/elements.vulcanized.html')
.pipe($.vulcanize({
stripComments: true,
inlineCss: true,
inlineScripts: true
}))
.pipe(gulp.dest(DEST_DIR))
.pipe($.size({title: 'vulcanize'}));
});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.