README.md

🛠 Status: Experimental

This project is currently in development.

pwa-lit-template

Getting started | Build for production | Create a new page | Environment configuration | Browser support

This project helps you to build Progressive Web Applications following the modern web standards, best practices and providing you with tools for that purpose. Out of the box, provides you with the following features:

• Simple way to create Web Components with LitElement.
• Small and powerful client-side router for Web Components with Vaadin Router.
• All the benefits from a PWA (manifest, service worker, offline UI) thanks to Workbox and pwa-helpers.
• SEO friendly thanks to the PageElement custom element and the html-meta-manager.
• A development server with auto-reload to serve the application without bundling with @web/dev-server.
• Simple build flow thanks to Rollup and @open-wc/building-rollup initial configuration.
• Easy deployment over to prpl-server or any static hosting.

Check out our roadmap to get informed of the latest features released and the upcoming ones.

Getting started

Prerequisites

• node.js

Furthermore, this project is built on TypeScript with the intention of improving the developer experience.

Install the dependencies

npm install

Start the development server

This command serves the app at http://localhost:8000:

npm start

Project structure

├─ images/
├─ patches/
├─ server/
├─ src/
│  ├─ components/
│  │  ├─ app-index.ts
│  │  └─ ···
│  ├─ config/
│  ├─ helpers/
│  │  ├─ page-element.ts
│  │  └─ ···
│  ├─ pages/
│  │  ├─ page-home.ts
│  │  └─ ···
│  └─ router/
│     └─ routes.ts
├─ index.html
├─ manifest.webmanifest
├─ package.json
├─ robots.txt
├─ rollup.config.js
└─ tsconfig.json

• images: is use to store the static resourced used by your application.
• patches: contains the patches to apply in the different packages mentioned here. It will be removed at some point.
• server: contains the logic to serve the application. And is where you are going to create your dist/ folder containing the bundle of your application.
• src
  • components: contains your custom Web Components. Inside this folder you will find the app-index.ts file, main root of your application following the PRPL patern.
  • config: stores the configuration (handles the environment at the build time).
  • helpers: contains two interesting features: PageElement and html-meta-manager. Go more in-depth with them here.
  • pages: where you create the pages for your application.
  • router: where you create the routes for your application.
• index.html: the application entry point.

Guides

Build for production

This command use Rollup to build an optimized version of the application for production:

npm run build

It has two outputs: in addition to outputting a regular build, it outputs a legacy build which is compatible with older browsers down to IE11.

At runtime it is determined which version should be loaded, so that legacy browsers don't force to ship more and slower code to most users on modern browsers.

Note: If you need to add static files to the build, like the images folder or the manifest.webmanifest, you should register them in the copy() plugin of the rollup.config.js.

Create a new page

1. Create the new page component (extending from PageElement helper) in the pages folder. For example a page-explore.ts.

   import { html, customElement } from 'lit-element';
   
   import { PageElement } from '../helpers/page-element';
   
   @customElement('page-explore')
   export class PageExplore extends PageElement {
     render() {
       return html`
         <h1>Explore</h1>
         <p>My new explore page!</p>
       `;
     }
   }

2. Register the new route in the routes.ts:

   {
     path: '/explore',
     name: 'explore',
     component: 'page-explore',
     metadata: {
       title: 'Explore',
       description: 'Explore page description'
     },
     action: async () => {
       await import('../pages/page-explore');
     }
   },

With SEO in mind, this project offers you the PageElement base class to help you to deal with it; it has a metadata() method that edits the HTML meta tags of the specific page with the metadata property defined in the route. And if you need dynamic information, you also can override the metadata() method.

Environment configuration

This project allows different configurations per environment. The files that manage that configuration can be found in src/config/ and the structure that we follow here is the next one:

├─ src/config/
|  ├─ config.{NODE_ENV}.ts
|  └─ index.ts

Before the build all the variables are shared between index.ts and config.development.ts but in the build process the import of that last file is changed by the file related with the target environment following the rule config.{NODE_ENV}.ts and loading the expected configuration file.

Lastly, the way to use that configuration is quite simple. You only need to import it:

import { config } from '../config';

And use it where you need it:

render() {
  return html`
    <footer>
      <span>Environment: ${config.environment}</span>
    </footer>
  `;
}

Browser support

• Chrome
• Edge
• Firefox
• Safari

To run on other browsers, you need to use a combination of polyfills and transpilation. This step is automated by the build for production command.

---

Things to be aware

• There is a patch that modifies the @vaadin/router's scroll standard behavior to have a more consistent scroll; now when you perform a click event, the scroll will be reset to the top position.

  Related issue: #1: Remove the Vaadin Router patch