Installing a Module

This guide will help you install a module from the Module Marketplace using the pos-cli. It is also possible to Install a Module using the Partner Portal Module Marketplace UI.

Module Installation using pos-cli

To install a module, go to the root directory of your project and type pos-cli modules install <module name>. For example, to install the core module, use the following command:

pos-cli modules install core

You can find a list of available modules in the Partner Portal Module Marketplace. You can also read more about the official platformOS Modules, which have been developed by platformOS employees to help you build new applications on platformOS without worrying about the basics.

installing a specific version of a module

If you would like to install a specific module version, you can use similar syntax to npm — by adding @ followed by the desired version number. For example, to install the core module version 1.5.1, use:

pos-cli modules install core@1.5.1

✔ Added module: core@1.5.3 to app/pos-modules.json
✔ Modules lock file updated: app/pos-modules.lock.json

We will explain those two files in a next sections.

pos-modules.json and app/pos-modules.lock.json

platformOS keeps tracks of the modules that should be installed using pos-modules.json files. When you use the pos-cli modules install command, we will automatically add entry to the pos-modules.json file with the current version. It is equivalent to npm's package.json file. You can modify this file manually as well. We recommend that all modules follow semantic versioning

You can use both ~ and ^ before a module version.

~ will increment the patch version. For example, ~1.2.3 will use releases from 1.2.3 to < 1.3.0.

^ will increment both the patch and minor versions. For example, ^1.2.3 will use releases from 1.2.3 to < 2.0.0.

An example pos-modules.json file might look like this:

{
  "modules": {
    "core": "^1.5.0",
    "user": "^2.0.0"
  }
}

The pos-modules.lock.json is equivalent to package-lock.json and should not be manually modified. It will be automatically generated and will lock compatible module versions, respecting their defined dependencies. Its purpose is to ensure that modules are not accidentally or automatically upgraded without explicit action.

Downloading module source code

The pos-cli modules install command only adds an entry to the pos-module files. When you deploy your application, the lock file is included in the release. If there are any changes required (for example, if you've added a new module or changed the version of an existing module), we will download the source code of the module (including the private folder).

However, most of the time you will want to download the source code anyway — either to avoid platformos-check errors/warnings about missing files, or to browse the source code. You can download the source code using the pos-cli modules download command. For example, to download the source code of the core module, use:

pos-cli modules download core

The zip archive with the source code will be automatically downloaded and unzipped in modules/<module name>. Please note that it will not include any files from the private directory though.)

You should never modify any files in the modules/<module name> directory — see Overwriting a module file to learn the recommended approach for modifying a module file.