Site client rules

These rules apply to website and native starters and custom clients. Site configuration describes your product; the client must implement its routing, visibility and provider behavior.

One route resolver

Resolve managed URLs through site.route({ path }), including the homepage with path: "". Use the result for both rendering and metadata. Honour redirects, return a real 404 for missing content and keep temporary upstream failures out of persistent caches. Do not manufacture article links from slugs; list-item path is optional. See API recipes.

Site publishing, Page publishing and client deployment are separate actions. Check all three when a route does not appear. Feed and sitemap generation must use the same public destination rules as the rendered client and must exclude previews and private routes.

Private editor previews

Desk preview URLs use /preview/v1/. Send their path through the normal Site route resolver. Preview content needs all of these protections:

• Return Cache-Control: private, no-store; apply the same private/no-store policy at the CDN and persistent route-data layers. Never serve a stale public fallback for a preview.
• Emit a noindex robots directive and disallow /preview/v1/ in robots.txt. Exclude it from navigation, feeds and sitemaps. Robots controls supplement access protection; they do not make an exposed page private.
• Treat the preview link as private editor material and preserve any platform access checks. Do not put it into shared logs, public analytics dimensions, share payloads or cache keys that become public artefacts.
• Keep the share controls visually representative, but replace the preview URL in every share/copy action with a verified public article URL. If no published article URL exists, use an approved public Site URL or disable the action.
• Preserve the visual position of comments where appropriate, but do not initialise a durable comment thread or any other public record keyed to a preview URL.

A preview should still represent configured production integrations. Keep intended analytics, advertising, GAM targeting, placements and VAST behavior where the publication’s policy permits them, using safe public identifiers rather than a preview URL. Do not treat noindex or cache bypass as a reason to blanket-disable providers. Verify real provider requests separately; visible slot markup is not proof that a campaign is eligible or serving.

Public and private caches

Use a no-auth client for shared public reads, with route-aware expiry and an agreed purge/freshness policy. A cache fill must not carry reader credentials. Bypass shared HTML and data caches for authenticated/personalised reads, auth/profile/subscription/checkout routes, previews, unsafe methods, Set-Cookie responses and framework revalidation/prefetch payloads that are not ordinary public HTML.

Keep browser freshness separate from CDN freshness. Use short browser revalidation for mutable news pages and deliberate edge TTLs. Auth-independent feeds, sitemaps and public data may remain shared for signed-in browsers only through an explicit allowlist that removes cookies before rendering. Record the actual cache lifetimes and bypass rules for the deployment.

Never hide protected bytes with CSS or a client-only paywall. Verify the permitted article representation before sending it to the client, including widgets, plain text, embedded state and metadata. See the monetization launch status: configuration and schemas alone do not certify deployed enforcement.

Article flags, comments and advertising

Use the article’s high-level fields, rather than placement metadata, for isBreaking, isSensitive, isNsfw, isSponsored, isEditorsChoice, enableComments and disableAdvertising. Expire Breaking presentation after the agreed news window; the reference client guidance uses five hours from publishedAt.

Initialise comments only for an eligible published article with enableComments === true and a configured provider. Comments are an opt-in integration; the generic website reference does not provision a live comment provider.

Resolve site, entity and client advertising policy before loading ads. disableAdvertising must suppress slots and ad requests. Pass Sensitive/NSFW and sponsorship signals into central targeting before requesting ads; a targeting key alone does not block delivery unless the ad server acts on it. Keep empty archives, search, login, checkout, confirmation and error screens free of ad requests under the reference client’s policy. Indexability and advertising eligibility are separate decisions.

Load Site-configured GTM, Chartbeat, GAM/GPT, VAST and custom HTML through shared provider infrastructure. Browser scripts and custom HTML run on the client; do not execute publisher snippets during server rendering. Verify account configuration, consent, SPA navigation and exclusions with the actual Site.

Acceptance before launch

Test a published homepage, section, article, redirect and missing route, then verify RSS/Atom and sitemap destinations. Test a private editor preview for no-store/noindex behavior, safe sharing, no durable comment state and intended provider requests. Inspect anonymous and authenticated cache behavior, article policy responses and error recovery in the deployed environment. The starter’s local build is only one part of this acceptance.