UNPKG

5.8 kBMarkdownView Raw
1This module can be used to serve up a Cordova application in the browser. It has no command-line, but rather is intended
2to be called using the following API:
3
4``` js
5var serve = require('cordova-serve');
6serve.launchServer(opts);
7serve.servePlatform(opts);
8serve.launchBrowser(target, url);
9serve.sendStream(filePath, request, response[, readStream]);
10```
11
12##launchServer()
13
14``` js
15launchServer(opts);
16```
17
18Launches a server with the specified options. Parameters:
19
20* **opts**: Options, as described below.
21
22##servePlatform()
23
24``` js
25servePlatform(opts);
26```
27
28Launches a server that serves up any Cordova platform (e.g. `browser`, `android` etc) from the current project.
29Parameters:
30
31* **opts**: Options, as described below.
32
33##launchBrowser()
34
35``` js
36launchBrowser(target, url);
37```
38
39Launches a browser window pointing to the specified URL. Parameters:
40
41* **target**: The name of the browser to launch. Can be any of the following: `chrome`, `chromium`, `firefox`, `ie`,
42 `opera`, `safari`.
43* **url**: The URL to open in the browser.
44
45##sendStream()
46
47``` js
48sendStream(filePath, request, response[, readStream]);
49```
50
51The server uses this method to stream files, and it is provided as a convenience method you can use if you are
52customizing the stream by specifying `opts.streamHandler`. Parameters:
53
54* **filePath**: The absolute path to the file to be served (which will have been passed to your `streamHandler`).
55* **request**: The request object (which will have been passed to your `streamHandler`).
56* **response**: The response object (which will have been passed to your `streamHandler`).
57* **readStream**: A custom read stream, if required.
58
59##The *opts* Options Object
60The opts object passed to `launchServer()` and `servePlatform()` supports the following values:
61
62* **root**: The file path on the local file system that is used as the root for the server, for default mapping of URL
63 path to local file system path. For `servePlatform()`, this value should be the Cordova project's root folder, or any
64 folder within it - `servePlatform()` will replace it with the platform's `www_dir` folder.
65* **port**: The port for the server. Note that if this port is already in use, it will be incremented until a free port
66 is found.
67* **urlPathProcessor**: An optional method to handle special case URLs - `cordova-serve` will by default
68 treat the URL as relative to the platform's `www_dir`, but will first call this method, if provided, to support
69 custom handling.
70* **streamHandler**: An optional custom stream handler - `cordova-serve` will by default stream files using
71 `sendStream()`, described above, which just streams files, but will first call this method, if provided, to
72 support custom streaming. This method is described in more detail below.
73* **serverExtender**: This method is called as soon as the server is created, so that the caller can do
74 additional things with the server (like attach to certain events, for example). This method is described in more
75 detail below.
76
77##urlPathProcessor()
78Provide this method if you need to do custom processing of URL paths. That is, custom mapping of URL path to local file path.
79The signature of this method is as follows:
80
81``` js
82urlPathProcessor(urlPath, request, response, do302, do404)
83```
84
85Parameters:
86
87* **urlPath**: The URL path to process. It is the value of `url.parse(request.url).pathname`.
88* **request**: The server request object.
89* **response**: The server response object.
90* **do302**: A helper method to do a 302 HTTP response (redirection). It takes a single parameter - the URL to redirect to.
91* **do404**: A helper method to do a 404 HTTP response (not found).
92
93Return value:
94
95Broadly, there are three possible actions you can take in your `urlPathProcessor` handler:
96
971. You completely handle the request (presumably by doing some sort of response and ultimately calling `response.end()`.
98 In this scenario, you should return `null`.
992. You have mapped the URL path to a custom local file path. In this scenario, you should return `{filePath: <value>}`,
100 where `<value>` is the local file path.
1013. You have determined you don't need to do any custom processing and will let cordova-serve to its default mapping. In
102 this scenario, you should return `{filePath: null}`.
103
104##streamHandler()
105Provide this method if you wish to perform custom stream handling. The signature of this method is as follows:
106
107``` js
108streamHandler(filePath, request, response)
109```
110
111Parameters:
112
113* **filePath**: This is the path to the local file that will be streamed. It might be the value you returned from
114 urlPathProcessor(), in which case it doesn't necessarily have to reference an actual file: it might just be an
115 identifier string that your custom stream handler will recognize. If you are going to end up calling `sendStream()`,
116 it is useful if even a fake file name has a file extension, as that is used for mime type lookup.
117* **request**: The server request object.
118* **response**: The serve response object.
119
120Return value:
121
122Return `true` if you have handled the stream request, otherwise `false`.
123
124##serverExtender()
125
126If you provide this method, it will be called as soon as the server is created. It allows you to attach additional
127functionality to the server, such has event handlers, web sockets etc. The signature of this method is as follows:
128
129``` js
130serverExtender(server, root)
131```
132
133Parameters:
134
135* **server**: A reference to the server (the result of calling `http.createServer()`).
136* **root**: The file path on the local file system that is used as the root for the server (if it was provided), for
137 default mapping of URL path to local file system path.
138