You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by er...@apache.org on 2020/04/08 06:24:21 UTC
[cordova-serve] branch master updated: doc(README): formatting,
syntax updating, wording (#31)
This is an automated email from the ASF dual-hosted git repository.
erisu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cordova-serve.git
The following commit(s) were added to refs/heads/master by this push:
new efc4674 doc(README): formatting, syntax updating, wording (#31)
efc4674 is described below
commit efc4674046ce54639f0e287b36be4794017d7167
Author: エリス <er...@users.noreply.github.com>
AuthorDate: Wed Apr 8 15:24:16 2020 +0900
doc(README): formatting, syntax updating, wording (#31)
* doc(README): formatting, syntax updating, wording
* chore: apply suggestion
Co-Authored-By: Raphael von der Grün <ra...@gmail.com>
---
README.md | 185 +++++++++++++++++++++++++++++++++++---------------------------
1 file changed, 106 insertions(+), 79 deletions(-)
diff --git a/README.md b/README.md
index 74852f5..03052d2 100644
--- a/README.md
+++ b/README.md
@@ -19,109 +19,136 @@
#
-->
+# cordova-serve
+
[](https://nodei.co/npm/cordova-serve/)
[](https://github.com/apache/cordova-serve/actions?query=branch%3Amaster)
-# cordova-serve
-This module can be used to serve up a Cordova application in the browser. It has no command-line, but rather is intended
-to be called using the following API:
-
-``` js
-var cordovaServe = require('cordova-serve')();
-cordovaServe.launchServer(opts);
-cordovaServe.servePlatform(platform, opts);
-cordovaServe.launchBrowser(ops);
+This module provides a JavaScript API to serve up a Cordova application in the browser.
+
+**API Example:**
+
+```js
+const cordovaServe = require('cordova-serve')();
+
+cordovaServe.launchServer(options);
+cordovaServe.servePlatform(platform, options);
+cordovaServe.launchBrowser(options);
```
-## launchServer()
+## API Methods
+
+### `launchServer()`
+
+Launches a local HTTP server.
-``` js
-var cordovaServe = require('cordova-serve')();
-cordovaServe.launchServer(opts).then(function () {
- var server = cordovaServe.server;
- var root = cordovaServe.root;
- var port = cordovaServe.port;
+**Code Example:**
+```js
+const cordovaServe = require('cordova-serve')();
+
+cordovaServe.launchServer(options).then(function () {
+ const { server, port, root } = cordovaServe;
...
-}, function (error) {
- console.log('An error occurred: ' + error);
+}, error => {
+ console.log(`An error occurred: ${error}`);
});
```
-Launches a server with the specified options. Parameters:
+**Parameters:**
+
+* **options**: described below in the following section "**launchServer & servePlatform Options**".
+
+**Return:**
+
+Returns a resolved or rejected promise depending on if the server had launched successfully.
-* **opts**: Options, as described below.
+On a fulfilled promise, the following properties are available on the returned object:
-Returns a promise that is fulfilled once the server has launched, or rejected if the server fails to launch. Once the
-promise is fulfilled, the following properties are available on the `cordovaServe` object:
-
- * **cordovaServe.serve**: The Node http.Server instance.
- * **cordovaServe.root**: The root that was specified, or cwd if none specified.
- * **cordovaServe.port**: The port that was used (could be the requested port, the default port, or some incremented
- value if the chosen port was in use).
+Property | Description
+-|-
+`serve` | The Node `http.Server` instance.
+`root` | The `root` that was specified, or `cwd` if none specified.
+`port` | The port that was used. (Either the requested port, the default port of `8000`, or the incremented value of the chosen port when the chosen port is already in use).
-## servePlatform()
+## `servePlatform()`
-``` js
-var cordovaServe = require('cordova-serve')();
-cordovaServe.servePlatform(platform, opts).then(function () {
- var server = cordovaServe.server;
- var port = cordovaServe.port;
- var projectRoot = cordovaServe.projectRoot;
- var platformRoot = cordovaServe.root;
+Launches a server that serves up any Cordova platform (e.g. `browser`, `android`, etc) from the current project.
+**Code Example:**
+
+```js
+const cordovaServe = require('cordova-serve')();
+
+cordovaServe.servePlatform(platform, options).then(() => {
+ const { server, port, projectRoot, root } = cordovaServe;
...
-}, function (error) {
- console.log('An error occurred: ' + error);
+}, error => {
+ console.log(`An error occurred: ${error}`);
});
```
-Launches a server that serves up any Cordova platform (e.g. `browser`, `android` etc) from the current project.
-Parameters:
-
-* **opts**: Options, as described below. Note that for `servePlatform()`, the `root` value should be a Cordova project's
- root folder, or any folder within it - `servePlatform()` will replace it with the platform's `www_dir` folder. If this
- value is not specified, the *cwd* will be used.
-
-Returns a promise that is fulfilled once the server has launched, or rejected if the server fails to launch. Once the
-promise is fulfilled, the following properties are available on the `cordovaServe` object:
-
- * **cordovaServe.serve**: The Node http.Server instance.
- * **cordovaServe.root**: The requested platform's `www` folder.
- * **cordovaServe.projectRoot**: The root folder of the Cordova project.
- * **cordovaServe.port**: The port that was used (could be the requested port, the default port, or some incremented
- value if the chosen port was in use).
-
-## launchBrowser()
-
-``` js
-var cordovaServe = require('cordova-serve')();
-cordovaServe.launchBrowser(opts).then(function (stdout) {
- console.log('Browser was launched successfully: ' + stdout);
-}, function (error) {
- console.log('An error occurred: ' + error);
-});
+**Parameters:**
+
+* **options**: described below in the following section "**launchServer & servePlatform Options**".
+
+**Return:**
+
+Note that for `servePlatform()`, the `root` value should be a Cordova project's root folder or any folder within it. `servePlatform()` will replace it with the platform's `www_dir` folder. If this value is not specified, the *cwd* will be used.
+
+Returns a resolved or rejected promise depending on if the server had launched successfully.
+
+On a fulfilled promise, the following properties are available on the returned object:
+
+Property | Description
+-|-
+`serve` | The Node `http.Server` instance.
+`root` | The requested platform's `www` folder.
+`projectRoot` | The root folder of the Cordova project.
+`port` | The used port. requested port, the default port `8000`, or incremented value of the chosen port when already in use).
+
+### `launchBrowser()`
+
+Launches a browser window pointing to the specified URL.
+
+**Code Example:**
+
+```js
+const cordovaServe = require('cordova-serve')();
+
+cordovaServe.launchBrowser(options).then(
+ stdout => {
+ console.log(`Browser was launched successfully: ${stdout}`);
+ },
+ error => {
+ console.log(`An error occurred: ${error}`);
+ }
+);
```
-Launches a browser window pointing to the specified URL. The single parameter is an options object that supports the
-following values (both optional):
+**Parameters:**
+
+* **options** (optional):
+
+Options | Description
+-|-
+`url` | The URL to open in the browser.
+`target` | The browser identifier to launch. **Valid identifier**: `chrome`, `chromium`, `firefox`, `ie`, `opera`, `safari`. (**Default:** `chrome`.)
+
+**Return:**
-* **url**: The URL to open in the browser.
-* **target**: The name of the browser to launch. Can be any of the following: `chrome`, `chromium`, `firefox`, `ie`,
- `opera`, `safari`. Defaults to `chrome` if no browser is specified.
+Returns a resolved or rejected promise depending on if the browser had launched successfully.
-Returns a promise that is fulfilled once the browser has been launched, or rejected if an error occurs.
+## launchServer & servePlatform Options
-## The *opts* Options Object
-The opts object passed to `launchServer()` and `servePlatform()` supports the following values (all optional):
+The `options` object passed to `launchServer()` and `servePlatform()` supports the following values (all optional):
-* **root**: The file path on the local file system that is used as the root for the server, for default mapping of URL
- path to local file system path.
-* **port**: The port for the server. Note that if this port is already in use, it will be incremented until a free port
- is found.
-* **router**: An `ExpressJS` router. If provided, this will be attached *before* default static handling.
-* **noLogOutput**: If `true`, turns off all log output.
-* **noServerInfo**: If `true`, cordova-serve won't output `Static file server running on...` message.
-* **events**: An `EventEmitter` to use for logging. If provided, logging will be output using `events.emit('log', msg)`.
- If not provided, `console.log()` will be used. Note that nothing will be output in either case if `noLogOutput` is `true`.
+Options | Description
+-|-
+`root` | The file path on the local file system that is used as the root for the server, for default mapping of URL path to the local file system path.
+`port` | The port for the server. Note that if this port is already in use, it will be incremented until a free port is found.
+`router` | An `ExpressJS` router. If provided, this will be attached *before* default static handling.
+`noLogOutput` | If true, all log output will be turned off.
+`noServerInfo` | If `true`, the `Static file server running on...` message will not be outputed.
+`events` | An `EventEmitter` to use for logging. If provided, logging will be output using `events.emit('log', msg)`. If not provided, `console.log()` will be used. Note that nothing will be output in either case if `noLogOutput` is `true`.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org