On this page
  1. Install
  2. Request a purge
  3. Acceptance and safe failures
  4. Coordinate pending public changes
  5. Compose independently
  6. API entry points and requirements
  7. Peer dependencies

This guide describes upcoming source contracts, not a publication receipt. Check release availability and keep your complete Playstack graph on one verified version.

@playstack/render

Render cache purge requests and durable change coordination with explicit targeting, safe outcomes and optional Redis persistence.

Reference: @playstack/render@0.1.0-beta.5 · TypeScript

Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.

@playstack/render submits a cache purge for one explicitly configured Render web service. It accepts a server-only credential, transport and clock without importing Next, Redis or queue adapters.

Install

After confirming preview access, install the package at your application's shared Playstack version:

sh
npm install --save-exact @playstack/render@0.1.0-beta.5

Check the peer requirements below before choosing a runtime or provider.

Request a purge

ts
import { createRenderPurgeClient } from '@playstack/render'

const render = createRenderPurgeClient({
  apiKey: renderApiKey,
  serviceId: renderSiteServiceId,
  fetch: globalThis.fetch,
  clock: { nowMs: Date.now },
})

const receipt = await render.purgeCache({ signal: shutdownSignal })

The client makes one bodyless POST to the fixed official API endpoint with redirect refusal and a per-invocation deadline. It never infers the site target from the worker's own service ID. Its default whole-call timeout is 15 seconds, including response disposal, with a maximum of 60 seconds.

Acceptance and safe failures

Only observed HTTP 202 returns an accepted receipt. A service purge covers all of its edge entries; it does not select routes or establish completed propagation. A caller must preserve changes arriving during a request and verify real content freshness separately. See Render's purge API.

RenderPurgeError exposes fixed codes, numeric status/rate metadata and not_submitted, not_accepted or unknown outcomes. Configuration/pre-call cancellation does not dispatch; timeouts, transport failures and cancellation after invocation cannot prove that no request escaped. Bodies, URLs, credentials and raw error causes are excluded. Known acceptance survives bad optional metadata or cleanup failures. The client never automatically retries.

Validated rate counters and absolute reset/retry deadlines help caller scheduling. Render's reset header is in epoch seconds; public resetAt/retryAt values use epoch milliseconds. Deadlines are not silently shortened. Quotas are shared across API endpoint groups/users, so coordinate more than just a service-local timer. See Render rate limits.

Coordinate pending public changes

@playstack/render/coordination persists change generations independently of queue wakeups. @playstack/render/coordination/redis supplies atomic Redis persistence without bundling a Redis SDK. Native node-redis clients work directly; createIoredisRenderPurgeClient() adapts existing ioredis/BullMQ clients.

ts
import { createRenderPurgeCoordinator } from '@playstack/render/coordination'
import { RedisRenderPurgePersistence } from '@playstack/render/coordination/redis'

const persistence = new RedisRenderPurgePersistence(redis, {
  namespace: 'public_content_prod',
  serviceId: render.serviceId,
  quotaScope: 'render_api_user',
})
const coordinator = createRenderPurgeCoordinator({ client: render, persistence })

await coordinator.publicContentChanged()
const result = await coordinator.processPending({ signal: workerShutdownSignal })

Use a reliable post-commit signal handoff and an independent periodic worker sweep. The package does not install a scheduler or require a queue migration. A claim reserves cooldown before HTTP and captures a precise generation; accepted work acknowledges only that snapshot. New changes stay pending, while stale workers cannot clear a successor's lease. Generation/lease counters remain decimal strings, including above JavaScript's exact integer range.

Shared API-user scopes retain provider deadlines separately from normal spacing. A stale 429 may extend the deadline without changing the current owner. The final storage check can refuse an outstanding unsent permit, while factual completion of already-started work remains recordable. This is cooperative coordination, not remote recall or proof of physical request drainage.

An accepted result with recording: 'unconfirmed' means Render acceptance is known but its durable acknowledgment is uncertain. Recovery inspects retained state; it does not erase pending work or invent a new event identity to skip cooldowns.

Temporary or unclassified storage failures expose coordination_storage_unavailable with retryable: true. Configuration/input errors, malformed replies and native integrity refusals remain non-retryable, including through coordinator wrapping. Messages are fixed and exclude raw Redis diagnostics. Retrying coordination still observes persistent leases and cooldowns; an uncertain write acknowledgment is not permission to repeat provider work unconditionally. Hosts own bounded backoff and investigation of unavailable or misconfigured storage.

Inspection reports the effective deadline across provider minima, ordinary spacing and service/shared-quota leases. Another service's longer active lease is included. Inspection never replaces the atomic claim and final dispatch check.

Persist namespace/service/quota bindings together. Use a durable Redis deployment with noeviction, bounded command behavior and reviewed access to its namespace. Keys share a Cluster hash slot and must never be expired or reset during cleanup. Existing expiring/corrupt state and mismatched scopes refuse before writes. This new state contract needs an explicit cutover from application-owned keys; no old-format reader or automatic migration is supplied.

Compose independently

Use a bounded non-retrying transport that honors cancellation; promise deadlines do not prove physical socket drainage or remote cancellation. Hosts own shutdown, durable pending changes, retries and service credentials.

The separate Render Next adapter provides explicit Pages Router final-response policy and production-server lifecycle without requiring a purge client, Redis page cache or queue migration. Cache Next continues to handle the origin cache and revalidation without becoming a dependency of this edge-purge client. Revalidate any origin cache before purging the edge to avoid repopulating it with stale origin content.

Local Node/Workers and packed consumer qualification does not replace a real Render staging test. Warm an edge HIT, mutate content, observe accepted purge and verify updated HTML/data before production activation. Yalc/registry publication and host configuration remain operator actions.

API entry points and requirements

Reference snapshot: @playstack/render@0.1.0-beta.5. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Public entry pointDeclaration file
@playstack/render./dist/index.d.ts
@playstack/render/errors./dist/errors.d.ts
@playstack/render/package.jsonNo TypeScript declaration (asset or metadata export).
@playstack/render/coordination./dist/coordination.d.ts
@playstack/render/coordination/redis./dist/coordination-redis.d.ts

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

Go

Playstack Pro tag
OriginsPricingBlogChangelogStatus

© 2026 Playstack. All rights reserved.

With OSS

By

Commune Software