Working with modules

A module adds something the platform does not ship to one project: a carrier, an accounting or invoicing connection, a payment gateway, a booking system, a CRM or newsletter sync, extra admin pages and widgets. This page is for the people who run a project: how to find a module, install it, set it up, keep it updated and remove it. Building one of your own is covered in Create your own module.

Everything below happens in the console's Modules area (the rail item before Settings). The full screen-by-screen tour is Console › Modules.

Who can do what#

The project's plan decides whether modules can be installed at all, which kinds, and how many (up to ten per project). A card the plan does not admit reads Needs a higher plan instead of Install.

1 Find a module#

Open Modules › Catalog. The cards are grouped by category (shipping, payments, accounting, booking, …) behind a chip row. Each card shows:

• its category and hosting (where its code runs — see Types of modules);
• who it is published to: Public catalog (the platform's modules, available to every project) or Private (your space's own packages);
• Documentation — what it does, how to set it up and what uninstalling keeps. Read it before installing.

2 Install it#

Install opens the install flow at the Grants step. It lists, read-only, what the module will be allowed to do in your project: which API routes it may call and which data paths it may read or write. Nothing touches the project until you accept.

What happens after you accept depends on the module type:

• Hosted and platform modules install immediately.
• Connected modules on their own server first prove the server is theirs (a short handshake). Then they install.
• Modules that run in your space cloud are built and deployed into your space's Firebase project first. A Deploying card shows Queued → Building → Ready — installing. That usually takes a few minutes, and you may leave the page meanwhile. Your space needs a connected cloud (Space › Cloud).

The installed module appears in the Installed block of the Modules pane, with a health dot.

3 Configure and verify#

Open the module from the Installed block. On its Overview tab:

1. Fill in the Configuration card: the account, API key or options the module asks for. Secret fields are write-only; once saved they only show set. Click Save.
2. Click Verify. The module checks its own configuration, for example by signing in to the third-party service, and reports back. The status chip moves from unverified to verified {date}.

Status chips: not configured · unverified · verified · failing · disabled. The Health table lists every kind of call the platform makes to the module, with its last result.

Provider modules (a carrier, invoicing, payment or order-processing module) become selectable where the project picks that service only once they are enabled and verified. For example, a carrier appears in Settings › Carriers › Delivery methods only then. Until that, it is listed greyed out with the reason.

4 Use it#

What a module adds depends on the module. Its documentation says where to find it:

• Admin pages open inside the console. They can be pinned to Home, and some appear in the Data area.
• Cards, buttons and forms sit on orders, products, customers or the module page.
• Overview widgets for the dashboard.
• Content collections under Data, for example a booking module's services and resources.
• Elements for your website. They appear in the element library and on the module page's Elements tab, with a live preview. You can place them like any element, edit them (your edits are kept across updates), or duplicate them. Build a new element creates one of your own on top of the module.
• E-mail templates and translations. They are added only where you don't already have them.

5 Keep it running#

• Enabled (the switch in the module's header): disabling stops every call to the module at once, and its elements render nothing on the website until you enable it again. For a provider module, the confirmation first lists what depends on it (open shipments, open payments, the invoicing provider…).
• Logs tab: deliveries the platform is still retrying or gave up on. Failed event deliveries are retried automatically.
• Identity (right rail): Reroll keys issues the module new credentials. Use it if you suspect a leak.
• Activity: every install, configuration change, update and uninstall is recorded in the project's Activity log, with field names but never values.

6 Update it#

When a newer version is published, the catalog card shows Update to {version} and the module page shows an Update available card with the release notes.

• If the new version needs no new permissions, platform modules move to it automatically. Other modules update when you click Review and update.
• If it asks for more (wider grants), it waits until a manager reviews the grant diff and accepts it on the module card.

An update never overwrites elements you customised.

7 Uninstall it#

In the module page's Danger zone:

• Uninstall · keep data removes the module but keeps its collections, records and the fields it wrote on your orders, products and customers. Installing it again picks them up.
• Uninstall · purge also removes all of that data.

Both remove the module's own elements from the library (pages that placed them show nothing there); your own duplicates stay. A provider module cannot be uninstalled while something still depends on it — the message names the orders. Finish them, or switch the project to another provider, first. A module that ran in your space cloud has its function removed too.

Next#

• Types of modules — what connected, hosted and platform mean, and the kinds of modules there are.
• Create your own module — build, pack, upload and install a module of your own.