NAME
bb-serve - Standalone widget development
SYNOPSIS
bb-serve [--help] [-v|--version]
bb-serve project [--help] [--prebuilt <paths>] [-x --exclude <node-glob>]
[--exclude-defaults] [-t|--template <path|node_module>] [--template.<var> <template-variable>]
[--serve-plugins <path|node_modules>] [-b|--build-plugins <path|node_modules>] [--port <port>]
[--host <host>] [--proxy <proxy>] [--proxy-path <path>] [sources...]
OPTIONS
Option | Description |
---|---|
-v, --version | output the version number |
--help | Output usage information |
COMMANDS
NAME
bb-serve project - Serve widgets in a standalone server
SYNOPSIS
bb-serve project [--help] [--prebuilt <paths>] [-x --exclude <node-glob>]
[--exclude-defaults] [-t|--template <path|node_module>] [--template.<var> <template-variable>]
[--serve-plugins <path|node_modules>] [-b|--build-plugins <path|node_modules>] [--port <port>]
[--host <host>] [--proxy <proxy>] [--proxy-path <path>] [sources...]
DESCRIPTION
The build process is as follows:
- Sources are found by globbing for model.xml files.
- Unbuilt sources are built with webpack using the model.xml as the entry file.
- If there is a 'path' property in the model that will be used as the entry point.
- Otherwise the default entry points are used (scripts/index.js).
- The files are built to a memory file system using webpack dev server.
The prebuilt paths are the paths which simply contain items which don't need to be built with webpack (or are dependencies, and have already been built).
Any paths given will be merged with the default set of paths to search:
- node_modules
- bower_components
- target/backbase
- target/vendor
OPTIONS
Option | Description |
---|---|
--prebuilt <paths> | Comma separated paths to prebuilt items (items that don't require a webpack build). These will be merged with the defaults (see DESCRIPTION) |
-x --exclude <node-glob> | Comma separated paths/globs to ignore (relative to sources) |
--exclude-defaults | Exclude prebuilt defaults |
-t, --template <path|node_module> | Path to page template to use, or name of node modules to use for page template. |
--template.<var> <template-variable> | Inject variables into handlebars page template. Refer to the docs for the template for supported variables |
--serve-plugins <path|node_modules> | Comma separated list of files or node_modules to load as middleware plugins for the server |
-b, --build-plugins <path|node_modules> | Comma separated path/node modules to use for building |
--port <port> | Port to start server on |
--host <host> | Host to listen on |
--proxy <proxy> | Proxy to use for --proxy-path requests (comma separated for multiple) |
--proxy-path <path> | Path to pass to proxy (comma separated for multiple) |
--help | Output usage information |
MIDDLEWARE
You can also write middleware plugins to modify the default behaviour of the express server.
The plugins are loaded as node modules. They must export 'default' as a factory which is called during the setup phase of the webpack dev server, and are passed a config object with the following properties:
- builtItems: Array of CXP Item Objects which have been built
- prebuiltItems: Array of CXP Item Objects where were dependencies (prebuilt)
- template: The page template file used for the request
- webpackCompiler: The webpack compiler used for the build
The factory must return the middleware function. The middleware function takes an express app as its only param, and can then do whatever you like.
EXAMPLE MIDDLEWARE
This middleware (on node v6) listens to the /debug path, and outputs debugging info:
module.exports = ({builtItems, prebuiltItems, template}) => (app) => app.get('/debug', (req, res) =>
res.send(`<pre>
template loaded: ${template}
built items: ${JSON.stringify(builtItems, null, 2)}
prebuilt items: ${JSON.stringify(prebuiltItems, null, 2)}
</pre>`
));
PAGE TEMPLATES
By default all requests through /widget-*
are routed to the widget's index.html file.
It's possible to change this behaviour by providing a --template option to be loaded instead.
If you have access to Backbase's blank template, you can install it and it will render the widget with the CXP portal client.
When you provide the --template option, the path to the template will also be used as the contentBase for any requests for static files.
Unless you have a very simple widget, it's recommended to install and run with the blank template. Check the Backbase docs for the correct path to install.
npm install -g path-or-uri-to-template-blank-template
PROXIES
You can configure a proxy to route all requests from "--proxy-path" to "--proxy". For example you can configure to proxy requests from /v1 to http://localhost:3030/. This is useful for developing against REST services and can be configured with the --proxy and --proxy-path options.
URL PARAMS
Any URL params you add to the request will be used to create preferences in the widget's model.xml.
For example, to set a property 'limit' to '5', just request: http://localhost:3003/widget-my-widget?limit=5
You can also set the locale param in the URL to switch the widget's locale property. With the default config-bb-locale implementation this provides an easy way to test switching locales: http://localhost:3030/widget-my-widget?limit=5&locale=nl
EXAMPLES
Serve from the current directory with blank template (see above note about installing the template first):
$ bb-serve project --template blank
Serve multiple source directories on a custom port:
$ bb-serve project widget-addressbook widget-accounts --port 3333
Customise the prebuilt/exclude options:
$ bb-serve project . --exclude '**/bower_components/**' --prebuilt ./target
Exclude prebuilt defaults:
$ bb-serve project . --exclude-defaults --prebuilt ./target
Provide custom middleware plugins and page template:
$ bb-serve project --serve-plugins ./plugins/rewrite.js,./plugins/debug.js --template ./standalone/index.html
Route to a custom proxy (overrides default proxy settings). This will route /api requests to my-api.com and /foo requests to my-foo.com.
$ bb-serve project --proxy-path /api,foo --proxy http://my-api.com/rest,http://my-foo.com
ENVIRONMENT VARIABLES
Set the amount of log output
LOG_LEVEL=silly|verbose|info|warn|error
Set whether or not to use colors in output
COLOR=false|true