Developing a new Module

This guide will help you develop and publish a new module.

Developing a standalone Module

General guidelines

We recommend treating each module as a standalone application. Thanks to the Module Directory Structure, you can deploy your module to a platformOS Instance.

In this repository, we recommend creating an example application that uses your module in the app directory. This directory will not be part of the module, but it can serve multiple purposes — such as writing end-to-end (e2e) tests for the module, or adding sample code to make it easier for developers to integrate your module.

For consistency, we recommend using the best practices, conventions, and architecture patterns introduced in the Core Module.

Defining a module using template-values.json

What distinguishes a regular platformOS application from a module is a template-values.json file. You can place it either in the project root directory, or in the modules/<your module name>. We recommend choosing the first option.

An example template-values.json file looks like this:

{
  "name": "Pos Module Core",
  "machine_name": "core",
  "type": "module",
  "version": "1.5.3",
  "dependencies": {}
}

key	description
name	it's a name that will be displayed in the Partner Portal Module Marketplace
machine_name	this should correspond to the namespace that you will use for your module; if you choose foo as a machine name, we expect to find files in modules/foo directory, and the content of this directory will be released as a module archive. Partner Portal will ensure that your chosen machine_name is globally unique, to avoid module conflicts.
version	specifies the current version, used by pos-cli modules push to release a new module version
dependencies	you can define dependencies here, in a way similar to how they are defined in app/pos-module.json, for example if you would like to add core module as a dependency in version ≥ 1.0.0 and < 2.0.0 you would use "dependencies": { "core": "^1.0.0" }

Creating a new module in Partner Portal

Currently, it is not possible to create a new module using pos-cli — you can only push a new release to an existing module. This means that to create a new module, you need to go to the Partner Portal Module Marketplace and use the Partner Portal's UI to create a new Module.

Releasing a new module version

Once you create a new module version in the Partner Portal Module Marketplace, you can easily release it. To do so, bump the version in template-values.json based on semantic versioning (most importantly, increment the major version if you are making a backward-incompatible change). After this, you can push the new version:

pos-cli modules push --email <your partner portal email>

We will ask for your password to authenticate. If successful, the content of the modules/<machine name> directory will be zipped (and stored in the tmp directory if you would like to review it). It will include all directories, allowing you to include source code for your frontend assets, for example, or generators to make it easier to use your module.

All Partner Portal users who have at least one instance using your module will be notified by email about a new release.

Releasing a beta version of a module

If you don't want your new version to be a default version, you can also mark it as a beta version. It will still be possible to install it using pos-cli modules install by specifying the exact version of the module. To mark a version as a beta release, add -beta.<version>, for example:

"version": "2.0.0-beta.1"

You can then update it to beta.2, beta.3, and finally make a proper release by removing -beta and setting the version to 2.0.0.