Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pwa-builder/PWABuilder-CLI
Node.js tool for App Generation
https://github.com/pwa-builder/PWABuilder-CLI
Last synced: about 2 months ago
JSON representation
Node.js tool for App Generation
- Host: GitHub
- URL: https://github.com/pwa-builder/PWABuilder-CLI
- Owner: pwa-builder
- License: other
- Archived: true
- Created: 2015-04-06T15:29:39.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2021-05-12T21:50:31.000Z (over 3 years ago)
- Last Synced: 2024-05-19T03:16:02.210Z (4 months ago)
- Language: JavaScript
- Homepage:
- Size: 2.56 MB
- Stars: 1,625
- Watchers: 83
- Forks: 140
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# DEPRECATION NOTICE
This CLI for PWABuilder is no longer maintained. Please use [PWABuilder.com](https://www.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](http://www.w3.org/TR/appmanifest/).
## Installation
````
npm install -g pwabuilder
````
## Documentation
To get started, visit our [wiki](https://github.com/manifoldjs/manifoldJS/wiki).
## Command Line Interface
### Usage
````
pwabuilder [options]
````
-or-
````
pwabuilder [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](https://github.com/manifoldjs/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 [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 [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 [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 [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 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](http://www.w3.org/TR/appmanifest/)
- [Chrome Hosted Apps](https://developer.chrome.com/apps/about_apps)
We plan to support the following manifest files in the future:
- [Web App Template](http://wat-docs.azurewebsites.net/JsonWindows)
- [Firefox Open Web Apps](https://developer.mozilla.org/Apps/Build/Manifest)
## 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](https://github.com/manifoldjs/ManifoldCordova#navigation-scope)).
## Changelog
Releases are documented in [GitHub](https://github.com/manifoldjs/ManifoldJS/releases).
## 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.