@bemobile/fusion-server
v5.2.8
Published
BE-Mobile
Downloads
81
Readme
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
, ormenuItem: { /* options */ }
. - Your module will make the routes that are marked with
offline: true
oroffline: '<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 import
ing 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 layoutsame
: Replace the topmost levelnew
: 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.