DEPRECATION NOTICE

This CLI for PWABuilder is no longer maintained. Please use PWABuilder.com instead. If you need to open an issue for PWABuilder-related things, please do so at https://github.com/pwa-builder/PWABuilder/issues

PWA Builder CLI

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

Commands

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.