DEV Community: Lucien Chemaly

Agentic Document Workflows: How to Wire PDF APIs into AI Agents That Actually Work in Production

Lucien Chemaly — Tue, 28 Jul 2026 08:08:22 +0000

The demo works. You send a PDF to GPT-4o, ask it to extract line items, and it returns something that looks like JSON. Then you run it on 500 invoices in staging and watch it hallucinate table rows, drop page-two data entirely, and return different field names on identical documents. By the time you get to 10,000 PDFs a day in production, the failure rate makes the whole approach unusable.

That's the prototype trap. Sending raw PDFs to a vision model gets you coherent prose, but it loses table structure, page coordinates, and element types. The output is nondeterministic, which means your downstream agent can't reliably route on field values, validate totals, or trigger conditional workflows. You end up with a pipeline that works in a notebook and breaks in a queue.

The delta between a demo and a deployable agentic document workflow is almost entirely in how you handle the document layer. The Document AI market is projected to grow from USD 14.66 billion in 2025 to USD 27.62 billion by 2030 at a 13.5% CAGR, and most of that investment is being made precisely because raw LLM extraction doesn't hold up under real operating conditions.

A dedicated, deterministic PDF API layer handles structural extraction and document operations, while the LLM handles reasoning and routing. This article shows you how to build that, specifically how to wire Foxit's PDF Services API into an agent pipeline that's auditable, composable, and designed to run at volume.

1. The Production Gap: Why LLMs Reading PDFs Break at Scale

LLM-based PDF extraction fails in production because vision models reconstruct document structure from visual patterns rather than reading it deterministically. At scale, this produces hallucinated table rows, token cost explosion, schema drift between runs, and no replayable audit trail. A better prompt won't fix any of these:

Hallucinated table rows: When a vision model interprets a multi-column PDF table as image input, it reconstructs structure from visual patterns. On clean PDFs, this is often accurate. On anything with merged cells, rotated text, or embedded watermarks, the model invents rows or merges adjacent data. At 10,000 invoices per day, a 2% hallucination rate is 200 wrong records, and you won't know which ones.
Token cost explosion: A 10-page PDF converted to images for vision input can consume 2,000–4,000 tokens per page depending on resolution. Processing 10,000 documents daily at that rate pushes monthly costs into the tens of thousands of dollars for the extraction step alone, before you've done any reasoning.
No structured output contract: The LLM returns whatever JSON shape seems plausible given the prompt. Field names drift between runs. Tables become arrays of strings on one call and arrays of objects on the next. Downstream validators fail silently because the schema wasn't enforced upstream.
No audit trail: If a contract clause gets misclassified and triggers the wrong workflow, you have no way to replay what the model saw and why it decided what it did. Under HIPAA or SOC 2, "the model just got it wrong" isn't an acceptable incident response.

A clean architectural boundary fixes all four. The PDF API handles structured extraction and document operations deterministically, and the LLM operates on the typed output rather than the raw document. That separation is what makes an agentic document workflow actually workable.

2. What an Agentic Document Workflow Actually Looks Like

An agentic document workflow (ADW) differs from RAG and traditional IDP by maintaining state across multi-step operations, coordinating extraction, retrieval, structured output, and downstream actions in a single orchestrated loop. The agent decides, acts, then decides again based on what the action produced.

LlamaIndex coined the term "Agentic Document Workflows" (ADW) to describe a pattern that goes beyond both RAG and traditional intelligent document processing. RAG retrieves text chunks and generates answers in one pass. Traditional IDP classifies and extracts, then routes to a rules-based engine. The agentic loop layers statefulness on top of both, which is what enables conditional routing, validation, and document generation inside the same pipeline.

The document lifecycle an agent must own in this model spans five stages, from ingest (OCR + structural parse) through extract (typed elements), reason (LLM decision layer), and act (generate, redact, sign, or archive), to emit (append an event trace for auditability). Each stage has a clear owner.

The mistake most teams make is mixing the LLM layer and the PDF API layer. The LLM should never see raw PDF bytes. It should receive typed JSON from the PDF API (table arrays, text blocks with bounding box coordinates, form field values) and make decisions on that structured data. The PDF API owns extraction. The LLM owns understanding.

3. The Core API Operations Agents Need

A production-ready PDF API layer for agentic workflows requires four capabilities, namely deterministic structural extraction that returns typed JSON, template-driven document generation, compliance-grade security operations (flatten, encrypt, redact), and programmatic eSign triggering with a native audit trail.

Structured extraction is the most important. The API should combine OCR, layout recognition, and AI parsing to return typed, element-classified JSON rather than raw text. Foxit's PDF Structural Extraction API extracts twelve different element types (text blocks, tables, form fields, images, and more) and returns them as structured JSON, making the output directly consumable by a downstream LLM or validation step without post-processing. The endpoint is currently in Trial status at schema v1.0.7, so pin your parsers to the version.schema field in the response. The schema can change between versions, and a breaking change will fail silently if you're not checking it.

Document generation: Agents that process documents also need to produce them. Foxit's DocGen API takes a base64-encoded DOCX template and a JSON data payload, merges them, and returns a PDF or DOCX. Before generation, the Analyze Document (Base64) endpoint inspects the template's merge fields, which means you can validate that your data payload covers all required placeholders before sending the generation request, rather than discovering missing fields in the output.
Security operations: Compliance archiving almost always requires flattening (merging annotations and form fields into a static layer), encryption, and sometimes redaction. These need to be callable as discrete API operations. The PDF Services API covers these as separate endpoints.
eSign triggering: If your workflow ends in a signature (contract approval, remittance confirmation, policy acknowledgment), the signing step needs to be a programmatic API call. The eSign API initiates signing workflows and maintains a native audit trail including signer identity, timestamps, and an activity history endpoint you can query. This is the one leg of the pipeline where Foxit provides audit data natively. The rest of the trace you build yourself (more on that in Section 5).

4. Wiring a PDF API into Your Agent: The REST Workflow Pattern

Every Foxit PDF Services API call follows a four-step async pattern (upload, submit, poll, download) that applies uniformly to extraction, OCR, compression, and flattening. Internalize this loop once and you can implement any operation without relearning the integration.

Prerequisites

To run the code in this section and the pipeline in Section 7, you need:

Python 3.8+ with pip and a virtual environment
The requests library
A code editor such as VS Code with the Python extension (PyCharm or any editor works too)
A free Foxit developer account (sign up here, no credit card required) for your client_id and client_secret

Set up the workspace in one shot:

mkdir adw-pipeline && cd adw-pipeline
python3 -m venv .venv && source .venv/bin/activate
pip install requests
export FOXIT_CLIENT_ID="your_client_id"
export FOXIT_CLIENT_SECRET="your_client_secret"

The four-step loop

POST to upload the source document as multipart/form-data to receive a documentId
POST to the operation endpoint (e.g., structural extraction) with the documentId to receive a taskId
GET to poll task status using the taskId until status is COMPLETED or FAILED
GET to download the result by its resultDocumentId (a ZIP holding the structural JSON for extraction, a processed PDF for everything else)

The full extraction loop against the https://na1.fusion.foxit.com base URL using requests:

import io
import json
import os
import time
import zipfile

import requests

BASE_URL = "https://na1.fusion.foxit.com/pdf-services/api"

HEADERS = {
    "client_id": os.environ["FOXIT_CLIENT_ID"],
    "client_secret": os.environ["FOXIT_CLIENT_SECRET"],
}


def upload_pdf(filepath: str) -> str:
    """Upload a PDF and return its documentId."""
    with open(filepath, "rb") as f:
        resp = requests.post(
            f"{BASE_URL}/documents/upload",
            headers=HEADERS,
            files={"file": f},
        )
    resp.raise_for_status()
    return resp.json()["documentId"]


def start_extraction(document_id: str) -> str:
    """Submit a structural extraction task and return the taskId."""
    resp = requests.post(
        f"{BASE_URL}/documents/pdf-structural-extract",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"documentId": document_id},
    )
    resp.raise_for_status()  # 202 Accepted
    return resp.json()["taskId"]


def poll_until_done(task_id: str, interval: int = 3, timeout: int = 120) -> str:
    """Poll task status until COMPLETED, then return the resultDocumentId."""
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        if data["status"] == "COMPLETED":
            return data["resultDocumentId"]
        if data["status"] == "FAILED":
            raise RuntimeError(f"Extraction failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


def download_structure(result_document_id: str) -> dict:
    """Download the result ZIP and return the parsed structural JSON."""
    resp = requests.get(
        f"{BASE_URL}/documents/{result_document_id}/download",
        headers=HEADERS,
    )
    resp.raise_for_status()
    with zipfile.ZipFile(io.BytesIO(resp.content)) as zf:
        return json.loads(zf.read("StructureInfo.json"))


def extract_pdf(filepath: str) -> dict:
    doc_id = upload_pdf(filepath)
    task_id = start_extraction(doc_id)
    result_doc_id = poll_until_done(task_id)
    return download_structure(result_doc_id)

In this code, you upload the source PDF to receive a documentId, submit the structural extraction task against documents/pdf-structural-extract (the API answers 202 Accepted with a taskId), poll the task endpoint every 3 seconds until the status flips to COMPLETED, then download the result document. The result arrives as a ZIP containing StructureInfo.json (the typed structural output) plus a rendered PNG of each page, so download_structure unpacks the archive in memory and returns the parsed JSON. A FAILED status surfaces as a RuntimeError instead of being silently retried.

For DocGen, the same upload-submit-poll-download shape applies conceptually, though the Base64 endpoint used in Section 7 is synchronous and returns the rendered document in the response body.

Scaling the async model: The PDF Services API doesn't offer webhook callbacks. For high-volume workloads at 10,000+ PDFs per day, a poll loop that blocks your agent threads will become a bottleneck. Use a job queue (SQS, Celery, Redis Streams) where each worker owns the poll loop for its assigned task, then calls the agent's reasoning step only after the extraction result is available. The eSign API is the Foxit product with native webhook support for event-driven callbacks. PDF Services is async polling only.

5. Event-Sourced AI: Building an Auditable Agent Trace

Event sourcing solves the agentic pipeline audit problem by capturing every AI decision as an immutable, append-only log entry keyed to a stable document ID. Every processing step (extraction, validation, generation, signing) becomes a replayable event with typed inputs, the policy version that governed the decision, and the output.

Consider a failure mode that won't surface until you're in an audit. An agent misclassified a contract clause as non-binding, triggered the wrong approval workflow, and now you need to demonstrate exactly what inputs the agent saw and what policy it applied. Without that capture, you're reconstructing from logs and guessing.

Event sourcing captures every state change in a system as an immutable event appended to a log. For an agent pipeline, that means every AI decision step appends a record containing its inputs, the policy or prompt version used, and the output. The log is append-only and keyed by a stable document_id. You can replay any document's processing history, re-run a specific step with a changed policy, and produce a per-document audit trail on demand.

Foxit's task-based API architecture gives you clean event boundaries to log. Each operation returns a typed payload, a taskId, and a status, and those are the natural checkpoints where you append events. The eSign API contributes a native audit trail for the signing leg (signer identity, timestamps, and a queryable activity history endpoint), which is the one part of the pipeline you don't have to instrument yourself.

The rest of the trace is yours to build. A minimal event schema needs five fields:

document_id: the stable key every event is grouped under
event_type: e.g., extraction_completed, validation_passed, document_generated
timestamp: when the event was appended
payload: the API response or LLM output for the step
policy_version: the prompt hash or policy ID that governed the decision

Write this to a Postgres table with id SERIAL, document_id UUID, event_type TEXT, payload JSONB, policy_version TEXT, created_at TIMESTAMPTZ DEFAULT NOW(). That's enough to replay any document through the pipeline and produce a per-event audit log.

A naive LLM pipeline leaves intermediate states opaque and non-replayable. A deterministic PDF API layer combined with an append-only event log links every decision to its source data so you can reconstruct it on demand. That's what makes HIPAA, SOC 2, or GDPR audits tractable.

6. MCP as the Agent-Native Integration Layer

The Model Context Protocol (MCP) exposes PDF API tools directly to LLM agent hosts (Claude Desktop, VS Code, Cursor) without custom wrapper code. Foxit's open-source MCP Server ships 35+ callable tools and authenticates via three environment variables, making it the fastest path from agent host to production PDF operations.

The Model Context Protocol (MCP) is an emerging open standard for exposing tool APIs to LLM-based agents. The agent host calls tools by name, the MCP server handles the underlying API calls, and typed results come back ready for the agent's context window, without custom wrapper code.

Foxit publishes an open-source MCP Server that exposes the PDF Services API as 35+ callable tools. It ships in Python (FastMCP framework, Python 3.11+, uv) and TypeScript (pnpm) variants, and authenticates via three environment variables (FOXIT_CLOUD_API_CLIENT_ID, FOXIT_CLOUD_API_CLIENT_SECRET, and FOXIT_CLOUD_API_HOST). Any MCP-compatible host (Claude Desktop, VS Code with GitHub Copilot, Cursor) can connect to it. If you're already using one of those hosts, you can call PDF tools without writing any wrapper code at all.

There's a genuine tradeoff, though. MCP eliminates custom integration work by adding a protocol hop and some latency overhead. For latency-sensitive, high-volume pipelines at the scale described in Section 4, direct REST calls with your own job queue are the right call. Use MCP when you want to iterate fast or when your agent host is already MCP-native and the overhead doesn't matter.

For full installation steps, the complete tool catalog, and host configuration for Claude Desktop and Cursor, see the dedicated guide, Foxit MCP Server: Give AI Agents Direct Access to 30+ PDF Tools via Model Context Protocol.

7. Build This Today: A Minimal Agentic Invoice Processing Pipeline

A production-ready agentic invoice processing pipeline takes six steps, starting from a free developer account and ending in an optional eSign approval, with every step appended to an audit log. It ingests a PDF invoice, extracts line items as structured JSON, validates totals with an LLM reasoning step, and generates a remittance PDF confirmation using the DocGen API. You can implement this against your own documents this week.

Step 1: Create a free Foxit developer account. The free Developer plan gives you 500 credits per year with no credit card required. Your Client ID and Client Secret are available immediately from the dashboard.
Step 2: POST your invoice PDF to the upload endpoint and capture the documentId. If you don't have an invoice handy, use this sample invoice PDF, the same document the output below was extracted from.

The sample invoice the pipeline ingests. The line item table is what structural extraction returns as a typed table element in Step 3.

Step 3: POST to the PDF Structural Extraction endpoint with the documentId. Poll until COMPLETED, then download the result ZIP and read StructureInfo.json (the extract_pdf function from Section 4 does all of this). The JSON types every element it detects, so the invoice's line item table arrives as a structured table element with typed cells, not as a block of text you then need to parse. Here is the output for the sample invoice, trimmed to one cell per concept:

{
  "analyzeResult": {
    "version": {
      "schema": "1.0.7",
      "software": "FoxitPDFAnalyzer",
      "model": "idp-analysis"
    },
    "pages": [
      {
        "pageNumber": 1,
        "size": { "width": 612, "height": 792, "unit": "point" },
        "state": "success"
      }
    ],
    "elements": [
      {
        "type": "title",
        "content": {
          "text": "INVOICE",
          "style": { "fontFamilyName": "Arial", "fontSize": 24.0 }
        },
        "region": { "page": 1, "boundingBox": [90, 71, 189, 71, 189, 99, 90, 99] },
        "score": 0.88,
        "id": "title1"
      },
      {
        "type": "paragraph",
        "content": { "text": "Invoice Number: INV-2025-0042" },
        "region": { "page": 1, "boundingBox": [90, 187, 254, 187, 254, 200, 90, 200] },
        "score": 0.87,
        "id": "paragraph3"
      },
      {
        "type": "table",
        "content": {
          "body": {
            "rowCount": 7,
            "columnCount": 5,
            "cells": [
              {
                "paragraph": {
                  "type": "paragraph",
                  "content": { "text": "Description" },
                  "id": "paragraph7"
                },
                "rowIndex": 0,
                "columnIndex": 1,
                "rowSpan": 1,
                "columnSpan": 1,
                "region": { "page": 1, "boundingBox": [171, 286, 258, 286, 258, 301, 171, 301] }
              },
              {
                "paragraph": {
                  "type": "paragraph",
                  "content": { "text": "$1,560.00" },
                  "id": "paragraph15"
                },
                "rowIndex": 1,
                "columnIndex": 4,
                "rowSpan": 1,
                "columnSpan": 1,
                "region": { "page": 1, "boundingBox": [430, 300, 517, 300, 517, 328, 430, 328] }
              }
            ]
          }
        },
        "regions": [{ "page": 1, "boundingBox": [82, 285, 519, 285, 519, 422, 82, 422] }],
        "id": "table1"
      }
    ]
  }
}

Pin your parser to analyzeResult.version.schema. The schema is at v1.0.7 and the endpoint is in Trial. Version increments are your signal to check for breaking changes.

Step 4: Pass the table JSON to your LLM agent. The prompt becomes a structured data validation task ("do the line item totals equal the invoice total?") rather than an OCR interpretation task. The LLM operates on typed data, not image pixels.
Step 5: POST the validated JSON plus a DOCX remittance template to the DocGen Generate Document (Base64) endpoint. A ready-made remittance template, verified end-to-end against the live API, matches the sample invoice's data.

The remittance template's merge tokens. Note that {{TableStart:line_items}} and {{TableEnd:line_items}} sit in the same table row, which is required for the loop to render. Run the Analyze Document (Base64) endpoint first to confirm your template's merge fields match your data payload, and keep the template under the endpoint's 4 MB post-base64 cap (compress embedded images in Word's Picture Format pane if you hit it). Receive the output PDF.

The remittance PDF generated from the template and the validated invoice data, rendered by the live DocGen API. Your Step 5 output should match this.

Step 6 (optional): POST to the eSign API to route the remittance for approval. The API creates a signing folder, notifies signers, and maintains the activity history audit trail.

Every step in this pipeline produces a discrete event with a typed payload. Append each one to your audit log. You end up with a complete, replayable record of what was extracted, what the agent decided, and what was generated, for every document that passes through the system.

Frequently Asked Questions

What is an agentic document workflow, and how does it differ from RAG?
An agentic document workflow (ADW) maintains state across multi-step operations and coordinates document processing, retrieval, structured output, and downstream actions in a single orchestrated loop. RAG retrieves text and generates a response in one pass. An ADW agent decides, acts, and then decides again based on what each action produced, enabling conditional routing, validation, and document generation within the same pipeline.

Why does sending raw PDFs to a vision model fail at scale?
Vision models reconstruct document structure from visual patterns rather than reading it deterministically. At 10,000 documents per day, even a 2% hallucination rate produces 200 wrong records, and you won't know which ones. Field name drift between runs breaks downstream validators, and there's no replayable audit trail when a misclassification triggers the wrong workflow.

How does a dedicated PDF API layer fix the production delta?
A dedicated PDF API like Foxit's PDF Services API extracts structure deterministically, returning typed JSON with twelve element types, bounding boxes, and form field values, rather than reconstructing it from pixels. The LLM then operates on that typed output rather than raw bytes, making the extraction step auditable, schema-consistent, and cost-predictable.

What is the async polling pattern in the Foxit PDF Services API?
Every operation follows the same four-step loop. POST to upload the document (returns a documentId), POST to the operation endpoint (returns a taskId), GET to poll status until COMPLETED or FAILED, then GET to download the result by its resultDocumentId. This pattern applies uniformly across extraction, OCR, compression, and flattening.

When should I use the Foxit MCP Server instead of direct REST calls?
Use the MCP Server when you're already in an MCP-native host (Claude Desktop, Cursor, VS Code with Copilot) and want to call PDF tools without writing wrapper code. Use direct REST calls with a job queue (SQS, Celery, Redis Streams) for latency-sensitive, high-volume pipelines where the protocol hop overhead matters.

How do I build an auditable trace for an AI document pipeline?
Implement event sourcing, where every AI decision step appends an immutable record to an append-only log containing document_id, event_type, timestamp, payload, and policy_version. Foxit's task-based API provides clean event boundaries, and each taskId response is a natural checkpoint. The eSign API contributes a native audit trail for the signing leg. The rest you instrument yourself.

Does the Foxit PDF Structural Extraction API schema change between versions?
Yes. The endpoint is currently in Trial status at schema v1.0.7, and the schema can change between version increments. Always pin your parsers to the analyzeResult.version.schema field in the response and check the Trial API reference when you see a version bump, or a breaking change will fail silently.

Final Thoughts

The delta between a working demo and a production agentic document workflow comes down to one architectural decision. Does your PDF layer produce deterministic, typed output? A vision model reconstructing structure from pixels doesn't scale. A dedicated extraction layer does.

Foxit's PDF Services API, DocGen API, and eSign API cover the full document lifecycle (extraction, generation, security operations, and signing) through a consistent REST pattern your agents can call reliably at volume. Add an append-only event log on top of those clean API boundaries and you have the auditability story that compliance teams and incident response actually require.

To test the extraction-to-generation pipeline against your own documents, create a free Foxit developer account (500 credits, no credit card required). The full API reference is at developer-api.foxit.com.

What document type are you trying to automate in your current pipeline, and which step is giving you the most friction? Drop it in the comments.

Building Event-Driven Manufacturing Microservices with Redpanda Connect

Lucien Chemaly — Tue, 21 Jul 2026 07:06:51 +0000

Modern manufacturing environments generate an immense stream of events from programmable logic controllers (PLCs), supervisory control and data acquisition (SCADA) systems, edge sensors, and quality inspection devices. On the shop floor, Message Queuing Telemetry Transport (MQTT) has become the dominant protocol for moving this telemetry between devices and systems. Its publish-subscribe model lets sensors push data to central brokers without needing to know who consumes it, and its lightweight design keeps memory and CPU usage low enough to run on the most constrained embedded hardware.

Collecting events, however, only solves part of the problem. The data still needs to be interpreted as it arrives. I wanted to see if you could catch a quality breach or a bearing about to fail the moment the reading came in, using nothing but off-the-shelf MQTT and Redpanda Connect and no custom middleware. Batch-oriented systems and periodic ERP polling are fine for a lot of manufacturing use cases, but not for that.

In this tutorial, I'll show you how to build a complete, runnable pipeline that:

Simulates sensor telemetry and publishes it via MQTT.
Ingests those events into Redpanda through Redpanda Connect, using its built-in MQTT input.
Routes enriched events to domain-specific Redpanda topics.
Powers three Python microservices (quality SPC, predictive maintenance, and a live dashboard) that consume events and produce alerts.

Prerequisites

Before you begin, make sure you have the following installed and running:

Tool	Details	Check Command
Docker Desktop	Includes Docker Engine and Docker Compose. Make sure it is running before you start	`docker compose version`
Python	3.10 or later	`python3 --version`
pip	Comes with Python, used to install project dependencies	`pip3 --version`

macOS note: Port 5000 is often used by AirPlay Receiver. The dashboard service defaults to port 5050 to avoid this conflict. If you want to use a different port, set HTTP_PORT when starting the dashboard.

Understanding the Role of Microservices in Modern Manufacturing

Traditional monolithic manufacturing execution systems (MES) combine quality control, machine management, job scheduling, and reporting into a single application. When high-frequency telemetry must be processed in milliseconds, these monoliths hit their limits. If you integrate a new sensor on a specific line, you have to fully redeploy the entire application. A bug in the new integration can cascade into unrelated functions.

Microservices address this by decoupling the monolith into independent, specialized services:

A quality service for measurements and SPC tolerances.
A maintenance service for predictive analytics on vibration and temperature data.
A dashboard service for real-time KPIs.

Each is developed, deployed, and scaled independently. The quality team can ship a new surface-inspection algorithm while the maintenance team simultaneously improves a bearing-wear model, with no shared deployment windows and no cross-team regression risk.

These advantages hinge on real-time event processing. When a quality measurement falls outside SPC limits, the system must alert operators and potentially halt the line within seconds, before hundreds of defective parts are produced. Delays of even a few minutes, typical of batch processing or periodic database queries, can result in costly scrap and machine damage.

Redpanda enables real-time event processing, designed for high-throughput, low-latency workloads. MQTT data flows through Redpanda Connect into topics where microservices consume it independently, creating a standardized ingestion path that eliminates point-to-point integrations. New services simply subscribe to the relevant topics.

Why MQTT for Shop-Floor Ingestion

Edge devices and PLCs often have limited computing capacity and memory. MQTT requires minimal resources and runs efficiently on even the most constrained hardware. This is important when thousands of sensors transmit data simultaneously across a factory floor.

MQTT's publish/subscribe model fits event-driven architecture naturally. Sensors publish readings to hierarchical topics such as factory/line1/machine-01/temperature or factory/line1/machine-02/vibration without knowing which services consume the data. Adding a new analytics service doesn't require a sensor reconfiguration because the service simply subscribes to the relevant topic tree.

MQTT's quality-of-service levels guarantee delivery even after temporary outages, which is essential in environments where metal structures and electromagnetic interference frequently disrupt connectivity.

Redpanda Connect provides a built-in MQTT input that pulls telemetry directly into Redpanda topics. Sensor data flows into the central event backbone without additional middleware or custom code, and no intermediate databases or REST APIs slow down the data path. Some deployments use MQTT-native brokers built on Redpanda (e.g., Waterstream) to consolidate broker and streaming layers for multi-factory setups.

Event Modeling and Stream Processing Patterns

Before writing any code, it helps to think about how topics, payloads, and delivery guarantees shape the system.

Designing Topics

Topic structure directly influences performance and maintainability. There are two common strategies:

Physical hierarchy (factory/line1/machine-01/temperature) is used when services focus on specific equipment or locations. A line-specific dashboard subscribes to factory/line1/# to receive only relevant data.
Functional domains (quality.measurements, maintenance.telemetry) are used when services focus on business functions. A quality service analyzing defects across all lines subscribes to a single topic.

I used physical hierarchy for MQTT ingestion here since it matches how the simulator already publishes data, then let Redpanda Connect's routing logic fan events out into functional Redpanda topics for the services that consume them.

The JSON format is human-readable and easy to debug. For production environments generating millions of events daily, Avro with Redpanda's Schema Registry offers schema evolution and compact serialization. Before a producer can publish data with a changed schema, the registry validates backward compatibility, preventing deployments that break downstream consumers.

Partition keys: Using machine_id as the message key ensures all events from a given machine land in the same partition, preserving ordering for time-dependent analyses like trend calculations and SPC windows.

Stream Processing Patterns

Pattern	Use Case	Example
Windowed aggregation	Continuous KPI calculation	A five-minute rolling window computes machine utilization for OEE dashboards
Complex event processing	Anomaly detection from correlated streams	Temperature rising above baseline while vibration increases triggers a predictive maintenance alert
Enrichment	Adding business context to raw telemetry	A compacted topic containing machine specifications provides tolerance limits without database lookups

Beyond processing patterns, teams must also decide how events are delivered and acknowledged across the system.

Delivery Semantics Trade-offs

At-least-once: No events are lost; duplicates are possible. Choose this for monitoring and alerting where a duplicate notification is acceptable, but missing a warning is not.
Exactly-once: Each event is processed exactly once, at the cost of higher latency and resource consumption. Use this for inventory counts, production totals, or financial calculations where duplicates skew results.
Event replay: Redpanda retains events with configurable retention (commonly 7–30 days). Engineers can reprocess historical events for root-cause analysis of intermittent failures.

Architecture Overview

The end-to-end pipeline looks like this:

Project Structure

To understand the project structure, clone the repository and look at the layout:

`bash git clone https://github.com/See4Devs/event-driven-redpanda.git cd event-driven-redpanda`

The repository contains three infrastructure configuration files at the root and four service directories, each with its own Python entry point and dependencies:

| event-driven-redpanda/ |-- docker-compose.yml # Orchestrates Redpanda, Mosquitto, Connect, Console |-- mosquitto.conf # Mosquitto broker config (anonymous access for dev) |-- connect.yaml # Redpanda Connect MQTT-to-Redpanda pipeline | |-- sensor_simulator/ | |-- simulator.py # Publishes fake MQTT telemetry for 3 machines | +-- requirements.txt # paho-mqtt | |-- quality_service/ | |-- service.py # SPC rolling-window breach detection -> alerts | +-- requirements.txt # confluent-kafka | |-- maintenance_service/ | |-- service.py # Vibration threshold anomaly detection -> alerts | +-- requirements.txt # confluent-kafka | +-- dashboard_service/ |-- service.py # Last-known-state HTTP API (Flask) +-- requirements.txt # confluent-kafka, flask |
| :---- |

Here is what each component does:

docker-compose.yml: Defines the infrastructure: a single-node Redpanda broker, the Redpanda Console web UI, an Eclipse Mosquitto MQTT broker, a Redpanda Connect pipeline container, and a one-shot topic-setup container that creates the six Redpanda topics on startup.
mosquitto.conf: Minimal Mosquitto configuration that listens on port 1883 with anonymous access (suitable for local development).
connect.yaml: Declarative Redpanda Connect pipeline. Subscribes to MQTT topic factory/line1/#, enriches payloads with ingestion metadata, and routes events to domain-specific Redpanda topics based on sensor_type using Bloblang expressions.
sensor_simulator/: Python script that publishes fake telemetry for three machines (machine-01, machine-02, machine-03), each with three sensor types (temperature, vibration, pressure), to MQTT topics following the pattern factory/line1/<machine_id>/<sensor_type>. A five percent anomaly injection probability simulates real-world spikes.
quality_service/: Consumes temperature and pressure events from quality.measurements, maintains a per-machine, per-sensor rolling window (default 30 readings), and publishes alerts to quality.alerts when a reading breaches the mean +/- 3 sigma threshold (simplified Western Electric Rule 1).
maintenance_service/: Consumes vibration events from maintenance.telemetry and applies threshold-based anomaly detection: WARNING when the rolling average exceeds 3.0 mm/s, CRITICAL when any single reading exceeds 5.0 mm/s. Publishes alerts to maintenance.alerts.
dashboard_service/: Consumes from all measurement and alert topics to build a last-known-state view of every machine in memory (the "digital twin" pattern), then serves it over a Flask HTTP API on port 5050.

Building the Pipeline: Step by Step

With the project cloned and the file layout in place, you can now walk through each component from infrastructure to application code.

Install Python Dependencies

From the project root, install the dependencies for all four services:

`bash pip3 install -r sensor_simulator/requirements.txt \ -r quality_service/requirements.txt \ -r maintenance_service/requirements.txt \ -r dashboard_service/requirements.txt`

This installs paho-mqtt, confluent-kafka, and flask.

Start the Infrastructure

Start all containers in the background:

`bash docker compose up -d`

This brings up five containers:

Container	Purpose	Exposed Port
`redpanda`	Kafka-compatible streaming broker	`19092` (Kafka API), `18082` (HTTP Proxy), `18081` (Schema Registry)
`redpanda-console`	Web UI for inspecting topics and messages	`8080`
`mosquitto`	MQTT broker for sensor ingestion	`1883`
`redpanda-connect`	MQTT-to-Redpanda pipeline	none
`topic-setup`	One-shot container that creates Redpanda topics, then exits	none

Wait a few seconds for the healthchecks to pass, then verify the topics exist:

`bash docker exec redpanda rpk topic list`

You should see all six topics:

`NAME PARTITIONS REPLICAS dashboard.state 3 1 maintenance.alerts 1 1 maintenance.telemetry 3 1 quality.alerts 1 1 quality.measurements 3 1 sensor.raw 3 1`

Note: The sensor.raw topic will remain empty during this tutorial. The simulator only produces temperature, vibration, and pressure readings, all of which are explicitly routed to quality.measurements or maintenance.telemetry. The sensor.raw topic acts as a catch-all for any unrecognized sensor types, ensuring unknown events are captured rather than dropped.

You can also open Redpanda Console in your browser to visually inspect topics and messages as they flow through the system. See the Redpanda Console documentation for a full feature overview.

Understand the Redpanda Connect Pipeline

Before starting the simulator, take a moment to review the connect.yaml file that is already running inside the redpanda-connect container. Here it is in full:

| yaml input: mqtt: urls: - tcp://mosquitto:1883 topics: - "factory/line1/#" client_id: "redpanda-connect-ingest" qos: 1 pipeline: processors: # Step 1: Parse the raw JSON payload - mapping: | root = this # Step 2: Add ingestion metadata - mapping: | root = this root.ingested_at = now() root.pipeline = "redpanda-connect" # Step 3: Route to topic based on sensor_type - mapping: | let st = this.sensor_type.lowercase() root = this meta target_topic = match $st { "temperature" => "quality.measurements", "pressure" => "quality.measurements", "vibration" => "maintenance.telemetry", _ => "sensor.raw", } output: kafka: addresses: - redpanda:9092 topic: ${! meta("target_topic") } key: ${! json("machine_id") } partitioner: fnv1a_hash max_in_flight: 64 |
| :---- |

Here are the key points:

input.mqtt.topics uses factory/line1/#. The # is MQTT's multi-level wildcard, subscribing to all sensors on line 1 regardless of machine or sensor type.
Pipeline.processors uses Bloblang mapping expressions. The match expression routes temperature/pressure events to quality.measurements, vibration events to maintenance.telemetry, and everything else to sensor.raw.
meta target_topic sets a metadata field that the output.kafka.topic field interpolates with ${! meta("target_topic") }.
output.kafka points at redpanda:9092 because Redpanda is Kafka API-compatible. Standard Kafka clients and Redpanda Connect's Kafka output work directly against Redpanda without modification.

The following diagram shows how MQTT topics flow through the Redpanda Connect pipeline and get routed to their respective Redpanda topics:

Simulate Sensor Telemetry

The sensor simulator publishes fake readings for three machines, each with three sensor types (temperature, vibration, pressure). Run it from the project root:

`bash python3 sensor_simulator/simulator.py`

Your output will look like this:

`Sensor simulator connected to localhost:1883 Publishing every 2.0s for machines: ['machine-01', 'machine-02', 'machine-03'] -> factory/line1/machine-01/temperature: 72.34 celsius -> factory/line1/machine-01/vibration: 1.45 mm_s -> factory/line1/machine-01/pressure: 5.12 bar -> factory/line1/machine-02/temperature: 71.89 celsius`

Each message is a JSON payload with this schema:

`json { "event_id": "a1b2c3d4-...", "machine_id": "machine-01", "sensor_type": "temperature", "value": 72.34, "unit": "celsius", "timestamp": "2025-01-15T10:30:00.000Z", "line": "line1", "factory": "factory-north" }`

Open Redpanda Console and navigate to the Topics tab. You should see messages flowing into quality.measurements and maintenance.telemetry.

Tip: Leave the simulator running in its own terminal window. Open new terminal windows for the following services.

Run the Quality SPC Service

Open a new terminal. This microservice consumes temperature and pressure events from quality.measurements, maintains a rolling window per machine per sensor, and publishes an alert to quality.alerts when a reading breaches the mean +/- 3 sigma threshold (simplified Western Electric Rule 1).

`bash python3 quality_service/service.py`

Output:

When the simulator injects an anomalous spike (five percent probability), the SPC check fires and produces an alert event:

`json { "alert_id": "...", "alert_type": "SPC_BREACH", "machine_id": "machine-03", "sensor_type": "temperature", "value": 92.15, "mean": 72.01, "stdev": 1.48, "z_score": 3.41, "sigma_threshold": 3.0, "window_size": 30, "timestamp": "2025-01-15T10:31:05.000Z" }`

Run the Predictive Maintenance Service

Open another terminal. This service consumes vibration events from maintenance.telemetry and applies threshold-based anomaly detection:

WARNING: rolling average exceeds 3.0 mm/s.
CRITICAL: any single reading exceeds 5.0 mm/s.

I picked 3.0/5.0 mm/s somewhat arbitrarily for this demo, but in a real deployment you'd tune these against your specific machine baselines. In a production system, this calls an ML inference endpoint. The threshold approach keeps the tutorial self-contained.

`bash python3 maintenance_service/service.py`

Output:

Run the Dashboard Service

Open one more terminal. The dashboard service materializes the last-known state of every machine by consuming all measurement and alert topics, then exposes an HTTP API:

`bash python3 dashboard_service/service.py`

Once it's running, query it:

| bash # All machines and their latest sensor readings curl -s http://localhost:5050/machines | python3 -m json.tool # Detail for a specific machine curl -s http://localhost:5050/machines/machine-01 | python3 -m json.tool # Recent alerts across all machines curl -s http://localhost:5050/alerts | python3 -m json.tool |
| :---- |

Here's an example response from /machines:

`json { "machine-01": { "temperature": { "value": 72.34, "unit": "celsius", "timestamp": "...", "topic": "quality.measurements" }, "vibration": { "value": 1.23, "unit": "mm_s", "timestamp": "...", "topic": "maintenance.telemetry" }, "pressure": { "value": 5.12, "unit": "bar", "timestamp": "...", "topic": "quality.measurements" } }, "machine-02": { "..." }, "machine-03": { "..." } }`

This is the "digital twin" pattern: a continuously updated materialized view in memory, rebuilt entirely from the event stream without relying on an external database.

Where Change Data Capture Still Makes Sense

Event-driven microservices excel at processing real-time MQTT streams, but many factories also run established enterprise systems that were not designed for event-driven architecture. ERP, MES, and warehouse management systems (WMS) store their data in relational databases.

Change data capture (CDC) helps bridge this gap. When a work order is released or inventory is adjusted, these changes occur as database transactions. Redpanda Connect supports CDC connectors for PostgreSQL, MySQL, and MongoDB that capture these deltas and publish them as events automatically.

A minimal CDC configuration for PostgreSQL with Redpanda Connect looks like:

`yaml input: postgres_cdc: dsn: "postgres://user:pass@erp-db:5432/manufacturing?sslmode=disable" schema: "public" tables: - work_orders - inventory snapshot: true output: kafka: addresses: - redpanda:9092 topic: 'erp.${! meta("table") }' key: ${! json("id") }`

Important: CDC should be used sparingly and exclusively for system-of-record deltas from transactional systems. Sensor streams, machine telemetry, and production events must remain event-native. CDC is not suitable for high-frequency time-series data because it is optimized for relational change capture, not continuous streams.

Cleanup

When you are done experimenting, stop the Python services with Ctrl+C in each terminal, then tear down the Docker infrastructure:

`bash docker compose down -v`

The -v flag removes the named volume (redpanda-data), freeing disk space. Omit it if you want to preserve topic data between runs.

All the code used in this tutorial is available on GitHub.

Conclusion

In this tutorial, you built a sensor-first, event-driven manufacturing pipeline end to end. MQTT telemetry flows from simulated machines through an Eclipse Mosquitto broker, where Redpanda Connect ingests, normalizes, and routes events into domain-specific Redpanda topics. Three independent Python microservices (quality SPC, predictive maintenance, and a live dashboard) consume these events and produce alerts or materialized views. The entire stack runs locally with Docker Compose.

I liked this setup because it took very little custom code to get there. The routing logic lives in a single Bloblang mapping in connect.yaml, and each microservice only has to worry about its own topic. Where legacy systems like ERP or MES aren't yet event-native, CDC connectors bridge the gap without forcing sensor data through the same relational path.

Build an Automated PDF Generation Pipeline: From Word Template to Signed Document

Lucien Chemaly — Fri, 10 Jul 2026 06:51:33 +0000

The first time you spin up Puppeteer and call page.pdf(), it feels solved. You get a PDF. It renders. Ship it.

That decision comes back to haunt you when you're generating 500 contracts a day, your designer updated the brand template and nobody propagated the change, compliance wants audit-ready flat files, and legal is asking why the e-signatures aren't attached to the archived copies. What started as a utility function is now load-bearing infrastructure, and the duct tape is showing.

Headless-browser rendering gives you a PDF with no template management, no compliance-grade output, and no downstream handoff. Those things require a different design. This guide walks through that design, a three-stage pipeline covering data binding from a Word template, synchronous document generation, post-processing for compliance and delivery, and an eSign handoff, all through REST APIs.

Why "Just Use Puppeteer" Breaks at Scale

Puppeteer works. At low volume, with a single developer maintaining the rendering code, it's perfectly reasonable. The cracks appear when you add real-world pressure.

The first problem is template drift. When your HTML template lives in a repository owned by engineers, every brand update requires a PR, a review, and a deploy. Product managers can't touch it. Designers can't touch it. The template ends up frozen in a past state of the brand because the cost of updating it is higher than the cost of tolerating the inconsistency.

The second problem is rendering inconsistency. Headless Chrome's output changes between Chrome versions. Fonts render differently depending on what's installed on the host OS. Your CI/CD environment produces slightly different PDFs than your local machine. For documents that are legally significant (contracts, invoices, disclosures), "slightly different" is not acceptable.

The third problem is the compliance delta. page.pdf() produces a valid PDF, but it gives you no flattened file for archival compliance, no linearized file for web serving, and no audit trail. Those capabilities don't exist in Puppeteer. You bolt them on separately, and each bolt is a seam where something can break.

A production document pipeline needs reproducible data binding (the same input produces consistent, deterministic output), compliance-ready output formats (flat, archivable, signable files), and downstream handoff (delivering documents into signing workflows, storage systems, or portals). A headless browser covers none of these, so each one becomes a separate integration you own and maintain.

Pipeline Architecture: What You're Actually Building

The pipeline has three stages. Understanding them before writing any code prevents the most common integration mistakes.

Stage 1 is the data source. Your CRM, ERP, database, or internal service provides a JSON payload containing the values that populate the document. Business logic lives here, including field mapping, conditional logic for what sections to include, and data validation before any API call goes out.

Stage 2 is document generation. A Word template defines the document structure, and the generation API merges the JSON payload into it, producing a PDF or DOCX. You POST, you get back a document.

Stage 3 is post-processing and delivery. The generated PDF moves into a processing pipeline for compliance operations (flatten for archiving, linearize for web delivery, compress for storage), then hands off to an eSign workflow or an archive system.

The synchronous versus asynchronous split is the architectural decision with the biggest impact on integration complexity. The Document Generation API runs synchronously, so you POST a request and receive the rendered document in the response body, with no job IDs and no polling. That fits naturally into request-response backend workflows, such as generating a contract when a user clicks "Send Agreement" in your CRM. PDF Services operations (flatten, linearize, compress) run asynchronously, so you submit a job, get a task ID, and poll for completion. The DocGen response is immediate, but the post-processing chain adds latency you need to account for in your design.

Authentication is consistent across all three stages. Every request includes client_id and client_secret as request headers, retrieved from the developer dashboard after creating your account. The base host for both DocGen and PDF Services in these examples is https://na1.fusion.foxit.com; your dashboard shows the host assigned to your account. Store the credentials as environment variables, not in source code. The full request and response schema for every endpoint used below lives in Foxit's API reference, so keep it open as you build.

Prerequisites

This is a hands-on tutorial with runnable code in Python, Node.js, and cURL. Before the first API call, set up the following:

A Foxit developer account for client_id / client_secret credentials. The free Developer plan includes 500 shared credits per year across PDF Services and Document Generation.
Python 3.8+ with pip and a virtual environment, or Node.js 18+ with npm. The examples use Python's requests and Node's axios plus form-data.
cURL for quick endpoint checks from the terminal.
A code editor such as VS Code with the Python extension (PyCharm, WebStorm, or Sublime Text work too).

Scaffold the workspace in one shot:

mkdir pdf-pipeline && cd pdf-pipeline
python3 -m venv .venv && source .venv/bin/activate
pip install requests
# Node alternative:
# npm init -y && npm install axios form-data
export FOXIT_CLIENT_ID="your_client_id"
export FOXIT_CLIENT_SECRET="your_client_secret"

In this block you create an isolated project directory, activate a Python virtual environment so dependencies don't leak into your system install, add the HTTP library the examples use, and export your Foxit credentials as environment variables that every script below reads from the environment rather than from hardcoded strings.

Setup and Your First API Call

Start by creating an account at account.foxit.com/site/sign-up. The free Developer plan takes about two minutes to configure and gives you immediate API access to validate a complete pipeline integration before committing to a paid tier.

Next you need a Word template. Rather than building one from scratch, download a ready-made sample, invoice_simple.docx, which already contains token placeholders. Tokens use double curly braces, and this template defines {{ companyName }}, {{ invoiceNumber }}, {{ invoiceDate \@ MM/dd/yyyy }}, and {{ totalDue \# "$#,##0.00" }}. The \@ and \# suffixes are formatting switches that tell the engine how to render dates and currency.

The first API call takes that .docx, encodes it as base64, attaches a JSON data payload, and POSTs it to the Document Generation endpoint. Encode the file first:

import base64

with open("invoice_simple.docx", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

In this code, you open the template in binary mode, base64-encode its raw bytes, and decode the result to a UTF-8 string so it can travel inside a JSON request body. In Node.js the equivalent is fs.readFileSync("invoice_simple.docx").toString("base64"). The API doesn't care which language produced the string, only that it's valid base64 that decodes to a well-formed .docx. Send a corrupted or truncated file and you'll get an error back with no usable output.

Now POST the encoded template with a matching data payload:

curl -X POST "https://na1.fusion.foxit.com/document-generation/api/GenerateDocumentBase64" \
 -H "client_id: $FOXIT_CLIENT_ID" \
 -H "client_secret: $FOXIT_CLIENT_SECRET" \
 -H "Content-Type: application/json" \
 -d '{
   "base64FileString": "<BASE64_ENCODED_DOCX>",
   "outputFormat": "pdf",
   "documentValues": {
     "companyName": "Acme Corp",
     "invoiceNumber": "INV-1042",
     "invoiceDate": "2026-01-15",
     "totalDue": "5700"
   }
 }'

In this request, base64FileString carries the encoded template, outputFormat selects pdf (use docx to get a populated Word file back instead), and documentValues is the object whose keys map to the {{token}} names in the template. Credentials go in the headers, never in the body. Every key in documentValues corresponds to a token; tokens you omit render as an empty string, and keys that don't match any token are ignored. Values can be strings or numbers, so "totalDue": "5700" and "totalDue": 5700 both work, though sending strings keeps formatting predictable.

The response returns the generated document as a base64 string in the base64FileString field:

{
  "message": "PDF Document Generated Successfully",
  "fileExtension": "pdf",
  "base64FileString": "<BASE64_ENCODED_PDF>"
}

Decode the base64FileString value to get the raw PDF bytes, then write them to disk, push to S3, or pass them straight into the next pipeline stage. There's no separate download step and no job ID to track, since the document is in the response body.

One constraint to plan around is the 4 MB cap on the .docx payload after base64 encoding. The usual culprits when you hit that ceiling are high-resolution embedded images, embedded fonts, and OLE objects. Compress images through Word's Picture Format tools to around 150 DPI, reference fonts instead of embedding them, and drop OLE objects entirely. For templates that genuinely exceed the limit after optimization, split them into component templates and merge the outputs downstream.

Designing Templates for Dynamic, High-Volume Documents

A few token patterns cover the vast majority of document generation use cases. Master these and you can handle contracts, invoices, compliance reports, onboarding kits, and offer letters from a single template architecture. To see all of them together, download invoice_table.docx, which exercises every pattern below.

Simple field substitution is the baseline. Place {{fieldName}} anywhere in the Word document (inside a paragraph, in a table cell, in a header) and the API replaces it with the corresponding value from the JSON payload.

Formatting switches control how the engine renders dates and numbers. Append \@ MM/dd/yyyy to a date token or \# "$#,##0.00" to a numeric token, and the engine formats the output for you. In invoice_table.docx, {{ invoiceDate \@ MM/dd/yyyy }} turns 2026-01-15 into 01/15/2026, and {{ totalDue \# "$#,##0.00" }} turns 5700 into $5,700.00.

Table row iteration handles line items, variable-length lists, and repeating structures. Wrap a table row with {{TableStart:arrayName}} and {{TableEnd:arrayName}} placed in the same row, reference each object's fields with bare {{fieldName}} tokens inside that row, and pass an array of objects in the payload. The engine expands the table to one row per array element. invoice_table.docx uses this structure:

| #              | {{description}}                  | {{qty}} | {{unitPrice \# "$#,##0.00"}} | {{lineTotal \# "$#,##0.00"}} |
| {{ROW_NUMBER}} | {{TableStart:lineItems}} ...     |         |                              | ... {{TableEnd:lineItems}}   |

The {{ROW_NUMBER}} token auto-numbers each generated row, and {{=SUM(ABOVE) \# "$#,##0.00"}} in a cell below the table sums the column above it. Driving that template with this payload:

{
  "outputFormat": "pdf",
  "documentValues": {
    "companyName": "Acme Corp",
    "invoiceNumber": "INV-1042",
    "invoiceDate": "2026-01-15",
    "lineItems": [
      {
        "description": "Consulting",
        "qty": "3",
        "unitPrice": "1500",
        "lineTotal": "4500"
      },
      {
        "description": "Licensing",
        "qty": "1",
        "unitPrice": "1200",
        "lineTotal": "1200"
      }
    ],
    "totalDue": "5700"
  }
}

produces a two-row table (1 Consulting 3 $1,500.00 $4,500.00 and 2 Licensing 1 $1,200.00 $1,200.00), a computed subtotal of $5,700.00, and a Total Due of $5,700.00, all formatted by the template. A 47-item order produces 47 rows with no template changes. The lineItems array is the only part of the payload that varies between a one-item order and a fifty-item order.

The actual PDF returned by the DocGen API for the payload above. Row numbers, currency and date formatting, the expanded line-item loop, and the SUM(ABOVE) subtotal all resolved server-side from the Word template.

For variable content that should appear only sometimes, drive it from the data layer. An omitted or empty token renders as blank, and an empty array produces zero table rows, so you control which content surfaces by controlling what you put in documentValues rather than by embedding branching logic in the template.

The operational implication matters for engineering teams at scale. Template ownership can live entirely outside the application codebase, whether that's a Word file in version control, a shared drive with access controls, or a document library. Non-engineers can modify the template without triggering a deploy cycle. The application code owns JSON payload construction and the template file owns document structure, which is what keeps the system maintainable as document types multiply.

For versioning, the practical approach is environment-specific template files, such as contract-v2.docx in production and contract-v3.docx in staging for validation before promotion. When you encode the template as base64 at request time, the version is implicit in which file you read. In-flight pipeline runs hold a reference to whichever file was live when they started, so there's no race condition with a template swap mid-generation.

Post-Generation Processing: Flatten, Linearize, Compress, and Sign

Most pipelines accumulate technical debt here. Teams generate the PDF and consider the job done, then bolt on post-processing as an afterthought when compliance raises questions or storage costs spike. Build the processing stage into the architecture from the start.

The bridge between DocGen and PDF Services works like this. DocGen returns a base64 PDF string. Decode it back to bytes and upload it once to PDF Services via POST /pdf-services/api/documents/upload, a multipart form upload that returns a documentId. From that point, PDF Services jobs chain by passing one job's resultDocumentId as the next job's input documentId, with no further download and re-upload cycles between operations.

// Node.js: bridge DocGen output into PDF Services and chain jobs
const axios = require("axios");
const FormData = require("form-data");

const BASE = "https://na1.fusion.foxit.com/pdf-services/api";
const auth = {
  client_id: process.env.FOXIT_CLIENT_ID,
  client_secret: process.env.FOXIT_CLIENT_SECRET,
};

// Step 1: decode the base64 PDF from DocGen and upload it once as multipart
async function uploadDocument(base64Pdf) {
  const form = new FormData();
  form.append("file", Buffer.from(base64Pdf, "base64"), {
    filename: "document.pdf",
    contentType: "application/pdf",
  });
  const res = await axios.post(`${BASE}/documents/upload`, form, {
    headers: { ...auth, ...form.getHeaders() },
  });
  return res.data.documentId;
}

// Step 2: kick off a flatten job that returns a taskId for async polling
async function flattenDocument(documentId) {
  const res = await axios.post(
    `${BASE}/documents/modify/pdf-flatten`,
    { documentId },
    { headers: { ...auth, "Content-Type": "application/json" } },
  );
  return res.data.taskId;
}

// Step 3: start a compress job on a result document, no re-upload needed
async function compressDocument(documentId, compressionLevel) {
  const res = await axios.post(
    `${BASE}/documents/modify/pdf-compress`,
    { documentId, compressionLevel },
    { headers: { ...auth, "Content-Type": "application/json" } },
  );
  return res.data.taskId;
}

// Step 4: poll GET /tasks/:taskId until COMPLETED or FAILED
async function waitForCompletion(taskId) {
  while (true) {
    const res = await axios.get(`${BASE}/tasks/${taskId}`, { headers: auth });
    const { status, resultDocumentId } = res.data;
    if (status === "COMPLETED") return resultDocumentId; // pass to next job
    if (status === "FAILED") throw new Error(`Task ${taskId} failed`);
    await new Promise((r) => setTimeout(r, 2000)); // 2s polling interval
  }
}

// Full chain: upload -> flatten -> compress -> return final ID for eSign
async function processDocument(base64Pdf) {
  const docId = await uploadDocument(base64Pdf);
  const flatTaskId = await flattenDocument(docId);
  const flatDocId = await waitForCompletion(flatTaskId);
  const compressTaskId = await compressDocument(flatDocId, "MEDIUM");
  return await waitForCompletion(compressTaskId);
}

In this code, you take the base64 PDF that DocGen returned, decode it into a binary Buffer, and push it to the upload endpoint as a multipart file (uploading the base64 string as JSON is rejected with a 415, since the endpoint expects form data). The upload returns a documentId. You start a flatten job against that ID, poll the task endpoint every two seconds until it reports COMPLETED, then feed the returned resultDocumentId straight into a compress job without re-uploading anything. The final resultDocumentId is what you hand to the eSign stage.

Three operations cover the core post-processing needs:

Flatten (POST /documents/modify/pdf-flatten) merges form fields and annotations into static page content, baking every value in as rendered text or image with no interactive elements remaining. This is required for compliance archiving under standards like PDF/A, and for producing tamper-evident audit files. If your documents land in a regulatory audit, a flattened PDF is the format auditors expect.
Linearize (POST /documents/optimize/pdf-linearize), also called "Fast Web View," restructures the internal byte order of the PDF so the first page renders before the rest of the file downloads. For portals serving multi-page contracts or reports, this cuts perceived load time. A 40-page contract in Fast Web View starts rendering in the browser immediately rather than waiting for the full download. It's the operation most teams skip and then regret when users complain about document load times.
Compress (POST /documents/modify/pdf-compress) reduces file size without degrading visible quality and takes a compressionLevel of LOW, MEDIUM, or HIGH. For high-volume pipelines sending documents via email or storing thousands of files, the delta between an uncompressed 800 KB file and a MEDIUM-compressed 200 KB file compounds quickly at scale.

For the eSign handoff, download the final document from PDF Services with GET /pdf-services/api/documents/{documentId}/download, then submit it to the Foxit eSign API to create an envelope, assign signers, and trigger the signing workflow. Because eSign runs on a separate host (https://na1.foxitesign.foxit.com), you move the bytes across rather than passing a PDF Services document ID directly. After authenticating for an eSign access token, create a folder with the PDF attached as a base64 string and "inputType": "base64", assign signers, and send. Configure a webhook endpoint in your application and the eSign API posts events (viewed, signed, completed, declined) as they happen.

Error Handling and Monitoring in Production

Document pipelines fail in three distinct ways, and handling each correctly prevents silent data loss.

Data validation failures happen before any API call goes out. Malformed JSON, missing required token values, or structural mistakes produce generation errors that are deterministic and reproducible. Validate your data payload against a schema before sending it to the DocGen endpoint. If totalDue is null when the document needs a value, catch that in your application layer rather than discovering a blank field in the rendered output.

Template rendering errors occur when the Word template contains broken token syntax or structural inconsistencies the generation engine can't resolve, such as loop tokens split across different table rows. These typically surface during integration testing, not in production, which means they're preventable. Use the Foxit Analyze Document API (POST /document-generation/api/AnalyzeDocumentBase64) to scan a template programmatically before promoting it. It returns singleTagsString, a comma-separated list of the scalar tokens the engine detected, and doubleTagsString, the table or loop region names. Diff those against your expected token set to catch mismatches before they reach users.

Downstream chain failures are the most dangerous because they happen after a successful generation step. The PDF was created correctly, but the flatten job failed, or the eSign envelope creation returned a 400. Without explicit handling, the document disappears into limbo.

// Polling with timeout and dead-letter branching, use for every chained job
async function pollWithTimeout(taskId, timeoutMs = 30000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await axios.get(`${BASE}/tasks/${taskId}`, { headers: auth });
    const { status, resultDocumentId, error } = res.data;
    if (status === "COMPLETED") return resultDocumentId;
    if (status === "FAILED") {
      // Log taskId, full error payload, and upstream context before re-queuing
      console.error(`Task ${taskId} FAILED:`, JSON.stringify(error));
      throw new Error(`Processing failed: ${error?.message}`);
    }
    await new Promise((r) => setTimeout(r, 2000));
  }
  // Timeout: treat as failure, don't silently drop the document
  throw new Error(`Task ${taskId} timed out after ${timeoutMs}ms`);
}

In this code, you cap the polling loop with a deadline so a stuck job can't block the pipeline forever. On COMPLETED you return the result document ID for the next stage, on FAILED you log the task ID and the full error payload before throwing, and on timeout you throw rather than returning silently, which guarantees a failed document raises a visible error instead of vanishing.

Log the task ID returned from every API call. When something fails, that ID is your audit trail into the Foxit API logs. Set timeout thresholds per stage, since a flatten job running for 60 seconds on a 10 KB file is stuck, not slow. Implement dead-letter logic for documents that fail post-generation processing, whether that means re-queuing with exponential backoff or alerting an operator. A failed post-processing step that silently drops a document is worse than a visible error.

Your Next Step: Run This End-to-End Today

The fastest way to validate the architecture is to get one call working before building the full pipeline.

Sign up at account.foxit.com/site/sign-up, where the free Developer plan takes about two minutes to configure and gives you immediate API access. Download invoice_simple.docx, base64-encode it, and call the DocGen endpoint with a JSON payload that fills companyName, invoiceNumber, invoiceDate, and totalDue. Decode the base64 response and open the PDF. That's the core loop validated in under 15 minutes, and Foxit's Postman collection in the developer portal makes it even faster to prototype before you write integration code.

From there, layer in the pipeline stages one at a time. Upload that PDF to PDF Services, run a flatten job, poll for completion, and verify the output. Then add the compress step. Then wire in the eSign handoff. Building incrementally means you know exactly where problems originate.

Foxit's developer portal has code samples in Node.js, Python, and cURL ready to copy. The free Developer plan gives you 500 shared credits per year to cover your entire exploration and POC phase.

What's the most brittle part of your current document generation setup, whether that's template management, rendering consistency, compliance archiving, or the eSign handoff? Drop your approach in the comments. The real-world variations in how teams solve this are usually where the genuinely interesting engineering decisions live.

Document Generation for Developers: Security, Compliance, and Build-vs-Buy Decisions for the Template-Plus-Data Pipeline

Lucien Chemaly — Fri, 29 May 2026 10:15:19 +0000

When a deal closes in your CRM and a contract still needs a human to open Word, paste in the account name, and adjust the pricing table, you have a document generation problem. The mechanism for solving it is well understood: a rendering engine resolves a template against a structured data payload and emits a finished file. What most guides skip is the implementation layer that determines whether the system survives an audit, scales past the first team that uses it, and stops requiring developer time after launch. That means credential handling, data residency, compliance certifications, and the build-vs-buy threshold for the rendering layer itself.

This article covers the architecture and the hard decisions. The "what is document generation" recap is intentionally short so the security, compliance, and decision-framework content has room to breathe.

Document Generation: The Core Mental Model

A document generation system does one thing: it takes a template (structural layout, fixed text, placeholders) and a data payload (field values for those placeholders), merges them in a rendering engine, and produces an output file.

Three adjacent concepts get conflated with document generation frequently enough to distinguish here. Document editing puts a human in the loop to modify content interactively. Document management handles storage, versioning, and retrieval of existing files. PDF form-fill annotates existing form fields with values without regenerating the document structure. Generation produces a net-new file on each call.

Output format is a real decision. PDF is the correct choice when the output is delivery-final, immutable, and audit-ready, such as a signed contract, a compliance report, or a customer invoice. DOCX is the right choice when the generated file feeds a downstream collaborative editing workflow, such as a first draft that legal needs to mark up before execution.

The rest of this article covers programmatic, API-driven generation at scale. If you're evaluating whether to build or buy the rendering layer, and whether your architecture can pass a SOC 2 or HIPAA review, this is the relevant frame.

The Three Components Every Document Generation System Requires

Every doc gen system at production scale requires three things: a template, a data payload, and a rendering engine. Getting the contract between them right at design time saves hours of debugging later.

Templates are .docx files authored in Microsoft Word, with {{field_name}} double-brace tags placed anywhere Word accepts text: headings, table cells, footers, text boxes, even page headers. The template is a contract with the data payload. Every tag is a required key. If {{invoiceNumber}} appears in the template and the payload omits invoiceNumber, the rendered output contains a blank where the invoice number should be. The API does not raise an error for missing keys, and absent keys render as empty strings. That behavior matters when you're designing your payload validation layer.

The data payload is a JSON object whose keys map to tag names in the template. A minimal invoice payload looks like this:

{
  "companyName": "Acme Corp",
  "invoiceNumber": "INV-001",
  "invoiceDate": "2026-01-15",
  "totalDue": 4200
}

String values drop in as-is. Numeric values render according to any format directives embedded in the tag itself, such as {{ totalDue \# "\$#,##0.00" }} for currency formatting. Null values and missing keys both render as empty strings.

The rendering engine is the service that resolves tags against the payload and emits the file. At render time, the engine performs tag substitution for scalar values, dynamic row expansion for array-backed table data, and output format encoding (Base64 for transport in JSON responses, or a binary write to disk). Its behavior on edge cases, including how it handles null values, missing keys, and malformed tags, is what you need to understand before connecting it to a production data source.

How the Foxit Document Generation API Request Model Works

The Foxit Document Generation API uses a three-field POST body. base64FileString carries the Base64-encoded .docx template. documentValues carries the JSON merge data. outputFormat is the lowercase string "pdf" or "docx". The endpoint is case-sensitive on outputFormat and returns HTTP 500 for any value outside those two strings.

The canonical endpoint for developer-tier accounts is https://na1.fusion.foxit.com/document-generation/api/GenerateDocumentBase64. Authentication is header-based: include client_id and client_secret alongside Content-Type: application/json. There is no OAuth flow, no token exchange, and no session management.

Base64 encoding is used because the API transports binary template content inside a JSON request body, where raw binary bytes would break JSON parsing. The encoding overhead adds roughly 33% to the payload size, which is why the endpoint enforces a 4 MB limit on the encoded template (approximately a 3 MB raw .docx file). Payloads that exceed this cap return HTTP 413 or a generic 500 with an opaque message. To slim an oversized template, compress images via Word's Picture Format menu, remove embedded fonts and OLE objects, and split templates that contain too many high-resolution graphics.

The synchronous execution model is a meaningful architectural choice. The rendered file arrives in the same HTTP response, eliminating the polling loop that complicates async pipelines.

sequenceDiagram
    participant App as Application
    participant API as GenerateDocumentBase64 Endpoint
    App->>API: POST with base64FileString, documentValues, outputFormat
    API->>API: Resolve tags against documentValues
    API->>API: Encode rendered file as base64
    API-->>App: 200 OK with base64FileString in response body
    App->>App: Decode base64, write output.pdf

Async polling patterns make sense when document volume is high enough to push render time past practical request timeouts, for example in overnight batch jobs processing tens of thousands of records. For on-demand generation triggered by a single user action or a webhook, synchronous delivery is simpler to implement and simpler to debug.

Dynamic tables require a specific token placement. To render an array of line items into a Word table, place {{TableStart:lineItems}} and {{TableEnd:lineItems}} in the same table row, with the field tags for each column also in that row. The engine repeats the row for each element in the lineItems array. You can also include {{ROW_NUMBER}} in the row to get an auto-incrementing index. Placing the start and end tokens in different table rows produces a broken render with no error message, which is one of the more opaque failure modes in the system.

The Analyze Document API is a utility endpoint worth knowing about when evaluating any doc gen service. Post a .docx file to it and it returns all embedded tag names in the template. This lets you programmatically validate that a template matches a payload schema before calling the generation endpoint, and auto-build the documentValues structure from a template file when the template changes.

Integration Patterns for Production Document Generation Workflows

The most common trigger pattern in CRM-connected workflows goes like this: a deal moves to Closed Won in Salesforce, a webhook fires to your application, your application queries Salesforce for the deal fields, your application posts to the doc gen API, the rendered PDF contract comes back synchronously, and your application attaches the file to the CRM record or sends it to the signatory. Because the API is a standard REST endpoint, integrating with HubSpot, Salesforce, or SAP requires no proprietary connector, just an authenticated HTTP POST.

For event-driven batch jobs, iterate over a dataset of N records and fire one POST per record. The key considerations are rate limiting and retry logic. If the downstream data source or the doc gen service has a request ceiling, a simple backoff-and-retry pattern handles transient failures without losing records. Log the request metadata (template version, record ID, timestamp) and the response status. Omit payload contents from logs when the payload contains regulated data.

When a required tag has no corresponding key in documentValues, the API renders a blank and moves on. The defensive pattern is to run payload validation against the tag list returned by the Analyze Document API before each call. For workflows where partial data is acceptable, build a fallback that fills missing keys with empty strings explicitly rather than relying on the API's implicit behavior. That delta matters during an audit when you need to explain why a generated compliance report had blank fields.

Security and Compliance for Document Generation Pipelines

client_id and client_secret travel as HTTP request headers, which means they're visible in any intermediary that can inspect headers in transit. Store them in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, or a CI/CD-native secrets store). They should never appear in source code, version control, or log output. Your application code should read from os.environ["CLIENT_ID"] rather than hardcoding the string value.

TLS at the API boundary encrypts the payload in transit, but your application is responsible for what happens to the document after the response arrives. If you're writing the rendered PDF to disk, a message queue, or cloud storage, that persistence layer needs its own encryption at rest. An unencrypted file sitting in an Amazon S3 bucket with overly permissive ACLs falls outside what the API provider's TLS covers.

SOC 2 Type II, GDPR, and HIPAA each have specific implications for doc gen pipelines that go beyond a logo on a vendor's compliance page. SOC 2 Type II requires an auditable trail of access controls and data handling over time, so you'll need to log which user or service account triggered each generation event and what template was used. GDPR treats personally identifiable information in generated documents as regulated data, which means data subject rights (access, deletion, correction) extend to any stored generated files in addition to the source database records. HIPAA adds the requirement that protected health information (PHI) in generated documents be handled under a signed Business Associate Agreement (BAA) with every service that processes or stores that data. Foxit's API platform carries SOC 2, GDPR, and HIPAA compliance posture, so the BAA question is addressable at the vendor level, but the application layer between your data source and the API remains your responsibility.

Template files are themselves a security surface. Avoid embedding default field values that contain PII directly in the template file, because .docx files land in version control, get emailed for review, and end up in shared drives. The template should contain the structural layout and formatting only, with PII traveling exclusively in the documentValues payload at generation time, ephemeral in the request and response.

Most managed doc gen providers don't persist the rendered document on their infrastructure after returning it in the response body, but verify this contractually before connecting regulated data. Log the request hash and response status. Document contents belong only in the storage system you control and have audited.

Build vs. Buy: Picking the Right Document Generation Rendering Approach

The DIY path uses open-source libraries. python-docxtpl renders Word templates in Python using Jinja2 syntax, covering scalar substitution and table loops at no licensing cost. jsPDF lets you construct PDFs in Node.js from scratch via code. Both give you complete control over rendering logic, and neither comes with a licensing fee. The cost is that your team owns maintenance, scaling infrastructure, and all compliance certification work. When your open-source rendering library has a memory leak under high concurrency, or when your auditor asks for your SOC 2 report, you answer those questions directly.

A managed REST API trades infrastructure ownership for faster integration, predictable credit-based pricing, and inherited compliance certifications. The break-even point shifts depending on three variables: team size, document volume, and whether the use case requires certified compliance. At low volume (fewer than 500 documents per month) with no regulated data, the open-source path is often the right call. At higher volume, or when a compliance review is on the roadmap, the time cost of building and certifying your own rendering infrastructure typically exceeds the subscription cost of a managed service by a meaningful margin.

To work out which path makes sense for your situation, answer these four questions:

How many documents does the system need to generate per month, and is that number growing?
Does the content include regulated data (PII, PHI, financial records) that triggers a compliance framework?
Does your team have in-house PDF rendering expertise, or would you be learning while building?
How often does the template change, and who owns that change process?

If document generation is a core differentiating feature of your product, investing in a custom rendering layer may pay off over time. If it's a workflow utility (such as generating invoices, contracts, or onboarding letters from existing system data), a managed API ships faster and costs less in total at moderate volume. The key signal is whether the rendering logic itself creates competitive value or whether it's plumbing.

Prerequisites

You'll need Python 3.8+ and pip for the quickstart, with venv recommended for isolation. Install the requests library for HTTP calls. VS Code with the Python extension works well as an editor, though PyCharm or Sublime Text work equally well. You'll also need a free Foxit developer account.

Set up the workspace and load your credentials into the environment:

mkdir foxit-docgen-quickstart && cd foxit-docgen-quickstart
python3 -m venv .venv && source .venv/bin/activate
pip install requests
export BASE_URL="https://na1.fusion.foxit.com"
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

Quickstart: Generate Your First Document via the API

Step 1. Activate a free developer plan at account.foxit.com/site/sign-up. You get 500 annual credits and no credit card is required. Retrieve CLIENT_ID and CLIENT_SECRET from the API Keys section of the developer dashboard, then load them into your environment using the block above.

Step 2. Download the sample invoice template from the foxit-demo-templates repository. The file contains {{ companyName }}, {{ invoiceNumber }}, {{ invoiceDate \@ MM/dd/yyyy }}, and {{ totalDue \# "\$#,##0.00" }} tokens, already validated against the live API.

Step 3. The script reads credentials from os.environ, Base64-encodes invoice_simple.docx, POSTs the three-field JSON body to https://na1.fusion.foxit.com/document-generation/api/GenerateDocumentBase64, decodes the base64FileString field in the response, and writes the bytes to output.pdf:

import base64
import json
import os
import requests

base_url = os.environ["BASE_URL"]
client_id = os.environ["CLIENT_ID"]
client_secret = os.environ["CLIENT_SECRET"]

with open("invoice_simple.docx", "rb") as f:
    template_b64 = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "base64FileString": template_b64,
    "documentValues": {
        "companyName": "Acme Corp",
        "invoiceNumber": "INV-001",
        "invoiceDate": "2026-01-15",
        "totalDue": 4200
    },
    "outputFormat": "pdf"
}

headers = {
    "client_id": client_id,
    "client_secret": client_secret,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{base_url}/document-generation/api/GenerateDocumentBase64",
    headers=headers,
    data=json.dumps(payload)
)
response.raise_for_status()

result = response.json()
output_bytes = base64.b64decode(result["base64FileString"])

with open("output.pdf", "wb") as f:
    f.write(output_bytes)

print("Rendered document written to output.pdf")

output.pdf is a rendered, branded invoice generated from structured data in a single synchronous HTTP call.

What integration pattern is your team using to trigger document generation: synchronous on-demand, event-driven, or batch?

Common Mistakes and Troubleshooting

Word's autocorrect will silently replace straight quotes inside tags with smart (curly) quotes in some locales, which breaks tag parsing entirely. The risk shows up most often in format directives such as {{ totalDue \# "$#,##0.00" }}, where the "..." around the picture string is what gets converted. If your tags aren't resolving, paste them from a plain-text editor rather than typing them directly in Word, or disable autocorrect for the template file.

Tag names are case-sensitive throughout the system. {{ companyName }} and {{ CompanyName }} are different tags. Cross-check every placeholder in the template against the JSON payload keys before your first test call.

Missing payload fields render silently as empty strings. Validate the full payload against the tag list from the Analyze Document API before each call in production, especially when templates change and new tags get added without a corresponding update to the payload-building code.

Loop tokens must sit in the same Word table row. Placing {{TableStart:lineItems}} in row 1 and {{TableEnd:lineItems}} in row 2 produces a broken render with no error. The entire row that contains both tokens becomes the repeating unit.

The base64.b64encode() function in Python returns a bytes object. Forgetting the .decode("utf-8") call means you'll pass a bytes object into json.dumps(), which raises a TypeError: Object of type bytes is not JSON serializable. The error message points at the serializer rather than the encoding step, which makes the root cause easy to miss.

When a template hits the 4 MB encoded size cap, the API returns HTTP 413 or a 500 with a vague message. Slimming the template is the fix. Retrying with the same payload produces the same error. Compress images via Word's Picture Format compress tool, remove embedded fonts, and drop any OLE objects you don't need in the generated output.

Conclusion

Document generation looks like a templating problem until you put it in front of an auditor. The rendering pipeline itself is the easy part, a template plus a structured payload merged by an engine that returns a finished file. What separates a working prototype from a system that holds up in production is the layer around the engine, where credential handling, data residency, SOC 2 and HIPAA coverage, and the build-vs-buy threshold are decided.

The build-vs-buy decision compounds over time. An in-house pipeline on top of python-docx or WeasyPrint is defensible when the output format is fixed, the templates are stable, and the team has long-term capacity to own the rendering layer. Once any of those assumptions slips, the compliance surface, the template maintenance burden, and the cross-format requirements pull engineering attention away from the product itself. Shifting the rendering layer to a managed API with SOC 2 Type II, GDPR, and HIPAA coverage already in place removes a class of work that does not differentiate your product, in exchange for a vendor dependency that is easier to manage than a homegrown engine.

The Python quickstart above is the smallest possible version of the production pattern, with credentials read from the environment, a synchronous request to GenerateDocumentBase64, and a base64-decoded PDF written to disk. From there the path forward is well-trodden, by adding template validation through the Analyze Document API, layering retries and observability around the call, and expanding the template library as new document types come online. The architecture and the hard decisions are the same whether you generate ten documents a day or ten thousand. Getting them right early is what keeps the system out of the audit findings later.

To test the three-field request model against a live endpoint today, activate a free Foxit developer account (no credit card and no sales call required) and run the Postman collection. Sign up at account.foxit.com/site/sign-up.

LINKEDIN POSTS

LinkedIn Post 1

Most teams treat document generation as a template problem. The real problem is the implementation layer that sits around the template.

The rendering pipeline itself is well understood: a template plus a structured data payload produces a finished file. PDF for audit-ready delivery, DOCX for collaborative editing workflows. That part takes an afternoon to prototype.

What takes months to get right:

Credential handling that doesn't leak API keys into logs or environment variables
Data residency controls for documents that carry PII or contract terms
SOC 2 and HIPAA compliance at the rendering layer, not just at the application layer
A build-vs-buy threshold that accounts for long-term maintenance, not just first-week velocity

The teams that skip this layer ship a working proof of concept, then spend the next two quarters patching it before an audit.

I wrote a detailed guide covering the architecture and the hard decisions, including a Python quickstart against the Foxit Document Generation API. Link in the comments.

LinkedIn Post 2

The build-vs-buy decision for document generation has one real variable: who maintains the rendering engine when requirements change.

Building your own pipeline on top of a library like python-docx or WeasyPrint is the right call when your output format is fixed, your templates are stable, and you have engineering capacity to own it long-term. Most teams don't have all three.

The hidden costs of building in-house:

HIPAA-compliant rendering requires data processing agreements and infrastructure controls your team has to configure and certify
SOC 2 coverage for the rendering layer means your internal build is in scope for your next audit
Template maintenance compounds as output types multiply across contracts, invoices, and compliance reports

Using a managed API like Foxit's shifts the compliance surface area and the maintenance burden off your team. The trade-off is vendor dependency, which is worth the cost once you're past the first two or three document types.

Full guide with the architecture breakdown and a working Python quickstart in the comments.

LinkedIn Post 3

The most common bug in a production document generation pipeline is silent.

A required field is missing from the payload. The API returns 200. The rendered PDF ships with a blank where the customer name should be. Nobody catches it until the customer does, or worse, until an auditor does.

This happens because the template-to-data contract is implicit. A Word template declares placeholders with {{ field_name }} tags, but a .docx file is not a schema. The rendering engine merges what it can match and treats missing keys as empty strings by design. That is the right default for a generic engine and the wrong default for a regulated workflow where a blank field is a real problem.

The pattern that closes the gap:

Use the Analyze Document API (or your provider's equivalent) to enumerate every tag in the template before each call
Validate the payload against that tag list at build time, not at render time
Treat a missing key as an explicit error in your application layer, not a downstream PDF problem
Log the template version and the payload schema together so audit reconstruction has both halves

Most managed doc gen APIs expose a template introspection endpoint for exactly this reason. Foxit ships one. Use it.

The full guide covers this pattern plus the rest of the security, compliance, and build-vs-buy decisions. Link in the comments.

Should You Vibe Code Your SaaS Starter or Just Buy One?

Lucien Chemaly — Fri, 29 May 2026 06:39:09 +0000

It's 2026 and AI coding tools have made everyone feel like a 10x engineer. Cursor writes your components. Claude Code refactors your whole codebase between sips of coffee. v0 spits out landing pages from a prompt. Bolt and Lovable promise you a "full SaaS in one shot."

So the thought creeps in: why would I pay $69 for a Next.js SaaS starter kit when I can vibe code one myself in a weekend?

This article is the answer to that question, with actual numbers. I'm going to walk through what it really takes to build a production-ready SaaS starter in 2026 with AI tools, how much it costs in subscriptions and time, and what you get for $69–$119 if you just buy one. Then you can decide for yourself.

Spoiler: the math is not even close.

What "production-ready" actually means

Before the math, let's pin down what we're building. A SaaS starter isn't a landing page. It's the entire foundation a paid product sits on. Bolt and Lovable can scaffold a frontend in a prompt; they cannot ship you the following list.

Here's what a real Next.js SaaS starter includes:

Authentication. Email/password, password reset, email verification, session management. Probably social OAuth (Google, GitHub, etc.). Probably 2FA. Definitely RBAC (owner, admin, member roles).
Payments. Stripe and/or LemonSqueezy. Subscriptions and one-time purchases. Customer portal. Webhook handling with signature verification, idempotency, and retry logic. Two-way product sync. Guest checkout. Tax. Refunds.
Database. Schema, migrations, seed data, RLS or equivalent permission layer, multi-tenancy if you need it.
Admin panel. User management, billing oversight, support tools, feature flags, maintenance mode.
Content layer. A CMS or page builder so a non-developer can edit marketing pages without a deploy. (Most kits ship an MDX folder and pretend this is a CMS. It isn't.)
Email. Transactional (welcome, password reset, receipt), templated, with a real provider (Resend, Postmark, SES).
Observability. Error tracking (Sentry), analytics, logging.
Security. Rate limiting, CSRF, secure headers, input validation everywhere, secret management.
Testing. Unit tests, E2E tests, CI pipeline.
DX. TypeScript strict mode, ESLint, Prettier, Husky, env validation, type-safe API.
Deploy. Vercel/Render/Fly/Cloudflare config, env vars, preview deployments, production runbook.

This is the floor. Skip any of it and you're shipping a hobby project, not a SaaS.

The vibe coding budget: what AI actually costs in 2026

Let's price the toolchain. You're not vibe coding with one tool — you're stitching several together.

Tool	Monthly Cost	What it's for
Cursor Pro	$20	Day-to-day code editor
Claude Max (5x or 20x)	$100–$200	The model that actually does the heavy lifting on long contexts
ChatGPT Plus	$20	Second opinion, image gen, faster turnaround on small stuff
v0 by Vercel (Premium)	$20	UI scaffolding
GitHub Copilot Pro	$10	If you want completion in your IDE too
Realistic total	$170–$270/mo

You can scrape by on $20–$40/mo with just Cursor and Claude Pro, but if you're seriously trying to build a production codebase with AI doing most of the writing, you'll burn through Pro-tier limits in a week. Anyone who's actually shipped a real project with AI in 2026 knows the $100+/month tier is where the work happens.

If the build takes you three months (we'll get to why that's optimistic in a second), you're looking at $500–$800 just in subscriptions.

The time budget: how long this actually takes

Here's the part most "vibe code your SaaS" tweets quietly skip. AI is fast at scaffolding. AI is medium-speed at debugging. AI is slow at the parts of a SaaS that matter most.

Let me break it down by component, with realistic ranges for a developer using current AI tools (2026), assuming 8-hour workdays:

Component	Hours (with AI)	Hours (without AI)
Auth with RBAC, 2FA, OAuth	20–40	60–100
Stripe + webhook reliability	30–60	80–120
LemonSqueezy as second provider	15–25	40–60
Database schema, migrations, RLS	15–25	40–60
Admin panel	30–50	80–120
CMS / page builder	60–150	200–400
Email + templates + provider wiring	10–20	30–50
Analytics dashboard	15–40	40–80
Observability (Sentry, logging)	5–10	15–25
Testing (unit + E2E)	20–40	60–100
Security pass (rate limiting, headers, validation)	10–20	30–50
Deploy, CI, env config	10–20	30–50
Landing pages, marketing, docs	20–40	50–80
Polish, edge cases, bug hunting	40–80	80–160
Total	300–620 hours	835–1,455 hours

AI saves you roughly half the work. That's real. But half of "a lot" is still a lot.

At a conservative $50/hour for a senior developer (and if you're cheaper than that, you're using time you could spend on the actual product), that's $15,000–$31,000 of your own time.

At $100/hour: $30,000–$62,000.

Where AI quietly costs you money

The hours estimate above assumes everything works. It usually doesn't. Here's where AI confidently produces code that almost works and then bites you in production.

Stripe webhooks. AI will write a webhook handler that looks great. Then a customer chargebacks, the event arrives out of order, your idempotency key is wrong, you double-issue a refund, Stripe disputes, you spend a Saturday on the phone with support. Stripe webhooks are where junior developers — and apparently most LLMs — discover the meaning of "distributed systems."

Session management. AI will give you a working JWT auth flow on the happy path. Then a user clears cookies on one device, the refresh token expires on another, and they hit an infinite redirect loop. You will debug this for two days.

Row-level security. AI is genuinely bad at RLS policies. Either it generates policies that don't actually enforce anything (so any logged-in user can read every other user's data), or it generates policies so restrictive that no one can read anything. There is no middle ground in the default output.

The CMS. This is the killer. Building a real CMS — drag-and-drop sections, inline editing, media library, draft/publish, image optimization, slug routing, SEO fields — is the kind of multi-week subsystem that AI scaffolds in a day and then can't finish in three months. It's a UX problem, not a code generation problem.

Email deliverability. AI writes the SMTP code. It doesn't tell you about SPF, DKIM, DMARC, warmup periods, or why your password reset emails go to spam for two weeks.

Edge cases you don't know exist. What happens if a webhook fires before a user's account row commits? What if a Stripe customer object exists but the local user row doesn't? What if two browser tabs both try to refresh a token at the same time? AI doesn't ask these questions. You only learn the questions after you ship and break.

Each of these gotchas costs you a day to a week. There are dozens of them. They're the difference between "I built a SaaS in a weekend" Twitter content and an actual production system.

What buying gets you for $69

For comparison, here's what a current-generation Next.js SaaS starter ships with on day one:

Next.js (latest), TypeScript strict mode
Auth with RBAC, password reset, email verification
Stripe and LemonSqueezy (toggle via env var)
Webhook handlers with signature verification, idempotency, retry
Customer portal with subscription and billing management
Admin panel with user, billing, and content management
A real CMS with 20+ section templates and a media library (if you pick the right kit — see the previous section on this)
AI chat widget with intent detection and lead capture
Real-time analytics with UTM attribution
Email integration (Resend, SES, etc.)
52+ unit tests, Playwright E2E tests
15 database migrations
15+ pre-built themes
Coming Soon and Maintenance modes
A CLAUDE.md so your AI tools actually understand the codebase

Price: $69–$119, one time.

The time-to-value is also different. With a ready-made kit, you clone the repo, fill in your env vars, and have a working SaaS in an afternoon. With a vibe-coded build, you have an afternoon of work that takes you to maybe 5% of the feature list above.

The honest math

Let me put it side by side.

	Vibe code with AI	Buy a starter kit
Cash outlay	$500–$800 (subscriptions over 3 months)	$69–$119 (one-time)
Your time	300–620 hours	5–20 hours setup
Cost of your time @ $50/hr	$15,000–$31,000	$250–$1,000
Time to working SaaS	3–6 months	1 afternoon
Risk of production bugs	High	Low (battle-tested code)
Maintenance	You, forever	Kit updates from maintainer
Learning value	High	Low

If your time is worth literally nothing — you're a student, you're between jobs, you're treating this as your free education — then vibe coding makes sense.

For anyone else, the comparison isn't $69 vs $500 in AI subscriptions. It's $69 vs three to six months of your life.

When you should vibe code it anyway

I'm going to push back on my own argument now, because there are real cases where building it yourself is the right call.

You're learning. If the goal is to understand how a SaaS works end-to-end, building it yourself with AI as your tutor is genuinely valuable. You'll come out the other side a better developer. The "wasted" time is the point.

Your stack is exotic. If you want to build on Bun + Hono + LibSQL + Better Auth + Polar + Cloudflare Workers, no starter kit serves you. You're going to build a lot of this yourself anyway.

You have specific architectural requirements. Multi-tenant with strict data isolation? On-prem deployment? Air-gapped enterprise? Most starter kits assume single-tenant SaaS on a cloud provider. Roll your own.

You're a senior engineer who actually QAs AI output. If you can spot when AI generates a subtly broken Stripe webhook and fix it in 10 minutes, the time penalty is much smaller. AI as a productivity multiplier for someone who already knows the answers is genuinely transformative. AI as a substitute for senior judgment is a trap.

You enjoy it. This is a real reason. If you'd rather spend a Saturday building auth than reading a kit's documentation, do it. Just don't pretend it's the economically rational choice.

When you should just buy

For everyone else — solo founders, indie hackers, teams who want to be selling product not building plumbing — the answer is obvious. Buy a starter kit.

The starter kit market in 2026 is more competitive than it's ever been. $69 buys you a codebase that two years ago would have been a $50,000 contract job. The differentiator now is which kit fits your needs, not whether to build it yourself.

If you want the most feature-complete kit on the market right now — auth, payments (Stripe + LemonSqueezy), admin panel, a real drag-and-drop CMS with 20+ section templates, AI chat widget, real-time analytics, the whole package — RapidLaunch ships all of it for $69–$119, one-time. That's less than a single month of Claude Max plus Cursor. And you'd still have to write the code.

The actual question

The vibe coding question is really a question about what you want to be doing.

If you want to be building a SaaS product — the thing that solves a customer problem, the thing you can sell — buying a starter is the only sane move. Your time is better spent on what makes your product different, not on rebuilding auth for the thousandth time.

If you want to be building a codebase for the experience of building it, vibe code away. AI makes this more fun than it's ever been.

Just be honest with yourself about which one you're doing.

Skip the build, ship the product →

The Best Next.js SaaS Starter Kits with a Built-in CMS (2026)

Lucien Chemaly — Mon, 18 May 2026 18:35:21 +0000

It's month two of your SaaS. Your co-founder pings you on Slack: "Can we change the hero headline? I think it's confusing." You open the repo, edit a string, push, wait for Vercel, redeploy. Five minutes for a typo.

Three weeks in, you've done this fifteen times.

This is the dirty secret of Next.js SaaS boilerplates. Almost all of them ship "a CMS" that turns out to be a folder of MDX files. Great for a developer who loves Git. Catastrophic for anyone else on the team — a non-technical co-founder, a marketing hire, a freelance copywriter — who needs to update content without going through a pull request.

Once you actually need a content workflow, you have three options:

Integrate a headless CMS as a separate service (Contentful, Sanity, Storyblok). Adds infrastructure, a recurring bill, another vendor.
Build one yourself. Weeks of work. Custom admin UI, role-based permissions, image uploads, draft/publish states, preview, version history. You will get this wrong the first time.
Pick a starter kit where the CMS is already built in. Cheapest, fastest, and the only option a sane solo founder should consider in 2026.

This article is about option three. I looked at the Next.js SaaS starter kit market and asked one question: who can actually run the marketing site without touching code?

Most kits don't make the cut. The ones that do break into three tiers, and the gap between tier 1 and tier 3 is enormous.

What counts as a "real" CMS in a starter kit

Before the ranking, here are the criteria. There are three tiers of CMS capability in this market, and the difference between them is what a non-developer can actually do on day one.

Tier 1 — Visual page builder / drag-and-drop CMS. A non-developer can build, edit, and publish marketing pages from an admin UI. Sections are pre-built components, content is editable inline, no Git involved. This is what most people picture when they say "CMS."

Tier 2 — Integrated headless CMS. A real CMS UI (typically Sanity Studio or similar) is wired into the kit. A non-developer can edit structured content (blog posts, testimonials, FAQs), but page layout is still code. You're not paying for the CMS as a separate SaaS — it ships with the kit.

Tier 3 — MDX blog. Markdown files in a /content folder. Useful for technical blogs, useless for anyone who doesn't use Git. Some kits dress this up with extra content types (changelog, roadmap), but the workflow stays dev-only.

Kits that ship none of the above don't make the list. I'll cover those briefly at the end for completeness.

A real-world test: changing the hero headline

Before the ranking, here's the test I keep coming back to. Imagine your co-founder, who doesn't code, wants to A/B test two hero headlines. What happens in each tier?

Tier 1 (visual builder): Log into the admin panel, click the hero section, type the new headline, save. Live in 30 seconds.
Tier 2 (headless CMS): Log into the CMS dashboard, find the "Homepage" document, edit the heroTitle field, publish. Live in a minute or two — but only if the developer set up that field as editable content, which is a one-time piece of work that may or may not be done.
Tier 3 (MDX blog): Slack the developer. Wait. The developer edits a .tsx file, commits, pushes, waits for the deploy. The headline is hardcoded, so they may have to refactor it before they can change it. Live in 20 minutes to 2 hours.

That's the difference between a CMS and a Git workflow with extra steps. Keep this scenario in mind as you read.

Here are the six kits with a real content layer, ranked by depth.

1. RapidLaunch — Tier 1 (Visual Page Builder)

Price: $69 (Starter) / $119 (Pro/Unlimited) — one-time
URL: rapidlaun.ch
CMS type: Drag-and-drop visual page builder

RapidLaunch is the only kit on this list with a full visual page builder out of the box. You get 25+ templates, 35+ customizable components, 20+ section templates, a visual navigation editor, a footer editor, and a media library. There's also an AI template generator that scaffolds a complete site layout from a business description.

What a non-developer can do on day one:

Build a landing page from pre-made sections (hero, pricing, FAQ, testimonials, feature grid, etc.) by dragging them into place
Edit copy, swap images, change CTAs without touching code
Edit the main navigation and footer through dedicated editors
Upload and manage images through the media library
Toggle Coming Soon mode or Maintenance mode with one click

This is the kind of workflow most teams don't get until they pay for Webflow ($30+/month) or stand up a headless CMS as a separate service. RapidLaunch ships it as part of the kit.

The rest of the stack (carried over from the wider comparison): Next.js 16 with App Router, TypeScript in strict mode, Supabase for database/auth/storage, Stripe and LemonSqueezy (choose via env var), Tailwind CSS + DaisyUI with 15+ theme presets, TipTap rich text editor, TanStack Query, Vitest + Playwright. Authentication includes Owner + Admin roles (RBAC).

Trade-offs: Supabase is the only database option. Auth is email/password only out of the box — Supabase supports social OAuth, but you'd add it yourself. The project is newer than ShipFast or Makerkit, so the community is smaller (though growing).

Verdict: The only kit on this list where a non-developer can run the marketing site from day one. If editing pages without a deploy is a requirement, this is the pick.

2. Indie Starter — Tier 2 (Sanity CMS Integration)

Price: $69 (Tier 1) / $199 (Tier 2) / $299 (Tier 3) — one-time, unlimited projects
URL: indie-starter.dev
CMS type: Integrated Sanity Studio

Indie Starter wires Sanity CMS into the kit so you get a real headless CMS UI without setting it up yourself. Most kits with a "blog" mean MDX files. Indie Starter means a hosted CMS dashboard where you can model content types, edit posts in a rich editor, schedule publishing, and manage media — the standard Sanity workflow.

What a non-developer can do on day one:

Edit blog posts, articles, and any custom content types in Sanity Studio
Upload and manage images
Preview content before publishing
Schedule posts

What they can't do: edit landing-page layout. Marketing pages are still code. The CMS handles structured content, not visual page composition.

The rest of the stack: Next.js (latest), TypeScript, Supabase (PostgreSQL), magic links + Google/GitHub OAuth, Stripe with webhooks, Tailwind CSS + Shadcn/ui, Resend, Umami + Google Analytics, Zod. SEO infrastructure (sitemaps, robots.txt, Schema.org) is built in.

Trade-offs: Sanity is a separate service. The integration is free, but Sanity has its own free-tier limits (3 users, 10K documents, 5GB assets) — if you outgrow them, that's a separate bill. Some features are tier-locked, so check what's in the $69 tier before committing. Supabase is the only database option. Limited auth compared to bigger kits.

Verdict: The second-best CMS story in this market, and at $69 the cheapest path to a real headless CMS workflow. Best for content-heavy products (blogs, knowledge bases, documentation) where structured content matters more than landing-page flexibility.

3. Nextbase — Tier 3+ (MDX Blog + Content Features)

Price: $99 (Essential) / $299 (Pro) / $399 (Ultimate) — one-time, lifetime access
URL: usenextbase.com
CMS type: MDX blog + roadmap, changelog, user feedback (Pro tier and up)

Nextbase ships an MDX blog like everyone else in tier 3, but the Pro tier ($299) adds content features that most starter kits don't: a user feedback collection system, a public roadmap, and a changelog. None of these are a CMS in the strict sense, but they're content features you'd otherwise build yourself or pay separate tools for (Canny, Featurebase, etc.).

What a non-developer can do on day one:

Read user feedback and roadmap submissions in the admin panel
Publish changelog entries (depending on implementation)
Not much beyond that — blog content still lives in MDX

The rest of the stack: Next.js 15+, TypeScript, Supabase, Stripe, Tailwind CSS + Shadcn, Jest + Playwright, Sentry, PostHog + Google Analytics, OpenAI GPT-4. The monitoring stack (Sentry + PostHog) is a real differentiator — you start with observability instead of bolting it on later.

Trade-offs: The blog is still MDX. Features are tier-locked, so the content extras only show up at $299 Pro and above. Supabase only. Smaller community than ShipFast or Makerkit.

Verdict: Worth considering if you want product-content features (feedback, roadmap, changelog) bundled in. Not a CMS replacement, but the closest thing to one in the tier 3 group.

4. ShipFast — Tier 3 (MDX Blog)

Price: $199 (Starter) / $249 (All-in) / $299 (Bundle) — one-time
URL: shipfa.st
CMS type: MDX blog

ShipFast is the most popular Next.js boilerplate by community size, but the CMS story is minimal: an MDX blog. That's it. No admin UI for content, no headless CMS integration, no page builder. ShipFast is built around the philosophy of shipping fast — content management is something you add later if you need it.

The rest of the stack: Next.js 15, TypeScript or JavaScript, MongoDB or Supabase, Google OAuth + magic links, Stripe + LemonSqueezy, Tailwind CSS, Mailgun or Resend. The 8,000+ Discord and shipping culture are the real product — the codebase itself is lighter than most competitors at the same price.

Trade-offs: Beyond the lack of CMS, there's no admin dashboard beyond basic user management, no analytics, no AI features. If your SaaS grows past MVP, you'll build a lot on top of what ShipFast ships.

Verdict: Best for founders who want to ship an MVP in a week and don't care about a CMS workflow until later. If you do care about CMS, look elsewhere.

5. LaunchFast — Tier 3 (MDX Blog)

Price: $99 (single framework) / $149 (Astro + Next.js + SvelteKit bundle) — one-time
URL: launchfa.st
CMS type: MDX blog

LaunchFast is the "bring your own stack" kit — it supports 5+ database providers, multiple email services, several storage backends, and deploys to half a dozen targets. The trade-off is that the kit itself is less opinionated, which extends to content: you get an MDX blog and the assumption that you'll wire up whatever CMS you want on top.

The rest of the stack: Next.js (also Astro and SvelteKit), TypeScript, MongoDB/Firebase/PostgreSQL/Redis/SQLite, flexible auth, Stripe + LemonSqueezy, Resend/Postmark/SendGrid/Mailgun/AutoSend, S3/R2/Firebase/Supabase Storage.

Trade-offs: Maximum flexibility, but more decisions and more wiring. If you want a CMS, you're integrating one yourself.

Verdict: Good if you already know you want a specific CMS (Payload, Strapi, Sanity, Directus) and want a kit that won't fight you when you add it. Not good if you want a CMS to be solved for you.

6. Shipped.club — Tier 3 (MDX Blog + Special Pages)

Price: $149 — one-time, lifetime access
URL: shipped.club
CMS type: MDX blog + waitlist / pre-order / affiliate pages

Shipped.club ships an MDX blog plus pre-built pages most kits don't include: a waitlist page, a pre-order page, and an affiliate program page. These aren't CMS-managed (they're code), but they're content surfaces that ship working out of the box.

The rest of the stack: Next.js 14, TypeScript, Supabase, NextAuth + Supabase Auth, LemonSqueezy (no Stripe), ChakraUI + Tailwind, MailChimp + Loops. PPP pricing is a nice touch.

Trade-offs: Stuck on Next.js 14. LemonSqueezy is the only payment option. Supabase only. Less documentation than the bigger kits.

Verdict: Worth considering if the bundled pages (waitlist, pre-order, affiliate) save you time and an MDX blog is enough on the content side.

Kits without any CMS at all

For honesty: four kits in the broader Next.js SaaS market ship with no CMS layer of any kind. Worth mentioning so this list doesn't look cherry-picked.

Supastarter ($349+): excellent on payments (5 providers), team management, and multi-framework support (Next.js / Nuxt / SvelteKit), but blog and docs only — no CMS.
Makerkit ($299+): strong on multi-tenant B2B with row-level security and the most complete auth on the market, but no CMS.
Nextless.js ($699+): AWS-native with serverless and React Native support, but no CMS.
Vercel SaaS Starter (free): minimal by design — auth, Stripe, Drizzle. You'd add a CMS yourself.

These are good kits for what they do. They just don't compete on content management.

CMS-Focused Comparison Table

Kit	Price	CMS Type	Non-Dev Editing	Blog	Visual Builder	Media Library
RapidLaunch	$69	Drag-and-drop builder	Yes	Via CMS	Yes (20+ sections)	Yes
Indie Starter	$69	Sanity CMS	Yes (Sanity Studio)	Sanity	No	Yes (Sanity)
Nextbase	$99 / $299 Pro	MDX + feedback/roadmap	Partial (admin only)	MDX (Pro)	No	No
ShipFast	$199	MDX	No	Yes	No	No
LaunchFast	$99	MDX	No	Yes	No	No
Shipped.club	$149	MDX + special pages	No	Yes	No	No

How to Choose

Choose RapidLaunch if you need a non-developer to own the marketing site, or you don't want to redeploy every time a headline changes. The drag-and-drop builder is the only one of its kind in this market, and at $69 one-time it undercuts two months of a Webflow CMS subscription.

Choose Indie Starter if you want a real headless CMS workflow (Sanity Studio) at the lowest possible entry price ($69). Best for content-heavy products where structured content matters more than visual page composition.

Choose Nextbase Pro if you want product-content features (user feedback, roadmap, changelog) bundled with your starter, and you're okay with MDX for the blog itself.

Choose ShipFast, LaunchFast, or Shipped.club if an MDX blog is genuinely enough for now and you'll handle content management yourself later. These are good kits — just don't pick them expecting a CMS workflow.

Final Thoughts

The CMS gap in the Next.js SaaS starter market is real. Most kits hand you authentication, payments, and a landing page, then leave content management as an exercise for the reader. For solo developers building their first product, that's often fine. For anyone with a non-technical co-founder, a marketing function, or a growth-stage product where copy changes weekly, it's a problem you'll hit by month two.

If you want a CMS workflow without paying extra for one or building it yourself, the practical choice today is RapidLaunch for a full visual page builder, or Indie Starter for an integrated Sanity workflow at the lowest price. Everything else in this market punts on the content layer.

If I were starting a new SaaS today and knew I'd be editing the marketing site regularly, I'd pick RapidLaunch. The combination of a drag-and-drop builder, an AI template generator, and the rest of the kit (auth, payments, admin dashboard, analytics) at $69–$119 one-time is a better deal than buying Webflow plus any other starter on this list.

Try RapidLaunch and run your marketing site without a deploy pipeline.

HTML to PDF API: Convert Web Content to PDF Programmatically with Foxit

Lucien Chemaly — Thu, 16 Apr 2026 17:04:49 +0000

Your Puppeteer setup works fine at low volume. You launch a Chrome process, load the page, call page.pdf(), and write the bytes to disk. Then your invoice generation hits 500 documents per night, your report export feature goes live across three time zones simultaneously, and the wheels come off. Chrome processes time out waiting for JavaScript hydration. Memory climbs until your container OOMs. The font that renders correctly on your MacBook looks wrong on the Linux build server. You spend a Friday afternoon tuning networkidle2 timeouts per template instead of shipping features.

That failure mode comes from treating a rendering engine as a conversion service. Headless Chrome is a browser, and running it at production document volume means operating a browser fleet: process pooling, memory isolation, crash recovery, rendering consistency across OS environments. All of that infrastructure overhead comes directly out of engineering time.

A managed REST API sidesteps that entirely. You POST your HTML (or a URL), the service renders the PDF, and you download the result. The rendering infrastructure becomes the API provider's problem. This guide covers how to build that conversion pipeline end-to-end using Foxit PDF Services API, from authentication through batch processing and production error handling.

The Production Problem with Headless Browser PDF Conversion

A standard Puppeteer setup looks like this:

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto(url, { waitUntil: "networkidle2" });
const pdf = await page.pdf({ format: "A4", printBackground: true });
await browser.close();

At five documents a day, this is fine. At five hundred concurrent, each puppeteer.launch() spins up a full Chromium process, roughly 100-200MB RSS on Linux. In a container with 2GB of memory and 20 concurrent requests, you're at the memory ceiling before accounting for the Node.js process or any other application memory.

The standard fix is a Chrome process pool (libraries like puppeteer-cluster or generic-pool). Now you're managing pool size tuning, handling pool exhaustion under burst traffic, and writing cleanup logic for crashed Chrome instances. You've added significant operational complexity to what started as a one-liner.

Font rendering is its own category of pain. Chrome on macOS uses CoreText. Chrome on Linux uses FreeType with fontconfig. The same CSS font-family: 'Inter' declaration produces visibly different output depending on whether Inter is installed as a system font or loaded via a @font-face declaration, and whether the fallback stack resolves differently across environments. Teams that ship invoice PDFs to customers discover this in production.

JavaScript execution adds another dimension. If your page renders a data table via a React component that fetches data on mount, networkidle2 is an unreliable wait condition. Network activity can go idle before the DOM finishes updating. You end up tuning waitForSelector or adding arbitrary timeouts per template, and those timeouts become technical debt that breaks when the page changes.

A managed REST API with consistent rendering environments and no infrastructure to maintain solves these problems at the architectural level.

How Cloud HTML-to-PDF APIs Handle Rendering

Cloud conversion APIs typically accept input in two modes: URL mode and file upload mode.

In URL mode, you pass a public URL. The API fetches the page, renders it, and returns a PDF. This works when your page is publicly accessible and all assets (fonts, images, stylesheets) load from the same domain or CDN. The tradeoff is that the API's rendering environment must reach your server, which creates a dependency on network reachability and your server's response time. If you're generating PDFs from an internal dashboard behind a VPN, URL mode doesn't work without additional networking.

In file upload mode, you construct the complete HTML file (with inlined CSS and assets where needed) and upload it to the API. The service processes the file and returns a PDF. This eliminates the external asset dependency and makes your conversion more deterministic. The same HTML file always produces the same PDF, regardless of what's deployed on your web server at the time.

Beyond input mode, rendering fidelity depends on several factors:

CSS @media print rules control what renders into the PDF. Navigation bars, sidebars, and hover states should be hidden via print stylesheets so they don't appear in the output.
Font loading strategy determines rendering consistency. Relying on system fonts produces different output across environments. Embedding fonts via @font-face with a CDN URL or base64-inlined data guarantees consistent rendering.
Page layout properties (paper size, margins, orientation) can be controlled through CSS @page rules embedded in the HTML itself. This keeps layout configuration in the document rather than in API parameters.
JavaScript execution matters for pages that render content dynamically. Some APIs wait for the page to stabilize before capturing; others capture immediately.

These factors are the same ones you'd manage with Puppeteer's page.pdf() options, but with a cloud API you handle them through your HTML and CSS rather than through in-process code.

Setting Up Foxit PDF Services API: Authentication and First Conversion

Foxit PDF Services API is a cloud-hosted REST API built on Foxit's proprietary PDF engine, backed by over 20 years of PDF technology development. Create an account at the Foxit Developer Portal (the Developer plan is free, includes 500 credits/year, and requires no credit card). Generate your API credentials (client_id and client_secret) from the Developer Dashboard.

Understanding the Async Workflow

Foxit PDF Services uses an asynchronous task-based workflow. Every operation follows the same pattern:

Submit the job (upload a file, or POST a URL)
Receive a taskId in the response
Poll the task status until it completes or fails
Download the result using the resultDocumentId from the completed task

This design handles long-running operations cleanly. A complex HTML page might take several seconds to render, and the async pattern means your client never blocks on a single HTTP request waiting for rendering to finish.

URL-to-PDF Conversion

For pages that are publicly accessible, URL-to-PDF is the simplest path. You POST the URL directly and the API fetches, renders, and converts it. The complete workflow in Python uses the requests library:

import os
import requests
from time import sleep

HOST = os.environ["FOXIT_API_HOST"]  # e.g., https://na1.fusion.foxit.com
CLIENT_ID = os.environ["FOXIT_CLIENT_ID"]
CLIENT_SECRET = os.environ["FOXIT_CLIENT_SECRET"]

AUTH_HEADERS = {
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET,
}


def create_url_to_pdf_task(url: str) -> str:
    """Submit a URL for PDF conversion. Returns a taskId."""
    headers = {**AUTH_HEADERS, "Content-Type": "application/json"}
    response = requests.post(
        f"{HOST}/pdf-services/api/documents/create/pdf-from-url",
        json={"url": url},
        headers=headers,
    )
    response.raise_for_status()
    return response.json()["taskId"]


def poll_task(task_id: str, interval: int = 5) -> dict:
    """Poll until the task completes or fails. Returns the task status object."""
    headers = {**AUTH_HEADERS, "Content-Type": "application/json"}
    while True:
        response = requests.get(
            f"{HOST}/pdf-services/api/tasks/{task_id}",
            headers=headers,
        )
        response.raise_for_status()
        status = response.json()
        if status["status"] == "COMPLETED":
            return status
        elif status["status"] == "FAILED":
            raise RuntimeError(f"Task {task_id} failed: {status}")
        sleep(interval)


def download_document(document_id: str, output_path: str) -> None:
    """Download the resulting PDF by its document ID."""
    response = requests.get(
        f"{HOST}/pdf-services/api/documents/{document_id}/download",
        headers=AUTH_HEADERS,
        stream=True,
    )
    response.raise_for_status()
    with open(output_path, "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)

# Full workflow: URL to PDF
task_id = create_url_to_pdf_task("https://example.com/invoice/1042")
result = poll_task(task_id)
download_document(result["resultDocumentId"], "invoice_1042.pdf")
print("PDF generated successfully.")

Three reusable functions map to the async workflow: create_url_to_pdf_task() submits a public URL and returns a taskId, poll_task() checks task status in a loop until it reaches COMPLETED or FAILED, and download_document() streams the resulting PDF to disk. The final three lines wire them together into the complete conversion pipeline.

Before running: Set your FOXIT_API_HOST, FOXIT_CLIENT_ID, and FOXIT_CLIENT_SECRET environment variables with the values from your Foxit Developer Dashboard. Never commit credentials to source control; use environment variables or a secrets manager.

HTML File-to-PDF Conversion

When your content isn't publicly accessible (internal dashboards, dynamically generated reports), you can upload an HTML file directly. This follows the same 4-step async pattern:

def upload_document(file_path: str) -> str:
    """Upload a file to Foxit. Returns a documentId."""
    with open(file_path, "rb") as f:
        response = requests.post(
            f"{HOST}/pdf-services/api/documents/upload",
            files={"file": f},
            headers=AUTH_HEADERS,
        )
    response.raise_for_status()
    return response.json()["documentId"]


def create_html_to_pdf_task(document_id: str) -> str:
    """Create an HTML-to-PDF conversion task. Returns a taskId."""
    headers = {**AUTH_HEADERS, "Content-Type": "application/json"}
    response = requests.post(
        f"{HOST}/pdf-services/api/documents/create/pdf-from-html",
        json={"documentId": document_id},
        headers=headers,
    )
    response.raise_for_status()
    return response.json()["taskId"]

# Full workflow: HTML file to PDF
doc_id = upload_document("report.html")
task_id = create_html_to_pdf_task(doc_id)
result = poll_task(task_id)
download_document(result["resultDocumentId"], "report.pdf")
print("HTML converted to PDF successfully.")

You first upload a local .html file via upload_document(), which returns a documentId referencing the uploaded file on Foxit's servers. Then create_html_to_pdf_task() submits that documentId for conversion. The rest of the workflow is identical: poll for completion, then download the result.

Note: Replace "report.html" with the path to your own HTML file. This code reuses the poll_task() and download_document() functions from the URL-to-PDF example above, so make sure both are defined in the same script.

URL-to-PDF skips the upload step because you POST the URL directly. HTML file conversion requires uploading the .html file first via the /documents/upload endpoint. Both use the same poll-and-download pattern after task creation.

Refer to the Foxit API documentation and the Postman workspace for the complete parameter reference, including any additional rendering options supported by these endpoints. The GitHub demo repository contains working examples in Python, Node.js, and PHP.

Controlling CSS and JavaScript Rendering in HTML-to-PDF Conversion

Regardless of which API you use for HTML-to-PDF conversion, output quality depends on how well you prepare the HTML. The rendering parameters live in your document, not in API request fields.

The most common rendering problem between "looks right in a browser" and "looks wrong in a PDF" is the CSS media type. By default, browsers render with screen styles, which means your navigation bar, sidebar, and hover states all appear in the output. For PDF output, you want your @media print rules to take over.

@media print {
  nav,
  .sidebar,
  .no-print {
    display: none;
  }

  body {
    font-size: 11pt;
    font-family: "Inter", Arial, sans-serif;
    color: #000;
  }

  .invoice-table {
    page-break-inside: avoid;
  }

  .page-header {
    page-break-before: always;
  }

  @page {
    size: A4;
    margin: 20mm 15mm;
  }
}

This stylesheet hides non-essential UI elements (navigation, sidebars) when printing, sets a clean body font, and uses page-break-inside: avoid to prevent the renderer from splitting a table row across pages. The nested @page rule sets the paper size and margins at the CSS level, so layout configuration stays in the document rather than in API parameters.

For font rendering consistency, don't rely on system fonts. Include a @font-face declaration in your HTML that loads from a CDN, or inline the font as base64:

<style>
  @font-face {
    font-family: "Inter";
    src: url("https://fonts.gstatic.com/s/inter/v13/UcCO3FwrK3iLTeHuS_fvQtMwCp50KnMw2boKoduKmMEVuLyfAZ9hiJ.woff2")
      format("woff2");
    font-weight: 400;
    font-style: normal;
  }
</style>

This embeds the Inter font directly in the HTML using a @font-face declaration pointing to Google Fonts. Inter renders in the PDF regardless of what fonts are installed in the API's container environment. The tradeoff is latency: the rendering engine fetches the font file during conversion. If you're running high-volume batch jobs, consider inlining the font as a base64 data URI to eliminate that network round trip.

For JavaScript-heavy pages, make sure the content has fully rendered before the API captures it. If you're using the URL-to-PDF endpoint, the API fetches and renders the live page, so your page's JavaScript will execute. For the HTML file upload path, keep your HTML self-contained with all data already rendered in the markup, rather than relying on client-side JavaScript to populate it after load.

Batch HTML-to-PDF Conversion at Scale

Sequential conversion is the naive starting point:

for invoice in invoices:
    doc_id = upload_document(invoice.html_path)
    task_id = create_html_to_pdf_task(doc_id)
    result = poll_task(task_id)
    download_document(result["resultDocumentId"], f"output/{invoice.id}.pdf")

Each invoice is processed one at a time, uploading, converting, polling, and downloading before moving to the next. Each iteration blocks on the poll loop before starting the next conversion. At a few seconds per document (upload, render, poll, download), 500 invoices could take over 30 minutes.

Concurrent dispatch with a semaphore to cap parallelism fixes that. Check your plan's rate limits before setting the semaphore ceiling in production.

import asyncio
import aiohttp
import os
from pathlib import Path

HOST = os.environ["FOXIT_API_HOST"]
CLIENT_ID = os.environ["FOXIT_CLIENT_ID"]
CLIENT_SECRET = os.environ["FOXIT_CLIENT_SECRET"]
MAX_CONCURRENT = 10  # Adjust based on your plan's rate limits


async def convert_one(
    session: aiohttp.ClientSession,
    sem: asyncio.Semaphore,
    invoice_id: str,
    html_path: str,
    output_dir: Path,
) -> tuple[str, bool]:
    async with sem:
        try:
            auth = {"client_id": CLIENT_ID, "client_secret": CLIENT_SECRET}

            # Step 1: Upload the HTML file
            with open(html_path, "rb") as f:
                form = aiohttp.FormData()
                form.add_field("file", f, filename="document.html")
                async with session.post(
                    f"{HOST}/pdf-services/api/documents/upload",
                    data=form,
                    headers=auth,
                ) as resp:
                    if resp.status != 200:
                        return invoice_id, False
                    upload_result = await resp.json()
                    doc_id = upload_result["documentId"]

            # Step 2: Create the conversion task
            async with session.post(
                f"{HOST}/pdf-services/api/documents/create/pdf-from-html",
                json={"documentId": doc_id},
                headers={**auth, "Content-Type": "application/json"},
            ) as resp:
                if resp.status != 200:
                    return invoice_id, False
                task_result = await resp.json()
                task_id = task_result["taskId"]

            # Step 3: Poll for completion
            while True:
                async with session.get(
                    f"{HOST}/pdf-services/api/tasks/{task_id}",
                    headers={**auth, "Content-Type": "application/json"},
                ) as resp:
                    status = await resp.json()
                    if status["status"] == "COMPLETED":
                        result_doc_id = status["resultDocumentId"]
                        break
                    elif status["status"] == "FAILED":
                        print(f"Task failed for {invoice_id}")
                        return invoice_id, False
                await asyncio.sleep(5)

            # Step 4: Download the result
            async with session.get(
                f"{HOST}/pdf-services/api/documents/{result_doc_id}/download",
                headers=auth,
            ) as resp:
                if resp.status == 200:
                    pdf_bytes = await resp.read()
                    (output_dir / f"{invoice_id}.pdf").write_bytes(pdf_bytes)
                    return invoice_id, True
                return invoice_id, False

        except Exception as e:
            print(f"Error converting {invoice_id}: {e}")
            return invoice_id, False


async def batch_convert(invoices: list[dict], output_dir: str = "output") -> dict:
    output_path = Path(output_dir)
    output_path.mkdir(exist_ok=True)

    sem = asyncio.Semaphore(MAX_CONCURRENT)
    connector = aiohttp.TCPConnector(limit=MAX_CONCURRENT)

    async with aiohttp.ClientSession(connector=connector) as session:
        tasks = [
            convert_one(session, sem, inv["id"], inv["html_path"], output_path)
            for inv in invoices
        ]
        results = await asyncio.gather(*tasks)

    succeeded = [r[0] for r in results if r[1]]
    failed = [r[0] for r in results if not r[1]]
    return {"succeeded": len(succeeded), "failed": failed}


# Usage
invoices = [
    {"id": "inv_1042", "html_path": "templates/invoice_1042.html"},
    {"id": "inv_1043", "html_path": "templates/invoice_1043.html"},
    # ... up to thousands of entries
]

result = asyncio.run(batch_convert(invoices))
print(f"Converted {result['succeeded']} PDFs. Failed: {result['failed']}")

asyncio and aiohttp let you process multiple conversions concurrently. The convert_one() function runs the full 4-step workflow (upload, create task, poll, download) for a single invoice, while batch_convert() dispatches all invoices in parallel, capped by a semaphore. Results are collected via asyncio.gather() and split into succeeded and failed lists.

Before running: Set FOXIT_API_HOST, FOXIT_CLIENT_ID, and FOXIT_CLIENT_SECRET as environment variables with your credentials from the Developer Dashboard. Adjust MAX_CONCURRENT based on your plan's rate limits, and update the invoices list with your actual file paths.

With MAX_CONCURRENT = 10 and several seconds per conversion (including polling), the batch processes 10 documents at a time. The semaphore prevents you from flooding the API with simultaneous requests and hitting the rate limit ceiling. asyncio is part of Python's standard library, so no additional dependencies beyond aiohttp are needed.

Credit consumption matters at scale. The Developer plan includes 500 credits/year. The Startup plan ($1,750/year) provides 3,500 credits. Each conversion typically costs 1 credit. For higher volumes, the Business plan ($4,500/year) includes 150,000 credits. Check your remaining credit balance via the Developer Dashboard before launching a large batch job.

For volumes beyond what a single process can handle efficiently, a queue-based architecture decouples submission from processing. Services like Amazon SQS or Redis Streams handle the message brokering:

App Server -> Message Queue (SQS / Redis Streams) -> Worker Pool (N workers)
  Worker: upload HTML -> create task -> poll -> download PDF -> store in S3/GCS
  Worker: update job status in Postgres / Redis

Each worker picks a job from the queue, runs the 4-step conversion workflow, writes the resulting PDF to S3 or GCS, and updates the job status in a database. This pattern handles burst volume naturally: jobs queue up during spikes, workers drain at the rate the API allows, and your app server is never blocked waiting for conversions to complete.

Production Deployment Patterns for HTML-to-PDF Pipelines

Error Handling and Retry Logic

Map HTTP status codes to decisions before writing any retry logic, because not all errors warrant a retry.

A 400 Bad Request means your request body is malformed. Retrying the same payload returns another 400, so fix the payload. A 429 Too Many Requests and a 503 Service Unavailable are transient: back off and retry. A FAILED task status means the conversion itself failed (possibly due to invalid HTML or unreachable URLs). Check the task response for diagnostic details.

import time
import random
import requests
from requests.exceptions import RequestException

PERMANENT_ERRORS = {400, 401, 403, 422}
TRANSIENT_ERRORS = {429, 500, 502, 503, 504}


def post_with_retry(
    url: str,
    max_retries: int = 4,
    base_delay: float = 1.0,
    **kwargs,
) -> requests.Response:
    """POST with exponential backoff and jitter for transient errors."""
    for attempt in range(max_retries + 1):
        try:
            response = requests.post(url, timeout=60, **kwargs)

            if response.status_code in range(200, 300):
                return response

            if response.status_code in PERMANENT_ERRORS:
                raise ValueError(
                    f"Permanent error {response.status_code}: {response.text}"
                )

            if response.status_code in TRANSIENT_ERRORS:
                if attempt == max_retries:
                    raise RuntimeError(
                        f"Max retries exceeded. Last status: {response.status_code}"
                    )
                delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
                print(f"Transient error {response.status_code}. Retrying in {delay:.1f}s...")
                time.sleep(delay)

        except RequestException as e:
            if attempt == max_retries:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(delay)

    raise RuntimeError("Unexpected: exhausted retries without returning or raising")

# Usage with the URL-to-PDF endpoint
auth_headers = {
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET,
    "Content-Type": "application/json",
}

response = post_with_retry(
    f"{HOST}/pdf-services/api/documents/create/pdf-from-url",
    json={"url": "https://example.com/invoice/1042"},
    headers=auth_headers,
)
task_id = response.json()["taskId"]

Every POST request goes through a retry loop with exponential backoff. The function distinguishes between permanent errors (like 400 or 401, which you shouldn't retry) and transient errors (like 429 or 503, which resolve on their own). Each retry doubles the wait time and adds random jitter to avoid synchronized retry waves.

Before running: Replace CLIENT_ID, CLIENT_SECRET, and HOST with your Foxit credentials and API host, or load them from environment variables as shown in the earlier examples.

The jitter (random.uniform(0, 0.5)) prevents a thundering herd where every worker wakes up and retries simultaneously after a 429 burst. Plain exponential backoff produces synchronized retry waves when all workers hit the rate limit at the same time.

Output Optimization: Compression and Linearization

After conversion, you can chain additional PDF operations using the same async pattern. Upload the resulting PDF, call the compression or linearization endpoint, poll, and download the optimized version.

For PDFs served directly in a browser, linearization enables Fast Web View, which lets the browser display page one while the rest of the file downloads:

def compress_and_linearize(input_pdf_path: str, output_path: str) -> None:
    """Compress a PDF, then linearize it for fast web viewing."""
    auth = {"client_id": CLIENT_ID, "client_secret": CLIENT_SECRET}
    json_headers = {**auth, "Content-Type": "application/json"}

    # Upload the PDF
    doc_id = upload_document(input_pdf_path)

    # Compress
    resp = requests.post(
        f"{HOST}/pdf-services/api/documents/modify/pdf-compress",
        json={"documentId": doc_id, "compressionLevel": "MEDIUM"},
        headers=json_headers,
    )
    resp.raise_for_status()
    task = poll_task(resp.json()["taskId"])
    compressed_doc_id = task["resultDocumentId"]

    # Linearize the compressed result (no need to re-upload; use the resultDocumentId)
    resp = requests.post(
        f"{HOST}/pdf-services/api/documents/optimize/pdf-linearize",
        json={"documentId": compressed_doc_id},
        headers=json_headers,
    )
    resp.raise_for_status()
    task = poll_task(resp.json()["taskId"])

    # Download the final optimized PDF
    download_document(task["resultDocumentId"], output_path)

You chain two PDF operations back-to-back here. First, you upload the PDF and compress it at MEDIUM level (valid options are LOW, MEDIUM, and HIGH). Once compression completes, you pass the resultDocumentId directly into the linearization step, which avoids a second upload. The final download gives you a PDF that's both smaller and optimized for progressive loading in browsers.

Note: This function reuses upload_document(), poll_task(), and download_document() from the earlier examples. Make sure those functions are defined in the same script with your credentials configured. The Foxit developer blog post on chaining PDF actions covers this pattern in detail.

Monitoring and Secret Management

Monitor three things per conversion job: how long each call takes (to spot API degradation early), credits consumed per job type (to forecast when you'll hit your plan ceiling), and failure rate broken down by error code (to catch template regressions before customers do). Set an alert when your remaining credits fall below 20% of the plan allocation. The Foxit Developer Dashboard surfaces real-time usage data worth checking before kicking off large batch runs.

Store API credentials in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager). When team members leave or you suspect a credential leak, rotate them from the Developer Dashboard. New credentials can be generated and old ones revoked without downtime, as long as you update your environment before revoking.

Start Converting HTML to PDF

The Foxit Developer plan is free, requires no credit card, and gives you 500 credits to start with. Grab your client_id and client_secret from the Developer Dashboard, then either clone the demo repository for ready-made examples in Python, Node.js, and PHP, or drop the URL-to-PDF snippet from this guide into a script and run it against any public page.

Once your first conversion comes back, check credit usage in the Dashboard to project costs at your production volume. If you need more throughput, the Startup plan ($1,750/year for 3,500 credits) is self-serve with no sales call.

Get started for free on the Foxit Developer Portal

The 10 Best Next.js Starter Kits for SaaS in 2026

Lucien Chemaly — Wed, 15 Apr 2026 06:45:10 +0000

You've decided to build a SaaS product with Next.js. The smart move is starting from a production-ready starter kit instead of spending three months wiring up auth, payments, and a dashboard from scratch. The not-so-smart move is picking the wrong one and realizing it six weeks in.

There are dozens of Next.js boilerplates competing for your money right now. Some are genuinely excellent. Some are glorified create-next-app templates with a Stripe webhook bolted on. This comparison cuts through the noise with real technical details: actual tech stacks, actual pricing, actual feature coverage, and honest trade-offs.

I've built products on several of these and evaluated the rest against real-world SaaS requirements: authentication with RBAC, payment flexibility, database architecture, CMS capabilities, and how much code you'll actually need to write after checkout.

Here are the 10 best Next.js starter kits for SaaS in 2026, ranked.

1. RapidLaunch

Price: $69 (Starter) / $119 (Pro/Unlimited) - one-time.
URL: rapidlaun.ch

Tech Stack:

Next.js 16 with App Router
TypeScript (strict mode)
Supabase (PostgreSQL + Auth + Storage)
Stripe + LemonSqueezy (choose via env variable)
Tailwind CSS + DaisyUI
TanStack Query
TipTap rich text editor
Zod validation
Vitest + Playwright testing

RapidLaunch is the most feature-complete starter kit on this list. Where most boilerplates give you auth, payments, and a landing page, RapidLaunch ships a full drag-and-drop CMS with 20+ section templates, an AI-powered chat widget with lead capture, real-time analytics with a 3D interactive visitor globe, and an AI template generator that builds complete websites from a business description.

What sets it apart:

The CMS alone justifies the price. You get 25+ templates, 35+ customizable components, a visual navigation editor, footer editor, and a media library. Your non-technical co-founder can update the marketing site without touching code. That's a feature most teams don't get until they integrate a headless CMS as a separate service.

The AI chat widget runs on configurable OpenAI models (GPT-4, O3 Mini, and five others) with real-time streaming, conversation memory, and an intent detection system that automatically triggers a contact form when it detects purchase intent. That replaces tools like Intercom or Drift that run $50-$150/month.

The analytics dashboard tracks visitors in real-time with UTM attribution, browser fingerprinting, individual visitor session histories, and a WebGL globe showing geographic distribution. That's the kind of feature you'd pay $200+/month for from a standalone analytics tool.

The full feature set:

Authentication with RBAC (Owner + Admin roles)
Stripe and LemonSqueezy billing (subscriptions, one-time, guest checkout)
Automated webhook handling and two-way product sync
Customer portal with account, billing, and subscription management
Admin panel (CMS, users, billing, analytics, chat management)
Maintenance mode and Coming Soon mode (one-click toggle)
Cookie consent system
SEO optimization
15+ DaisyUI theme presets
52+ unit tests, 15 database migrations
CLAUDE.md file for AI-assisted development

Trade-offs: Supabase is the only database option. If you need raw PostgreSQL with a different hosting provider or want MongoDB, you'll need to adapt the data layer. Auth is email/password only out of the box (no social OAuth yet, though Supabase supports adding it). The project is newer than established competitors like ShipFast or Makerkit, so the community is still growing.

Verdict: If you want the most complete out-of-the-box experience (CMS + AI + analytics + auth + payments) at a price that undercuts most competitors, RapidLaunch is the strongest option available right now.

2. ShipFast

Price: $199 (Starter) / $249 (All-in) / $299 (Bundle with CodeFast) - one-time
URL: shipfa.st

Tech Stack:

Next.js 15
TypeScript or JavaScript
MongoDB or Supabase
Google OAuth + Magic Links
Stripe + LemonSqueezy
Tailwind CSS
Mailgun or Resend for email

ShipFast is the most popular Next.js boilerplate by sheer community size. Built by Marc Lou, it has a 5,000+ member Discord with revenue leaderboards and a culture of shipping fast. The average user launches in 7 days.

What you get: Auth, payments, email with DNS setup, SEO, a blog, pre-built UI components, and $1,210 in partner discounts. It's laser-focused on getting an MVP out the door with minimal friction.

Trade-offs: No CMS, no admin dashboard beyond basic user management, no analytics, no AI features. The database choice is MongoDB or Supabase only. If your SaaS grows beyond MVP stage, you'll be building significant infrastructure on top of what ShipFast provides. The community and shipping culture are genuinely valuable, but the actual codebase is thinner than competitors at the same price point.

Verdict: Best for solo founders who prioritize speed over feature completeness and value the community aspect. If you want to ship an MVP in a week and figure out the rest later, ShipFast delivers on that promise.

3. Supastarter

Price: $349 (Solo) / $799 (Startup, 5 seats) / $1,499 (Agency, 10 seats, white-label) - one-time
URL: supastarter.dev

Tech Stack:

Next.js, Nuxt, or SvelteKit (same features across frameworks)
TypeScript
Prisma or Drizzle ORM
better-auth (2FA, passkeys, RBAC)
Stripe, LemonSqueezy, Polar, Creem, Dodo Payments (5 providers)
Hono.js with oRPC
Tailwind CSS + Radix UI
TanStack Query
trigger.dev / QStash for background jobs

Supastarter is the enterprise option. Five payment providers, framework-agnostic (the same feature set works on Next.js, Nuxt, or SvelteKit), i18n baked in, team/organization management, and a super admin dashboard.

What sets it apart: The payment flexibility is unmatched. Five providers means you can support customers in markets where Stripe isn't available without rebuilding your billing layer. The Agency tier at $1,499 includes white-label licensing, which is the right call if you're building SaaS products for clients. It's also optimized for AI coding agents (Cursor and Claude Code ready).

Trade-offs: No built-in CMS (blog and docs only), no AI features, no analytics dashboard. The starting price at $349 is higher than most alternatives, and the Agency tier at $1,499 is the most expensive kit on this list. The breadth of options (three frameworks, two ORMs, five payment providers) means more decisions upfront. If you're a solo developer building one product, Supastarter may be more kit than you need.

Verdict: Best for teams and agencies that need multi-framework support, maximum payment flexibility, and white-label capabilities. Overkill for a solo founder building one product.

4. Makerkit

Price: $299 (Pro, individual) / $599 (Teams, 5 collaborators) - one-time, lifetime access
URL: makerkit.dev

Tech Stack:

Next.js 16, React 19
TypeScript 5
Supabase (with RLS), Drizzle, or Prisma (choose your stack)
OAuth + MFA (Google, GitHub, Facebook, X, Discord, TOTP)
Stripe Checkout + Customer Portal
Tailwind CSS v4 + Shadcn UI
Playwright for E2E testing

Makerkit has been around since 2022, making it one of the longest-running Next.js SaaS kits. It's focused on multi-tenant B2B SaaS with row-level security, RBAC, and team management built in from the start.

What sets it apart: The database flexibility is strong. You choose between Supabase with row-level security, Drizzle ORM with Better Auth, or Prisma 7 with Better Auth. Each stack is fully implemented, not just a config toggle. The Figma UI kit and React.Email templates are nice touches that save design time. Auth is the most complete of any kit here: email/password, magic links, social OAuth (five providers), and TOTP MFA.

Trade-offs: No CMS, no AI features, no built-in analytics. The $299 starting price is on the higher side for an individual license. The multiple stack options, while flexible, mean the documentation and codebase are more complex to navigate than a more opinionated kit.

Verdict: Best for B2B SaaS products that need multi-tenancy, strong auth, and row-level security from day one. The longest track record of any kit on this list.

5. Nextbase

Price: $99 (Essential) / $299 (Pro) / $399 (Ultimate) - one-time, lifetime access
URL: usenextbase.com

Tech Stack:

Next.js 15+
TypeScript
Supabase
Stripe
Tailwind CSS + Shadcn
Jest + Playwright
Sentry error tracking
PostHog + Google Analytics
OpenAI GPT-4

Nextbase takes a tiered approach. The $99 Essential tier covers auth, payments, multi-tenancy, admin panel, and MDX docs. The $299 Pro tier adds a blog, user feedback collection, roadmap functionality, changelog, and user impersonation. The $399 Ultimate tier unlocks everything.

What sets it apart: AI integration with GPT-4 is built in, and the monitoring stack (Sentry + PostHog) means you start with observability from day one instead of bolting it on later. The $99 entry price for a solid set of core features is competitive.

Trade-offs: Supabase only. Features are locked by tier, so you need to check exactly what you're getting at each price point. No CMS beyond the MDX blog. The community is smaller than ShipFast or Makerkit.

Verdict: Strong mid-range option with a genuinely useful tiered pricing model. The $99 Essential tier is one of the best value propositions for a production-ready starter.

6. LaunchFast

Price: $99 (single framework) / $149 (Astro + Next.js + SvelteKit bundle) - one-time
URL: launchfa.st

Tech Stack:

Next.js (also Astro and SvelteKit versions)
TypeScript
5+ database options (MongoDB, Firebase, PostgreSQL via Neon/Supabase/Xata, Redis, SQLite)
Flexible auth (email, magic links, OAuth)
Stripe + LemonSqueezy
Tailwind CSS
Resend, Postmark, SendGrid, Mailgun, AutoSend
S3, Cloudflare R2, Firebase, Supabase Storage

LaunchFast is the "bring your own stack" option. It supports more database providers, email services, file storage backends, and deployment targets than any other kit on this list.

What sets it apart: At $99 you get maximum flexibility. Swap databases, auth providers, payment processors, and deployment targets without rewriting your app. The $149 bundle gives you the same feature set across three frameworks. Deployment options include Vercel, Cloudflare Workers, Render, Fly.io, Netlify, and AWS Amplify.

Trade-offs: Less opinionated means more decisions and more wiring. No CMS, no AI features, no analytics dashboard. The documentation covers breadth over depth for each provider combination. If you want something that works out of the box with minimal configuration, this isn't it.

Verdict: Best for developers who have strong preferences about their stack and want a starter kit that adapts to them, not the other way around. The $99 price point is excellent for the flexibility offered.

7. Shipped.club

Price: $149 - one-time, lifetime access
URL: shipped.club

Tech Stack:

Next.js 14
TypeScript
Supabase
NextAuth + Supabase Auth
LemonSqueezy
ChakraUI + Tailwind CSS
MailChimp + Loops
MDX blog

Shipped.club is the budget option that doesn't feel like one. At $149 you get a complete starter with auth, payments, a landing page, waitlist page, pre-order page, and an affiliate program built in.

What sets it apart: The affiliate program is a feature no other kit on this list includes out of the box. Dual UI framework support (Chakra UI and Tailwind) gives you styling flexibility. PPP (Purchasing Power Parity) pricing makes it accessible globally. There's also a Chrome Extension version if that's your product format.

Trade-offs: Stuck on Next.js 14 (not the latest). LemonSqueezy is the only payment option (no Stripe). Supabase only. Less documentation and a smaller community than the top-tier competitors.

Verdict: Best bang for your buck if you're on a tight budget and LemonSqueezy fits your payment needs. The affiliate program inclusion is a smart differentiator.

8. Indie Starter

Price: $69 (Tier 1) / $199 (Tier 2) / $299 (Tier 3) - one-time, unlimited projects
URL: indie-starter.dev

Tech Stack:

Next.js (latest)
TypeScript
Supabase (PostgreSQL)
Magic links + social OAuth (Google, GitHub)
Stripe with webhooks
Tailwind CSS + Shadcn/ui
Sanity CMS
Resend for email
Umami + Google Analytics
Zod validation

Indie Starter stands out for its tiered pricing model starting at just $69. The Sanity CMS integration is a differentiator; most kits ship a basic MDX blog, but Indie Starter gives you a proper headless CMS for content management.

What sets it apart: The $69 entry tier makes it the cheapest paid option on this list. SEO infrastructure (sitemaps, robots.txt, Schema.org markup) is built in, not an afterthought. Sanity CMS integration means you get a real content management workflow, not just markdown files.

Trade-offs: Feature availability varies by tier. Supabase is the only database option. The community is smaller. Limited auth options compared to Makerkit or Supastarter.

Verdict: Best for indie hackers who want a solid foundation at minimal cost. The $69 tier is genuinely usable, not a stripped-down demo.

9. Nextless.js

Price: $699 (Single, 1 project) / $2,099 (Unlimited) - one-time + optional $199-$599/year renewal
URL: nextlessjs.com

Tech Stack:

Next.js 14
TypeScript
AWS Lambda (serverless)
PostgreSQL, MySQL, MongoDB, or DynamoDB
AWS Cognito (email, social login, MFA)
Stripe
AWS SES, SendGrid, Postmark, Mailgun, Mandrill
AWS CDK (Infrastructure as Code)
Tailwind CSS
Jest (unit, integration, E2E)

Nextless.js is the AWS-native option. If your company runs on AWS and needs serverless architecture with Infrastructure as Code, this is the only kit that delivers that out of the box.

What sets it apart: Full AWS CDK templates for infrastructure provisioning. Four database options in the Unlimited tier. Silo multi-tenancy model for proper data isolation. React Native boilerplate included for mobile support. This is the only kit on this list with a mobile-ready path.

Trade-offs: The most expensive option by far ($699-$2,099). Annual renewal for updates adds ongoing cost. AWS vendor lock-in is real. The serverless architecture has a learning curve if you're not already AWS-comfortable. Stuck on Next.js 14. No CMS, no AI features, no analytics.

Verdict: The right choice only if you're building on AWS and need serverless architecture with IaC. For everyone else, the price and complexity aren't justified.

10. Next.js SaaS Starter (by Vercel)

Price: Free (open source)
URL: github.com/nextjs/saas-starter

Tech Stack:

Next.js (latest)
TypeScript (93% of codebase)
PostgreSQL + Drizzle ORM
Email/password auth with JWTs in cookies
Stripe
Shadcn/ui
Zod validation
pnpm

The official Next.js SaaS starter from Vercel. It's intentionally minimal: auth, Stripe checkout, subscription management via Customer Portal, Server Actions with Zod validation, an activity logging system, and protected routes with middleware.

What sets it apart: It's free, it's from Vercel, and it uses the latest Next.js patterns. The codebase is clean and readable, making it an excellent learning resource. No bloat, no unnecessary abstractions. If you understand what you're building and just need a solid starting point, this does the job.

Trade-offs: Intentionally minimal means you'll add everything yourself: email service, landing pages, admin dashboard, CMS, AI integration, analytics, advanced auth (social OAuth, MFA), file storage. This is a starting point, not a finished product. If you factor in the hours to build what paid kits include, the "free" label is misleading.

Verdict: Best for experienced developers who want maximum control and are comfortable building features from scratch. Also the best learning resource for understanding Next.js SaaS architecture patterns.

Feature	RapidLaunch	ShipFast	Supastarter	Makerkit	Nextbase	LaunchFast	Shipped.club	Indie Starter	Nextless.js	Vercel Starter
Starting Price	$69	$199	$349	$299	$99	$99	$149	$69	$699	Free
Pricing Model	One-time	One-time	One-time	One-time	One-time	One-time	One-time	One-time	One-time + renewal	Free
Next.js Version	16	15	Latest	16	15+	Latest	14	Latest	14	Latest
TypeScript	Strict	Optional	Yes	Strict	Yes	Yes	Yes	Yes	Yes	Yes
Database	Supabase	MongoDB/Supabase	Prisma/Drizzle	Supabase/Drizzle/Prisma	Supabase	5+ options	Supabase	Supabase	4 options	PostgreSQL
Auth: Email/Password	Yes	No	Yes	Yes	Yes	Yes	Yes	Yes (magic links)	Yes	Yes
Auth: Social OAuth	No (extensible)	Google	5+ providers	5 providers	Yes	20+ providers	Yes	Google, GitHub	Yes	No
Auth: MFA/2FA	No	No	Yes (passkeys)	TOTP MFA	No	No	No	No	Yes	No
Auth: RBAC	Yes	No	Yes	Yes (RLS)	Yes	No	No	No	Yes	No
Stripe	Yes	Yes	Yes	Yes	Yes	Yes	No	Yes	Yes	Yes
LemonSqueezy	Yes	Yes	Yes	No	No	Yes	Yes (only)	No	No	No
Other Payments	No	No	Polar, Creem, Dodo	No	No	No	No	No	No	No
CMS/Page Builder	Drag-and-drop (20+ sections)	No	No	No	No	No	No	Sanity CMS	No	No
Blog	Via CMS	Yes	Yes	Yes	MDX (Pro tier)	MDX	MDX	Sanity	No	No
Admin Dashboard	Yes (full)	Basic	Yes	Yes	Yes	No	No	No	Yes	No
AI Chat Widget	GPT-4 (7 models)	No	No	No	GPT-4	No	No	No	No	No
AI Site Generator	Yes	No	No	No	No	No	No	No	No	No
Built-in Analytics	Yes (3D globe, UTM, fingerprinting)	No	No	No	PostHog + GA	No	No	Umami + GA	No	No
Customer Portal	Yes	No	Yes	Yes	Yes	No	No	No	Yes	Yes (Stripe)
Email Integration	Yes	Mailgun/Resend	Multiple	React.Email	Resend	5 providers	MailChimp/Loops	Resend	5 providers	No
i18n	No	No	Yes	No	No	No	No	No	No	No
Multi-tenancy	No	No	Yes	Yes (RLS)	Yes	No	No	No	Yes (silo)	No
Testing Suite	Vitest + Playwright	No	Yes	Playwright	Jest + Playwright	No	No	No	Jest	No
Maintenance Mode	Yes	No	No	No	No	No	No	No	No	No
Affiliate Program	No	No	No	No	No	No	Yes	No	No	No
Mobile Support	No	No	No	No	No	No	No	No	React Native	No
Figma UI Kit	No	No	No	Yes	No	No	No	No	No	No
Unlimited Projects	Pro tier	Yes	Solo tier+	Pro tier	Yes	Yes	Yes	Yes	Unlimited tier	Yes
Community Size	Growing	8,000+	1,300+	Established	Growing	110+	330+	Small	Small	15.7K stars

Final Thoughts

The Next.js starter kit market has matured significantly. Every option on this list will save you time compared to starting from scratch. The difference comes down to how much time.

Kits like the Vercel SaaS Starter and LaunchFast give you a foundation and expect you to build. Kits like ShipFast and Shipped.club get you to MVP fast with the essentials. And kits like RapidLaunch, Supastarter, and Makerkit aim to give you a near-complete product from day one.

If I'm starting a new SaaS project today, my pick is RapidLaunch. The combination of a full CMS with drag-and-drop builder, AI-powered chat with lead capture, enterprise-grade analytics, and dual payment provider support (Stripe + LemonSqueezy) at $69-$119 one-time is the best value proposition in this space. You'd spend more than that in a single month on the standalone tools it replaces.

Get started with RapidLaunch and launch your SaaS in days, not months.

Backstage SaaS & Open Source Alternatives

Lucien Chemaly — Thu, 29 Jan 2026 07:26:39 +0000

Spotify's Backstage created the Internal Developer Portal category. It showed that a central hub for services, documentation, and tooling could actually improve how developers work. But here's what a lot of engineering leaders figure out the hard way: Backstage isn't right for every team.

If you're reading this, you've probably realized that adopting Backstage means committing serious engineering resources. You need a dedicated team, TypeScript expertise, and months of setup time. For a lot of teams, the operational overhead just isn't worth it.

But the problem Backstage solves doesn't go away. As your organization grows past about 150 people, you hit what's called the Dunbar Number Effect. Anthropologist Robin Dunbar found that humans can only maintain stable social networks of around 150 people. Go beyond that, and tribal knowledge disappears. Nobody knows who owns what. The informal Slack channels that worked when you were 30 people turn into complete chaos.

You need a system to fix this chaos, a "system of record" for your engineering organization. But you don't need the complexity of self-hosted Backstage to get there.

This guide covers the best Backstage alternatives in 2026. I'll break down three paths you can take, Build, Buy, or Hybrid, and help you figure out which one makes sense without drowning your platform team in maintenance work.

The Three Paths to an IDP: Build, Buy, or Hybrid

Before we look at specific tools, you need to understand the three approaches you can take:

Build (Self-Hosted Backstage): You take the open-source Backstage project and dedicate engineers to build, customize, and maintain your own portal. Ultimate flexibility, but significant headcount and operational costs.

Buy (Proprietary IDPs): You purchase a SaaS solution from a vendor like Cortex or Port. Quick to set up and feature-rich, but you're locked into their proprietary data model.

Hybrid (Managed Backstage): You use a service like Roadie that handles the hosting and maintenance of Backstage for you. You get the open-source ecosystem without the operational burden.

Backstage Alternatives: At a Glance

Here's a quick comparison of your options:

Tool	Core Technology	Hosting Model	Key Strength	Ideal For
Roadie	Backstage	SaaS (Managed)	Backstage ecosystem without the overhead	Teams who want Backstage's power but need a managed solution
Cortex	Proprietary	SaaS	Engineering metrics and scorecards	Organizations focused on measuring service quality
Port	Proprietary	SaaS	Developer-friendly API and flexibility	Teams building custom workflows
Atlassian Compass	Proprietary	SaaS	Deep Atlassian integration	Companies invested in the Atlassian stack
OpsLevel	Proprietary	SaaS	Service maturity and reliability checks	SRE teams enforcing production standards
Self-Hosted Backstage	Backstage (OSS)	Self-Hosted	Ultimate customization	Large orgs with dedicated platform teams (5+ engineers)

The Hybrid Approach: Managed Backstage

Roadie

Roadie isn't an alternative to Backstage, it's a different way to adopt it. The core idea is that you shouldn't have to choose between the power of an open-source community and the convenience of a SaaS product.

I've talked to a lot of teams who committed to self-hosting Backstage, only to realize it requires 3-12 engineers and 6-12 months to get production-ready. That's a significant investment. Roadie solves this by providing a secure, scalable, and fully managed Backstage experience out of the box.

Best for: Teams who've decided on Backstage but want to accelerate their timeline and reduce operational burden.

Key Features:

Get a production-ready Backstage instance running in minutes. Roadie handles upgrades, security, and maintenance.
Enterprise features like Role-Based Access Control, enterprise-grade search, and scorecards come built-in.
Install any open-source Backstage plugin without rebuilding your instance.

Considerations: Roadie uses Backstage as its foundation, so you get the same data model and core experience. If you want a completely different, highly opinionated UI, a proprietary vendor might fit better.

The "Buy" Approach: Proprietary IDPs

Cortex

Cortex has established itself as a leader in the IDP space. They focus heavily on service quality, reliability, and engineering metrics. Their Scorecards feature is particularly strong for defining standards and tracking adoption.

Best for: Organizations focused on establishing and measuring engineering standards.

Key Features: A central inventory for microservices and APIs, scorecards to track service health, and a scaffolder for creating new services from templates.

Considerations: Cortex is proprietary. You're locked into their data model, and migrating away later could be painful.

Port

Port is built around flexibility. Their developer-friendly API lets you ingest any data and build custom workflows. They position themselves as a platform for building a developer portal, not a rigid out-of-the-box solution.

Best for: Platform teams with strong dev skills who want to build highly custom experiences.

Key Features: A flexible "blueprint" model to define any asset, a self-service hub for custom actions, and scorecards for tracking quality.

Considerations: Port's flexibility is powerful but comes with a steeper learning curve. Expect more initial setup compared to more opinionated platforms.

Atlassian Compass

Atlassian Compass is Atlassian's entry into developer experience. Its main advantage is seamless integration with Jira, Confluence, and Bitbucket.

Best for: Companies already standardized on Atlassian tools.

Key Features: A component catalog for tracking ownership, health scorecards, and deep native integration with other Atlassian products.

Considerations: If you're not an Atlassian-centric organization, Compass may feel less compelling compared to other options.

OpsLevel

OpsLevel is a mature player focused on service ownership and reliability. SRE and platform teams like them because they help answer, "Is our software ready for production?"

Best for: SRE-driven organizations enforcing service maturity standards.

Key Features: A complete service catalog, an extensive library of automated maturity checks, and integrations with on-call tools like PagerDuty.

Considerations: OpsLevel's focus is more on reliability and standards than on developer self-service, which is stronger in other platforms.

The "Build" Approach: Self-Hosted Backstage

Choosing to self-host Backstage is a significant commitment. You should treat it like building an internal product, not just deploying a tool.

Best for: Large organizations with a well-funded platform team (5+ engineers) that has a clear mandate to build and maintain a customized developer portal.

Key Features: Complete control over the code and data model. You can customize it to your exact specifications.

Considerations: This path has a high cost of ownership. You need to account for the fully-loaded salaries of a dedicated engineering team, 6-12 months of initial build time, and ongoing operational burden for maintenance and upgrades.

How to Choose the Right Path

Your choice depends on your organization's priorities, resources, and philosophy. Here are the questions you should ask:

How important is the open-source ecosystem to us?

If you want to avoid vendor lock-in and tap into community innovation, choose between self-hosting Backstage or using a managed service like Roadie. If you prefer an all-in-one vendor experience, a proprietary option like Cortex or Port makes more sense.

What's the size and skill set of our platform team?

If you have 5-10 engineers with TypeScript experience and a mandate to build a custom portal, self-hosted Backstage is viable. If your platform team is smaller or focused on other priorities, Roadie or a proprietary vendor is more efficient.

What's our most critical problem right now?

If you need scorecards and don't mind vendor lock-in, tools like Cortex or OpsLevel offer polished solutions.

If you want to build custom workflows from scratch and are comfortable in a closed-source ecosystem, Port gives you a flexible API.

If your organization lives entirely in the Atlassian suite, Compass is a natural extension.

If you want enterprise features combined with the freedom of the open-source ecosystem, Roadie gives you both.

Final Thoughts

An Internal Developer Portal is a long-term investment in your developer experience. The choice between Build, Buy, and Hybrid depends entirely on your team's size, skills, and priorities.

I've seen teams succeed with all three approaches. The key is being honest about what you can realistically maintain and what problems you're actually trying to solve.

I'm curious what path you're evaluating. Are you leaning toward self-hosting Backstage? Considering a proprietary vendor? Looking at the hybrid approach with something like Roadie? What's the biggest factor driving your decision, team size, budget, or something else? Drop a comment and share what's working (or not working) in your evaluation process.

The "Glue Work" Trap: Why Your Best Engineer Looks Like Your Worst Performer

Lucien Chemaly — Wed, 28 Jan 2026 07:46:49 +0000

Your top engineer closed half the tickets the new grad did last quarter. The performance dashboard says they're underperforming. Your gut says the opposite.

I ran into this problem after moving from data engineering into management. One of my engineers spent three hours debugging why the nightly ETL job was timing out, which was blocking the entire team from running integration tests. They pair-programmed with our new hire to help them understand the data architecture. They wrote detailed documentation for the ETL migration because no one else would. They jumped into a Microsoft Teams thread at 9 PM to unblock a production deployment that couldn't wait until morning.

Then I pulled up the performance dashboard. They had closed half the tickets that our new grad closed that quarter.

The metrics said they were underperforming. My experience working with them said the opposite. They were the glue holding our team together.

This isn't a data engineering problem. It's an engineering management problem. Your best engineers spend their time on essential work that keeps the team functional, but none of it shows up in the systems that measure performance.

Why Your Metrics Are Lying to You

Jira and similar project management tools measure intent, not reality. They track what you planned to do, not what actually happened.

The problem compounds as engineers get more senior. Junior engineers can focus on tickets. Senior engineers spend most of their time on work that never gets a ticket: reviewing 40% of the team's PRs, helping others debug gnarly issues, fixing the CI pipeline that's been broken for weeks, sitting in architecture reviews to share context.

Creating a Jira ticket for "helped someone debug their environment setup" feels absurd. It took 20 minutes. But do that five times a week, and you've spent nearly two hours on invisible work. Multiply that across code reviews, production firefighting, mentoring conversations, and architectural guidance, and engineers can easily spend 50-70% of their time on work that has no corresponding ticket.

The result: visible output shrinks as actual value increases. The ticket dashboard shows your best engineer as underperforming while they're actually the team's MVP.

Tanya Reilly calls this "being glue", the technical leadership work that holds teams together but doesn't map cleanly to traditional promotion criteria.

Why Brag Documents Don't Work

The standard advice is to have engineers maintain brag documents. Julia Evans popularized this approach: engineers keep a running log of everything they do, then compile it for performance reviews.

This rarely works in practice.

It requires constant discipline. Engineers need to remember to update it after every contribution. Most forget until the week before their review, then try to reconstruct six months of work from memory.

It also feels self-aggrandizing. Engineers are trained to let their work speak for itself. Writing "I am great because I did X" feels uncomfortable, even when X is genuinely valuable.

And here's the real problem: without data backing it up, a brag document is just the engineer's word against the metrics. When you're under pressure to justify ratings, you'll default to the numbers.

Brag documents work for some people. But they put the burden on the wrong person. As a manager, you should have systems that capture your team's actual work, not force them to manually log it.

What the Data Actually Shows

Your engineers' work leaves digital traces everywhere. Every PR they review generates data in GitHub. Every commit they make has metadata. Every Teams conversation is timestamped. Every calendar event is logged.

This digital exhaust contains proof of the glue work. The challenge is assembling it into a coherent picture.

When an engineer reviews 127 PRs while their peers review 30, that's measurable. It explains why their ticket count is lower. They're multiplying everyone else's productivity.

Those 50-line PRs fixing type definitions, updating the Dockerfile, or adding error handling don't map to epics. But they're real work that keeps the system running.

When an engineer spends a week unblocking another team's API integration, that work might not even show up in your team's metrics. But it has real business impact.

The data exists. You just need to surface it.

How Tools Like Span Solve This Problem

I came across Span and I wish I'd known about them when I was dealing with the invisible work issue on my team.

The approach is different from traditional productivity tools. Instead of trying to make engineers track their work better, Span analyzes the actual work in your codebase and other systems. It looks at your code, PRs, Jira tickets, incident management tools, and calendars to understand what's really happening.

The platform uses AI to automatically categorize work into different types. That random Tuesday afternoon an engineer spends fixing the ETL timeout? Span classifies it as infrastructure work without them needing to create a ticket. The three hours spent reviewing PRs? That shows up in the data.

One feature that particularly addresses the glue work problem is called Investment Mix. According to one of their customers, Chad Bayer (VP of Technology at The Helper Bees), "Span's Investment Mix is the best on the market. It now powers our executive updates and board discussions, replacing what used to be a time-consuming manual process."

Investment Mix shows how engineering time is distributed across different categories of work. Instead of just counting tickets, you can see the actual breakdown between feature development, code reviews, infrastructure improvements, and maintenance work. That paints a completely different picture than "closed 8 tickets this quarter."

The platform also tracks metrics like PR cycle time and team velocity, helping you spot patterns in how work flows through your team. You can see if code reviews are a bottleneck or if infrastructure work is eating into feature development time.

The key thing is that it uses the actual work as the source of truth. It doesn't matter if an engineer created a ticket. If they made substantial changes to the infrastructure, that work gets classified and measured automatically.

How to Identify Glue Work in Your Team

You need to actively look for this. Your best engineers won't complain that their glue work is invisible. They're too busy doing the work.

Here are the patterns to watch for:

The Review Burden: Pull up your team's PR activity. If one engineer is reviewing 2-3x more PRs than everyone else, that's glue work. They're acting as a quality gate for the entire team.

The Unblocking Pattern: Watch for engineers who are constantly mentioned in other people's PRs or Teams/Slack threads. If someone's name keeps coming up when people need help, they're doing glue work.

The Infrastructure Tax: Some engineers volunteer to fix the annoying things that everyone complains about but no one wants to own. The flaky tests. The slow CI pipeline. The missing documentation. This work is nearly invisible but high-impact.

The Onboarding Load: If you have an engineer who every new hire gets paired with for their first few weeks, that's glue work. They're transferring institutional knowledge that doesn't exist anywhere else.

The Cross-Team Coordination: Watch for engineers who spend time in meetings with other teams or helping unblock dependencies. This work often doesn't even show up in your team's metrics, but it has real business impact.

How to Credit Glue Work in Performance Reviews

Once you identify the glue work, you need to explicitly credit it in performance reviews and compensation decisions.

Instead of apologizing for an engineer's ticket count, reframe the conversation around leverage and impact. Present the review with data, not gut feelings.

Show that they spent 35% of their time on developer enablement. Then show how that translated into team velocity improvements. If the team shipped 23% more features in the second half of the quarter compared to the first half, and the engineer's increased review load preceded that improvement, connect those dots.

Quantify specific contributions:

They reviewed 130 PRs that quarter, representing a significant portion of the team's total output. Their review feedback reduced the revision cycle time by an average of 8 hours per PR.
They spent 15% of their time on infrastructure improvements that cut the CI pipeline time from 45 minutes to 12 minutes, saving the team approximately 180 hours in aggregate wait time.
They pair-programmed with three junior engineers on complex features. All three shipped their work on schedule with minimal revision cycles.

The data doesn't just prove they were busy. It proves they were strategic about where they invested time.

When you present this to your director, the response will be immediate. The engineer gets promoted instead of getting a "meets expectations" rating.

How to Change Your Team's Incentives

Measuring glue work isn't enough. You need to actively reward it, or engineers will optimize for what gets measured.

Change how you run performance reviews. Explicitly evaluate engineers on three dimensions:

Individual Contribution: Traditional feature development and bug fixes. This is what Jira measures.

Team Multiplication: Code reviews, mentoring, infrastructure work, and knowledge sharing. This is what tools like Span measure.

Cross-Team Impact: Work that helps other teams or the company, even if it doesn't show up in your team's metrics.

Weight all three dimensions equally. An engineer who excels at team multiplication but has lower individual contribution numbers can still get an "exceeds expectations" rating.

Also change how you assign work. When planning sprints, explicitly allocate time for glue work. If an engineer is going to spend 30% of their time on code reviews, plan for them to close 30% fewer tickets. This prevents the trap where engineers get overloaded with both feature work and glue work, then get dinged for not completing enough tickets.

The Long-Term Impact

Six months after implementing these changes, the results are clear.

Team velocity increases by 30%+. Not because people work more hours, but because the glue work gets distributed more evenly. Junior engineers close more tickets because they get unblocked faster. Mid-level engineers contribute to code reviews and documentation. Senior engineers still do the most glue work, but they're not penalized for it.

Retention improves. Engineers who were considering leaving because they felt like their contributions weren't valued become your strongest advocates and refer excellent engineers to your team.

Hiring gets easier. When candidates ask how you evaluate performance, you can show them the actual data on how you measure and reward different types of contributions. Engineers who care about doing high-quality work are attracted to teams that recognize all forms of contribution, not just ticket velocity.

What You Should Do Tomorrow

Start by identifying who on your team is doing the most glue work. Pull up your GitHub data and look at PR review patterns. Talk to your junior engineers about who they go to when they're stuck.

Then look at how you're measuring performance. If you're only looking at ticket velocity, you're missing half the picture. Find ways to quantify the other half, whether that's through manual data gathering or tools like Span.

Finally, have explicit conversations with your team about glue work. Tell them you value it. Show them you're measuring it. Make it clear that doing glue work won't hurt their career trajectory.

Glue work is career-making if it's visible. It's career-ending if it stays invisible. As a manager, making it visible is your job, not your engineers'.

The engineers who succeed at senior levels aren't the ones who close the most tickets. They're the ones who multiply their team's effectiveness. Code review, mentoring, infrastructure work, and technical guidance are how they create that leverage.

But leverage without measurement looks like low productivity. You need systems that capture the full picture of contributions, not just the subset that maps cleanly to ticket boards.

If you have engineers spending time on glue work, make sure it's being captured and credited. They shouldn't have to choose between doing high-impact work and having a successful performance review.

How do you measure glue work on your team? I'd love to hear what's worked (or hasn't worked) for other engineering managers. Drop a comment below.

10 Proven Ways to Improve Developer Productivity (Without Burning Out Your Team)

Lucien Chemaly — Tue, 13 Jan 2026 14:49:12 +0000

Engineering leaders face relentless pressure to ship faster. The tempting response is to push harder, add hours, and demand more. But this approach fails. The 2025 DORA State of AI-Assisted Software Development report, surveying nearly 5,000 technology professionals, reveals that 90% now use AI tools at work, spending a median of two hours daily with them. Yet only 24% trust the output. More telling: extended crunch periods create an almost perfect correlation between overtime and defect rates.

The path to sustainable velocity isn't raw effort. It's removing friction, protecting focus, and building systems that let your engineers do their best work. Here are ten strategies backed by recent research that actually move the needle.

1. Protect focus time by clustering interruptions

The cost of context switching is staggering. Dr. Gloria Mark's research at UC Irvine established that workers need an average of 23 minutes and 15 seconds to fully refocus after an interruption. Her 2023 book Attention Span updated this to roughly 25 minutes and revealed something worse: the average time spent on any screen before switching has dropped to just 47 seconds.

For developers, the damage compounds. GitHub's Good Day Project found that developers have an 82% chance of having a good day with minimal interruptions, but only a 7% chance when interrupted frequently. Paul Graham captured this perfectly in his 2009 essay on the maker's schedule: "A single meeting can blow a whole afternoon, by breaking it into two pieces each too small to do anything hard in."

Action: Implement no-meeting days or cluster all meetings into specific blocks. A 2022 MIT Sloan study of 76 companies found that one meeting-free day per week increased productivity by 35%. Two meeting-free days pushed that to 71%. The optimal balance was three no-meeting days per week, protecting 60% of the work week for focused work.

2. Cut CI/CD wait times to eliminate forced context switches

When a build takes 20 minutes, developers switch to something else. Then they need another 25 minutes to regain context when the build completes. That single build just cost 45 minutes of cognitive overhead.

The 2025 DORA report shows that AI adoption increased throughput but also instability, with teams shipping faster but experiencing higher change failure rates when they lack robust control systems. The difference isn't just speed, it's that fast feedback loops let developers stay in flow.

Action: Invest in incremental builds, parallelized test suites, and intelligent test impact analysis. AI-driven test selection can reduce CI run times by 40-80% by running only tests affected by recent changes. Kent Beck's original 10-minute rule from Extreme Programming Explained: "Automatically build the whole system and run all of the tests in ten minutes. A build that takes longer than ten minutes will be used much less often, missing the opportunity for feedback." Every minute beyond that threshold increases the likelihood of costly context switches.

3. Treat internal documentation as a product

The 2024 Stack Overflow Developer Survey found that 61% of developers spend more than 30 minutes daily searching for answers, with 26% spending over an hour. That's one entire workday per week burned on hunting for answers that should be documented.

The impact on teams is severe. New hires take two to three months longer to become productive when documentation is poor. The 2024 Stack Overflow survey also found that while 70% of developers know where to find answers, only 56% can find them quickly, and 53% report that waiting on answers disrupts their workflow.

Action: Allocate dedicated time for documentation maintenance. Treat your internal wikis like a product with owners, roadmaps, and quality standards. Organizations with poor documentation waste hundreds of hours weekly for mid-sized engineering teams, equivalent to losing multiple full-time engineers to information hunting.

4. Deploy AI coding tools, but measure what matters

GitHub Copilot has crossed 20 million users, with 90% of Fortune 100 companies now using it. GitHub's controlled study showed developers completed tasks 55% faster with Copilot, and Duolingo's engineering team estimated 25% speed increases for engineers new to a codebase.

But the data isn't universally positive. A December 2025 CodeRabbit analysis of 470 open-source PRs found AI-generated code produces 1.7x more issues than human-written code, including 1.4x more critical bugs. The 2024 DORA report noted that while AI adoption increased documentation quality by 7.5% and code review speed by 3.1%, it was also associated with higher instability. Meanwhile, only about 33% of developers trust AI code accuracy according to the 2025 Stack Overflow survey, with 46% actively distrusting AI-generated code.

The real risk is "AI sprawl," where teams adopt multiple tools without understanding impact.

Action: Roll out AI assistants to reduce boilerplate and repetitive tasks, where they excel. But measure outcomes, not just adoption. Platforms like Span help leaders see if AI is reducing coding time or just increasing review time, allowing you to optimize the toolchain without guessing. Span's AI code detector can identify AI-generated code with 95% accuracy, giving you ground truth on adoption and impact. The goal is reduced toil, not just more code.

5. Standardize the inner development loop

"It works on my machine" remains one of the most expensive phrases in engineering. Each developer maintaining their own unique environment creates configuration drift, onboarding delays, and debugging nightmares.

Cloud development environments (CDEs) and dev containers eliminate this friction. Teams using mature internal developer platforms report significant reductions in cognitive load and faster onboarding. Spotify's platform engineering team found a 55% improvement in time-to-tenth-pull-request for new developers using standardized environments.

Action: Standardize development environments using containers, devcontainers, or cloud-based development tools. Define the inner loop (edit, build, test, debug) as a first-class product. When any developer can clone a repo and start contributing within hours instead of days, you've removed one of the most persistent friction points in engineering.

6. Set explicit code review SLAs

Code sitting in review is inventory on a shelf. It's not delivering value, it's accumulating merge conflicts, and the author has already context-switched away. Meta's engineering research found a correlation between time-in-review and engineer dissatisfaction.

High-performing teams treat review latency as a key metric. Google's engineering practices mandate responding to code reviews within one business day maximum.

Action: Establish team SLAs for review turnaround. A reasonable target: first review within four hours for internal team PRs, full cycle time under 24 hours. Keep PRs small (under 400 lines) for higher defect discovery rates. Research shows that reducing the time between acceptance and merge can improve code velocity by up to 63%.

7. Create on-call rotations to protect maker time

The "tap on the shoulder" through Slack is insidious. It feels harmless, but it fragments focus and distributes interruptions unpredictably across the team. Shadow work, the unplanned requests and ad-hoc support that never appears on a sprint board, silently drains capacity. When everyone is "available," no one is protected.

Action: Implement explicit on-call rotations where designated engineers handle interruptions while others focus. During on-call workdays, engineers do only on-call work with no feature development expected. If your on-call engineers regularly handle more than 2 incidents per 12-hour shift, Google SRE data suggests your system has reliability problems that need addressing - either through better automation, improved monitoring, or expanding the rotation. This protects the rest of the team's time while ensuring responsive support.

8. Build self-service infrastructure through platform engineering

Filing tickets for AWS access, waiting for DevOps to configure a database, or requesting permission to deploy are all symptoms of underdeveloped platform capabilities. Each handoff adds days of latency and forces developers into waiting mode.

Gartner predicts that by 2026, 80% of large software engineering organizations will have platform engineering teams, up from 45% in 2022. A 2024 survey of Kubernetes experts found 96% of organizations already have a platform engineering function, and the 2024 DORA report showed teams using internal developer platforms saw 10% increases in team performance.

Action: Build "golden paths" for common workflows: deploying a new service, provisioning a database, setting up monitoring. Spotify pioneered this approach, creating opinionated, well-documented pathways that reduce cognitive load while still allowing teams to deviate when needed.

9. Measure systems and processes, not individual output

Stack-ranking developers by commits or lines of code pushes them to game the numbers instead of doing good work, and it destroys psychological safety. The 2024 Stack Overflow survey found that only 20% of developers report being happy at work, with 62% citing technical debt as their top frustration. The DORA research team explicitly warns against using their metrics for individual evaluation—these metrics exist to identify systemic bottlenecks, not to rank people.

Action: Use metrics to debug your engineering system, not your engineers. Look for process flaws: calendar fragmentation, review bottlenecks, deployment friction, documentation gaps. Span's platform is valuable here because it highlights systemic issues, like calendars full of fragmented time, rather than simply counting lines of code. This preserves psychological safety while surfacing real obstacles.

10. Regularly survey developers and act on feedback

Happy developers write better code. The DORA Accelerate research found that high-performing teams are 2x as likely to exceed organizational performance goals. Google's 2022 research established that perceived code quality causally increases productivity. Yet most organizations never systematically ask their engineers what's getting in the way.

Productivity cannot be reduced to a single metric. You need satisfaction data alongside performance data. And you need to actually fix what developers say is broken.

Action: Run quarterly developer experience surveys. Ask what sucks. Then visibly address the top pain points. The investment pays compound returns.

Start with two changes this quarter

You don't need to implement all ten strategies at once. Pick two that address your team's biggest friction points. If your calendar is a disaster, start with meeting-free days. If code rots in review, set explicit SLAs. If developers waste hours searching for answers, invest in documentation.

The goal isn't maximum velocity for one sprint. It's sustainable pace that your team can maintain indefinitely. The 2025 DORA data is clear: AI functions as an amplifier, magnifying the strengths of high-performing teams and the dysfunctions of struggling ones. Teams that prioritize stability and developer well-being outperform those that sacrifice them for short-term speed. Build the system that lets your engineers do their best work, and the velocity will follow.

The 7 Best Developer Portals for Enterprise Teams in 2025

Lucien Chemaly — Thu, 08 Jan 2026 09:07:29 +0000

Your platform team spent a year and $2 million building an internal developer portal. Or maybe you bought one off the shelf. Either way, you're probably wondering if you made the right choice.

Here's what I've learned after working with dozens of companies implementing internal developer portals: the "build versus buy" decision isn't really the question anymore. The market has changed completely since 2020. Companies that went with self-hosted Backstage discovered that "free and open-source" actually means paying for 3-12 full-time engineers. Organizations that bought proprietary platforms found themselves locked into data models they can't escape. And the ones who picked wrong are now facing painful migrations.

I've spent the last few years talking to engineering leaders about their IDP implementations, and I've noticed the landscape has evolved into three distinct approaches:

Build: Self-hosted Backstage installations that give you maximum flexibility but cost over $1M per year to operate.

Buy: Proprietary SaaS platforms like Cortex and Port with polished interfaces but permanent vendor lock-in.

Hybrid: Managed Backstage solutions that give you the open-source ecosystem without the engineering overhead.

In this guide, I'll walk through the seven platforms that enterprise teams are actually using at scale. I'm focusing on the strategic trade-offs that matter three years after your initial decision, when you'll discover whether you made the right choice or not.

What Actually Matters in an Enterprise Developer Portal

Before I dive into specific platforms, let me share what I've learned matters most when evaluating IDPs. A lot of these platforms look great in demos but fall apart in production.

Ecosystem and Extensibility

Can you integrate with your entire toolchain, or are you stuck with whatever the vendor decides to support? At enterprise scale, you're probably using 50+ different tools across CI/CD, monitoring, security, and cloud infrastructure. The difference between supporting 20 integrations versus 250+ becomes critical when half your value comes from centralizing everything in one place.

Vendor Lock-In Risk

What happens to your data if you need to switch platforms in two years? Open-source-based solutions like Backstage use standardized YAML entity definitions you can export and migrate anywhere. Proprietary platforms often use custom data models that trap all your organizational knowledge inside their systems forever.

Maintenance Overhead

Does running the platform require a dedicated team, or can your existing platform engineers manage it alongside their other work? I've seen self-hosted solutions consume 3-5 full-time engineers just for maintenance, upgrades, and troubleshooting. This is what I call the "TypeScript tax," the hidden cost of maintaining frontend infrastructure that most DevOps teams aren't equipped to handle.

Enterprise Readiness

Does the platform provide role-based access control (RBAC), single sign-on (SSO), and SOC2 compliance out of the box? For regulated industries or companies with strict security requirements, these aren't nice-to-haves. They're table stakes. Building them yourself in a self-hosted environment can take months.

Day 2 Operations

Look beyond the initial setup. How difficult is it to upgrade when breaking changes occur? How do you handle search infrastructure at scale? What happens when you need to migrate to a new backend system? The platforms that look easiest on day one often become maintenance nightmares by day 700.

1. Roadie: Managed Backstage for Teams Who Value Their Time

Category: Hybrid (Managed Backstage)

Best For: Teams that want Backstage's ecosystem without the operational burden

Roadie delivers the full power of Spotify's open-source Backstage platform as a managed SaaS service. This is what I call the hybrid approach. You get access to the entire Backstage ecosystem with 211 open-source plugins, standardized data models, and active community development. But you don't need to maintain any of the infrastructure.

The platform handles everything you'd normally spend engineering time on: hosting, security patches, database management, enterprise-grade search, and those painful upgrades like the New Backend System migration that challenged self-hosted teams throughout 2024. Your team focuses on configuring integrations and building workflows, not debugging TypeScript or updating React components.

Key Features:

Minimal-maintenance Backstage platform with automated upgrades
Access to entire open-source plugin ecosystem (211 plugins, 82 supported out-of-the-box)
Built-in Tech Insights for scorecards and engineering standards (paid add-on)
Enterprise RBAC (basic RBAC in Teams plan, custom RBAC in Growth plan)
No vendor lock-in since the data model is standard Backstage YAML

What I Like:

The biggest advantage is what I call avoiding the TypeScript tax. Platform engineering teams can focus on building platform capabilities instead of maintaining TypeScript and React frontends. Any Backstage plugin works, including community-developed integrations. Complex upgrades like the New Backend System transition happen automatically. Most customers see value within weeks, not months. Your catalog definitions are portable YAML files, not proprietary formats.

The Trade-offs:

You're working within Backstage's UI constraints, which means less drag-and-drop flexibility compared to tools like Port. It's more structured, which some teams see as a feature and others see as a limitation. While Roadie offers secure connectivity options like the Roadie Broker for on-premises resources, it's primarily a hosted service. If your security team absolutely requires on-premises deployment, self-hosted Backstage might be your only option.

Pricing: Teams plan starts at $24 per developer per month with a 50-seat minimum (50-150 developers). Growth plan pricing is custom with a 100-seat minimum (100+ developers). Only active contributors to your source control management incur costs. Non-coding team members like product managers and leadership can access for free. Tech Insights is an optional paid add-on. View pricing details.

2. Cortex: When You're Obsessed with Scorecards

Category: Proprietary SaaS

Best For: Organizations focused on service maturity scorecards and reliability metrics

Cortex built a polished, opinionated developer portal that's heavily focused on measuring and improving service quality through scorecards. The platform excels at gamifying service ownership with detailed maturity models, SLO tracking, and automated scoring based on engineering best practices using Bronze/Silver/Gold levels.

The UI feels modern and intuitive, especially if your team is already familiar with SaaS tools like Datadog or PagerDuty. Cortex's scorecard system is more sophisticated than most alternatives, offering fine-grained control over scoring criteria with flexible rule definitions and excellent visualization of how your services stack up against engineering standards.

Key Features:

Advanced scorecard system with customizable rubrics using Bronze/Silver/Gold levels
Strong reliability engineering focus with SLOs, incidents, and on-call tracking
Polished, modern UI optimized for service discovery
AI-powered features including Ownership Prediction and Velocity Dashboard for DORA metrics
60+ out-of-the-box integrations with major monitoring and development tools

What I Like:

The scorecard sophistication is genuinely best-in-class. If you want to track service maturity with Bronze/Silver/Gold level visualization and detailed point-based scoring, nothing else comes close. The UI is beautiful and impresses stakeholders. The reliability focus is excellent for teams prioritizing SRE practices. You can get a basic catalog running quickly. New AI features for ownership prediction and metrics analysis are interesting additions.

The Trade-offs:

Cortex is known for being expensive at enterprise scale, especially compared to Backstage-based alternatives. The data model is Cortex-specific, making migration difficult if you ever want to leave. You're limited to whatever integrations Cortex builds. You can't leverage community plugins like you can with Backstage. The template and workflow capabilities lag behind Backstage's Software Templates.

Pricing: Not publicly disclosed. You need to sign up for a demo to get pricing information. However, the Forrester Total Economic Impact study from July 2024 lists pricing at approximately $65 per user per month at scale. Multiple tiers available (Engineering Intelligence, Accelerate, Full IDP, Site License) with features scaling from basic catalog and scorecards to full platform capabilities. Request pricing.

3. Port: The Builder's Platform

Category: Proprietary SaaS

Best For: Teams that need to model non-standard assets or want maximum UI customization

Port takes a completely different approach. Instead of giving you an opinionated developer portal, it gives you building blocks to create your own. The platform's no-code interface lets you define custom data models (called Blueprints) for any asset type, not just services and APIs, but environments, IoT devices, or cloud resources.

This flexibility makes Port uniquely suited for organizations with complex, non-standard infrastructure that doesn't fit typical service catalog patterns. You can build custom views, define relationships between any entity types, and create workflows that match your exact processes. Port recently rebranded as an "Agentic Internal Developer Portal" with enhanced AI capabilities.

Key Features:

Fully customizable data models and UI views via Blueprints
No-code interface for defining entities and relationships
Strong visualization capabilities for complex systems
Self-service actions using Cookiecutter templates
50+ integrations including DORA metrics tracking
AI agent capabilities and Engineering360 dashboard

What I Like:

Port gives you ultimate flexibility to model anything your organization needs, not just traditional services. You can build exactly the interface your teams need. It's excellent for multi-cloud, hybrid environments with diverse asset types. The visual workflow builder lets you create automation without writing code.

The Trade-offs:

Maximum flexibility means you're building everything from scratch. There's less out-of-the-box value compared to opinionated platforms. You can't leverage the Backstage open-source plugin ecosystem, though the Ocean Framework provides extensibility through data integrations and workflow automation. While Port supports Markdown, it lacks the full TechDocs build pipeline and search capabilities you get with Backstage. Teams need time to master the data modeling concepts, which means a steeper learning curve.

Pricing: Free tier available (up to 15 seats, 10,000 entities). Startup tier at $30 per developer per month. Enterprise tier available with premium features including SSO, advanced RBAC, ISO 27001 and SOC2 Type 2 certifications, and dedicated support. View pricing details.

4. OpsLevel: Fast Setup, Limited Growth

Category: Proprietary SaaS

Best For: Teams focused primarily on service ownership and maturity tracking

OpsLevel started as a service maturity and ownership tool before evolving into a broader developer portal. This shows in its excellent service ownership features and straightforward approach to tracking engineering standards through its Rubric system with Bronze/Silver/Gold levels, plus separate Scorecards for team-specific standards.

The platform offers the fastest time-to-initial-value for basic service cataloging. Typical deployments complete in 30-45 days. You can have a working catalog with ownership information and basic checks running within hours. But this simplicity comes at a cost. OpsLevel's feature set is more constrained than platforms built on extensible architectures. Recent additions include AI-powered features for check generation and catalog enrichment.

Key Features:

Fast setup for basic service catalog (typical 30-45 day deployment)
Strong focus on service ownership and maturity rubrics
Good integration with CI/CD systems for automated checks (60+ integrations)
AI-generated checks and AI-enriched catalog
Package version inventories for SBOM visibility
Clean, straightforward UI

What I Like:

You can get a basic catalog running faster than with any alternative. The service ownership focus is excellent for clarifying who owns what. Good built-in templates for measuring service quality. The interface is less complex than more feature-rich platforms, which some teams prefer. New AI features streamline catalog management.

The Trade-offs:

You can't easily add community plugins or build custom integrations. The UI is less flexible than Port or Backstage for customization. The feature set is primarily focused on cataloging and checks, with less emphasis on documentation or scaffolding. The migration path is unclear if you outgrow the platform since it uses a proprietary data model.

Pricing: Not publicly disclosed. Pricing is based on team size with custom quotes. Per-developer pricing model with volume discounts available. Includes SOC2 Type 2 compliance and SAML-based SSO. Pricing customizable based on needs including self-hosted options and support levels. Request pricing.

5. Atlassian Compass: The Jira Extension

Category: Proprietary SaaS

Best For: Organizations deeply invested in the Atlassian ecosystem

If your company runs on Jira, Bitbucket, and Confluence, Compass offers the most seamless native integration you'll find. The platform leverages Atlassian's identity system, pulls in data from other Atlassian products automatically, and feels like a natural extension of your existing toolchain.

Compass provides automated service health monitoring, tracking metrics from integrated tools and surfacing problems before they escalate. For teams already paying for Atlassian products, Compass represents an incremental cost with minimal integration effort. The platform has scorecards with a new Maturity Levels feature added in 2025.

Important Note: Atlassian deprecated the Templates and scaffolding feature on December 1, 2025. This is a significant capability reduction for teams requiring self-service service creation.

Key Features:

Native integration with Jira, Bitbucket, Confluence, and Opsgenie
Automated service health monitoring
Component tracking with Atlassian-native data models
Integrated incident management through Opsgenie
Scorecards with Maturity Levels feature
Built on Atlassian Forge with GraphQL APIs for extensibility

What I Like:

The Atlassian integration is unbeatable if you use Jira for everything. The UX feels consistent with other Atlassian products, so there's minimal learning curve. Automated health monitoring works well. You can get it as a standalone product or bundled with some enterprise packages.

The Trade-offs:

This is what I call the Atlassian trap. The platform struggles with non-Atlassian tools like GitHub, GitLab, or CircleCI. The scaffolding feature was removed on December 1, 2025, so it's no longer available for service creation. You can't extend it with community plugins since it uses a proprietary ecosystem. It's more of a service catalog with add-ons than a complete platform interface.

Pricing: Free tier available (3 full users, unlimited basic users). Standard tier at $8 per user per month includes basic features. Premium tier at $25 per user per month includes IP Allowlisting, advanced integrations, 99.9% uptime SLA, and premium support. Discounted rates available for teams above 101 users. Compass is a standalone product with separate billing from other Atlassian tools. View pricing details.

6. Backstage: The Industry Standard (Self-Hosted)

Category: Open Source (Self-Hosted)

Best For: Large enterprises with dedicated platform engineering teams and specific compliance requirements

Spotify's Backstage is the industry-standard open-source developer portal framework. It powers IDPs at Spotify, American Airlines, Pinterest, and thousands of other organizations. You own the code, control the infrastructure, and can customize anything.

But this flexibility comes with significant operational costs. Self-hosting Backstage requires 3-5 dedicated engineers to manage infrastructure, handle upgrades, maintain search systems, and keep up with the rapidly evolving codebase. Roadie's survey of the Backstage community found that successful self-hosted deployments had at least three engineers dedicated full-time. Some companies have teams of 12 people just for Backstage.

Breaking changes occur regularly with monthly releases. Major migrations like the New Backend System transition that completed in 2024 consumed months of engineering time for self-hosted teams. For perspective on the true cost, Zalando invested over $4 million across four years developing their internal platform before open-sourcing their work as part of Backstage.

Key Features:

Fully open-source with Apache 2.0 license
250+ community plugins covering every major tool
Extensible architecture for custom plugins and integrations
Active community and regular monthly releases
CNCF Incubating project with strong enterprise adoption

What I Like:

You have ultimate control and can customize without limits. There are no license costs since it's free to download and use. The ecosystem is massive with the largest community and plugin library (250+ plugins). You have no vendor dependency and can run it anywhere, modify anything. It's the industry standard backed by CNCF and major enterprises.

The Trade-offs:

The operational overhead is substantial. Successful deployments require 3-5 full-time engineers minimum. Some teams reach 12 full-time employees just maintaining Backstage. Most DevOps teams lack frontend skills for React and TypeScript customization, which is what I call the TypeScript tax. Monthly breaking changes and major migrations like the New Backend System require significant engineering investment.

You manage databases, search infrastructure with Elasticsearch, monitoring, and security patches. The hidden costs are enormous. At typical senior platform engineer compensation of $250K per year fully loaded, 3-5 engineers cost $750K to $1.25M annually, plus infrastructure costs of $12K to $24K per year. Total cost of ownership typically exceeds $2M+ over three years when you factor in engineering time, opportunity cost, and infrastructure.

Pricing: Free (open source under Apache 2.0 license). However, total cost of ownership includes 3-5 engineer salaries ($750K to $1.25M+ annually) plus infrastructure costs ($12K to $24K+ annually). TCO typically exceeds $2M+ over three years.

7. Configure8: The Discovery Platform

Category: Proprietary SaaS

Best For: Organizations prioritizing discovery and cost analytics

Configure8 positions itself as a universal catalog that can ingest and relate data from virtually any source. The platform emphasizes discovery features, helping teams understand what they have and how it's interconnected. It also offers strong cloud cost integration, surfacing spending data alongside technical resources.

While Configure8 has solid core features including 30+ integrations and workflow-based Self-Serve Actions, its smaller market presence and proprietary nature make it a riskier choice than platforms with larger ecosystems or open-source foundations.

Key Features:

Universal catalog supporting diverse asset types
Strong discovery and search capabilities
Cloud cost analytics integration
Relationship mapping across resources
Workflow-based Self-Serve Actions
Available as SaaS or on-premises deployment

What I Like:

It's good at helping teams understand what exists in their infrastructure. The cost integration is unique, combining cloud spending data with technical resources. It can pull data from many systems. You get deployment flexibility with both SaaS and on-premises options.

The Trade-offs:

The ecosystem is smaller with less community support and fewer integrations (30+) than larger platforms. The data model is Configure8-specific, which means proprietary lock-in. There are fewer public case studies and enterprise deployments than alternatives. As a smaller player in a competitive market, there's some uncertainty about long-term viability.

Pricing: Free tier available (up to 10 users for scorecards). Paid tiers available with SOC2 certification and RBAC features. Enterprise pricing available with additional features and volume discounts. Available as both SaaS and on-premises deployment. Contact Configure8 for detailed pricing. View pricing page.

Quick Comparison

Platform	Foundation	Maintenance	Ecosystem Size	Lock-In Risk	Enterprise Features
Roadie	Open Source (Backstage)	Minimal (Managed)	211 plugins	Low (standard YAML)	RBAC, SSO, SOC2 Day 1
Cortex	Proprietary	Minimal (SaaS)	60+ integrations	High (proprietary)	Strong
Port	Proprietary	Minimal (SaaS)	50+ integrations	High (proprietary)	Good
OpsLevel	Proprietary	Minimal (SaaS)	60+ integrations	High (proprietary)	Basic
Compass	Proprietary	Minimal (SaaS)	Atlassian-centric	High (proprietary)	Good (if Atlassian)
Backstage	Open Source	High (3-12 engineers)	250+ plugins	None	DIY
Configure8	Proprietary	Minimal (SaaS)	30+ integrations	High (proprietary)	Moderate

Making Your Choice

The right IDP depends on your organization's constraints, technical culture, and platform engineering maturity. Here's how I'd think about it:

Choose Self-Hosted Backstage if you have a team of 10+ platform engineers, unlimited budget, and specific requirements that absolutely can't be met by managed solutions. You're willing to invest significant engineering time in maintenance and customization for maximum control. Be prepared for 3-12 dedicated engineers and $2M+ total cost of ownership over three years.

Choose Cortex or Port if you value polished UI above everything else, don't mind proprietary lock-in, and want specific workflow capabilities their platforms emphasize. Budget for potentially higher costs at scale (around $65 per user per month for Cortex, around $30+ per user per month for Port enterprise tiers).

Choose OpsLevel if you need a basic service catalog immediately and your primary use case is tracking ownership and maturity, not building complex workflows or maintaining extensive documentation.

Choose Compass if you live entirely in the Atlassian ecosystem and can accept its limitations with non-Atlassian tools. Note that scaffolding and templates were deprecated on December 1, 2025. The integration efficiency may outweigh the platform's constraints if you're already deep in the Atlassian world.

Choose Roadie if you want the industry standard (Backstage) with its entire ecosystem and community support, but you value your engineers' time too much to spend it on infrastructure maintenance. It's what I consider the golden path for enterprises that want modern platform capabilities without the platform tax or the $2M+ cost of building from scratch.

The key question isn't which platform has the most features. It's which platform lets your engineers focus on building platform capabilities instead of maintaining platform infrastructure. At the 150+ engineer scale where IDPs become critical, that distinction determines whether your portal becomes a force multiplier or just another thing to maintain, potentially at a cost exceeding $2M over three years if you go the self-hosted route.

Final Thoughts

After evaluating these platforms for the past few years, I keep coming back to a simple principle: your platform team should build platform capabilities, not maintain platform infrastructure. The $2M+ you'd spend on self-hosting Backstage could fund a lot of actual platform work.

If you're serious about Backstage but want to skip the TypeScript tax, request a personalized demo of Roadie that'll show you what managed Backstage looks like in practice. Worth checking out before you commit to building everything yourself.