Weblutions Documentation
Weblutions Main Site Contact Us Our Discord
FaxStore IconFaxStore

App Manifest & Packaging

By Josh M. 5 mins 2

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


Manifest Options

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

backend

apps/

JavaScript (or .sharf) for routes and other server code. Folder paths are kept, so myapp/routes.js installs to apps/myapp/routes.js.

css

public/themes/

Theme style sheets. Folders are removed from the path. The first file becomes the store's theme, so only use this for themes.

ejs

src/views/apps/

Page views. Folders are removed from the path. Prefix the file names with your app name, e.g. myapp-settings.ejs.

js

public/assets/

Browser scripts and other public files, served from /assets/. Folders are removed from the path.

npm

FaxStore's node_modules

npm packages the app needs that aren't already in FaxStore's package.json.

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.


Example

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"]
}

Packaging the Zip

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.ejs

Keep file names unique to your app, for example by starting them with your app's name, so they don't clash with other apps.


How Installing Works

When a store owner installs an app from the staff panel, FaxStore:

  1. Downloads the app zip from the App Store.

  2. 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.

  3. 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.

  4. 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.

  5. Restarts FaxStore on Linux servers so the app loads straight away. On other systems the owner is asked to restart FaxStore.


How Apps Are Loaded

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.


Using Other Apps

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.


Server Features for Apps

Apps can use these from the Express app:

Setting

Use

app.get('httpServer')

FaxStore's HTTP server, e.g. to attach socket.io: new Server(app.get('httpServer')).

app.get('sessionMiddleware')

FaxStore's login session middleware, e.g. io.engine.use(app.get('sessionMiddleware')) so sockets know who's logged in.

The session holds the logged in user at session.passport.user. Look the user up in the users table before trusting their permissions.