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.
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
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.
- 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
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.
yarn install
- 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!
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'
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.
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
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.