---
title: "@playstack/render"
description: "Render cache purge requests and durable change coordination with explicit targeting, safe outcomes and optional Redis persistence."
tags: ["package","infrastructure","render","cache","pro"]
---

{/* package-access:start */}

> **Pro.** Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@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.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), 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.

{/* package-install:end */}

## 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](https://api-docs.render.com/reference/purge-cache).

`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](https://api-docs.render.com/reference/rate-limiting).

## 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](/docs/packages/infrastructure/render-next)
provides explicit Pages Router final-response policy and production-server
lifecycle without requiring a purge client, Redis page cache or queue migration.
[Cache Next](/docs/packages/infrastructure/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.

{/* package-reference:start */}

## 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 point | Declaration file |
| --- | --- |
| `@playstack/render` | `./dist/index.d.ts` |
| `@playstack/render/errors` | `./dist/errors.d.ts` |
| `@playstack/render/package.json` | No 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](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}
