Store Module — Types & Registry API - Business Platform Documentation

The Business Platform Store provides a curated catalogue of pre-built modules that can be installed into a project with a single click. This document describes the core types and the registry API that powers the Store.

Core Types

`StoreModule`

Represents a single installable module in the Store.

Field	Type	Description
`name`	`FeatureName`	Unique identifier for the module (matches the underlying feature name).
`label`	`InlineTranslation`	Localised display name shown in the Store UI.
`description`	`InlineTranslation`	Short localised description of what the namespace provides.
`icon`	`string`	URL to the module's icon image.
`version`	`string`	Current published version of the module (semver string).
`tags`	`string[]`	Tag names used for filtering (see `StoreTag`).
`requiredExtensions`	`FeatureExtensionName[]`	Extensions that are always installed with this module.
`extensions`	`FeatureExtensionName[]`	All available extensions (required + optional).
`changelog?`	`StoreChangelog[]`	Optional ordered list of changelog entries, newest first.

Example

const contactModule: StoreModule = {
  name: FeatureName.CONTACT,
  label: { en: "Contacts", de: "Kontakte" },
  description: { en: "Manage your contacts and relationships." },
  icon: "https://img.icons8.com/fluency/96/contacts.png",
  version: "1.2.0",
  tags: ["crm", "function"],
  requiredExtensions: [FeatureExtensionName.CONTACTS_TYPE],
  extensions: [
    FeatureExtensionName.CONTACTS_TYPE,
    FeatureExtensionName.CONTACTS_BOM
  ]
};

`StoreCollection`

A curated bundle of multiple StoreModules, presented as a ready-made starter pack. When a user selects a collection, all listed modules are pre-selected along with a set of recommended extensions.

Field	Type	Description
`name`	`string`	Unique identifier for the collection.
`label`	`InlineTranslation`	Localised display name.
`description`	`InlineTranslation`	Localised description.
`icon`	`string`	URL to the collection's icon image.
`color`	`string`	Accent colour (hex) used in the UI.
`modules`	`FeatureName[]`	Ordered list of namespace names included in this collection.
`preSelectedExtensions?`	`FeatureExtensionName[]`	Extensions that are pre-checked when the collection is applied.

Example

const crmCollection: StoreCollection = {
  name: "crm-pack",
  label: { en: "CRM Pack", de: "CRM-Paket" },
  description: { en: "Customer relationship management with companies, contacts, opportunities and email." },
  icon: "https://img.icons8.com/fluency/96/contacts.png",
  color: "#4F46E5",
  modules: [
    FeatureName.COMPANY,
    FeatureName.CONTACT,
    FeatureName.OPPORTUNITY,
    FeatureName.EMAIL
  ],
  preSelectedExtensions: [
    FeatureExtensionName.COMPANIES_TYPE,
    FeatureExtensionName.COMPANIES_BOM,
    FeatureExtensionName.CONTACTS_TYPE,
    FeatureExtensionName.CONTACTS_BOM,
    FeatureExtensionName.OPPORTUNITIES_TYPE,
    FeatureExtensionName.OPPORTUNITIES_BOM,
    FeatureExtensionName.EMAILS_TYPE,
    FeatureExtensionName.EMAILS_ACTIONS,
    FeatureExtensionName.EMAILS_BOM
  ]
};

Website showcase fields (optional)

These fields power the public product detail page rendered by the Module Showcase Detail widget (/products/<slug>). Every field is optional, and each page section hides itself when its field is empty.

Field	Type	Description
`slug?`	`string`	URL segment for the detail page, e.g. `"real-estate"`.
`showOnWebsite?`	`boolean`	Opt-in flag for website visibility.
`priorityDisplay?`	`boolean`	Opt-in flag for priority placement in the product list.
`marketingDescription?`	`InlineTranslation`	Richer hero copy (falls back to `description`).
`highlights?`	`InlineTranslation[]`	Plain feature bullets — rendered only when `features` is empty.
`features?`	`StoreFeature[]`	Rich feature cards `{ icon, title, description }` (preferred over `highlights`).
`stats?`	`StoreStat[]`	Headline metrics `{ value, label }` shown as a stat strip.
`useCases?`	`StoreUseCase[]`	Persona cards `{ icon, title, description }`.
`testimonials?`	`StoreTestimonial[]`	Social proof `{ quote, author, role?, company?, avatarUrl? }`.
`faqs?`	`StoreFaq[]`	FAQ accordion entries `{ question, answer }`.
`heroImageUrl?`	`string`	CDN URL of the hero banner image.
`videoUrl?`	`string`	CDN URL of an intro/demo video.
`screenshots?`	`StoreScreenshot[]`	Carousel images `{ url, caption? }` — see the warning below.

screenshots and videoUrl must be REAL captures of the actual product. They render under "See it in action" and read as genuine product UI, so AI-generated or mock images would be misleading advertising (a UWG §5 risk in Germany). Capture them from the running backoffice (e.g. via Playwright). The hero/icon images are decorative illustrations and may be AI-generated.

icon (FontAwesome v6 class), the hero illustration and the icon are served from https://cdn.smallstack.com/images/store/…. Generate the decorative hero/icon images with npm run store:generate-collection-image -- <slug>; prompts live in agents/_shared/store-image-prompts.json.

The Powered by these modules section is derived automatically from modules via getCollectionModules(collection) — no extra fields needed; it surfaces each StoreModule's icon, label, longDescription (or description) and color.

`StoreTag`

A classification label used to filter modules in the Store sidebar.

Field	Type	Description
`name`	`string`	Unique identifier for the tag.
`label`	`InlineTranslation`	Localised display name.
`type`	`"industry"	"function"`
`icon?`	`string`	Optional Font Awesome class string (e.g. `"far fa-building"`).

Tags of type "industry" are shown under the Industry heading; tags of type "function" are shown under Function.

`StoreChangelog`

A single entry in a module's changelog.

Field	Type	Description
`version`	`string`	The version this entry describes.
`description`	`InlineTranslation`	Short localised summary of changes.

`InstalledModule`

Recorded on the Project document when a module is successfully installed. Updated in-place when the same module is re-installed or upgraded.

Field	Type	Description
`moduleName`	`FeatureName`	Name of the installed module.
`installedAt`	`string`	ISO 8601 timestamp of first installation.
`installedVersion`	`string`	Version that was installed.
`updatedAt?`	`string`	ISO 8601 timestamp of most recent update.
`updatedVersion?`	`string`	Version applied in the most recent update.
`installedExtensions`	`InstalledExtension[]`	List of extensions that were installed.

`InstalledExtension`

Field	Type	Description
`extensionName`	`FeatureExtensionName`	Name of the installed extension.
`installedAt`	`string`	ISO 8601 timestamp of when this extension was installed.

Store Registry API

The registry is populated at application startup by importing the side-effect module store.init.ts. Once initialised, the following functions are available.

Initialisation

// Import once — typically in your app's entry point or server bootstrap.
import "@smallstack/shared/templates/store.init";

This registers all built-in modules, collections, and tags. After this import the query functions below work correctly.

Module functions

`registerModule(module: StoreModule): void`

Adds a module to the registry. Throws if a module with the same name is already registered.

`getModule(name: FeatureName): StoreModule | undefined`

Returns the registered module for the given name, or undefined if not found.

`listModules(): StoreModule[]`

Returns all registered modules in registration order.

`searchModules(query: string): StoreModule[]`

Case-insensitive full-text search across module name, label values, and description values. Returns matching modules.

const results = searchModules("contact");
// → [contactModule, ...]

`isModuleInstalled(project: Project, moduleName: FeatureName): boolean`

Returns true if the given module has a recorded InstalledModule entry on the project.

`getInstalledVersion(project: Project, moduleName: FeatureName): string | undefined`

Returns the installedVersion (or updatedVersion if an update was applied) for the given module, or undefined if not installed.

`hasModuleUpdate(project: Project, moduleName: FeatureName): boolean`

Returns true when the module's current registry version is greater than the version recorded on the project.

`getModulesWithUpdates(project: Project): StoreModule[]`

Returns all registered modules for which hasModuleUpdate is true. Used to populate the Updates Available banner.

const updatable = getModulesWithUpdates(project);
if (updatable.length > 0) {
  // show StoreUpdatesBanner
}

Collection functions

`registerCollection(collection: StoreCollection): void`

Adds a collection to the registry.

`getCollection(name: string): StoreCollection | undefined`

Returns the collection for the given name, or undefined if not found.

`listCollections(): StoreCollection[]`

Returns all registered collections in registration order.

Tag functions

`registerTag(tag: StoreTag): void`

Adds a tag to the registry.

`getTag(name: string): StoreTag | undefined`

Returns the tag for the given name, or undefined if not found.

`getTagsByType(type: "industry" | "function"): StoreTag[]`

Returns all tags of the given type. Used to populate the Store sidebar sections.

const industryTags = getTagsByType("industry");
const functionTags = getTagsByType("function");

Extension dependencies

FeatureExtension supports an optional requires field that declares other extensions that must be present before this one can be installed.

interface FeatureExtension {
  name: string;
  label: InlineTranslation;
  /** Other extensions that must be installed before this one. */
  requires?: FeatureExtensionName[];
  check: (options: FeatureExtensionCheckOptions) => FeatureExtensionCheckResult;
  execute: (options: FeatureExtensionExecuteOptions) => void;
}

Use resolveExtensionDependencies to expand a user's selection into the full set of required extensions:


import { getFeatureExtension, resolveExtensionDependencies } from "@smallstack/shared";

const resolved = resolveExtensionDependencies(
  [...selectedExtensions],
  getFeatureExtension
);
// resolved.extensions — full set including auto-added dependencies
// resolved.autoAdded  — extensions added automatically due to `requires`

Module installation flow

The user opens Project Settings → Store.
StoreLayout loads all modules via listModules() and filters them by search query, tag, or collection.
The user expands a StoreModuleRow, optionally toggles optional extensions, and clicks Install or Update.

InstallModuleModal builds an ApplyTemplateBody and enriches it with module-tracking fields:

interface ApplyTemplateBodyWithModule extends ApplyTemplateBody {
  moduleName?: string;       // FeatureName of the module being installed
  moduleVersion?: string;    // Version string from StoreModule.version
  installedExtensions?: string[]; // FeatureExtensionName[] of selected extensions
}

A PUT request is sent to /api/projects/[projectId]/extensions.
The server applies the template entities inside a MongoDB transaction, then — if moduleName and moduleVersion are present — writes or updates an InstalledModule record on the project document.
- New install: pushes a new entry to project.installedModules.
- Re-install / update: uses a positional $set to update updatedAt, updatedVersion, and installedExtensions in place.

Built-in collections

The following collections ship with the platform out of the box.

Name	Key	Included modules
Real Estate Pack	`real-estate-pack`	Contacts, Todos, Real Estate
CRM Pack	`crm-pack`	Companies, Contacts, Opportunities, Emails
Blog Pack	`blog-pack`	Blog
Handyman Pack	`handyman-pack`	Handyman
Field Service Pack	`field-service-pack`	Contacts, Field Service
SaaS Website Pack	`website-saas-pack`	Website SaaS
Landing Page Pack	`website-landing-page-pack`	Website Landing Page
Portfolio Pack	`website-portfolio-pack`	Website Portfolio
Warehouse Pack	`warehouse-pack`	Warehouse
Check-in Pack	`checkin-pack`	Contacts, Visitor

Migration from Templates

The previous Templates section (route /settings/templates) has been replaced by the Store. Any existing bookmark or direct link to the templates route is automatically redirected to /settings/store via a client-side goto with replaceState: true. No data migration is required — installed template state is transparently superseded by the new installedModules tracking.