On this page
  1. Install
  2. Compose a production server
  3. Cache contract
  4. Purge and qualification
  5. API entry points and requirements
  6. 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-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:

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

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

Compose a production server

ts
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 pointDeclaration file
@playstack/render-next./dist/index.d.ts
@playstack/render-next/package.jsonNo 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.

PeerCompatible rangeWhen needed
next>=15.5.28 <16 || >=16.4.2 <17Optional; 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.

Go

Playstack Pro tag
OriginsPricingBlogChangelogStatus

© 2026 Playstack. All rights reserved.

With OSS

By

Commune Software