PWA Builder

This tool is used to create hosted web applications based on a W3C Web App manifest.

Installation

npm install -g pwabuilder

Documentation

To get started, visit our wiki.

Command Line Interface

Usage

pwabuilder <website-url> [options]

-or-

pwabuilder <command> [options]

Options

|       Option       | Description | | ----------------- | --------------- | | website-url | URL of the hosted website. This parameter is not required if a manifest location is specified with the -m option | | -d, --directory | (optional) Path to the generated project files (default value: current directory) | | -s, --shortname | (optional) Application short name. When specified, it overrides the short_name value of the manifest | | -l, --loglevel | (optional) Tracing log level options. Available log levels: debug,info,warn,error (default value: warn) | | -p, --platforms | (optional) Platforms to generate. Supported platforms: windows,windows10,android,ios,web (default value: all platforms) | | -m, --manifest | (optional) Location of the W3C Web App manifest file (URL or local path). If not specified, the tool looks for a manifest in the site URL. Otherwise, a new manifest will be created pointing to the site URL. | | -i, --image | (optional) Local path to the image file used to generate missing icons in the manifest | | -f, --forceManifestFormat | (optional) Allows to specify the manifest format and skip the automatic detection. Can be used when the manifest contains additional, non-standard members. | | -c, --crosswalk | (optional) Enable Crosswalk for Android. Crosswalk is a web runtime that can be used to replace the stock WebView used by Android Cordova apps. Crosswalk is based on Google Chromium with Cordova API support and has better HTML5 feature support compared to the default WebView available in Android. | | -w, --webAppToolkit | (optional) Adds the Web App Toolkit cordova plugin. The Web App Toolkit is a plugin for creating Windows, Android and iOS apps based on existing web content. It depends on the Hosted Web App Plugin. Used in the right way, it can facilitate the creation of compelling extensions to your web content for users across platforms. | | -S, --Sign | (deprecated --optional - for package command) Return a signed package for Windows 10. | | -W, --DotWeb | (deprecated --optional - for package command) Generate a .web package for Windows 10. | | -a, --AutoPublish | (deprecated --optional - for package command) Auto-publish a package for Windows 10. |

Commands

|             Command           | Description | | ------------------------- | --------------- | | package [directory] [options] | Creates a package for supported platforms (windows10, android, iOS) for uploading to the Store. In some cases, like Windows 10, data must be pulled from the store and updated in the manifest before it can be uploaded. directory is the root path where to look for the target platforms (defaults to the current location). options: -l | --loglevel, -p | --platforms, -S | --Sign, -W | --DotWeb, -a | --AutoPublish | | platform add <platform-id> <source> [options] | Adds a new platform. platform-id is the platform to be added. source could be either npm package, a GitHub reporitory or a local path to the platform source code. options: -l | --loglevel | | platform remove <platform-id> [options] | Removes an existing platform. platform-id is the platform to be removed. options: -l | --loglevel | | platform list [options] | List the existing platforms. options: -l | --loglevel | | run <platform> [directory] [options] | Launches the app of the specified platform. Currently, android, ios, windows and windows10 platforms are supported by this command. directory is the root path where to look for the target platforms (defaults to the current location). options: -l | --loglevel | | open <platform> [directory] [options] | (for Windows only) Opens the project file of the generated Windows 8.1 / Windows 10 app in Visual Studio. directory is the root path where to look for the target platforms (defaults to the current location). options: -l | --loglevel |

Example

Creating a new hosted web application

pwabuilder http://shiftr.azurewebsites.net -d C:\Projects -l info -p windows10,android

Packaging a Windows 10 app for submission to the Store

pwabuilder package -p windows10 -l debug

Client Library

Manifest Module

var manifestTools = require('manifestTools');

getManifestFromSite(siteUrl, callback)

Retrieves a manifest from a website. It looks for a manifest meta tag in the HTML content of the specified website URL; if no manifest is found, a new W3C manifest is retrieved with default start_name and short_name values.

siteUrl is the URL of the website that hosts the manifest.

callback(err, manifestInfo) returns an error or the manifest object in manifestInfo.

getManifestFromFile(filePath, callback)

Retrieves a manifest from a local path.

siteUrl is the path there the manifest file is located.

callback(err, manifestInfo) returns an error or the manifest object in manifestInfo.

writeToFile(manifestInfo, filePath, callback)

Writes manifest info to the specified path. manifestInfo Manifest data in JSON format.

filePath The path to write to.

callback(err, validationResults) returns an error or an array of validation results.

fetchManifestUrlFromSite(siteUrl, callback)

If found, gets the manifest URL from the specified website URL.

siteUrl is the URL of the website.

callback(err, content) returns an error or a content object with start_url and short_name members.

downloadManifestFromUrl(manifestUrl, callback)

Downloads the manifest from the specified URL.

manifestUrl is the URL of the manifest.

callback(err, manifestInfo) returns an error or the manifest object in manifestInfo.

validateAndNormalizeStartUrl(siteUrl, manifestInfo, callback)

Validates the format of the manifest is a W3C manifest format.

siteUrl is the URL of the website.

manifestInfo is the manifest's data in JSON format.

callback returns an error or the manifest object in manifestInfo.

convertTo(manifestInfo, outputFormat, callback)

Converts the manifest data to the specified output format.

manifestInfo is the manifest's data in JSON format.

outputformat is the format to which the manifest will be converted.

callback(err, manifestInfo) returns an error or the manifest object in manifestInfo.

validateManifest(manifestInfo, targetPlatforms, callback)

Makes sure the manifest is valid for the specified target platforms.

manifestInfo is the manifest's data in JSON format.

targetPlatforms are the platforms to validate against.

callback(err, validationResults) returns an error or an array of validation results.

manifestInfo format

manifestInfo.content stores the manifest content.

manifestInfo.format specifies the type of manifest (possible values: W3C, undefined).

Builder Module

var projectBuilder = require('projectBuilder');

createApps(w3cManifestInfo, rootDir, platforms, options, callback)

Generates the applications for the specified platforms.

w3cManifestInfo is the manifest's data in JSON format.

rootDir is the root directory where the apps will be generated.

platforms a string array specifying one or more target platforms: windows10,windows,android,ios,web.

options an object with one or more properties that customize the generated application:

• crosswalk (boolean) enable Crosswalk in the Cordova Android app
• webAppToolkit (boolean) adds the Web App Toolkit https://github.com/manifoldjs/Web-App-ToolKit cordova plugin

callback(err) returns an error, if any.

Project Tools module

var projectTools = require('projectTools');

runApp(platform, callback)

Execute the app for the chosen platform.

platform The app will execute for the selected platform.

callback returns an error, if any.

openVisualStudio(callback)

Opens the Visual Studio project.

callback returns an error, if any.

Unit Tests

In the terminal, install the Grunt task runner:

npm install -g grunt-cli

In order to run tests and jshint, execute the following command:

grunt

Supported Input Manifests

• W3C Web App
• Chrome Hosted Apps

We plan to support the following manifest files in the future:

• Web App Template
• Firefox Open Web Apps

Navigation Scope

The W3C manifest defines a scope that restricts the URLs to which the application can navigate. PWA Builder supports the scope setting for the Android, iOS and Windows platforms (more details here).

Changelog

Releases are documented in GitHub.

Known Issues

• Creating the directory shortcuts to the Cordova platform-specific projects may fail when running in the Windows environment. The tool reports _"WARNING: Failed to create shortcut for Cordova platform: XXXX."__ where XXXX is ios, windows, or android. This is caused by an issue in Node.js which has been fixed in more recent releases. To resolve this issue, upgrade Node.js to the latest version.

• Adding the windows platform in the Linux and Mac OS environments fails. The tool reports "WARNING: Failed to add the Cordova platforms: XXXX." where XXXX includes windows. This is caused by an issue in the Windows platform for Cordova. Depending on the cordova-windows version, running the tool can show one of two errors: "Cannot find module 'Q'." or "No such file or directory.". Until this problem is fixed by Cordova, we've removed the windows platform from the default list when creating the app in Linux or Mac OS.

• Error when building an iOS application for projects generated in a Windows machine and then copied to an OS X machine. Xcode reports "Shell Script Invocation Error - Command /bin/sh failed with exit code 126". This happens when the execution permission (+x) is lost on some scripts when copying between the different file systems.

  To resolve this, open a Terminal window in OS X and execute the following command to restore the executable bit on the script.

  chmod +x [path to the PWA Builder project]/cordova/platforms/ios/cordova/lib/copy-www-build-step.sh

• Issues in Visual Studio 2015 RC with the Windows solution generated by Cordova:

  • Opening the CordovaApp.sln solution file might hang Visual Studio while loading the Windows 8 project. As a workaround, remove the Windows 8 project file from the solution.
  • When building the solution, Visual Studio reports the following error in the Windows 10 project: "'ValidateAppxManifest' failed. Unspecified error". As a workaround, clean and rebuild the solution.

License

PWA Builder

Copyright (c) Microsoft Corporation

All rights reserved.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ""Software""), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.