Skip to content
SHC Docs

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.

RungWhat it gives youWho can author itWhere it lives
1. The standard pageIdentity, install command, screenshots, description, add-ons, versions, related appsEveryone, automaticallyNothing to write
2. Authored editorialHero, capability cards, metric strip, how-to steps, FAQ, closing CTA, plus screenshotsYou, in app.yamllanding: and gallery:
3. A bespoke pageA hand-written page in TSX with its own arrangementAn SHC engineer onlyfeatures/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.

There are three ways to end up on the standard page, and in the code they are the same line:

  1. 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.
  2. 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.
  3. 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.

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.

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.


  1. Write a landing: block set in app.yaml. Start with hero and highlights; add metrics only if you have countable facts a reader could verify from your app’s own files, and faq for the objections you actually get.
  2. 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.
  3. 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.