<p align="center"><strong>WORK IN PROGRESS</strong></p>

Features

Framework Agnostic<br> Build with your preferred framework or with none at all!<br>Official presets for Preact, React, Vue, and Svelte.
Plug 'n Play<br> Don't worry about configuration, unless you want to.<br>Presets and plugins are automatically applied. Just install and go!
Fully Extensible<br> Includes a plugin system that allows for easy, fine-grain control of your configuration... when needed.
Feature Rich<br> Supports Babel, Bublé, Browserslist, TypeScript, PostCSS, ESLint, Prettier, and Service Workers out of the box!
Instant Prototyping<br> Quickly scaffold new projects with your preferred view library and toolkit.<br>Kick it off with a perfect Lighthouse score!
Static Site Generator<br> Export your routes as "pre-rendered" HTML.<br>Great for SEO and works on any static hosting service.

Installation

PWA is split up into two main components (core and cli) in addition to its list of presets and plugins.

While most will opt for the CLI, the core module handles all configuration and can be used as a standalone module.

Please refer to each package for installation, API, and Usage information.

Quick Start

# Install globally
$ npm install --global @pwa/cli
# OR
$ yarn global add @pwa/cli

# Display CLI's help text
$ pwa --help

# Generate new project
$ pwa init

Note: The global modifiers are only required for global command-line usage!<br> Local devDependency installation will also work, but then pwa usage is limited to the project.

Concepts

Please read about Progressive Web Apps if the term is unfamiliar to you.

Presets

Presets are collections of plugins that are tailored for a particular framework.

While there may be "official" presets, this does not mean that PWA can only support these candidates! The current options are:

These packages are auto-loaded during PWA's initialization and are applied first, before any Plugins or custom configuration. This means that you always have the option to override a value or setting shipped within the Preset.

Plugins

Plugins are (typically) individual features or chunks of configuration that are encapsulated for easy/automatic application within your build process.

While there may be "official" plugins, this does not mean that PWA can only support these functionalities! The current plugins include:

These packages are auto-loaded during PWA's initialization and are applied second, after any Presets and before custom configuration. This allows Plugins to override settings from Presets.

Plugins may (sometimes) expose a new key on the config tree and then reference this value later in composition. This allows the end-user to change the Plugin's settings before running the build.

Please see @pwa/plugin-critters for an example of this practice.

Commands

This section applies to @pwa/cli specifically.

Build

Build your application for production

$ pwa build --help

  Description
    Build production assets

  Usage
    $ pwa build [src] [options]

  Options
    --analyze     Launch interactive Analyzer to inspect production bundle(s)
    -o, --dest    Path to output directory  (default build)
    -h, --help    Displays this message

Export

Export routes' HTML for static hosting

Instead of --routes, you may define a routes array within pwa.config.js config file.

If no routes are defined in either location, PWA will traverse your "@pages"-aliased directory (default: src/pages/**) and attempt to infer URL patterns from the file structure.

In the event that no files exist within that directory, PWA will show a warning but still scrape the index ("/") route.

$ pwa export --help

  Description
    Export pre-rendered pages

  Usage
    $ pwa export [src] [options]

  Options
    -o, --dest        Path to output directory  (default build)
    -w, --wait        Time (ms) to wait before scraping each route  (default 0)
    -r, --routes      Comma-delimited list of routes to export
    -i, --insecure    Launch Chrome Headless without sandbox
    -h, --help        Displays this message

Important: Using export requires a local version of Chrome installed! See chrome-launcher.<br>Additionally, the --insecure flag launches Chrome without sandboxing. See here and here for help.

Watch

Develop within a live-reload server

Within your pwa.config.js's webpack config, any/all devServer options are passed to Webpack Dev Server.

$ pwa watch --help

  Description
    Start development server

  Usage
    $ pwa watch [src] [options]

  Options
    -H, --host     A hostname on which to start the application  (default localhost)
    -p, --port     A port number on which to start the application  (default 8080)
    -q, --quiet    Disable logging to terminal, including errors and warnings
    --https        Run the application over HTTP/2 with HTTPS
    --key          Path to custom SSL certificate key
    --cert         Path to custom SSL certificate
    --cacert       Path to custom CA certificate override
    -h, --help     Displays this message

Build vs Export

Export can be thought of as "Build 2.0" — it spins up a Headless Chrome browser and programmatically scrapes your routes.

This is ideal for SEO, PWA behavior, and all-around performance purposes, as your content will exist on the page before the JavaScript application is downloaded, parsed, boots, and (finally) renders the content.

The generated HTML pages will be placed in your build directory. A /login route will be exported as build/login/index.html — this makes it compatible with even the "dumbest" of static hosting services!

Note: Running export will automatically run build before scraping.

Configuration

Overview

All configuration within the PWA tree is mutable! Presets, Plugins, and your custom config file write into the same object(s). This is great for composability and extensibility, but be warned that your custom config may break the build if you're not careful.

:bulb: Official presets & plugins are controlled releases and are ensured to play nicely with one another.

The config object(s) for your project are assembled in this sequence:

Presets: All non-webpack config keys
Plugins: All non-webpack config keys
Custom: All non-webpack config keys
Presets: The webpack config key, if any
Plugins: The webpack config key, if any
Custom: The webpack config key, if any

Because the final config object is passed to Webpack, internally, the webpack key always runs last as it composes & moves everything into its relevant loaders, plugins, etc.

Important: When defining a custom webpack key it must always be a function!

Mutations

Every config key can be defined or mutated in the same way!

Any non-Function key will overwrite the existing value. This allows strong opinions and/or allows a Plugin to define a new config key and reference it later on.

Any Function key will receive the existing, matching config-value for direct mutation. This is for fine-grain control over the existing config.

// defaults:
exports.hello = { foo:1, bar:2 };
exports.world = ['How', 'are', 'you?'];

// preset/plugin/custom:
exports.hello = function (config) {
  config.bar = 42;
  config.baz = [7, 8, 9];
}
exports.world = ['I', 'am', 'fine'];
exports.HOWDY = 'PARTNER!';

// result:
exports.hello = {
  foo: 1,
  bar: 42,
  baz: [7, 8, 9]
}
exports.world = ['I', 'am', 'fine'];
exports.HOWDY = 'PARTNER!';

Functions

Any config key that is a function will have the signature of (config, env, opts).

config

Type: Mixed

This will be the existing value

Pwa

Install / Use

README