Storefront pages: what your app's page in the marketplace can be
Layer 6. Services. Services
Every published app has a page at https://marketplace.selfhostedcloud.org/apps/<name>.
This document says what controls that page, what you as an app author can
change, and, plainly, what you cannot.
There are three rungs. Higher rungs are not “better pages”; they are pages with a different author, and the rung you can reach is decided by who you are, not by how good your app is.
| Rung | What it gives you | Who can author it | Where it lives |
|---|---|---|---|
| 1. The standard page | Identity, install command, screenshots, description, add-ons, versions, related apps | Everyone, automatically | Nothing to write |
| 2. Authored editorial | Hero, capability cards, metric strip, how-to steps, FAQ, closing CTA, plus screenshots | You, in app.yaml | landing: and gallery: |
| 3. A bespoke page | A hand-written page in TSX with its own arrangement | An SHC engineer only | features/marketplace/src/flagship/ |
Rung 1: the standard page, and it is the floor
Section titled “Rung 1: the standard page, and it is the floor”You do not opt into this and you cannot lose it. Publish an app and it has a page: the app’s glyph and title, its tagline, its version / category / tier, a visible install command, its screenshots if it has any, its description, its add-ons if it publishes any, its release history, and a rail of sibling apps in the same category.
Every section renders nothing at all when its data is absent. There are no placeholders, no “screenshots coming soon”, no empty carousels. An app with only a name and a description gets a page that looks deliberate, because 86 of the 90 apps in the catalogue today are exactly that and a store where most pages look unfinished is a broken store.
This is also the fallback for everything below. If a rung-3 page fails to load or throws while rendering, the visitor gets this page; see The fallback is the default.
Rung 2: authored editorial, and this is the rung that is for you
Section titled “Rung 2: authored editorial, and this is the rung that is for you”Two keys in app.yaml control it, both documented in
App definition: gallery: (screenshots) and
landing: (editorial blocks).
landing: is a closed vocabulary. You pick a block type from a fixed
list (hero, highlights, metrics, steps, faq, cta) and fill in
typed string fields. You cannot write HTML, Markdown, MDX, a colour, a URL or
a class name.
That restriction is deliberate and it is a security boundary, not a style guide. An app can eventually be authored by somebody SHC did not employ, and anything an app carries then becomes untrusted input rendering on a page every visitor loads. Raw HTML there is stored XSS with a supply chain in front of it; Markdown in practice means “HTML plus a sanitizer you must never misconfigure”; MDX compiles and executes JavaScript. So the storefront renders your strings as React text children and nothing else, there is no sanitizer to get wrong, and the worst a hostile author can do is write rude prose: a moderation problem rather than a security one.
What you give up is the ability to invent a layout. What you get is a page that looks like the rest of the store instead of like a blog post, and a review path that does not require anyone to audit your markup.
An unknown block type is dropped, silently and on purpose. An older
storefront deployed against a newer catalogue degrades to fewer sections
rather than crashing. A block that renders as nothing is usually a type:
typo. CI’s catalogue validator refuses blocks outside the vocabulary on a
main push, so this fails your pipeline rather than your production page.
Rung 3: a bespoke page, and only an SHC engineer can write one
Section titled “Rung 3: a bespoke page, and only an SHC engineer can write one”A bespoke page is TypeScript in this repository. It is a .tsx file under
features/marketplace/src/flagship/<app>/, registered by hand in
features/marketplace/src/flagship/registry.ts, compiled into the storefront
build, and reviewed like any other code.
Say it plainly: an app author cannot write one, and neither can a vendor or
a future third-party listing. There is no field in app.yaml that reaches
it, no upload, and no request form. The module has to exist at build time and
the registry line has to be added by somebody with commit access to this
repository.
That is the correct boundary for a curated editorial surface (the same
way an app store’s “Editors’ Choice” story is written by the store and not by
the developer), and it is the wrong boundary for everything else. Which is why
it is not the only surface an app has: rung 2 is what serves the other ~80
apps and any third-party listing, and rung 2 gets better independently of
whether anyone ever writes a rung-3 page. If your app’s page is not saying
what you want it to say, the answer is landing: and gallery:, not this.
A bespoke page is also not a licence to invent a design. It is composed from
the same component vocabulary the standard page uses
(features/marketplace/src/listing/): the same identity band, the same
install affordance, the same add-on rows, so a flagship page reads as a
richer arrangement of the store’s design language rather than as a foreign
object dropped into it. A page that needed to fork a component is a page that
found a missing prop on the original; the fix goes upstream.
The fallback is the default
Section titled “The fallback is the default”There are three ways to end up on the standard page, and in the code they are the same line:
- The app has no bespoke page. True for 89 of 90 apps. The registry lookup returns nothing and the standard screen renders with no Suspense boundary and no error boundary around it: the ordinary path costs nothing.
- The page’s code chunk never arrives. Bespoke pages are code-split, so each is a network request; a deploy that rotates hashed filenames under an open tab, or an offline client, makes that request fail. The Suspense fallback is the standard page, so a slow chunk shows a complete, useful page rather than a spinner.
- The page throws while rendering. Caught by an error boundary that then renders the standard page and reports the failure (naming the app) to the console.
An app store that shows a blank screen for an app is worse than one that shows a plain page, so the plain page is what you get from doing nothing, from a page that never loads, and from a page that breaks.
Why they are code-split
Section titled “Why they are code-split”Twenty-one flagship apps eventually means twenty-one hand-written pages. A
static import of all of them would land in the storefront’s entry bundle and
be paid for by every visitor who opens the home page and never touches a
flagship app, the majority. Each registry entry is therefore a literal
dynamic import(), which the bundler can statically analyse into one chunk
per page, so a visitor downloads exactly the page they opened. This is
enforced at the source level by flagship/flagship.spec.tsx, because a static
import changes no behaviour at all; it just moves bytes onto the critical
path, which no unit test can see.
Which apps have one today
Section titled “Which apps have one today”One: nextcloud. Not twenty-one. The other twenty flagship apps have not been commissioned, and twenty-one half-designed pages would be a worse storefront than one page that is actually good.
Nextcloud was chosen on material that exists, measured over
apps/flagship/: four apps declare a landing: at all, three declare a
gallery:, two publish all six block types, and nextcloud is the only
app in the intersection of complete editorial and a captured
screenshot. (GitLab has the full six blocks and not one frame; Uptime Kuma
has a frame and incomplete copy.) Those counts are asserted in
flagship/nextcloud/nextcloudPage.spec.tsx against the apps on disk, so
the argument goes red when it stops being true rather than quietly going
stale.
Nothing on a storefront page is invented. No fabricated screenshots, no
testimonials, no user counts, no awards. Every number, sentence and picture on
the nextcloud page comes from apps/flagship/nextcloud/ or from the App
Listing row, and every slot with no data renders nothing. These pages are
customer-facing marketing: a fabricated placeholder is not a placeholder, it
is a false statement that ships.
What to do about your own app’s page
Section titled “What to do about your own app’s page”- Write a
landing:block set inapp.yaml. Start withheroandhighlights; addmetricsonly if you have countable facts a reader could verify from your app’s own files, andfaqfor the objections you actually get. - Capture a
gallery:frame. Three apps of ninety have one, so this buys the most for the least work of anything most apps can do, and it is the one that makes a page look like a product rather than a database row. - Do not ask for a rung-3 page. If rung 2 cannot express something your app genuinely needs, that is a gap in the block vocabulary, and the fix is a new block type (which every app gets) rather than a bespoke page for one.
See App definition → Gallery for the gallery:
schema and the capture/provenance rules.