FaxStore
Apps uploaded to the FaxStore App Store are zip files with a manifest.json at the top level. The manifest tells FaxStore where each file in the app goes when a store owner installs it from Staff Panel > Apps. This page covers the manifest, how the installer handles each option, and how FaxStore loads apps when it starts.
Table of Contents
Every option is an array of file names, written as paths inside the app zip. Leave an option out, or use an empty array, if the app doesn't need it.
Option | Installed to | Notes |
|---|---|---|
|
| JavaScript (or |
|
| Theme style sheets. Folders are removed from the path. The first file becomes the store's theme, so only use this for themes. |
|
| Page views. Folders are removed from the path. Prefix the file names with your app name, e.g. |
|
| Browser scripts and other public files, served from |
| FaxStore's | npm packages the app needs that aren't already in FaxStore's |
npm packages can be a name, or a name and version: winston, socket.io@4, @scope/package@^1.2.0. Each one must be a valid npm package name. Anything else, like spaces or extra commands, stops the install before any files are written.
The manifest from the Live Chat app:
{
"backend": ["livechat.js", "livechat/service.js", "livechat/routes.js"],
"css": [],
"ejs": ["livechat-inbox.ejs", "livechat-history.ejs", "livechat-configure.ejs"],
"js": [],
"npm": ["socket.io@4"]
}Put manifest.json at the top level of the zip, and every file at the path the manifest lists. For the example above:
livechat-app.zip
├── manifest.json
├── livechat.js
├── livechat/
│ ├── service.js
│ └── routes.js
├── livechat-inbox.ejs
├── livechat-history.ejs
└── livechat-configure.ejsKeep file names unique to your app, for example by starting them with your app's name, so they don't clash with other apps.
When a store owner installs an app from the staff panel, FaxStore:
Downloads the app zip from the App Store.
Checks the package before writing anything. If manifest.json is missing or isn't valid JSON, a listed file isn't in the zip, or an npm package name isn't valid, the install stops and the owner sees what's wrong. No files are written, so an app is never half installed.
Extracts the files to the folders in the table above. If the app has css files, the first one is set as the store's theme.
Installs each npm package with npm, on every operating system. If a package fails to install, the app's files stay installed and the owner sees an orange message with the exact npm install command to run.
Restarts FaxStore on Linux servers so the app loads straight away. On other systems the owner is asked to restart FaxStore.
When FaxStore starts, it runs every .js and .sharf file at the top level of the apps folder as an app:
module.exports = async function(app, connection, bot, faxstore) {
// your app
};Files in folders inside apps/ are not run as apps. Put helper modules in a folder named after your app and require them from your main file, e.g. require('./myapp/routes').
If your app's function throws, or its returned promise rejects, FaxStore logs that the app failed to start and keeps running. In developer mode the error is printed to the console.
Apps load after FaxStore's own routes. Use paths with at least two parts, like /myapp/settings, so FaxStore's single-part page routes (/:page) don't catch them.
Create and update your app's database tables when it starts, with CREATE TABLE and ALTER TABLE checks, rather than asking owners to run SQL.
faxstore.apps.get(id) returns a registered app, or null if it isn't installed. faxstore.getExtension works the same. It also finds apps by name, for apps that don't set an id.
An app shares functions with other apps through api. For example, a Pushover app:
faxstore.apps.register({
id: 'pushover',
name: 'Pushover Notifications',
api: {
send: async function({title, message, url}) {
// send the notification
}
}
}, __filename);Another app can then use Pushover if it's installed, and skip it if it isn't:
const pushover = faxstore.apps.get('pushover');
if(typeof pushover?.api?.send === 'function') {
Promise.resolve(pushover.api.send({title, message, url})).catch(() => {});
}Look an app up when you use it, not when your app starts. Apps start at the same time, so the app you need might not have registered yet when yours starts.
faxstore.apps.has(id) returns true if the app is registered.
A registered app has the options it registered with, plus filename, the name of the file it registered from.
faxstore.apps is the list of every registered app, e.g. faxstore.apps.map(a => a.id).
faxstore.apps.unregister(id) removes an app. faxstore.unregisterExtension works the same.
To register an app with FaxStore see the Registering Apps page.
Apps can use these from the Express app:
Setting | Use |
|---|---|
| FaxStore's HTTP server, e.g. to attach socket.io: |
| FaxStore's login session middleware, e.g. |
The session holds the logged in user at session.passport.user. Look the user up in the users table before trusting their permissions.