@bemobile/fusion-server v5.2.7

BE-Mobile Fusion Server

Javascript Utility library to conveniently build a Fusion web server with nodeJS.

Usage

prerequisites

You will need nodejs (Node LTS version 20 required) and git installed. To consume your server, you will need a BE-Mobile Fusion Client (the client can be downloaded from our customer portal. Ask our team to request access.)

Quickstart

You can generate a new project with some demo content by executing

npx @bemobile/fusion-server@latest create <project-name>

This command will do a few things:

• Create a new directory <project-name> with a simple barebone project.
• Install @bemobile/fusion-server as npm dependency
• Instantiate a git repository with an initial commit

You can now change into the directory and start the server:

cd <project-name>
npm start

Manual Installation

Add the package to the project

npm install @bemobile/fusion-server

Then, add a "start" script to your package.json:

{
    "scripts": {
        "start": "fusion start",
        "translations:collect": "fusion translations:collect"
    }
}

Project structure

config

The application will look for a fusion.config.ts in your project root.

We recommend adding at least an initialize callback. These locales can also be moved to an external module. See the generated project for an example.

To see all your available options, see the well documented FusionConfig interface.

import { FusionConfig } from '@bemobile/fusion-server';

const config: FusionConfig = {
    initialize: async ({ headers }) => {
        const { authorization } = headers;
        if (/^Basic /.test(authorization)) {
            const [username, pw] = new Buffer(
                authorization.replace(/^Basic /, ''),
                'base64'
            )
                .toString('utf8')
                .split(':');
            if (pw === 'secret') {
                return { username, locale: 'de' };
            }
        }
        return { username: null, locale: 'en' };
    },
};

export default config;

modules

Pages are organized in so-called modules. The directory the modules are searched for is ./modules by default, but can be configured in the config.

A module is either a simple .ts file, or a directory with an index.ts file.

In the simplest case, your module will include routes:

import { Module } from '@bemobile/fusion-server';

const Demo: Module = {
    routes: {
        Action: {
            menuItem: true,
            handler({ fusion }) {
                const page = fusion.addPage('Sound').setTitle('Sound');
                page.setBackAction().home();
            },
        },
    },
};

export default Demo;

Your module file (either <modulename>.ts or <modulename/index.ts>) will have to default export a module record of type Module.

A module will make sure:

• Your module's routes are being made available to the webserver, as well as listed in your project's routes.ts
• Your module will get a section in the main menu, listing all routes that are marked with menuItem: true, or menuItem: { /* options */ }.
• Your module will make the routes that are marked with offline: true or offline: '<offline-setting>' offline available, including them in the offline menu if they have a menuItem setup.

If your routes are more complex, we recommend putting the handlers callbacks into own files, referencing in a module directory by importing them.

routes

A fully-configured route would look like the following:

{
  routes: {
    Action: {
      path: '/custom-path',
      menuItem: {
        icon: 'InterfaceEssential.Alert.AlarmBellRing',
        color: '#de1c66',
      },
      offline: true,
      level: 'same',
    },
  },
  // ...rest of the module
}

MenuItem

Set menuItem to a configuration record, on which you can set icon (see our documentation for possible values), title, color, and large.

Setting menuItem to true will set default values for the menuItem.

Offline

Set the offline property to make your route available offline.

Possible values are:

• true: The page will be refetched every time the route handler has changed.
• home: The page is shown on the offline menu. It will be refetched every time.
• revalidate: The page will be refetched every time.
• <some-number>: The number represents the page 'version number'. The page will be refetched every time the version number changes.

level

By default, the whole view will be replaced when the handler is called. The level property allows you to just replace the topmost level (eg a dialog), or to just create a new level (eg a dialog) on top of the existing layout.

Possible values are:

• base: Replace the whole layout
• same: Replace the topmost level
• new: Add a new level ontop

Path

You can replace the autogenerated path in the webserver. The default path is /<module-name>/<route-name>. Replacing this value should be necessery only in the rarest case.

route manifest generation

For routing in your application, you have to know the path which the webserver will serve the page on.

The fusion-server provides you with a routes manifest in your project's root.

import { RouteHandler } from '@bemobile/fusion-server';
import { routes } from '../../routes';

export const MyRouteHandler: RouteHandler = ({ fusion }) => {
    const page = fusion.addPage('MyRoute').setTitle('My Route');
    page.setBackAction().home();

    page.addButton('Go to next page')
        .placeElement()
        .onConfirm()
        .request(routes.MyModule.MyOtherRoute);
};

Translate your project

The NodeJS BE-Mobile Fusion Server provides built-in support for translations via GNU gettext.

Collect translatable strings

In order to mark a string as translatable text, use the _ function, which is provided to route handlers and menuItem callbacks:

import { Module } from '@bemobile/fusion-server';

const TranslationExample: Module = {
    routes: {
        Action: {
            menuItem: ({ _ }) => ({
                title: _('My first fusion module'),
            }),
            handler({ fusion, _ }) {
                const page = fusion.addPage().setTitle(_('Welcome'));
                page.setBackAction().home();
            },
        },
    },
};

export default TranslationExample;

Per default, texts which have not been translated – as in this case – will just be returned as is. This allows you to write your texts just like you want them to be displayed in your default language, taking care of the translations later in the development cycle.

In order to collect all translatable strings, execute

npm run translations:collect

This command will collect all translatable strings and write them into the ./translations directory. It will update the definitions file ./translations/definitions.pot and every <locale>.po file found in that directory.

Translate your strings

Create a new locale

All your translations are saved in the ./translations directory in the po file format as <locale>.po (eg german should be saved as de.po).

In order to create a new locale, just copy the definitions.pot file and save it to de.po. From now on, the translations:collect command will also update the strings available in de.po.

Now, open the de.po file and add translations for the strings that have been found (in the example above, that would be My first fusion module and Welcome). You can open the po file either in your text editor, or use specialized software, like poedit or lokalize.

Make sure the locale in the initialize handler of your fusion.config.ts is set to de to see the translations in effect.

Deployment

Deploy via pm2

pm2 is a tool that monitors nodejs applications and restarts applications stuck in a failed state.

The BE-Mobile Fusion Server supports being started over pm2 in order to ensure production-grade stability.

After installing pm2, use the following command to start your server instance:

pm2 start --name my-fusion-app ./node_modules/@bemobile/fusion-server/bin/fusion.js -- start

pm2 provides a multitude of options. See their documentation to get more information.