Skip to content
This repository has been archived by the owner on Apr 10, 2021. It is now read-only.

Dabolus/polymer3-webpack-starter-kit

Repository files navigation

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

Build Status Dependencies Status Dev Dependencies Status Maintainability Greenkeeper

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.