DEV Community: jake

Generate PPTX in Express.js with PaperJSX

jake — Sun, 02 Aug 2026 14:30:49 +0000

PaperJSX generates PowerPoint files from JSON inside Express route handlers with zero native dependencies. Install the package, add a POST route, accept a JSON body, call generate(), and return the buffer with PPTX MIME headers. The complete API endpoint is 15 lines of code.

1. Install

This guide is Express-specific. Not on Express? See the framework-agnostic hub, generate PPTX from any data source, or the Google Sheets to PPTX walkthrough.

npm install express @paperjsx/json-to-pptx

Two packages. No postinstall scripts, no native compilation. PaperJSX has zero native dependencies — it runs anywhere Express runs, including Docker containers, PM2 clusters, and traditional VPS deployments.

2. Minimal Express route

import express from "express";
import { generate } from "@paperjsx/json-to-pptx";

const app = express();
app.use(express.json());

app.post("/api/pptx", async (req, res) => {
  try {
    const buffer = await generate(req.body);

    res.set({
      "Content-Type":
        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
      "Content-Disposition": 'attachment; filename="report.pptx"',
    });

    res.send(buffer);
  } catch (err) {
    res.status(400).json({ error: err.message });
  }
});

app.listen(3000, () => console.log("Listening on :3000"));

Test it with curl:

curl -X POST http://localhost:3000/api/pptx \
  -H "Content-Type: application/json" \
  -d '{"slides":[{"elements":[{"type":"text","value":"Hello from Express","style":{"fontSize":36,"bold":true}}]}]}' \
  -o test.pptx

Open test.pptx in PowerPoint, Keynote, or Google Slides. The file is valid OOXML — no repair dialog, no corruption.

How do you add charts and tables?

The JSON body can include any element type PaperJSX supports. Here is a request body that produces a slide with a bar chart and a data table.

{
  "slides": [
    {
      "elements": [
        {
          "type": "text",
          "value": "Q3 revenue by region",
          "style": { "fontSize": 28, "bold": true }
        },
        {
          "type": "chart",
          "chartType": "bar",
          "data": {
            "categories": ["NA", "EMEA", "APAC"],
            "series": [
              { "name": "Revenue", "values": [4200, 3100, 2800] }
            ]
          }
        },
        {
          "type": "table",
          "headers": ["Region", "Revenue", "Growth"],
          "rows": [
            ["NA", "$4.2M", "+10%"],
            ["EMEA", "$3.1M", "+7%"],
            ["APAC", "$2.8M", "+27%"]
          ]
        }
      ]
    }
  ]
}

The chart is native and editable — recipients can click it in PowerPoint and modify the data. For combo charts (bar + line on the same axis), set "chartType": "combo" and add a "type" field per series. Extended features across all four formats require Pro ($199/mo). For the supported schema, see the PPTX documentation.

How do you generate from database data?

In production, PPTX schemas are assembled from database queries — not hardcoded JSON. Here is a route that generates a multi-slide deck from a list of regions stored in a database.

import { db } from "./db.mjs";

app.get("/api/report", async (req, res) => {
  const regions = await db.query("SELECT * FROM regions");

  const doc = {
    slides: [
      // title slide
      {
        elements: [
          { type: "text", value: "Q3 report",
            style: { fontSize: 36, bold: true } }
        ]
      },
      // one slide per region
      ...regions.map(r => ({
        elements: [
          { type: "text", value: r.name,
            style: { fontSize: 24, bold: true } },
          {
            type: "chart",
            chartType: "bar",
            data: {
              categories: ["Q1", "Q2", "Q3"],
              series: [{ name: "Revenue", values: r.quarterly }]
            }
          }
        ]
      }))
    ]
  };

  const buffer = await generate(doc);
  res.set({
    "Content-Type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
    "Content-Disposition": 'attachment; filename="q3-report.pptx"',
  });
  res.send(buffer);
});

How do you add PDF, DOCX, and XLSX?

The same JSON body can produce any of PaperJSX's four output formats. Add a format query parameter and switch the generator. This is the same pattern used in the multi-format tutorial and the Next.js PDF tutorial.

import { generate as toPptx } from "@paperjsx/json-to-pptx";
import { generate as toDocx } from "@paperjsx/json-to-docx";
import { generate as toPdf }  from "@paperjsx/json-to-pdf";
import { generate as toXlsx } from "@paperjsx/json-to-xlsx";

const formats = {
  pptx: { fn: toPptx, mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation" },
  docx: { fn: toDocx, mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" },
  pdf:  { fn: toPdf,  mime: "application/pdf" },
  xlsx: { fn: toXlsx, mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" },
};

app.post("/api/generate", async (req, res) => {
  const format = req.query.format || "pptx";
  const gen = formats[format];
  if (!gen) return res.status(400).json({ error: "Invalid format" });

  const buffer = await gen.fn(req.body);
  res.set({
    "Content-Type": gen.mime,
    "Content-Disposition": `attachment; filename="report.${format}"`,
  });
  res.send(buffer);
});

The client calls POST /api/generate?format=pdf with the same JSON body to get a PDF. One codebase, one data structure, four output formats.

Production considerations

Concern	Recommendation
Request body size	Increase Express's JSON limit for schemas with base64 images: `app.use(express.json({ limit: '10mb' }))`
Timeout	A 10-slide deck generates in ~200ms. Set `req.setTimeout(30000)` only for very large documents with many embedded images.
Concurrency	`generate()` is CPU-bound and stateless. Use PM2 cluster mode or Node.js `cluster` module to utilize multiple cores.
Input validation	Validate the JSON schema before passing to `generate()`. At minimum: verify `slides` is a non-empty array and each element has a `type` field.
Error handling	Wrap `generate()` in try/catch. Invalid schemas throw descriptive errors. Return 400 with the error message.
Authentication	Document generation endpoints should be authenticated. Use your existing Express auth middleware (JWT, session, API key).

Start generating PPTX in Express — read the quick start, explore the PPTX reference, or see the hosted API quick start.

Generate PPTX in Hono on Bun with PaperJSX

jake — Sun, 02 Aug 2026 14:30:48 +0000

Hono has tens of millions of weekly npm downloads and runs on every JavaScript runtime. PaperJSX generates PPTX, PDF, DOCX, and XLSX from JSON with zero native dependencies. Together: one API endpoint that generates PowerPoint decks on Bun, Node.js, Deno, or Cloudflare Workers — same code, any runtime. This tutorial starts with Bun, then shows how to deploy the same code to other runtimes with zero changes.

Why Hono + Bun?

According to Hono's npm page, it is "a small, simple, and ultrafast web framework built on Web Standards." Per its npm page, it receives roughly 47 million weekly downloads (as of July 2026). According to PkgPulse, Hono is the recommended default for new greenfield projects in 2026, replacing Express for new API development.

Hono's architecture makes it ideal for document generation endpoints: zero dependencies, sub-14KB bundle, Web Standard Request/Response objects, and the same code deploys to Bun, Node.js, Deno, Cloudflare Workers, and AWS Lambda. PaperJSX shares the same philosophy — zero native dependencies, pure JavaScript, any runtime.

Not on Hono? The framework-agnostic pattern lives in generate PPTX from any data source, and Express users should start with the Express PPTX tutorial instead.

Setup

bun create hono@latest doc-api
# Select: bun
cd doc-api
bun add @paperjsx/json-to-pptx

The endpoint

import { Hono } from "hono";
import { generate } from "@paperjsx/json-to-pptx";

const app = new Hono();

app.get("/", (c) => c.text("doc-api running on Bun + Hono"));

app.post("/generate", async (c) => {
  const body = await c.req.json();

  // Accept an optional format (default: pptx)
  const schema = body.schema;
  if (!schema?.slides) {
    return c.json({ error: "Missing schema.slides" }, 400);
  }

  const start = performance.now();
  const buffer = await generate(schema);
  const ms = (performance.now() - start).toFixed(1);

  return new Response(buffer, {
    headers: {
      "Content-Type":
        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
      "Content-Disposition": 'attachment; filename="deck.pptx"',
      "X-Generation-Time": `${ms}ms`,
    },
  });
});

export default app;

bun run dev
# Started server at http://localhost:3000

curl -X POST http://localhost:3000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "slides": [
        {
          "elements": [
            { "type": "text", "value": "Q3 Report",
              "style": { "fontSize": 36, "bold": true } },
            { "type": "chart", "chartType": "bar",
              "data": {
                "categories": ["NA", "EMEA", "APAC"],
                "series": [
                  { "name": "Revenue", "values": [4200, 3100, 2800] }
                ]
              }
            }
          ]
        }
      ]
    }
  }' -o deck.pptx

Open deck.pptx in PowerPoint. One slide with a title and a native editable bar chart. The X-Generation-Time header shows how long generation took — typically 20–50ms on Bun for a simple deck.

How do you serve multiple formats?

Accept a format parameter to generate PPTX, PDF, DOCX, or XLSX from the same JSON schema. This is the same multi-format pattern adapted for Hono.

import { Hono } from "hono";
import { generate as toPptx } from "@paperjsx/json-to-pptx";
import { generate as toPdf }  from "@paperjsx/json-to-pdf";
import { generate as toDocx } from "@paperjsx/json-to-docx";
import { generate as toXlsx } from "@paperjsx/json-to-xlsx";

const formats: Record<string, { fn: Function; mime: string; ext: string }> = {
  pptx: { fn: toPptx, ext: "pptx", mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation" },
  pdf:  { fn: toPdf,  ext: "pdf",  mime: "application/pdf" },
  docx: { fn: toDocx, ext: "docx", mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" },
  xlsx: { fn: toXlsx, ext: "xlsx", mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" },
};

const app = new Hono();

app.post("/generate/:format", async (c) => {
  const fmt = formats[c.req.param("format")];
  if (!fmt) return c.json({ error: "Unsupported format" }, 400);

  const { schema } = await c.req.json();
  const buffer = await fmt.fn(schema);

  return new Response(buffer, {
    headers: {
      "Content-Type": fmt.mime,
      "Content-Disposition": `attachment; filename="output.${fmt.ext}"`,
    },
  });
});

export default app;

Now POST /generate/pptx, POST /generate/pdf, POST /generate/docx, or POST /generate/xlsx — one API, four formats, same JSON schema.

How do you deploy to other runtimes?

The same src/index.ts deploys to every Hono-supported runtime. Only the entry point and deployment command change.

Runtime	Run command	Deploy
Bun	`bun run dev`	Docker, Fly.io, Railway
Node.js	`npx @hono/node-server`	Any Node host
Deno	`deno run --allow-net src/index.ts`	Deno Deploy
Cloudflare Workers	`wrangler dev`	`wrangler deploy`
AWS Lambda	SAM local	SAM deploy
Vercel	`vercel dev`	`vercel`

For Node.js, add the @hono/node-server adapter:

import { serve } from "@hono/node-server";
import app from "./src/index";

serve({ fetch: app.fetch, port: 3000 });

For Cloudflare Workers, export default app is already the correct entry point — Workers use the same fetch handler that Hono exports by default. PaperJSX's PPTX engine runs within Workers' size limits. For larger format packages (PDF, DOCX, XLSX), use Bun or Node.js where bundle size is not constrained.

This runtime portability is why Hono is the recommended framework for PaperJSX API endpoints. Write once, deploy anywhere — the same code that runs on Bun locally deploys to Cloudflare Workers in production, or to a Node.js container, or to Supabase Edge Functions (which also uses Web Standard APIs via Deno).

Comparison with Express

For Express users migrating to Hono, the API is familiar but cleaner. See the Express PPTX tutorial for the Express version — the Hono version is shorter, type-safe, and deploys to more runtimes without adapter libraries.

Dimension	Express	Hono
TypeScript	Community types (`@types/express`)	Native (built-in)
Runtimes	Node.js only	Bun, Node, Deno, CF Workers, Lambda
Bundle size	~2 MB (with deps)	14 KB (zero deps)
File response	`res.set()` + `res.send()`	`new Response(buffer, { headers })`
PaperJSX integration	Works	Works (same code, more runtimes)

Start generating documents with Hono — read the PPTX quickstart, explore multi-format generation, or see the Express tutorial for comparison.

Generate PPTX from Google Sheets data with PaperJSX

jake — Fri, 24 Jul 2026 14:31:16 +0000

Read data from a Google Sheet, transform it into a PaperJSX JSON schema, and generate a PowerPoint deck with native editable charts — all in a single Node.js script. No copy-paste, no Google Slides, no manual formatting. The output is a real .pptx file that opens in Microsoft PowerPoint. Run it once manually, schedule it with cron, or trigger it from a webhook. Total setup: 15 minutes.

What problem does this solve?

Sales teams maintain pipeline data in Google Sheets. Every week, a manager needs a PowerPoint deck summarizing the numbers. The current workflow: open the sheet, copy cells, paste into PowerPoint, manually create charts, fix formatting, save, email. This takes 30–60 minutes every week and produces inconsistent results.

The automated workflow: a Node.js script reads the Google Sheet, builds a PaperJSX JSON schema with charts and tables, generates a PPTX, and saves it to a shared drive or emails it. The script runs in under 5 seconds. The output is consistent every time.

How do you set up Google Sheets API credentials?

For server-side automation, use a Google Cloud service account — no OAuth consent screen, no user login, no browser interaction.

According to the Google Sheets API Node.js quickstart, the setup requires three steps: enable the Google Sheets API in your Google Cloud project, create a service account with a JSON key, and share the target spreadsheet with the service account's email address (e.g., sheets-reader@your-project.iam.gserviceaccount.com).

Save the downloaded JSON key as credentials.json in your project directory. Do not commit this file to version control — add it to .gitignore.

2. Install dependencies

npm install google-spreadsheet google-auth-library @paperjsx/json-to-pptx

Three packages: google-spreadsheet (clean wrapper around the Google Sheets API), google-auth-library (service account authentication), and @paperjsx/json-to-pptx (PPTX generation from JSON).

How do you read data from the sheet?

Assume a Google Sheet called "Q3 Sales" with this structure:

Region | Q1 | Q2 | Q3 | Growth

NA | 3200 | 3800 | 4200 | 10.5%

EMEA | 2400 | 2900 | 3100 | 6.9%

APAC | 1600 | 2200 | 2800 | 27.3%

import { GoogleSpreadsheet } from "google-spreadsheet";
import { JWT } from "google-auth-library";

const SHEET_ID = "1abc...your-sheet-id";

const auth = new JWT({
  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
  key: process.env.GOOGLE_PRIVATE_KEY,
  scopes: ["https://www.googleapis.com/auth/spreadsheets.readonly"],
});

export async function readSalesData() {
  const doc = new GoogleSpreadsheet(SHEET_ID, auth);
  await doc.loadInfo();

  const sheet = doc.sheetsByTitle["Q3 Sales"];
  const rows = await sheet.getRows();

  return rows.map(row => ({
    region: row.get("Region"),
    q1: Number(row.get("Q1")),
    q2: Number(row.get("Q2")),
    q3: Number(row.get("Q3")),
    growth: row.get("Growth"),
  }));
}

The google-spreadsheet package returns rows as objects with column headers as keys. We extract the data we need and convert numeric strings to numbers with Number().

4. Transform into PaperJSX schema

export function buildDeckSchema(data) {
  return {
    slides: [
      // Slide 1: title
      {
        elements: [
          { type: "text", value: "Q3 2026 sales report",
            style: { fontSize: 36, bold: true } },
          { type: "text",
            value: `Generated ${new Date().toISOString().slice(0, 10)} from Google Sheets`,
            style: { fontSize: 14, color: "#6B6960" } }
        ]
      },

      // Slide 2: bar chart — revenue by region
      {
        elements: [
          { type: "text", value: "Revenue by region",
            style: { fontSize: 24, bold: true } },
          {
            type: "chart",
            chartType: "bar",
            data: {
              categories: data.map(d => d.region),
              series: [
                { name: "Q2", values: data.map(d => d.q2) },
                { name: "Q3", values: data.map(d => d.q3) }
              ]
            }
          }
        ]
      },

      // Slide 3: data table
      {
        elements: [
          { type: "text", value: "Regional breakdown",
            style: { fontSize: 24, bold: true } },
          {
            type: "table",
            headers: ["Region", "Q1", "Q2", "Q3", "Growth"],
            rows: data.map(d => [
              d.region,
              `$${d.q1.toLocaleString()}`,
              `$${d.q2.toLocaleString()}`,
              `$${d.q3.toLocaleString()}`,
              d.growth
            ]),
            style: {
              headerBackground: "#1A1A18",
              headerColor: "#FFFFFF"
            }
          }
        ]
      }
    ]
  };
}

The transform function maps spreadsheet rows to PaperJSX elements. Charts use data.map() to extract arrays from the row objects — categories from the region column, values from the quarterly columns. This is the same data structure used in the JSON-to-PPTX quickstart.

5. Generate the PPTX

import { generate } from "@paperjsx/json-to-pptx";
import { writeFileSync } from "node:fs";
import { readSalesData } from "./read-sheet.mjs";
import { buildDeckSchema } from "./build-schema.mjs";

const data = await readSalesData();
console.log(`Read ${data.length} regions from Google Sheets`);

const schema = buildDeckSchema(data);
const buffer = await generate(schema);

const filename = `q3-sales-${new Date().toISOString().slice(0, 10)}.pptx`;
writeFileSync(filename, buffer);
console.log(`Generated: ${filename}`);

export GOOGLE_SERVICE_ACCOUNT_EMAIL=sheets-reader@your-project.iam.gserviceaccount.com
export GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."

node generate.mjs
# Read 3 regions from Google Sheets
# Generated: q3-sales-2026-04-12.pptx

Open q3-sales-2026-04-12.pptx in PowerPoint. It contains three slides: a title slide with the generation date, a bar chart comparing Q2 and Q3 revenue by region (native and editable), and a styled data table with all quarterly figures and growth rates. The chart is a real PowerPoint chart — click it to see the data table.

Complete script

Here is the entire pipeline in one file for easy copy-paste.

import { GoogleSpreadsheet } from "google-spreadsheet";
import { JWT } from "google-auth-library";
import { generate } from "@paperjsx/json-to-pptx";
import { writeFileSync } from "node:fs";

const SHEET_ID = process.env.GOOGLE_SHEET_ID;

// 1. Authenticate
const auth = new JWT({
  email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
  key: process.env.GOOGLE_PRIVATE_KEY.replace(/\\n/g, "\n"),
  scopes: ["https://www.googleapis.com/auth/spreadsheets.readonly"],
});

// 2. Read Google Sheet
const doc = new GoogleSpreadsheet(SHEET_ID, auth);
await doc.loadInfo();
const sheet = doc.sheetsByIndex[0];
const rows = await sheet.getRows();
const data = rows.map(r => ({
  region: r.get("Region"),
  q1: Number(r.get("Q1")),
  q2: Number(r.get("Q2")),
  q3: Number(r.get("Q3")),
  growth: r.get("Growth"),
}));

// 3. Build PaperJSX schema
const schema = {
  slides: [
    { elements: [
      { type: "text", value: `${doc.title}`,
        style: { fontSize: 36, bold: true } },
    ]},
    { elements: [
      { type: "text", value: "Revenue by region",
        style: { fontSize: 24, bold: true } },
      { type: "chart", chartType: "bar",
        data: {
          categories: data.map(d => d.region),
          series: [
            { name: "Q2", values: data.map(d => d.q2) },
            { name: "Q3", values: data.map(d => d.q3) },
          ]
        }},
    ]},
    { elements: [
      { type: "text", value: "Breakdown",
        style: { fontSize: 24, bold: true } },
      { type: "table",
        headers: ["Region", "Q1", "Q2", "Q3", "Growth"],
        rows: data.map(d => [d.region, `$${d.q1}`, `$${d.q2}`, `$${d.q3}`, d.growth]) },
    ]}
  ]
};

// 4. Generate PPTX
const buffer = await generate(schema);
const filename = `report-${new Date().toISOString().slice(0, 10)}.pptx`;
writeFileSync(filename, buffer);
console.log(`✓ ${filename} (${data.length} regions, ${schema.slides.length} slides)`);

How do you schedule it with cron or webhooks?

Run the script every Monday morning:

# Every Monday at 8:00 AM
0 8 * * 1 cd /path/to/project && node sheets-to-pptx.mjs

Or trigger it from a Google Apps Script when the sheet changes — add a webhook that calls your API endpoint, which runs the generation script and saves the output to Google Drive or sends it via email. For the API route pattern, see the Express tutorial or the Next.js tutorial.

The same pipeline works with other data sources. Replace the Google Sheets read with a database query (see the invoice tutorial), an API response, or a CSV file. PaperJSX does not care where the data comes from — it only cares about the JSON schema.

Start automating spreadsheet-to-deck workflows — read the PPTX quickstart, explore multi-format generation, or see pricing.

Generate PPTX from Airtable, Notion, or PostgreSQL

jake — Fri, 24 Jul 2026 14:31:14 +0000

One pattern, any data source. Read records from Airtable, Notion, or PostgreSQL. Transform rows into a PaperJSX JSON schema. Generate a PPTX with charts. The data source changes; the generation code doesn't. This article shows the same quarterly report deck built from three different data sources — proving the pattern is data-source-agnostic. For Google Sheets, see the dedicated tutorial.

The pattern has three steps: Read (fetch records from the data source), Transform (map records to a PaperJSX JSON schema), and Generate (produce the file). Steps 2 and 3 are identical regardless of data source. Only Step 1 changes.

How do you read from Airtable?

According to Airtable's official npm package, "the Airtable API is your own RESTful API for your base. You will use your table names to address tables, column names to access data stored in those columns."

npm install airtable @paperjsx/json-to-pptx

import Airtable from "airtable";
import { generate } from "@paperjsx/json-to-pptx";
import { writeFileSync } from "node:fs";

// 1. READ from Airtable
const base = new Airtable({
  apiKey: process.env.AIRTABLE_TOKEN,
}).base(process.env.AIRTABLE_BASE_ID);

const records = await base("Sales")
  .select({ view: "Grid view" })
  .all();

const data = records.map(r => ({
  region: r.get("Region"),
  revenue: r.get("Revenue"),
  growth: r.get("Growth"),
}));

// 2. TRANSFORM to JSON schema
const schema = buildDeckSchema(data);

// 3. GENERATE
writeFileSync("report.pptx", await generate(schema));

How do you read from Notion?

Notion's @notionhq/client package queries databases and returns structured property objects. Each property (title, number, select, date) has a specific type that you extract from the API response.

npm install @notionhq/client @paperjsx/json-to-pptx

import { Client } from "@notionhq/client";
import { generate } from "@paperjsx/json-to-pptx";
import { writeFileSync } from "node:fs";

// 1. READ from Notion database
const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});

const response = await notion.databases.query({
  database_id: process.env.NOTION_DATABASE_ID,
});

const data = response.results.map(page => ({
  region: page.properties.Region.title[0].plain_text,
  revenue: page.properties.Revenue.number,
  growth: page.properties.Growth.number,
}));

// 2. TRANSFORM + 3. GENERATE (identical to Airtable)
const schema = buildDeckSchema(data);
writeFileSync("report.pptx", await generate(schema));

How do you read from PostgreSQL?

Direct database queries with the pg package. No API wrapper, no rate limits, fastest option for large datasets.

npm install pg @paperjsx/json-to-pptx

import pg from "pg";
import { generate } from "@paperjsx/json-to-pptx";
import { writeFileSync } from "node:fs";

// 1. READ from PostgreSQL
const client = new pg.Client(process.env.DATABASE_URL);
await client.connect();

const { rows } = await client.query(`
  SELECT region, SUM(amount) as revenue,
         ROUND(100.0 * (SUM(amount) - LAG(SUM(amount))
         OVER (ORDER BY region)) / LAG(SUM(amount))
         OVER (ORDER BY region), 1) as growth
  FROM orders
  WHERE created_at >= '2026-07-01'
  GROUP BY region ORDER BY revenue DESC
`);

await client.end();

const data = rows.map(r => ({
  region: r.region,
  revenue: Number(r.revenue),
  growth: Number(r.growth),
}));

// 2. TRANSFORM + 3. GENERATE (identical)
const schema = buildDeckSchema(data);
writeFileSync("report.pptx", await generate(schema));

The shared transform function

All three integrations use the same buildDeckSchema function. It is a pure function: data in, JSON schema out. No side effects, no data-source-specific logic.

export function buildDeckSchema(data) {
  return {
    slides: [
      { elements: [
        { type: "text", value: "Q3 2026 revenue report",
          style: { fontSize: 36, bold: true } },
      ]},
      { elements: [
        { type: "text", value: "Revenue by region",
          style: { fontSize: 24, bold: true } },
        { type: "chart", chartType: "bar",
          data: {
            categories: data.map(d => d.region),
            series: [{
              name: "Revenue",
              values: data.map(d => d.revenue),
            }]
          }},
      ]},
      { elements: [
        { type: "text", value: "Breakdown",
          style: { fontSize: 24, bold: true } },
        { type: "table",
          headers: ["Region", "Revenue", "Growth"],
          rows: data.map(d => [
            d.region,
            `$${d.revenue.toLocaleString()}`,
            `${d.growth}%`,
          ]) },
      ]},
    ]
  };
}

The data parameter is an array of objects with region, revenue, and growth properties. Whether those objects come from Airtable's record.get(), Notion's page.properties, PostgreSQL's rows, or Google Sheets — the schema doesn't care. This is the JSON layer pattern applied to data integration.

Extend: add more data sources

The pattern works with any data source that returns structured data. Replace Step 1 with your API client:

Google Sheets — see the dedicated tutorial
Supabase — supabase.from("table").select() (see the Edge Functions tutorial)
Stripe — stripe.invoices.list() (see the Stripe invoice tutorial)
REST API — fetch("https://api.example.com/data")
CSV file — parse with papaparse, transform rows
MongoDB — collection.find().toArray()

The transform function stays the same. The generate call stays the same. Only the data retrieval changes. For batch generation at scale (10,000+ documents from a database), wrap the pattern with p-limit or BullMQ.

Start generating documents from your data source — PPTX quickstart, Google Sheets integration, or batch generation at scale.

Generate PPTX from JSON in 5 minutes

jake — Thu, 16 Jul 2026 14:31:16 +0000

PaperJSX converts a JSON object to a valid PowerPoint file with one function call. Install @paperjsx/json-to-pptx, define your slides as a JSON schema with text, charts, images, and tables, call generate(), and write the resulting buffer to disk or return it from an API endpoint. The entire flow takes under 5 minutes.

Prerequisites

Node.js 18 or later (LTS recommended)
npm, yarn, or pnpm
A text editor

No native dependencies, no binary installs, no LibreOffice subprocess. PaperJSX is pure JavaScript — it runs anywhere Node.js runs, including Vercel Functions, AWS Lambda, Cloudflare Workers, Deno, and Bun.

1. Install

npm install @paperjsx/json-to-pptx

The package is <5 MB

with zero native dependencies. Compare this to Aspose's per-format SDKs at 50–200 MB each, or wkhtmltopdf-based solutions that require headless browser binaries. According to a 2025 survey by Vercel, cold start time in serverless functions correlates directly with bundle size — lighter packages mean faster first-request latency.

2. Define slides as JSON

A PaperJSX document is a plain JavaScript object. The root has a slides array. Each slide has an elements array. Each element has a type and type-specific properties.

const doc = {
  slides: [
    {
      elements: [
        {
          type: "text",
          value: "Hello from PaperJSX",
          style: {
            fontSize: 36,
            bold: true,
            color: "#1A1A18"
          }
        },
        {
          type: "text",
          value: "Generated from a JSON schema in Node.js",
          style: {
            fontSize: 18,
            color: "#6B6960"
          }
        }
      ]
    }
  ]
};

This is the minimum viable document — one slide, two text elements. The JSON is portable: you can store it in a database, generate it from a template, return it from an API, or have an AI agent produce it.

3. Generate the PPTX

import { generate } from "@paperjsx/json-to-pptx";
import { writeFileSync } from "node:fs";

const doc = {
  slides: [
    {
      elements: [
        {
          type: "text",
          value: "Hello from PaperJSX",
          style: { fontSize: 36, bold: true }
        }
      ]
    }
  ]
};

const buffer = await generate(doc);
writeFileSync("output.pptx", buffer);

console.log("Done — output.pptx written");

node generate.mjs

That's it. Open output.pptx in PowerPoint, Keynote, Google Slides, or LibreOffice Impress. The file is valid OOXML — no repair dialog, no corruption.

The generate() function returns a Buffer in Node.js. It does not write to disk automatically — you control where the output goes. This makes it trivial to return the PPTX from an HTTP endpoint, upload it to S3, or pipe it to a stream.

4. Serve from an API route

In production, PPTX generation typically runs server-side behind an API endpoint. Here is a minimal Express route and a Next.js API route that both generate and return a PPTX file.

import express from "express";
import { generate } from "@paperjsx/json-to-pptx";

const app = express();
app.use(express.json());

app.post("/api/generate-pptx", async (req, res) => {
  const buffer = await generate(req.body);

  res.set({
    "Content-Type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
    "Content-Disposition": 'attachment; filename="report.pptx"',
  });

  res.send(buffer);
});

app.listen(3000);

import { generate } from "@paperjsx/json-to-pptx";
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const doc = await req.json();
  const buffer = await generate(doc);

  return new NextResponse(buffer, {
    headers: {
      "Content-Type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
      "Content-Disposition": 'attachment; filename="report.pptx"',
    },
  });
}

The MIME type for PPTX files is application/vnd.openxmlformats-officedocument.presentationml.presentation. Setting Content-Disposition to attachment triggers a download in the browser rather than trying to render the binary content inline.

5. Add charts, images, and tables

Text-only slides are a starting point. Production presentations need charts, images, and tables. Each is an element type in the JSON schema.

Charts

PaperJSX generates native, editable OOXML charts — not images. According to internal benchmarks, a 10-slide deck with 5 charts generates in under 200ms

on a 2-core serverless function. Recipients can click the chart in PowerPoint and modify the data directly.

{
  type: "chart",
  chartType: "bar",
  data: {
    categories: ["Q1", "Q2", "Q3", "Q4"],
    series: [
      { name: "Revenue", values: [1200, 1800, 2400, 3100] },
      { name: "Expenses", values: [800, 1100, 1500, 1900] }
    ]
  },
  style: {
    width: 8,
    height: 4.5,
    showLegend: true
  }
}

Supported chart types on the free tier include bar, line, pie, scatter, and area. Pro - Single ($79/mo) unlocks extended chart and document features for PPTX — capabilities that python-pptx has been unable to deliver since 2017.

Images

Images can be passed as file paths, URLs, or base64-encoded strings.

{
  type: "image",
  src: "./logo.png",
  style: {
    width: 2,
    height: 1,
    x: 0.5,
    y: 0.5
  }
}

Supported formats: PNG, JPEG, SVG, GIF, and WebP. SVG images are embedded as vector graphics and remain crisp at any zoom level. PaperJSX does not require images to be base64-encoded (unlike pdfmake, which requires base64 for all images).

Tables

{
  type: "table",
  headers: ["Region", "Q3 Revenue", "Q3 Growth"],
  rows: [
    ["North America", "$4.2M", "+12%"],
    ["EMEA", "$3.1M", "+8%"],
    ["APAC", "$2.8M", "+22%"]
  ],
  style: {
    headerBackground: "#4580B0",
    headerColor: "#FFFFFF",
    alternateRowFill: "#F5F4F0"
  }
}

Tables auto-size column widths based on content length. Unlike pdfmake, which has had an open issue for tables wider than the page width since 2015, PaperJSX handles overflow automatically by adjusting column proportions.

Complete JSON schema reference

The full PPTX schema is documented in the PPTX package guide. Here is a summary of all element types.

Element type	Key properties	Tier
`text`	value, style (fontSize, bold, italic, color, align)	Free
`image`	src (path, URL, or base64), style (width, height, x, y)	Free
`shape`	shapeType (rect, ellipse, arrow), style (fill, stroke)	Free
`table`	headers, rows, style (headerBackground, alternateRowFill)	Free
`chart`	chartType, data (categories, series), style (showLegend)	Free (basic) / Pro (combo)

Every element also accepts an optional position object with x, y, width, and height values in inches. If omitted, PaperJSX auto-layouts elements vertically with sensible margins.

Same JSON, four output formats

The defining feature of PaperJSX is that the JSON schema is format-agnostic. The same object that produces a PPTX file can also produce a PDF, DOCX, or XLSX file — each from a separate generate() function in a format-specific package.

import { generate as toPptx } from "@paperjsx/json-to-pptx";
import { generate as toPdf }  from "@paperjsx/json-to-pdf";
import { generate as toDocx } from "@paperjsx/json-to-docx";

const doc = { /* same JSON schema */ };

const [pptx, pdf, docx] = await Promise.all([
  toPptx(doc),
  toPdf(doc),
  toDocx(doc),
]);

Without PaperJSX, the same multi-format output would require PptxGenJS for PPTX, pdfmake or PDFKit for PDF, the docx npm package for DOCX, and ExcelJS for XLSX — four separate libraries with four separate APIs, four separate data structures, and four separate sets of bugs. Public search-demand data shows developers looking for "json to pptx," "json to pdf," and "json to docx" at a combined volume of 600–1,400 searches/month, suggesting strong demand for a unified solution.

Troubleshooting

Error	Cause	Fix
`ERR_MODULE_NOT_FOUND`	Using `require()` instead of `import`	Add `"type": "module"` to `package.json` or use `.mjs` extension
PowerPoint repair dialog	Invalid element structure in JSON	Validate your JSON against the PPTX package guide. Most common cause: missing `type` field on an element.
Empty slides	`elements` array is empty or missing	Ensure every slide object has at least one element in its `elements` array
Charts render as blank rectangles	`series.values` contains non-numeric data	Ensure all values in the `values` array are numbers, not strings
Image not found	Relative path resolves incorrectly in serverless	Use absolute paths or base64-encoded images in serverless environments

Start generating PPTX from JSON — read the full quickstart, explore the PPTX package guide, or try the playground.

Why AI-generated PPTX triggers the repair dialog

jake — Thu, 16 Jul 2026 14:31:13 +0000

If Microsoft's own OpenXML SDK — a purpose-built library maintained by the Office team — has produced files that trigger PowerPoint's repair dialog (issue #1226, issue #1955), an LLM generating raw OOXML has zero chance of doing better. This article explains the seven technical causes of PPTX corruption, why sequential token generation is architecturally incompatible with OOXML's constraints, and the pattern that eliminates the problem entirely.

What is inside a PPTX file?

A PPTX file is not a single document — it is a ZIP archive containing 15–40 interconnected files. Unzip any .pptx and you will find a structure like this:

presentation.pptx/
├── [Content_Types].xml          ← declares every part's MIME type
├── _rels/
│   └── .rels                    ← root relationships
├── ppt/
│   ├── presentation.xml         ← slide list, size, settings
│   ├── _rels/
│   │   └── presentation.xml.rels ← maps rId → slide/master parts
│   ├── slides/
│   │   ├── slide1.xml           ← shapes, text, references
│   │   └── _rels/
│   │       └── slide1.xml.rels  ← slide → layout, images, charts
│   ├── slideLayouts/
│   │   └── slideLayout1.xml
│   ├── slideMasters/
│   │   └── slideMaster1.xml
│   ├── theme/
│   │   └── theme1.xml
│   └── charts/                  ← each chart embeds an Excel workbook
│       ├── chart1.xml
│       └── _rels/
│           └── chart1.xml.rels  ← references embedded .xlsx
├── ppt/embeddings/
│   └── Microsoft_Excel_Worksheet1.xlsx  ← chart data source
└── docProps/
    ├── app.xml
    └── core.xml

Every .rels file maps relationship IDs (rId1, rId2, ...) to target parts. The [Content_Types].xml file declares the MIME type of every part in the archive. The presentation.xml file references slides by relationship ID, and each slide references its layout, master, images, and charts by relationship ID.

PowerPoint validates this entire graph on open. If any reference is broken — an rId pointing to a part that does not exist, a part not declared in [Content_Types].xml, or XML elements in the wrong order — PowerPoint shows the repair dialog.

Seven causes of the repair dialog

1. Element ordering violations

OOXML's XSD schema specifies that child elements must appear in a particular order within their parent. This is the most common and most subtle cause of corruption.

<!-- CORRECT: sldLayoutIdLst before AlternateContent -->
<p:slideMaster>
  <p:cSld>...</p:cSld>
  <p:sldLayoutIdLst>...</p:sldLayoutIdLst>
  <mc:AlternateContent>...</mc:AlternateContent>
</p:slideMaster>

<!-- WRONG: reversed order → repair dialog -->
<p:slideMaster>
  <p:cSld>...</p:cSld>
  <mc:AlternateContent>...</mc:AlternateContent>
  <p:sldLayoutIdLst>...</p:sldLayoutIdLst>
</p:slideMaster>

According to OpenXML SDK issue #1226, this exact element ordering reversal happened in Microsoft's own SDK between versions 2.11 and 2.18. The AlternateContent and sldLayoutIdLst elements were swapped, causing repair dialogs for every generated file. If the official SDK maintained by the Office team gets element ordering wrong, the complexity of this constraint should be clear.

2. Orphaned relationship IDs

Every reference between parts uses a relationship ID. A slide references its layout as rId1 in slide1.xml.rels. If the slide XML contains r:id="rId3" but slide1.xml.rels has no entry for rId3, PowerPoint cannot resolve the reference and triggers repair.

3. Missing content type declarations

The [Content_Types].xml file at the root of the ZIP must declare every part. Add a chart to ppt/charts/chart1.xml without adding <Override PartName="/ppt/charts/chart1.xml" ContentType="application/vnd.openxmlformats-officedocument.drawingml.chart+xml"/> to the content types file, and PowerPoint rejects the file.

4. Chart workbook mismatches

PPTX charts embed a complete Excel workbook (.xlsx) as their data source. According to OpenXML SDK issue #240, streaming data to the embedded package part — even using the official SDK — corrupts the PowerPoint file. The chart XML (chart1.xml) references cells by range, and those ranges must match the structure of the embedded workbook exactly. Any mismatch produces a repair dialog.

5. Invalid namespace prefixes

OOXML uses multiple XML namespaces (a: for Drawing, p: for Presentation, r: for Relationships, mc: for Markup Compatibility). If a namespace prefix is used without declaration, or the wrong namespace URI is bound to a prefix, the file is invalid XML before PowerPoint even attempts to parse it.

6. Duplicate IDs

Slide IDs in presentation.xml, shape IDs in each slide's shape tree, and relationship IDs in each .rels file must be unique within their scope. Generating two slides with the same id="256" or two shapes with the same id="2" triggers validation failures.

7. Malformed ZIP structure

OOXML files use ZIP as the container format. The ZIP archive must use the correct compression method (Deflate), must not include extraneous entries, and must end with a valid Central Directory record. Generating the ZIP incorrectly — wrong compression ratio, missing entries, or incorrect byte offsets — produces a file that PowerPoint cannot parse at all.

Does even the official SDK get it wrong?

The most compelling evidence that raw OOXML generation is fragile: Microsoft's own OpenXML SDK has a history of producing files that trigger the repair dialog.

Issue #1226 (Nov 2022): Element ordering regression — AlternateContent and sldLayoutIdLst reversed in versions 2.11–2.18. Every file generated with the affected versions triggered repair. The fix was a single-line element reorder.
Issue #1571 (Nov 2023): A developer creating a PPTX with tables using the SDK received the repair dialog, and after repair the presentation was empty — all content destroyed.
Issue #1955 (Aug 2025): Creating a "simple blank pptx" with the SDK triggered the repair dialog. A blank file. With the official SDK.
Issue #1948 (Jun 2025): Adding a video element via the SDK corrupted the file. The video appeared after repair but the repair dialog triggered on every open.
Issue #240 (Aug 2017): Streaming chart data to an embedded package part corrupted the PowerPoint file.

These are bugs in a purpose-built SDK maintained by the team that designed the OOXML specification. The SDK has full access to the XSD schemas, comprehensive test suites, and years of production hardening. It still gets element ordering, relationship management, and embedded data wrong. A general-purpose LLM generating raw XML tokens has none of these safeguards.

Why can't LLMs solve this?

LLMs generate tokens sequentially — each token is predicted based on the tokens that came before it. OOXML requires global consistency across 15–40 files in a ZIP archive. These are fundamentally incompatible requirements.

Consider what an LLM would need to do to generate a valid PPTX with one chart:

Generate [Content_Types].xml declaring all parts that will exist — but it hasn't generated those parts yet
Generate presentation.xml.rels with relationship IDs that will match references in slides not yet generated
Generate slide1.xml with a chart reference (r:id="rId2") that matches an entry in slide1.xml.rels not yet generated
Generate chart1.xml with cell references (Sheet1!$A$1:$B$4) that match the structure of an embedded workbook not yet generated
Generate the embedded .xlsx workbook (itself a ZIP archive of XML files) with data that matches the chart's references
Assemble everything into a ZIP archive with correct byte offsets

Every step requires information from future steps. The content types file must know about parts that do not yet exist. The relationship files must know about targets that have not been generated. The chart XML must reference cells in a workbook that has not been created. This is a forward-reference problem that sequential token generation cannot solve.

This is not a model quality issue. GPT-6 and Claude 5 will have the same architectural limitation. Better models will produce more plausible XML — but "more plausible" is not "valid." A file that is 99.9% correct OOXML but has one misordered element still triggers the repair dialog.

The architectural solution

The solution is a structured JSON layer: separate content (what the AI decides) from format compliance (what a rendering engine guarantees). The quick start shows the boundary in code.

The AI produces JSON — slide count, text, chart data, table rows — and the rendering engine handles everything that requires global consistency: element ordering (XSD-compliant), relationship ID assignment (unique and cross-referenced), content type declarations (complete), embedded workbook creation (synchronized with chart XML), namespace declarations (correct URIs), and ZIP assembly (valid Deflate compression with correct Central Directory).

If the JSON is structurally valid (correct types, required fields present), the output file is guaranteed to open without the repair dialog. The engine's test suite runs against every PowerPoint version and the OOXML Validator extension. For working code, see the JSON-to-PPTX quickstart or the MCP server guide.

For the broader architecture, read the PPTX package guide and MCP server guide.

Generate PPTX that never triggers repair — start with the quickstart, read the PPTX guide, or set up the MCP server.

Documentation Screenshot CI: The Scenario Manifest Pattern

jake — Thu, 16 Jul 2026 09:05:15 +0000

A CI job that takes screenshots is not a screenshot system.

It is a camera. Useful, fast, and very capable, but still a camera. The system begins when every screenshot has a scenario: the route, state, viewport, ready condition, capture target, output path, docs usage, and owner that explain why the image exists.

That scenario manifest is the pattern that turns documentation screenshots from ad hoc files into maintained artifacts.

Browser automation is already strong. Playwright can capture pages and locators. GitHub Actions can run workflows and store artifacts. shot-scraper shows how approachable CLI-driven screenshot capture can be. The missing layer is usually the manifest.

Why do CI screenshots become hard to trust?

Most teams start with a script: start the app, open a URL, wait a bit, take a screenshot, upload the PNG. That works until someone asks ordinary maintenance questions. Which docs page uses this image? Which account state was captured? Why is it full-page instead of cropped? Who approves replacement? What changed since the previous approved asset?

If the answer lives in a developer's memory, the screenshot is not maintainable. The manifest moves those answers into the repo.

The manifest defines the artifact

A scenario manifest should be boring and explicit. It does not need to describe every browser instruction. It needs to define the screenshot's contract.

id: settings-api-keys-one-active-key
docsPage: docs/api-keys/create.mdx
route: /settings/api-keys
fixture: team-workspace-one-active-key
viewport:
  width: 1440
  height: 900
theme: light
ready: '[data-docs-ready="api-keys"]'
target: '[data-docs-shot="api-keys-panel"]'
output: static/img/api-keys/create-key.png
owner: docs-platform
publish: review-required

The exact shape can be JSON, YAML, TypeScript, or another structured format. The important thing is that the manifest is the source of truth, not the screenshot file name and not a comment inside a Playwright test.

Where should implementation details live?

The manifest should not become a second programming language. Put policy and identity in the manifest. Put browser mechanics in the runner.

The runner can translate the manifest into Playwright calls: create or select the fixture, navigate to the route, set viewport and theme, wait for the ready signal, capture the target, and write the image plus metadata. This keeps scenarios readable to non-specialists. A docs lead can review whether the scenario represents the right page. An engineer can maintain the runner. A product marketer can see what assets are connected to a launch flow.

Should you trigger screenshots by dependency or by panic?

Screenshot sweeps happen when screenshots are disconnected from change. A manifest lets CI decide which screenshots are suspect, which is how teams stop doing screenshot sweeps before every launch.

Track scenario dependencies in the manifest or in a nearby index. A docs page dependency might point to docs/api-keys/create.mdx, a product dependency to app/settings/api-keys/**, a fixture dependency to fixtures/team-workspace-one-active-key.json, and a component dependency to the shared table or panel used in the screenshot. When one of those inputs changes, CI can run the related scenario. When unrelated code changes, the screenshot job can stay quiet.

GitHub Actions workflow syntax supports path-based triggers and job conditions, but many teams eventually add a small dependency resolver so they can map changed files to scenario IDs. The resolver does not need to be clever. It only needs to prevent "run every screenshot for every commit" from becoming the default.

Store the generated image and the decision record

A screenshot without metadata is hard to review. Once your docs screenshot is a build artifact, it carries provenance. Store the generated image beside a small decision record that includes the scenario ID, commit SHA, workflow run ID, docs page, product route, fixture, viewport, output path, previous approved asset, diff status, and review state.

GitHub Actions artifacts are useful for build-time storage. If the team wants longer-lived review, move the artifact into a review system or asset store after the CI run. Either way, do not force reviewers to reconstruct context from logs.

Why use review states instead of pass/fail only?

Documentation screenshot changes are not only pass or fail.

A changed screenshot may be correct because the product UI changed. An unchanged screenshot may still be wrong because the docs copy moved on. A failed capture may be a scenario problem, a fixture problem, or a real product bug.

Use review states that match documentation work:
generated, unchanged, changed, approved, rejected, docs edit needed, and scenario fix needed. This language keeps the workflow honest without pretending every screenshot difference is a broken test. CI can tell you what happened. People decide what belongs in the docs.

Add a publishing rule per scenario

Not every screenshot needs the same level of caution. The manifest should include a publishing policy.

The default should be review required, especially for public setup flows, billing settings, security settings, and anything behind login. Internal test artifacts should never publish. Low-risk generated reference images can earn lighter rules later, but only after the team has enough history to know the scenario is stable.

How can failures improve the manifest?

The first screenshot CI failures are usually informative. A route needs seeded data. A ready signal is too vague. A capture target is unstable. A viewport does not match the docs layout. An animation or toast overlaps the target. Auth state expires. A feature flag differs from production.

Do not treat these as one-off CI annoyances. Each failure should improve the manifest or runner. Add the fixture. Tighten the ready condition. Capture the locator instead of the full page. Pin the theme. Add an owner.

This is how the screenshot system gets more reliable without pretending every product surface is deterministic on day one.

Use Reshot to keep the manifest and review together

Reshot is designed around this pattern: scenario manifests, generated capture artifacts, review decisions, and approved outputs.

You can keep Playwright as the browser runner. You can keep GitHub Actions as the CI layer. Reshot keeps the screenshot from becoming an anonymous PNG. The workflow is straightforward: define the scenario, run it when dependencies change, store the generated image with metadata, review changed artifacts with context, and publish approved assets to the docs path.

The scenario manifest is the handoff object. It gives Reshot enough context to show what changed, why it ran, who owns it, and whether it can replace the public docs image. That is how the manifest keeps visual debt from accumulating between releases.

Sources

[C1] Playwright screenshots - Official page, full-page, buffer, and locator screenshot support.
[C2] GitHub Actions workflow syntax - Official workflow trigger and job configuration reference.
[C3] GitHub Actions workflow artifacts - Official artifact storage and sharing documentation.
[C4] shot-scraper - Open source CLI project for repeatable website screenshots.

How to Review a Signup Regression After a Next.js Release

jake — Tue, 14 Jul 2026 14:31:32 +0000

A signup regression after a Next.js release should not start with panic. It should start with a narrow review.

The dangerous version is familiar: a deploy ships green and signup quietly gets worse, and a few hours later signup looks weaker. Someone opens product analytics. Someone checks Sentry. Someone asks which pull request touched auth. Someone else wonders whether traffic changed. The team has evidence, but not a review.

The useful question is smaller: did this deploy make the signup path worse, and what evidence supports the next action?

Which signup path should you name before opening dashboards?

"Signup is down" is not specific enough.

Signup may include a marketing page, account creation form, email verification, company profile, workspace creation, plan selection, invite acceptance, and first activation step. A Next.js release might affect only one of those pieces. If the review treats signup as one blob, the team can miss the actual regression.

Start by naming the path precisely: /signup, /signup/company, /auth/callback, /join/[invite], /onboarding/workspace, or whatever route actually changed. Then name the success event. It should be a user outcome, not a page view. Account created, email verified, workspace created, invite accepted, or onboarding completed is stronger than "visited signup."

PostHog's funnel docs are useful here because they separate steps, drop-off, conversion rate, breakdowns, and historical trends. A funnel can show where people left. It still needs deploy context before it becomes a release review.

How do you freeze the release context?

Capture the deploy while it is still fresh:

Field	What to record
Deploy	Commit SHA, deploy URL, deploy time
Pull request	Auth, form, validation, layout, tracking, copy, pricing, invite logic
Owner	The team or person responsible for the signup path
Path	The precise route or flow being reviewed
Metric	Signup completion, invite acceptance, verification success, workspace creation
Windows	Before and after intervals with comparable traffic
Evidence	Product funnel, Sentry issue, route trace, logs, page analytics
Decision	Stable, watch, investigate, rollback candidate

Vercel's deployment docs matter because deployments carry concrete release context: generated URLs, environments, commits, logs, and project metadata. Use that context as the anchor. Do not let the review become "sometime after the release."

How do you compare signup against itself?

Do not start with all-site conversion. Signup can regress while the rest of the product looks normal. It can also look worse because a campaign sent colder traffic into the top of the funnel.

Use the deploy timestamp as the anchor and compare a similar window before and after release. The window should match traffic shape where possible. A Monday morning release should not be compared casually against late Friday night traffic unless volume and source mix are stable.

The comparison should answer the practical question without pretending one chart proves causality. Did the protected signup metric move after deploy? Did the PR touch code, content, routing, auth, pricing, flags, or validation on that path? Did traffic source, geography, device mix, or campaign exposure change enough to explain it? Did companion evidence point at the same route?

The comparison should preserve uncertainty. A dip after deploy is not automatically caused by the deploy. A clean error dashboard is not automatically proof that signup is healthy.

What runtime evidence should you check second?

After the path and metric are named, check runtime evidence.

Sentry's Next.js docs cover error monitoring, tracing, session replay, logs, and profiling for Next.js. In a signup review, Sentry is where you look for new exceptions on the signup route, failed server actions, hydration errors on the form, slow transactions around validation or workspace creation, and replay samples where users hit an error state.

The runtime signal is strongest when it lines up with the product signal, because PostHog shows behavior while Sentry shows breakage and a deploy review needs both. "Signup completion dropped and validation exceptions appeared on /signup/company after the validation PR" is a review. "Sentry has a new issue somewhere" is a lead.

Check route and span evidence when the symptom is soft

Signup regressions are not always loud. A route can become slower without throwing. A server action can retry. A third-party auth call can add latency. A dynamic route can fetch more than it did yesterday.

The Next.js OpenTelemetry guide shows default spans for route rendering, fetches, API routes, and metadata work, plus custom spans. That instrumentation helps explain soft regressions: a route render got slower, an auth callback made a slower external call, workspace creation moved from one backend call to several, or a fetch cache change added latency in the first signup step.

The review does not need every span. It needs enough route evidence to explain whether the deploy plausibly changed the path.

Check behavior and traffic context

Product analytics can show the behavioral shape of the regression: more users start signup but fewer complete it, one step loses more people than usual, mobile moves while desktop stays stable, or a flagged cohort behaves differently. Vercel Web Analytics can add page-level context through visitor and page behavior. PostHog can add events, cohorts, flags, and funnel breakdowns. Use those signals to prevent false blame.

For example:

Signup completion dropped after deploy, but traffic from a new campaign doubled and those visitors historically convert lower. Sentry is quiet. Mark watch and recheck with segmented traffic.

That is very different from:

Signup completion dropped after deploy, traffic mix is stable, and Sentry shows new validation failures on the same route. Mark investigate.

Use four decision states

The review should end with a state. Stable means signup stayed in range. Watch means signup moved but the evidence is mixed. Investigate means signup moved and the deploy plausibly touched it. Rollback candidate means signup moved and technical evidence points to the release. This language keeps the team from treating every dip as an incident or every clean error dashboard as a dismissal.

Why write the note while the evidence is fresh?

A good signup regression note is short:

Deploy 9f3c changed company signup validation. /signup/company completion dropped in the first stable post-deploy window. Traffic mix was normal. Sentry shows new validation errors on the same route. Marked investigate; owner is onboarding.

A weak note is:

Signup looks down after the deploy.

The weak note forces the next person to reconstruct the release. The strong note lets them act.

TrueClara is built for that strong note. It keeps deploy metadata, path ownership, signup metrics, evidence links, and the decision together. Your analytics and monitoring tools remain the evidence sources. TrueClara keeps the signup review from dissolving into tabs.

The next time signup moves after a Next.js release, do not start by asking which dashboard is right. Start with the path. Anchor it to the deploy. Layer the evidence. Record the decision.

Sources

[C1] PostHog funnels - Product analytics documentation for funnel steps, conversion, breakdowns, and trends.
[C2] Sentry Next.js docs - Sentry documentation for Next.js errors, traces, replay, logs, and profiling.
[C3] Next.js OpenTelemetry guide - Official Next.js instrumentation guide for route, fetch, API, and custom spans.
[C4] Vercel deployments - Vercel documentation for deploy methods, URLs, environments, and release metadata.
[C5] Vercel Web Analytics - Vercel documentation for page-level visitor behavior.

PostHog Behavior, Sentry Breakage: Deploy Review Needs Both

jake — Thu, 09 Jul 2026 14:30:42 +0000

PostHog and Sentry are not interchangeable tools. They answer different questions.

PostHog is where a team looks when it wants to understand product behavior: events, funnels, cohorts, feature flags, experiments, session replay, and conversion movement. Sentry is where a team looks when it wants to understand software failure: exceptions, traces, performance issues, releases, replays, and the technical context around a broken experience.

After a deploy, both are useful. Neither one, alone, is the full release review.

The question is not "PostHog or Sentry?" The better question is: did this deploy hurt the route we care about, and which evidence proves the next action?

What does each tool answer after a deploy?

A Next.js release can damage a product path without creating a loud exception. It can also create errors without changing the customer outcome enough to matter. That is why deploy review gets messy when a team treats one dashboard as the source of truth.

Sentry for Next.js is strong when the release causes runtime trouble. It can surface errors, performance spans, traces, replays, and release-adjacent debugging context. If a server action starts throwing, a hydration issue appears, or a route slows down, Sentry is often where the technical explanation begins.

PostHog's Next.js docs are strong on product instrumentation. Events, feature flags, user behavior, and funnels help answer whether people completed the path after the release. If signup completion dipped or onboarding step two started losing users, product analytics is the right evidence source.

Vercel Analytics can explain page-level behavior and traffic changes. The Next.js OpenTelemetry guide shows the instrumentation layer underneath routes, fetches, and custom spans.

Each tool is useful. The deploy review is the layer that asks them all the same question.

Question	Best evidence source
Did users complete the path at the same rate?	PostHog funnel or event analysis
Did the release introduce new runtime failures?	Sentry issues, traces, and replays
Did traffic mix or page behavior change?	Vercel Analytics and acquisition context
Did a route render, fetch, or backend call change?	OpenTelemetry spans and traces
Did the PR actually touch the path?	Pull request diff and deploy metadata

Why does deploy impact fall between dashboards?

Most teams already have enough telemetry to see the symptoms. The hard part is keeping the symptoms attached to the release.

A deploy goes out at 10:14. Signup dips by 11:00. Sentry shows a small increase in validation errors. PostHog shows a larger drop at one step. Vercel shows traffic was normal. The PR changed a validation rule. That is a useful story, and it mirrors the pattern in a green Next.js deploy that quietly hurt signup.

But if those facts live in separate tabs, the team has to assemble the story every time. One person pastes a Sentry link. Another posts a funnel screenshot. Someone asks which commit shipped. Someone else asks whether traffic changed. By the time the group agrees on the route, half the context is already stale.

Deploy impact is not a dashboard category. It is an operating question:

Which release created the question?
Which path could a customer feel?
Which metric says the path got better or worse?
Which evidence supports the movement?
What decision did the team make?

TrueClara keeps that question as a case file.

Do not force product analytics to explain engineering failure

PostHog can show that signup completion dropped. It can show the step where users left. It can show whether a feature flag was involved. It can show cohorts, replays, and events around the behavior.

But a product analytics tool is not the best place to inspect stack traces, slow spans, server-side exceptions, or release health. If the route moved because a server action started failing under a certain payload, Sentry or trace data should carry that investigation.

The mistake is using the funnel as proof of cause. A funnel movement tells you something changed in behavior. It does not prove why.

A useful review sentence sounds like this:

Signup completion dropped after deploy 9f3c. PostHog shows the loss at company validation. Sentry shows new validation exceptions on the same route. Investigate the validation change.

That sentence uses product analytics for behavior and error monitoring for failure. It does not make either tool do the other's job.

Do not force error monitoring to explain product movement

Sentry can show a clean release while a route still gets worse. A copy change can confuse users without throwing. A layout change can hide a button without causing a JavaScript exception. A pricing experiment can reduce upgrade completion with no runtime failure. An auth flow can become slower or more confusing before it breaks.

In those cases, the absence of a Sentry incident is useful but not final. It narrows the investigation. It does not close the review.

The route still needs product evidence:

Did users reach the same step?
Did they complete the same action?
Did the exposed audience change?
Did a feature flag split the population?
Did the traffic source change?

A deploy can be technically clean and commercially worse. That is the point of reviewing the path, not only the app.

Build a deploy review packet

The practical answer is not another giant dashboard. It is a packet that keeps the route, release, and evidence together.

Packet field	Why it matters
Deploy and PR	Prevents vague "after the release" debugging
Route or path	Keeps the review tied to a customer experience
Protected metric	Defines what healthy means
Product evidence	Shows behavior movement
Runtime evidence	Shows failures, latency, traces, or replay context
Traffic context	Explains whether audience changed
Decision	Turns evidence into action

The packet does not replace PostHog, Sentry, Vercel, or OpenTelemetry. It makes them answer the same release question.

When should you mark stable, watch, investigate, or rollback candidate?

Use stable when the protected metric stays in range and companion evidence is quiet.

Use watch when the path moved but the supporting evidence is mixed. Maybe traffic changed. Maybe the sample is thin. Maybe the movement is near the edge of normal variance. Watch is a real state because it prevents overreaction.

Use investigate when the path moved and the deploy plausibly touched it. At that point the owner needs evidence links, not another meeting.

Use rollback candidate when the route movement and technical evidence point to the same release. That still requires judgment, but the conversation becomes concrete: the release changed this path, the path got worse, and the evidence supports action. For a full walkthrough of that moment, see the deploy shipped, the route got worse, now what.

Use TrueClara to keep the question intact

TrueClara is built for the space between product analytics and error monitoring. It does not ask a team to abandon either tool. It keeps deploy metadata, route ownership, path metrics, and evidence links attached to the release.

That gives the team a release review object:

what shipped
what route it touched
what behavior changed
what PostHog showed
what Sentry showed
what Vercel or trace data explained
what decision the team made

PostHog shows behavior. Sentry shows breakage. Vercel and OpenTelemetry add traffic and instrumentation context. TrueClara keeps the deploy question intact long enough for the team to answer it.

Who owns the release review?

Tool choice is not the only reason deploy-impact reviews fail. Ownership is just as important.

If product owns the funnel, engineering owns the errors, growth owns experiments, and platform owns deployments, the review can fall between teams. Everyone has a useful dashboard. Nobody owns the release question.

Assign the owner by path, not by tool. If the deploy touched signup, the signup owner owns the review. If it touched checkout, the checkout owner owns the review. If it touched onboarding, the onboarding owner owns the review. Engineering still investigates technical evidence. Product still interprets behavior. The owner keeps the decision moving.

A path owner should be able to say:

this deploy touched my path
this metric defines path health
these evidence links matter
this is stable, watch, investigate, or rollback candidate

That ownership model prevents the team from debating whether PostHog or Sentry is the "real" source. The real source is the review packet. The tools provide evidence.

What if the answer is no action?

A good deploy review often ends with no action. That is not wasted work.

If the route stayed stable, the team learned that the release did not damage the protected path. If the route moved but traffic mix explains it, the team avoided a false incident. If product behavior changed but Sentry stayed quiet, the team learned to investigate UX or copy before chasing exceptions. If errors increased but the path stayed healthy, the team can prioritize cleanup without treating it as a product emergency.

The value is not always a rollback. The value is a decision with evidence.

That decision becomes part of release memory. The next time signup moves, the team can compare against prior reviews instead of starting from scratch. Over time, the route review becomes a habit: every important deploy leaves behind a short record of what happened to the customer path.

Sources

[C1] PostHog Next.js docs - Product analytics, feature flag, and event instrumentation for Next.js apps.
[C2] Sentry for Next.js - Error monitoring, performance monitoring, tracing, replay, and release debugging for Next.js.
[C3] Vercel Analytics - Page-level visitor analytics for Vercel applications.
[C4] Next.js OpenTelemetry guide - Official route, fetch, and span instrumentation guidance for Next.js.

CI Can Take Screenshots. It Should Not Publish Them Blindly.

jake — Thu, 09 Jul 2026 14:30:37 +0000

CI is a good place to generate product screenshots. It is a dangerous place to publish them without review.

A browser can open the product, load a fixture, wait for the UI, capture the page, and store the result as a build artifact. Playwright supports page screenshots, full-page screenshots, element screenshots, and buffers. GitHub Actions can run the job on pull requests, scheduled builds, or docs changes. Tools like shot-scraper make website screenshot capture easy to script.

The capture problem is manageable. The publishing problem is where teams get hurt.

A CI screenshot can be technically fresh and still wrong for the docs.

Treat screenshots like build artifacts

A build artifact has provenance. It came from a commit, a workflow, an environment, and a set of inputs. A docs screenshot needs the same treatment.

If a screenshot appears in public documentation, the team should be able to answer:

Which commit generated it?
Which route did it capture?
Which fixture or account state was loaded?
Which viewport and theme were used?
Which selector proved the page was ready?
Which docs page uses the asset?
Who approved the replacement?

Without that trail, the screenshot is just a generated PNG. It may be correct. It may be a loading state with nice pixels.

Artifact field	Example
Commit	pull request head SHA
Route	\/settings\/api-keys
Fixture	team workspace with one active key
Viewport	1440x900
Ready condition	data-docs-ready="api-keys"
Capture target	API key table panel
Docs usage	docs\/api-keys\/create.mdx
Review state	approved, rejected, needs scenario fix

This metadata is what makes CI screenshots safe to review.

Separate screenshot tests from docs screenshots

Visual regression tests and documentation screenshots overlap, but they are not the same job.

A visual regression test asks, "Did the UI change unexpectedly?" A docs screenshot asks, "Does this image still teach the product step correctly?"

The same browser capture may support both jobs, but the review rules are different. A pixel difference can fail a regression test. In docs, a pixel difference may be the expected result of a product improvement. Conversely, a screenshot can pass a pixel threshold and still be bad documentation if it shows the wrong user state or crop.

A clean CI design keeps the outputs separate:

Output	Owner	Decision
Visual regression result	Engineering	Pass, fail, update baseline
Docs screenshot artifact	Docs, product, or support owner	Approve, reject, request scenario fix
Public docs asset	Docs publisher	Replace only after approval

That separation prevents engineering test baselines from becoming public documentation by accident.

Make product state deterministic enough

Screenshot CI fails when the product state depends on live data, random accounts, timestamps, or whatever a developer had in their local workspace.

The fix is not always a full fake backend. Start with the state that matters for the screenshot. If the screenshot teaches API key creation, the page needs a workspace with a known key state. If it teaches billing settings, the page needs a known plan and payment state. If it teaches integration setup, the page needs connected and disconnected variants.

Useful controls include:

seeded demo workspaces
mocked network responses for unstable external data
fixed dates and time zones
explicit feature flag values
test users with known roles
data attributes for capture targets and ready states

The goal is not to make the entire product deterministic. The goal is to make the screenshot state reproducible.

Wait for the UI you mean to capture

A surprising number of bad screenshots are readiness bugs. The browser captured too early. A skeleton was still visible. A chart had not drawn. A toast covered the button. A font swapped after capture. A settings panel was still animating.

The wait condition should be part of the scenario, not an invisible sleep.

Weak:

wait 3000ms
take full-page screenshot

Better:

open route
wait for account fixture to load
wait for data-docs-ready="billing-settings"
capture locator for the billing panel

Playwright gives teams the browser primitives. The scenario should express what "ready" means for the docs image.

Do not auto-replace public docs on every run

The safest default is: CI generates, humans approve, publishing replaces.

Auto-replacement can work for low-risk internal references. It is risky for public product documentation, especially setup flows, compliance screens, billing pages, admin permissions, and integration guides. Those images carry trust. A wrong screenshot can make the docs look current while making the instruction worse.

Use review states:

State	Meaning
Generated	CI produced the screenshot
Changed	The artifact differs from the current docs asset
Needs review	A human must approve replacement
Approved	The screenshot can publish
Rejected	The asset is wrong or docs need editing
Scenario fix needed	The automation captured the wrong state

This gives the team a lane for screenshots instead of a folder of files.

Use Reshot between CI and the docs repo

Reshot keeps the screenshot scenario, CI artifact, review decision, and approved docs asset together. It does not replace Playwright. It does not replace your CI provider. It gives the screenshots a workflow.

A practical setup looks like this:

Define scenarios for screenshots that matter.
Run the scenarios in CI when product or docs inputs change.
Store generated artifacts with commit, route, fixture, viewport, and docs usage.
Send changed screenshots to review.
Publish approved assets back to the docs repo or asset store.

This is how CI becomes useful for documentation screenshots without becoming reckless.

The browser can take the picture. The team still needs to decide whether the picture belongs in the docs.

Name artifacts so people can debug them

Screenshot artifacts often fail at the boring layer: naming. A folder called screenshots is not enough when a reviewer needs to know which product state produced an image.

Use names that carry useful context without becoming unreadable:

Naming part	Example
Product area	settings-api-keys
Scenario state	one-active-key
Viewport	desktop-1440
Theme or locale	light-en
Commit or run id	pr-1842

A generated file like settings-api-keys_one-active-keydesktop-1440_pr-1842.png is not beautiful, but it is debuggable. The reviewer can tell what it is before opening it. The CI logs, artifact store, and docs replacement step can all refer to the same object.

Pair the file name with a small metadata record. The metadata should include the route, fixture, ready condition, capture target, docs page, and reviewer state. That turns a PNG into a traceable artifact.

Record common failure modes

The first few CI screenshot failures will teach the team more than the happy path. Capture them as scenario fixes instead of one-off debugging.

Common failure modes include:

app captured before hydration finished
test account missing required plan or role
modal or toast covering the target element
external integration state unavailable
browser viewport different from docs layout
animation or chart rendering after capture
feature flag exposing a different UI than production

Each failure should improve the scenario. Add a better ready signal. Seed the fixture. Mock the unstable response. Capture the locator instead of the full page. Pin the feature flag. The point is not to make screenshots flawless immediately. It is to make the workflow more deterministic each time it fails.

This is why review is so important. Review does not only protect the docs. It improves the screenshot system itself.

Sources

[C1] Playwright screenshots - Official screenshot APIs for pages, locators, full-page captures, and buffers.
[C2] GitHub Actions docs - Workflow automation and artifacts in CI.
[C3] shot-scraper docs - Scriptable website screenshot capture.

Playwright Screenshots for Documentation: What to Automate and What to Review

jake — Wed, 08 Jul 2026 14:30:37 +0000

Playwright can take the screenshot. It cannot decide whether that screenshot still belongs in your docs.

That distinction matters. Playwright's screenshot guide covers the mechanics: full-page captures, element captures, buffers, clipping, image quality, and file output. Those primitives are exactly what a docs team needs to stop retaking the same product screenshot by hand.

But documentation screenshots are not ordinary test artifacts. A product image in a setup guide is part of the instruction. It has to show the right user state, the right public UI, the right viewport, and enough surrounding context for a reader to complete a task. Automation helps only when it creates a reviewable artifact instead of a folder full of mystery PNGs.

Automate repeatable product states first

The best first candidates are screenshots where the product state is repeatable and the cost of staleness is high.

Start with the screenshots that help users finish operational tasks: creating an API key, connecting an integration, changing a billing setting, configuring OAuth, exporting data, or checking an admin permission. These screenshots usually have a known route, a stable UI target, and a docs page that depends on them. They are much better candidates than launch collages, annotated marketing images, or one-off editorial visuals.

Playwright's locator screenshot support is especially useful here because many docs images should show a panel, table, modal, or settings section rather than the entire browser window. Capturing a locator keeps the screenshot tied to the instructional object.

Put the screenshot in a scenario manifest

A Playwright test file can capture a page, but the docs team needs more than executable code. It needs a scenario record that explains why the screenshot exists.

A useful scenario manifest contains:

Field	Example
Docs page	docs/integrations/github.mdx
Product route	/settings/integrations/github
Fixture	workspace with GitHub connected
Viewport	desktop 1440x900
Theme	light
Ready signal	data-docs-ready="github-connected"
Capture target	integration settings panel
Output	static/img/integrations/github-connected.png
Owner	docs-platform

This manifest is not bureaucracy. It is the maintenance contract. When the UI changes, the reviewer can see what state the screenshot was supposed to show. When capture fails, the engineer can tell whether the route, fixture, selector, or docs path is wrong.

Use Playwright for readiness, not sleeps

Documentation screenshots often fail in a boring way: the browser captures too early.

A skeleton is still visible. A chart has not rendered. A toast covers the button. A font swaps after the screenshot. A menu animation has not finished. The screenshot looks plausible, but it teaches the wrong thing.

Do not hide readiness in a long timeout. Express it in the scenario. The runner should navigate to the route, select the fixture, wait for the loaded state that matters, confirm the target element is visible, and only then capture the intended locator.

Playwright's docs for screenshots show how simple the capture call can be. The hard part is the sentence before it: "This page is now in the state the docs need."

Separate visual tests from docs screenshots

Playwright also supports visual comparisons, and teams often ask whether docs screenshots should just be visual tests.

They overlap, but they are not the same workflow.

A pixel diff is useful evidence, not the final decision. If a button moved because the product shipped a better layout, the docs screenshot probably should change. If the image changed because the capture account lost access to a feature, the screenshot should not publish.

Visual comparison asks whether the UI changed unexpectedly. Documentation screenshot review asks whether the image still teaches the step correctly. The same browser capture can feed both workflows, but the decision record should be separate. Visual testing protects UI behavior. Screenshot review protects public instructions.

Store artifacts with enough context

GitHub Actions artifacts are a good place to store generated screenshots during CI. The important part is naming and metadata.

A screenshot artifact should answer basic questions without asking the reviewer to inspect CI logs. It needs the commit, scenario, route, fixture, viewport, theme, current docs asset, and whether the candidate differs from the approved version.

Use names that are readable in a CI artifact list:

settings-api-keys__one-active-key__desktop-1440__light__pr-1842.png

The file name does not need to carry everything. Pair it with a small JSON record containing route, owner, ready signal, docs path, and review status. That turns a Playwright output file into a docs artifact.

Review what automation cannot know

Automation can detect that an image changed. It cannot know whether the change is useful, public, or misleading.

Review is where docs, product, support, and engineering have different but useful perspectives. Engineering can tell whether the UI state is valid. Docs can tell whether the screenshot still supports the surrounding copy. Support can spot the states users misunderstand. Product can confirm whether the flow is ready to describe publicly. If a banner, toast, wrong account, unreleased flag, or bad crop appears in the image, the reviewer catches it before the docs inherit the mistake.

Publish only after approval

A safe pipeline has two distinct jobs:

Generate screenshots from Playwright scenarios.
Publish approved docs assets.

Do not collapse those jobs just because CI can write to the docs repo. A technically fresh screenshot can still be wrong. It can show a test account, a transient experiment, a loading state, or a feature that has not launched.

Use review states, but keep the state model simple. A screenshot is generated, changed, needs review, approved, rejected, or blocked on a scenario fix. That is enough to keep CI fast and publishing conservative without turning the workflow into a status taxonomy.

Use Reshot as the artifact layer

Reshot fits between Playwright and the docs repository. Playwright handles browser automation. GitHub Actions or another CI system runs the job. Reshot keeps the scenario, generated screenshot, metadata, review decision, and approved output together.

That lets teams automate the repeatable parts without losing editorial judgment. A practical Reshot setup defines scenarios for the screenshots that matter, runs Playwright when a scenario input changes, stores the generated image with metadata, routes changed screenshots into review, and publishes only the approved asset back to the docs path.

Playwright is the capture engine. Reshot is the place where the capture becomes a documentation artifact with state, ownership, and a decision.

Sources

[C1] Playwright screenshots - Official screenshot primitives for page, full-page, buffer, and locator capture.
[C2] Playwright visual comparisons - Official guidance for snapshot and visual comparison testing.
[C3] GitHub Actions workflow artifacts - Official artifact upload, download, and retention guidance.
[C4] shot-scraper - Open source CLI project for automated website screenshots.

Next.js Observability Is Not Deploy Impact

jake — Tue, 07 Jul 2026 14:30:43 +0000

Next.js observability tells you what the application is doing. Deploy impact tells you whether the release changed a product path that matters.

Those are related questions, but they are not the same question.

A team can have Sentry installed, OpenTelemetry spans flowing, Vercel Web Analytics enabled, Speed Insights collecting Core Web Vitals, and product analytics events in place. The deploy can still leave everyone asking the same awkward question: did this release hurt signup, checkout, onboarding, invite acceptance, or another route customers actually feel?

The missing layer is not more raw signal. It is the review that ties signal to a deploy, a route, a protected metric, and a decision.

Observability gives you witnesses, not the case file

The official Next.js OpenTelemetry guide describes instrumentation for route rendering, fetches, API routes, metadata generation, and custom spans. That is useful engineering evidence. It can tell you that a route got slower, a fetch changed shape, or a server action became noisier.

Sentry's Next.js docs explain how to collect errors, performance data, replays, logs, and tracing context from a Next.js app. That is also useful evidence. It can tell you when a release introduced a new exception or made a transaction slower.

Vercel Web Analytics gives page and visitor behavior. Vercel Speed Insights helps watch real-user performance signals. PostHog's Next.js docs cover product events and feature flags.

All of those tools answer important questions. Error monitoring can show a runtime failure. Tracing can show a route, fetch, or handler changing shape. Web analytics can show page traffic and visitor behavior. Product analytics can show funnel movement. Deployment metadata can show what shipped and when.

None of that automatically decides whether the product path got worse because of the release. Deploy impact starts when those witnesses are attached to the same release question.

The deploy question is narrower than the observability question

Observability asks: what is happening in the system?

Deploy impact asks: after this deploy, did this product path get worse?

That narrower question is why the review should start with a route, not a dashboard. If a pull request touched /signup/company, the first review target is signup completion and the evidence around that path. If it touched payment state, the first review target is checkout completion and payment failure context. If it changed auth middleware, the first review target may be login success, invitation acceptance, and protected route access.

The route keeps the review honest. Without it, the team can waste time scanning broad charts until one of them looks interesting. With it, the team can move in a straight line: anchor the question to a deploy, name the path a user could feel, compare the path against a health metric, then decide whether the companion evidence supports action.

The answer may still be "no action." That is fine. A reviewed stable path is useful release memory.

A green deploy is only a shipping fact

Vercel's deployment docs are clear that every successful build creates a deployment with its own URL, and Git pushes or pull requests can trigger those deployments. That is the shipping layer.

The product layer starts after the deployment exists.

A successful build tells you the app was assembled and deployed. It does not tell you whether users completed signup at the same rate. It does not tell you whether the pricing page sent fewer people to checkout. It does not tell you whether a validation change increased retries without throwing an exception.

This distinction matters because a team can mistake platform health for product health. The build may pass while signup gets slower. Sentry may stay quiet while checkout completion dips. Web Vitals may stay normal while an onboarding step becomes confusing. Product analytics may show a dip that is later explained by traffic mix rather than code.

The review should preserve both facts: the deploy was technically green, and the path still needs evidence.

Use a deploy impact packet

A deploy impact packet is small enough to become habit. It is not a postmortem. It is not a dashboard replacement. It is the minimum object that keeps the release question from scattering.

Field	Example
Deploy	Commit, deployment URL, shipped time
Pull request	What changed and who owns it
Path	`/signup/company`, `/checkout`, `/onboarding/connect`
Protected metric	Completion, successful submit, activation, payment success
Before window	Comparable traffic before release
After window	First stable traffic window after release
Evidence links	Sentry issue, trace sample, PostHog funnel, Vercel page
Decision	Stable, watch, investigate, rollback candidate

The packet is deliberately boring. Boring is useful when a chart is moving and everyone wants to jump to a theory.

Watch for the false comfort of complete instrumentation

Instrumentation coverage can become its own trap. Once a team has enough traces, events, logs, and analytics, it is tempting to believe the answer is in there somewhere. It usually is. The problem is retrieval under pressure.

If the team has not named the path, the search space is too large. If it has not named the deploy, every chart becomes a possible coincidence. If it has not named the decision state, the review ends as a Slack thread instead of an action.

The decision language should stay plain. Stable means the protected metric stayed in range and evidence is quiet. Watch means the path moved, but traffic, sample size, or companion evidence is mixed. Investigate means the path moved and the deploy plausibly touched it. Rollback candidate means the path moved and technical evidence points to the same release.

That standard does not require perfect causality. It requires enough evidence to choose the next action.

Decide what to review before the release

The best post-deploy review starts in the pull request.

If a PR touches a value route, add the post-deploy review target before merge: affected path /signup/company, protected metric company signup completion, evidence to check in validation errors, signup funnel, and route traces, owner onboarding, review window first stable post-deploy traffic window. That short note changes the release habit. The team is no longer surprised after the chart moves. It already knows which path deserves attention.

This is where TrueClara fits. It keeps the deploy, path, metric, evidence links, and decision together. Sentry remains the place to inspect errors and traces. PostHog remains the place to inspect events and funnels. Vercel remains the place to inspect deployments, page behavior, and performance. TrueClara keeps them attached to the product path the release may have changed.

Observability tells you what the system emitted. Deploy impact tells you whether the release changed the path customers care about. Next.js teams need both, but they should not confuse one for the other.

Sources

[C1] Next.js OpenTelemetry guide - Official Next.js guide for instrumentation, default spans, custom spans, testing, and deployment.
[C2] Sentry Next.js docs - Sentry setup and monitoring documentation for Next.js applications.
[C3] Vercel Web Analytics - Vercel documentation for page and visitor analytics.
[C4] Vercel Speed Insights - Vercel documentation for real-user performance measurements.
[C5] Vercel deployments - Vercel deployment methods, URLs, environments, and deployment metadata.
[C6] PostHog Next.js docs - PostHog setup guidance for Next.js, events, and feature flags.