---
title: "@playstack/render-next"
description: "Explicit public Pages Router response policy and owned production server lifecycle for Render edge caching."
tags: ["package","infrastructure","render","next","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 */}

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.

{/* 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-next@0.1.0-beta.5
```

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

{/* package-install:end */}

## 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.

{/* package-reference:start */}

## 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](/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 */}
