@bb-cli/bb-serve

Standalone widget development

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
@bb-cli/bb-serve
Minified + gzip package size for @bb-cli/bb-serve in KB

Readme

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

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.