Module Dependencies
Author:
Marco Heuer
Changed on:
4 Apr 2025
Overview
Learn how module dependencies work, how they are described and when they are enforced.
Key points
- Module dependencies are declared in
`resources/module.json` - Format follows the NPM Semver layout
- Fluent CLI enforces dependencies during the module installation, more info in the CLI Reference
- Fluent CLI becomes module version aware as of v1.0.2
Why use dependencies?
To structure and group distinct business functionalities and release them independently of each other, we need to define, declare and enforce compatibility between their packages. Fluent Modules do this by declaring the Modules and the versions - or version ranges - in their
`module.json`This can be as simple as defining a dependency on the Fluent Core Reference Module, as the Order Reference Module does:
1{
2 "_schema": "1.0.0",
3 "name": "fluent-commerce/order",
4 "version": "1.3.0",
5 "title": "Order Reference Module",
6 "authors": [
7 {
8 "name": "Fluent Commerce",
9 "email": "info@fluentcommerce.com",
10 "web": "https://fluentcommerce.com"
11 }
12 ],
13 "dependencies": [
14 {
15 "name": "fluent-commerce/core",
16 "type": "module",
17 "version": "^1.0.0"
18 }
19 ],
20 "contracts": []
21}Language: plain_text
Name: Order Reference Module's module.json
Description:
Core Module > 1.0.0 and < 2.0.0 dependency declared
In this example, the Order Module says it requires Core Module version
`1.0.0``2.0.0``>= 1.0.0``< 2.0.0`Defining Module Hierarchies
Declaring module dependencies allows for defining module hierarchies, where each module defines their next-level dependencies.
Consider this example of a hierarchy: starting with a top-level data module that contains only the inventory data, named
`b2c-sample-data-inventory``b2c-sample-data`Visually, it would look similar to this:
In subsequent pages we will describe in more detail how to think about and design such module hierarchies and their tradeoffs.
Semver Versioning Scheme
Modules adopted the widely used semantic versioning scheme, or semver for short, in the current version 2.0.0. Find more information on Semver on their site. More specifically, the Fluent CLI uses Node's Semver implementation as described, here.
Notable is the support for advanced range operators, such as
- Hyphen ranges, eg. :=
`1.2.3 - 2.3.4``>=1.2.3 <=2.3.4` - X-ranges, eg. :=
`1.x``>=1.0.0 <2.0.0-0` - Tilde ranges: Allow patch-level changes if a minor version is specified on the comparator. Allow minor-level changes if not. Eg. :=
`~1.2.3`:=`>=1.2.3 <1.(2+1).0``>=1.2.3 <1.3.0-0` - Caret ranges: Allows changes that do not modify the left-most non-zero element in the tuple. Eg.
`[major, minor, patch]`:=`^1.2.3``>=1.2.3 <2.0.0-0`
These provide ample flexibility in specifying dependent module versions or version ranges.
In the example above, the Order Module declared a dependency on the Core Module
`^1.0.0``>=1.0.0``<2.0.0`Inspecting Module Versions
To find out which modules are installed in an account, including their versions, one can use the Fluent CLI command
`fluent module list -p <profile>`For example:
1$ fluent module list -p acmeprofile
2┌───────────────────────┬─────────┬──────────────────────────┬───────────────┐
3│ name │ version │ performedOn │ performedBy │
4├───────────────────────┼─────────┼──────────────────────────┼───────────────┤
5│ fluent-commerce/core │ 2.0.0 │ 2025-04-04T22:15:19.756Z │ account_admin │
6│ fluent-commerce/order │ 1.3.0 │ 2025-04-04T22:23:35.800Z │ account_admin │
7└───────────────────────┴─────────┴──────────────────────────┴───────────────┘Language: plain_text
Name: Listing of modules in an account
Description:
Example output with two modules installed
