@weftly/loader
v0.5.0
Published
DB-less published-snapshot loader + renderer for Weftly customer sites (CDN fetch + `PublicSnapshotPageTreeRenderer`).
Readme
@weftly/loader
DB-less published-snapshot loader + renderer for Weftly customer sites
(CDN fetch + PublicSnapshotPageTreeRenderer).
Install
npm install @weftly/loaderPeer deps: next ^16.2.6, react/react-dom ^19.2.0. Depends on @weftly/runtime.
Next.js setup
@weftly/loader renders @weftly/runtime components, which ship precompiled
CSS Modules (*.module.css). Add both packages to transpilePackages:
// next.config.ts
export default { transpilePackages: ['@weftly/runtime', '@weftly/loader'] }Exports
@weftly/loader— snapshot types,PublicSnapshotPageTreeRenderer, CDN loaders, andresolvePublicCollectionLists()for request-dependent collection pagination and URL filters.
Version 0.4 migration
Version 0.4 adds context-aware collection-list snapshots and server-side
resolution for request-dependent collection pagination and URL filters. It is
an intentional breaking release for direct Content API client consumers:
collection responses now include projected fields, assets, and an offset.
- Update consumers to
@weftly/loader@^0.4.0and@weftly/runtime@^0.2.1. - Resolve public snapshots with
resolvePublicCollectionLists()before rendering when a request contains collection pagination or mapped URL filters. - Treat Content API helpers as server-only and configure
WEFTLY_CONTENT_API_URLandWEFTLY_CONTENT_API_KEYin the server runtime. - Update direct
fetchPublicCollectionItems()consumers for the newfields,assets, andpagination.offsetresponse properties.
Already-published version-1 snapshots remain readable. Missing query plans are normalized to a static fallback, while newly published snapshots include the context-aware list instances required for nested collection scopes.
The coordinated versions for named slots and materialized linked-section metadata
are @weftly/[email protected], @weftly/[email protected], and @weftly/[email protected].
The loader preserves validated source revision metadata while rendering the
materialized tree without fetching a central section definition.
Version 0.5 is additive: collection query plans may carry live (external
API collections) and manifests may carry liveCollections.
resolvePublicCollectionLists() always re-queries live lists (also on page one
and for nested instances), caches them for at most the source's cache TTL and
keeps the embedded snapshot items when the Content API request fails. Older
loaders ignore the new fields and render the embedded items.
loadPublicPageSnapshotWithLiveFallback() replaces loadPublicPageSnapshot()
for live item-detail pages: when the CDN has no snapshot for
/<collectionKey>/<slug> and the manifest lists the collection in
liveCollections with detailRoutes, it builds the snapshot on demand through
fetchPublicRouteSnapshot() (/api/content/v1/route, cached for the live
TTL). Every other 404 stays a 404 without a Content API request.
For a release, build and validate the SDKs, commit a clean release state, then
publish the runtime dependency before the host and loader. The commands below
assume the release branch is main; published versions cannot be republished.
pnpm build:sdk
pnpm --filter @weftly/runtime publish --access public --publish-branch main --ignore-scripts
pnpm --filter @weftly/host publish --access public --publish-branch main --ignore-scripts
pnpm --filter @weftly/loader publish --access public --publish-branch main --ignore-scripts
npm view @weftly/[email protected] version
npm view @weftly/[email protected] version
npm view @weftly/[email protected] version
cd apps/customer-template
npm install '@weftly/runtime@^0.2.4' '@weftly/host@^0.2.5' '@weftly/loader@^0.4.1' --save
npm ci
npm run buildAfterwards, run pnpm check:customer-template-release from the repository root.
It checks all three published packages, template ranges, registry-backed lock
entries, and host/loader runtime dependencies. The Customer template release
gate workflow also performs a standalone npm ci and build.
Runtime-validated responses
loadPublicManifest() and loadPublicPageSnapshot() validate response JSON at
runtime and return the canonical PublicManifestSnapshot and
PublicPageSnapshot types. Syntactically invalid JSON returns
reason: 'invalid-json'; valid JSON with the wrong shape returns
reason: 'invalid-payload'.
For rollout compatibility, the parser recognizes one documented legacy
version-1 page shape: snapshots created before alternates existed are
normalized to alternates: {} and then checked against the complete current
contract. No other required fields are defaulted.
Custom response extensions require an explicit parser instead of a generic type assertion:
const result = await loadPublicPageSnapshot({
projectId: 'project-id',
locale: 'de',
path: '/',
parser: (payload: unknown): ExtendedSnapshot | null =>
isExtendedSnapshot(payload) ? payload : null,
})Migration from the former unchecked generic call:
// Before: compile-time assertion only; response JSON was not checked.
loadPublicPageSnapshot<ExtendedSnapshot>(options)
// Now: runtime proof is required for a custom contract.
loadPublicPageSnapshot({ ...options, parser: parseExtendedSnapshot })The Content API client applies the same distinction. Collection lists and
detail responses validate the stable item envelope; dynamic item values
remain Record<string, unknown>. A custom detail contract can be supplied via
the parser option of fetchPublicCollectionItem().
License
Weftly Community License — see LICENSE. Production use requires a valid Weftly license key.
