This page is the console walkthrough. For a task-by-task guide, see Working with modules. For what connected and hosted mean, see Types of modules. To build a module of your own, start with Create your own module. The full developer reference — the manifest, the signed envelope, the install token, events with retries, packages and the lifecycle — is the Modules section.
A module is a connector or a feature the platform does not ship — an ERP sync, an accounting export, a reservation system — packaged as a manifest plus code that runs on the module's own host. The platform calls it with signed requests and it calls the platform back with a scoped token of its own; nothing it does runs inside the console. A module is either connected (the client hosts the code — on any HTTPS host, or deployed by the platform into the space's own cloud) or hosted on the platform's module runner; the platform holds the contract either way. An Elements module is the lightweight third kind: only an element library — its elements plus their shared CSS and script — with no code that runs anywhere, no token, no events and nothing to configure (see Elements modules below).
The Modules area#
Modules is its own area on the rail, before Settings. Its pane has two pages — Catalog (visible to a manager, or to any member whose develop capability is at least readable) and Upload package (platform admins, and developers submitting for review) — and an Installed block: one row per installed module with a health dot (ok / not configured / failing; a disabled module is dimmed) that opens its page. Every change to a module — install, configure, enable, update, uninstall, a key reroll — lands in the project's Activity feed with the module id and the field names touched, never a value.
Catalog#
The Modules page lists the project's installed modules as a table (version, hosting, the status chip: not configured, unverified, verified {date}, failing, disabled) and the catalog as cards grouped by category behind a chip row. Next to the categories, the Elements chip shows only the modules that bring element libraries (the Elements page's Explore elements in Modules opens the catalog with it on; the address keeps ?kind=elements, so the filtered view can be shared); each such card says how many elements it adds. What a project sees is the platform's public packages plus the packages published for its space; each card carries its category, its hosting and who it is published to (Private for your space's own packages, Public catalog for the platform's). The project's plan decides what it may install — Tier 1 connected modules, Tier 2 and up hosted ones too, up to ten per project (Elements modules need no module feature and don't count towards the ten; the plan's Elements modules line says how many it allows) — and a card the plan does not admit reads Needs a higher plan instead of Install. A card's Install opens the upload page in install mode, at the Grants step — the module's route and path grants are shown read-only and accepted explicitly before anything touches the project. An installed module with a newer version shows Update to {version} on its card.
Documentation#
Every module carries its own documentation — what it does, how to set it up and what uninstalling keeps. Open a catalog card's Documentation button (or the same link on the Grants step) to read it before installing; an installed module shows it on its page's Documentation tab. It appears in your console language when the module is translated, otherwise in the module's default language. Modules published before documentation was required show an empty page until their next version.
Upload package#
Four steps on one page: pick the zip → check → grants → install or update. The browser pre-flights the package before it leaves (archive listing, the manifest rules, size caps — the same row ids the server emits), then the bytes go up and the check report comes back: rows grouped by level, the measured block, and on a later version the diff (grants widened, schema fields removed, egress hosts added). An error keeps you on the report; a warning is shown and the flow continues. A package without documentation (README.md, or docs/cs.md / docs/en.md) is refused. The last step is one button — Install on {project} or Update {project} to {version}. An Elements module has no grants: its last step is Elements — how many elements the package adds and from which kits — with a plain Install (or Update) button. A platform admin's upload for a space is published at once. A developer (an account with the developer role, a member of the project) can upload too: the package is submitted for review and becomes installable in the space once a platform admin approves it in Module review. Installing, configuring and updating stay with the project's managers.
Modules that run in your space cloud. Some modules have no server of their own: the platform deploys them as a function into your space's cloud (the Firebase project connected under Space → Cloud). Their Grants step reads Runs in: your space cloud instead of an endpoint. Installing or updating one first builds that function — the page switches to a Deploying card with the state (Queued, Building, Ready — installing), the function's name and the project, and checks every 15 seconds; the module installs itself as soon as the function is ready, usually within a few minutes, and you may leave the page meanwhile. If the build fails the card shows the error and Try again. If your space has no cloud connected, or its key may not deploy functions, the install stops with a message saying so. Uninstalling such a module removes its function too.
Module review (platform admins)#
Packages uploaded to the platform catalog, and the packages developers
submit for their space, wait for a review before any store can install them. Platform admins find them under Modules → Module
review (/platform/modules): one card per version with its automated
check report (including the dry run on the module runner), the uploader's
notes, the hosts it may call, and Open in sandbox links for its admin
pages. Approve publishes it (installs that follow updates automatically
move to it on the platform's next update pass unless its grants widened, which a
manager then accepts on the module card); Reject needs a note, shown to
the uploader. A version visible to all stores needs a second reviewer —
not the person who uploaded it. Check again re-runs the checks without
changing anything. A master can Yank a version: every store running it
stops using the module at once and sees the reason on the module card, with
an Update to the previous version.
Hosted and platform modules run on the platform's module runner — they have no endpoint of their own, install without a handshake, and their admin pages are served by the console itself.
The module page#
A header (name, status and hosting chips, version, the Enabled switch) over the tabs Overview · Elements · Gallery · Documentation · Data · Logs · Grants (Elements only for a module that adds something to the storefront, Gallery only for one that ships elements). Gallery renders every element of the module with its sample content on your project's design, the same specimen wall as the Elements page's Gallery, with Open in Elements on each one. Overview holds the Update available card (release notes, the grant diff, Review and update), the Configuration card (the module's own fields; secrets are write-only with a set indicator; Save, and Verify to have the module confirm its configuration) and the Health table, one row per point the platform calls. The right rail: About (vendor, category, source, installed by / at, the endpoint — or, for a module the platform deployed into your space cloud, the Deployed function (its URL, project and version) — a drift notice when the module reports a newer version than the one installed), Data it owns (its collections and state), Pages & widgets (the pages a connected module adds to the console — each opens inside the console on the module's own origin, signed in as you for five minutes at a time; who may open a page is set by the module: each page names the capability it needs — commerce, content, community, web or develop, develop when it names none — and a member with at least read access to that capability opens it, from its link, the Data area or a Home pin, even without develop. A page that supports it keeps its place in the console address, so reloading or sharing the link reopens it where you were. A page may also ask for the project's team list — the members' names, e-mails and roles, including the space's owners and admins — so it can offer assignees or mentions; the module is told this list each time the page signs you in; members who have not created their account yet are not on it), Identity (the managed token, the hook entry, Reroll keys) and the Danger zone — Uninstall · keep data or Uninstall · purge, which also removes the module's collections, records and fields. Both remove the elements the module added (below). Logs lists the deliveries the platform is retrying or gave up on; Grants shows the installed version's trees read-only. An Elements module's page is shorter: tabs Overview · Elements · Gallery · Documentation; its Overview opens with a Design system card that says whether the project has a design system — the module's elements take their colours, fonts and shapes from it, and fall back to the module's own neutral look until one is created (Create design system takes you there) —, no configuration, health, data, pages or identity, no Verify or Reroll keys; About shows its element count, and the danger zone has a single Uninstall (there is no data to keep or purge).
Module elements#
A module with a storefront side adds ready-made elements to the project's library — a booking calendar, a form, a list — and keeps them up to date. The module page's Elements tab lists them in a table with a state per element:
- As shipped — identical to the module's version; a module update replaces it.
- Customized — you edited it in this project. Your edits are kept: module updates skip the element. Reset to module version (managers) discards the edits and makes it follow the module again.
- Conflict — an element of yours already used the same id, so the module's element was not installed; Replace with the module's element overwrites yours.
- Missing — the element is no longer in the library; Restore puts it back.
Edit opens the element in Studio › Elements; Duplicate makes a copy that is yours — updates never change it. Build a new element starts a new element bound to the module: by hand or with the Studio assistant, it can use everything the module offers on the storefront (the module's element guide describes how). Your duplicates and new elements are listed under Your elements using this module.
Under the table, the Preview shows each element as it will look on your site — on the project's design and with the module's real data (your resources, services, free times). Pick an element with its tab or with Preview on its row, switch between the full, tablet and phone widths, or open it full screen. The preview only reads: a button that would send something, such as Book, does nothing here. An element that depends on what a visitor did before — a booking form for a time picked on another page, a visitor's own reservations — shows its empty state. The same live preview is used in Studio › Elements and its Gallery.
All of these elements share the stylesheet and script the module provides; they load automatically on pages that place one of its elements — the stylesheet before the elements' own CSS, the script before their own scripts — and cannot be edited. Pages without any of the module's elements are untouched. The previews in the console use the same stylesheet and script.
Elements modules. A module that is only an element library (a design system's components, a set of page sections) installs without grants, runs no code on the platform and has nothing to configure — its page has just Overview, Elements and Documentation. Everything else in this section applies unchanged: its elements are pristine or customized, updates skip what you edited, disabling hides them (and its shared stylesheet) on the site, and uninstalling removes them.
Disabling a module makes every placement of its elements — the module's own and yours built on it — render nothing on the published site within seconds; the Studio preview shows a "module disabled" note in their place, and the element picker stops offering them. Enabling the module brings them back. Uninstalling (keep data or purge) removes the module's own elements from the library, so pages that placed them show nothing there; your duplicates and new elements stay in the library, editable, but render nothing until the module is installed again. A module update that drops an element you customized leaves your version in the library as your own.
Needs the develop capability to see; mutations are manager actions (editing elements needs web).
Provider modules#
Some modules provide a service the platform otherwise does itself — a carrier (shipping), an invoicing system, a payment gateway or an order processing system (an ERP or warehouse). Their documentation says which. A provider module becomes selectable where the project picks that service — a carrier module in the carrier list of Settings › Carriers › Delivery methods — only once it is enabled and verified (configure it, then Verify on its page); until then it is listed but greyed out with the reason (module disabled / not verified), and the API refuses the choice the same way.
Disabling a provider module first checks what depends on it and lists it in the confirmation: orders with an open shipment through the carrier, orders with an open payment, the module being the project's invoicing provider or order processor, orders still waiting for a call to it. Disabling still goes ahead when you confirm — those calls then fail until you enable it again. Uninstalling is refused while any of these is true (the message names the orders); finish or cancel them, or switch the project to another provider, first. An update that would drop a service the project is using (for example a version that is no longer a carrier while a delivery method uses it) is refused the same way.
The fields a provider module keeps on orders and invoices (its records, the pending call state) are managed by the platform: the console shows them read-only, and an edit that would change them is refused (managed by the provider). Carrier modules follow the project's plan like every other module: when the plan no longer admits the module, its calls are refused.