Note: following Polymer 3, this project is now in maintenance mode. This means that it won't receive new features, I will just keep updating its deps to keep it fresh. To write vanilla progressive web applications with web components, use the PWA Webpack Starter Kit instead.

Polymer 3 Starter Kit with Webpack

Want to use the latest Polymer 3 but you don't know how to get started? Got you covered!

This starter kit was built from scratch to allow you to start using today the features of tomorrow.

Features:

• Latest Polymer 3 preview
• Components split into component class, styles and templates. No more huge files with mixed content!
• TypeScript with TSLint preconfigured, so that you can write reliable, high quality code
• Using SCSS by default. Write less, do more!
• Lazy-loading using the brand new JavaScript dynamic import syntax
• A static and a dynamic subroute example, currently missing from the original Starter Kit. This one has been added because it is not always so obvious how to use the router for a subroute
• Shared styles and custom iconset, just like the original PSK
• Automatic service worker generation using Workbox
• Webpack 4 to bundle 'em all!
• Basic Firebase configuration to allow easy deployment out of the box

Preview

You can see an online preview of the project on my Github Pages.

Note that GH Pages does not currently support routing all the requests to an index.html, so you won't be able to link to a specific page of this online preview. However, you can still switch from one page to another once you've loaded the index.

Setup

• Install Node.js. Because of the syntax used in the configuration files, at least v8.3 is required. If you want to feel safe, the latest LTS will work well.
• Install yarn
• Clone this repository

  git clone https://github.com/Dabolus/polymer3-webpack-starter-kit.git <your-app-name> && cd <your-app-name>

• Install the project dependencies

  yarn install

  This will automatically install both the frontend and the build tools dependencies. Go on reading to understand the project structure and why it is organized in this way.
• Optional: if you wish to deploy your PWA on Firebase, remember that you also need to install firebase-tools

  yarn global add firebase-tools

• Profit!

Available scripts

yarn serve
# Starts webpack dev server with live reload on http://localhost:8080

yarn build
# Builds the production ready website in the build/ directory
# By default, the base path of the built project will be '/'
# If you wish to change this behavior, you can set the basePath
# variable to whatever you want the base path to be inside conf/app.config.js
# REMEMBER TO ADD THE LEADING AND TRAILING SLASHES

yarn deploy [...args]
# Alias of 'firebase deploy'. The args will be passed to firebase
# e.g. yarn deploy --only hosting
# Note that this command won't build the project before deploying it,
# so you will have to do it yourself.
# e.g. yarn build && yarn deploy
# By default, the files to deploy are the ones inside the build/ directory
# To change this behavior, change the "public" property in 'firebase.json'

Project configuration

You can find a lot of useful configuration options inside the conf/app.config.js file. If these options aren't enough for you, you can always edit webpack configuration and everything else at you needs.

Project Structure

---

polymer3-webpack-starter-kit (click to expand)

├── conf

Contains the configuration-related files

│ ├── webpack

Files related to webpack configurations

│ │ ├── custom-loaders

Directory containing custom loaders for webpack

│ │ │ ├── index.js

A file that automagically loads all the loaders that are added inside the 'custom-loaders' folder

│ │ │ └── minify-template.loader.js

A custom loader that minifies the HTML and CSS contained in template strings

│ │ ├── base.config.js

The base webpack configuration, which other configurations extend

│ │ ├── dev-server.config.js

The development server configuration, aka the options passed to 'webpack-serve'

│ │ ├── dev.config.js

The development configuration for webpack, optimized for being fast and verbose

│ │ └── prod.config.js

The production configuration for webpack, optimized to output highly compressed chunks for production use

│ ├── app.config.js

Contains some configuration variables used all around the project

│ ├── postcss.config.js

PostCSS configuration file

│ └── typify-env.js

An helper used to typify the environment variables (it detects whether an environment variable is a boolean, a number or a string)

├── src

Contains the app source files

│ ├── components

Contains our custom Web Components

│ │ ├── icons

A custom element used to define our own custom iconset

│ │ │ ├── defs.html

The HTML file containing the icons SVG definitions

│ │ │ └── index.ts

The TypeScript class that declares the custom element and imports the icons definitions

│ │ ├── shared-styles

A custom element used to define the styles shared between our other elements

│ │ │ ├── defs.scss

The SCSS file containing the shared styles definitions

│ │ │ └── index.ts

The TypeScript class that declares the custom element and imports the shared styles

│ │ ├── shell

Our app shell. It is the most important custom element in our app, as it will load all the other custom elements on demand. Check out the PRPL pattern for more info

│ │ │ ├── shell.component.ts

The TypeScript class that declares the shell custom element and imports the element styles and template

│ │ │ ├── shell.style.scss

The styles for the shell component

│ │ │ └── shell.template.html

The template for the shell component

│ │ ├── view1

The view1 component, the most simple view in our app

│ │ │ ├── view1.component.ts

The TypeScript class that declares the view1 custom element and imports the element styles and template

│ │ │ ├── view1.style.scss

The styles for the view1 component

│ │ │ └── view1.template.html

The template for the view1 component

│ │ ├── view2

The view2 component, that contains three lazy-loaded subviews

│ │ │ ├── subview1

view2 - static subview1

│ │ │ │ ├── subview1.component.ts

The TypeScript class that declares the subview1 custom element and imports the element styles and template

│ │ │ │ ├── subview1.style.scss

The styles for the subview1 component

│ │ │ │ └── subview1.template.html

The template for the subview1 component

│ │ │ ├── subview2

view2 - static subview2

│ │ │ │ ├── subview2.component.ts

The TypeScript class that declares the subview2 custom element and imports the element styles and template

│ │ │ │ ├── subview2.style.scss

The styles for the subview2 component

│ │ │ │ └── subview2.template.html

The template for the subview2 component

│ │ │ ├── subview3

view2 - static subview3

│ │ │ │ ├── subview3.component.ts

The TypeScript class that declares the subview3 custom element and imports the element styles and template

│ │ │ │ ├── subview3.style.scss

The styles for the subview3 component

│ │ │ │ └── subview3.template.html

The template for the subview3 component

│ │ │ ├── view2.component.ts

The TypeScript class that declares the view2 custom element and imports the element styles and template

│ │ │ ├── view2.style.scss

The styles for the view2 component

│ │ │ └── view2.template.html

The template for the view2 component

│ │ ├── view3

The view3 component, that contains a lazy-loaded dynamic subview

│ │ │ ├── dynamic-subview

view3 - dynamic subview

│ │ │ │ ├── dynamic-subview.component.ts

The TypeScript class that declares the dynamic-subview custom element and imports the element styles and template

│ │ │ │ ├── dynamic-subview.style.scss

The styles for the dynamic-subview component

│ │ │ │ └── dynamic-subview.template.html

The template for the dynamic-subview component

│ │ │ ├── view3.component.ts

The TypeScript class that declares the view3 custom element and imports the element styles and template

│ │ │ ├── view3.style.scss

The styles for the view3 component

│ │ │ └── view3.template.html

The template for the view3 component

│ │ ├── view404

The view404 component, that is loaded when the user tries to access to a non existent route

│ │ │ ├── view404.component.ts

The TypeScript class that declares the view404 custom element and imports the element styles and template

│ │ │ ├── view404.style.scss

The styles for the view404 component

│ │ │ └── view404.template.html

The template for the view404 component

│ │ └── index.ts

A file that loads and registers the static custom elements (the ones that are not lazy loaded)

│ ├── static

A folder containing the static assets of the app, i.e. the ones that will be copied without being altered by the webpack loaders

│ │ ├── images

Static images folder

│ │ │ ├── manifest

Manifest icons

│ │ │ │ ├── icon-144x144.png

Manifest icon - 144x144px

│ │ │ │ ├── icon-192x192.png

Manifest icon - 192x192px

│ │ │ │ ├── icon-48x48.png

Manifest icon - 48x48px

│ │ │ │ ├── icon-512x512.png

Manifest icon - 512x512px

│ │ │ │ ├── icon-72x72.png

Manifest icon - 72x72px

│ │ │ │ └── icon-96x96.png

Manifest icon - 96x96px

│ │ │ └── favicon.ico

The app favicon

│ │ ├── manifest.json

The app manifest

│ │ └── sw.js

A mock service worker, used as a placeholder during development to avoid caching

│ ├── bootstrap.ts

The bootstrapper of our app. It is used to load all the external dependencies together with our custom elements into the app bundle

│ ├── index.hbs

The index of our app, as an Handlebars template. Having an HBS file allows us to build the HTML with some basic logic, like referencing some scripts only if some condition happens

│ ├── service-worker.js

Description

│ └── typings.d.ts

It contains the custom typings for our app, i.e. the ones that are not bundled with the library we install and are not installable via @types/library

├── .gitignore

The project gitignore file

├── .travis.yml

Travis configuration file, which will automatically build and deploy the project on Firebase

├── CONTRIBUTING.md

A file that explains how to contribute to the project

├── firebase.json

Firebase configuration file

├── package.json

The project main package.json. It contains our app information (name, description, version, etc) and dependencies, as well as the scripts to test, build and deploy the app

├── README.md

The README of the project (this file that you are reading)

├── tsconfig.json

TypeScript configuration file

├── tslint.json

TSLint configuration file

└── yarn.lock

The project Yarn lockfile

---

Contributing

PRs are welcome! You noticed a bug, a possible improvement or whatever? Any help is always appreciated, so don't hesitate opening one!

Be sure to check out the contributing guidelines to fasten up the merging process.