@playstack/render-next
Explicit public Pages Router response policy and owned production server lifecycle for Render edge caching.
Reference: @playstack/render-next@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.
Explicit Render edge-cache response policy for a built Next.js Pages Router application. The application owns which pages are public, their freshness, data loaders, Next configuration and content-change signals. There is no Redis page cache, purge client or queue dependency.
Install
After confirming preview access, install the package at your application's shared Playstack version:
npm install --save-exact @playstack/render-next@0.1.0-beta.5Check the peer requirements below before choosing a runtime or provider.
Compose a production server
import next from 'next';
import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { startPagesRouterServer } from '@playstack/render-next';
const directory = resolve('site');
const buildId = (await readFile(resolve(directory, '.next/BUILD_ID'), 'utf8')).trim();
const hostname = '0.0.0.0';
const port = 3000;
const application = next({ dev: false, dir: directory, hostname, port });
const site = await startPagesRouterServer({
application, hostname, port,
cachePolicy: {
buildId,
pagePolicy: pathname => pathname === '/' || pathname.startsWith('/articles/')
? { maxAgeSeconds: 600, staleWhileRevalidateSeconds: 30,
staleIfErrorSeconds: 120, notFoundMaxAgeSeconds: 10 }
: null,
publicAssets: [{ pathname: '/logo.svg', policy: { maxAgeSeconds: 3600 } }],
},
});
// During host shutdown, await site.close() before disconnecting dependencies.
// The host owns signals, readiness, process exit and other resource shutdown.Run next build first and start your entry point with NODE_ENV=production.
Supply the current build ID from the actual configured distDir (the example
uses .next). This is ordinary custom-server output, not Next standalone or
static export output. Do not apply it to App Router/RSC routes, middleware rewrites,
base paths or internationalized data routing without separate qualification.
Next is an optional peer; policy imports work without it installed. Production
Pages integration is qualified against exact Next 15.5.28 and 16.4.2, not
every version in the supported peer ranges. Native Next compression stays enabled;
no compress: false configuration is required. No ambient environment or process
signal handlers are changed.
startPagesRouterServer prepares the supplied application and owns its HTTP
listener and application closure. close() is idempotent, stops admission, drains
requests/handler promises, then closes the application. Its default shutdown
budget is 15 seconds (configurable up to 60 seconds). On timeout it destroys owned
HTTP connections and rejects; this is not proof that arbitrary application work
has stopped. The host must not disconnect other dependencies on a failed drain.
The exposed server is an escape hatch, not permission for two lifecycle owners.
For an existing Node server, wrap its Next request handler with
withPagesRouterCachePolicy(handler, cachePolicy) and retain lifecycle ownership.
Cache contract
Only CDN-Cache-Control is owned. Browser/origin Cache-Control remains intact.
Public 200 HTML and current-build Pages JSON share one application page policy;
optional public 404 caching has its own short lifetime. Every query variant
on an opted-in pathname must also be public; token-bearing callbacks must never
opt in. Other statuses, unknown
routes, API/internal paths, invalid data paths and unexpected content types use
no-store. All durations are integer seconds, at most one year; positive
maxAgeSeconds is mandatory for an opted-in policy.
Requests with authorization or any cookie bypass origin cache admission, including analytics cookies. Set-Cookie responses, unsupported header/query variants, and Vary values other than Accept-Encoding also bypass. No arbitrary cookie allowlist is inferred. Public loaders must produce anonymous public data; this origin adapter cannot control an edge cache hit that never reaches it. Before enabling preview or personalized behavior on a public URL, separately qualify the provider's request-cookie/authorization bypass and cache-key behavior; an origin response header cannot enforce an edge request rule.
Next data redirects can be HTTP 200 JSON. Data is admitted only when end()
receives one raw, unencoded, valid Pages JSON payload of at most 1 MiB, with no
redirect markers. That proof remains valid when native Next subsequently applies
gzip and declares Vary: Accept-Encoding. The decoded content and final status
must still satisfy the same public-page or exact notFound policy. A native data
404 may omit Content-Type; only its exact
{"notFound":true} payload can use the configured short policy in that case.
Explicit wrong MIME types still bypass. Pre-encoded input, unsupported/multiple
content encodings, gzip without the required Vary, streaming, earlier header
flushes/writes, larger or malformed payloads and data HEAD responses bypass
caching rather than buffering or decompressing bodies.
HTML HEAD remains eligible. Duplicate Set-Cookie headers are preserved. Handler
failures yield a fixed 500 before headers, or destroy a started response, without
logging raw exceptions. A failure after public response headers have already
left, including a gzip transmission failure, cannot revoke those headers; keep
public responses genuinely public through completion and qualify transmission
failure behavior separately. Next and host logging require their own privacy
policy.
Fingerprint-named /_next/static/ assets retain Next's positive public immutable
policy. Other public files require exact explicit paths and freshness; there is
no automatic filesystem crawl. Route predicates and callbacks remain trusted
application code, but errors fail closed.
Purge and qualification
@playstack/cache-next manages origin caching/revalidation. @playstack/render
submits service-wide edge purges; its optional coordinator retains durable change
generations. Neither is required by this response adapter. Refresh origin data
before signaling a purge; purging an edge cannot repair stale origin data.
Use Render's All files setting only after qualifying this server in staging. Prove an edge HIT, a committed content change, an accepted purge and updated HTML and matching data, then deletion/restoration and private/error bypass. Local HTTP and production Next tests do not establish real Render propagation, cache keys, security or production readiness. Do not enable caching on separate private API or worker services merely because the public site adopts this package.
API entry points and requirements
Reference snapshot: @playstack/render-next@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-next | ./dist/index.d.ts |
@playstack/render-next/package.json | No TypeScript declaration (asset or metadata export). |
Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.
Peer dependencies
Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.
| Peer | Compatible range | When needed |
|---|---|---|
next | >=15.5.28 <16 || >=16.4.2 <17 | Optional; only for the entry points that use it. |
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.