Linked Pages
A linked page is a page on a site that shows content from somewhere else: an upstream page your platform supplies. A platform with hundreds of customer sites can keep one "Privacy policy", "Inventory" or "Contact us" page and let every site link it. When the upstream page changes, every linked page shows the change. A site that wants its own version duplicates the page and edits the copy.
Your platform owns the upstream pages. ChaiBuilder stores only the upstream page's id on the linked page and asks your code for its content whenever it is needed.
What editors see
With the feature on, Add New Page offers two tabs: Create from scratch and Link upstream page. The Link tab lists the pages your platform offers, grouped under the headings you supply. The editor picks one, a parent page and a slug, and the new page opens in the builder.
- A linked page is view-only. The canvas shows the upstream content, nothing on it can be edited, and the page never saves. A notice offers Duplicate and edit.
- Duplicate and edit copies the upstream content into the page, asks for confirmation, and turns it into an ordinary editable page. Later upstream changes no longer reach it.
- Reset throws the copy away, including its own design tokens, and links the page to its upstream page again. It also asks first.
- The pages manager labels each such page Linked or Cloned, and both open like any other page.
- A linked page gets no language pages until it is duplicated.
A dynamic upstream page (a template that matches many URLs) must be linked under a parent page, takes its parent's path as its own, and has no slug of its own. It has no View live link, because it has no single URL.
The word "upstream page" is a default. Name it the way your platform does with
labels.features.upstreamPage on the editor, as a string or a map of locales:
<ChaiWebsiteBuilder labels={{ features: { upstreamPage: { en: 'System Page', fr: 'Page système' } } }} />
Turn it on
Three pieces, all on the server:
- Set
features: { upstreamPages: true }. The flag is off by default. - Pass an
upstreamPageSourcetobuildChaiBuilderConfig. - Register a
LIST_UPSTREAM_PAGESaction that returns the pages a site may link.
// chaibuilder.config.ts
import { buildChaiBuilderConfig } from 'chaipro/nextjs/server'
import type { ChaiUpstreamPageSource } from 'chaipro/types'
import { ListUpstreamPagesAction } from './actions/list-upstream-pages'
const upstreamPageSource: ChaiUpstreamPageSource = {
// May this site link this page on this user's behalf? Return the page, or null.
async findLinkable({ id, appId, userId }) {
const page = await platform.pages.findOfferedTo(appId, id, userId)
return page ? { id: page.id, name: page.name, pageType: page.pageType, dynamic: page.isTemplate } : null
},
// The published content a linked page of this site renders and a duplicate copies.
async getContent(id, { appId, live }) {
const page = await platform.pages.contentFor(id, appId, { published: live })
return page ? { blocks: page.blocks, seo: page.seo } : null
},
}
export default buildChaiBuilderConfig({
db,
features: { upstreamPages: true },
upstreamPageSource,
actions: { LIST_UPSTREAM_PAGES: new ListUpstreamPagesAction() },
})
findLinkable
Called before a page is linked and before a duplicate is reset. Return the page when site
appId may link it for userId, or null to refuse. This is your access check: ChaiBuilder
trusts the answer.
getContent
Returns { blocks, seo } for the page, or null when it is gone. Two rules:
- Make the content the site's own. Links, global blocks and any other ids in the blocks should point at the site's rows, not at the site the page came from.
- Respect
live. Whenliveis true the call is for a live render, so match the site's published rows, since only those render. Otherwise (the editor, preview, a duplicate) match its drafts.
LIST_UPSTREAM_PAGES
The action returns { pages: ChaiUpstreamPageOption[] }, the options the Link tab lists:
| Field | Description |
|---|---|
id |
The upstream page's id, stored on the linked page |
name |
Shown in the list |
pageType |
The page's type, or null |
slug |
Optional. Prefills the slug; the name is slugified when it is absent |
group |
Optional. The heading the page is listed under |
dynamic |
Optional. true for a template that takes its parent's path |
Write it like any custom action, and check the caller's permissions inside it.
Caching
Every cached render of a linked page carries the tag upstream-page-<id>, where <id> is the
upstream page's id. When an upstream page's published content changes, revalidate that tag and
every site linking the page picks up the change:
import { revalidateTag } from 'next/cache'
revalidateTag(`upstream-page-${upstreamPageId}`)
Linked page caches also follow the site's own publishes, so publishing, unpublishing or deleting a global block or a page a linked page links to refreshes it without any work on your side. See Caching and Revalidation.
Permissions
Linking, duplicating and resetting all need pages:update. Who may link which upstream page is
decided by your findLinkable and LIST_UPSTREAM_PAGES. With the flag off, or with no
upstreamPageSource, linking, rendering and duplicating are refused with FEATURE_DISABLED.
Related
- Configuration - the
upstreamPagesflag andupstreamPageSource - Global Blocks - shared content within one site
- Plugins - writing the
LIST_UPSTREAM_PAGESaction - Caching and Revalidation - tags and manual revalidation

