DEV Community: Sanjay Singh

How to Use a Custom Domain for Your ZyVOP Publication

Sanjay Singh — Wed, 21 Oct 2026 10:35:48 +0000

When engineers read technical content, the URL in the browser sends an immediate trust signal. An architectural deep-dive hosted on blog.yourbrand.dev/distributed-locks carries immediate credibility; the same article published on a shared platform path like platform.com/@user/12345 always feels like a guest post on rented land.

Yet connecting a custom domain to a modern publishing engine often turns into a minefield of edge cases:

DNS Protocol Limits: RFC 1034 prohibits standard CNAME records on root apex domains, creating routing headaches for writers who want clean root URLs.
Certificate Handshake Loops: Managing upstream TLS alongside third-party DNS proxies (like Cloudflare orange-cloud) frequently causes verification to stall or certificates to fail renewal.
SEO Cannibalization: Cross-posting to community feeds without strict edge-level canonical rewriting splits your domain authority, leaving external aggregators ranking above your primary site.
Link Rot on Plan Changes: Most hosted platforms abruptly disconnect custom domains the instant a subscription lapses, returning 404s and permanently damaging hard-earned backlinks.

ZyVOP was architected to eliminate these failure modes. On Founding Pro, you can attach your personal domain or company publication in minutes—complete with automated edge TLS, host-level 308 normalization, dynamic XML sitemaps, and built-in canonical protection.

This guide walks through the exact mechanics of ZyVOP's custom domain engine and provides step-by-step instructions to configure your DNS correctly on the first attempt.

1. System Architecture: Decoupled Identity & Edge Ingress

ZyVOP strictly decouples the human developer from the publication brand:

Developer Profile (zyvop.com/author/:username): Your personal identity on the ZyVOP developer network. Houses your personal bio, avatar, followers, comments, and global bylines.
Publication (blog.yourdomain.com or yourdomain.com): Your independent media asset. Features custom typography, dark/light brand logos, custom favicon, static pages (/about, /projects), Google AdSense (/ads.txt), and dedicated feeds.

The Dual-Engine Ingress Strategy

Custom Subdomains (blog.yourcompany.com, notes.dev): Powered by Cloudflare for SaaS Custom Hostnames. A simple CNAME record routes incoming HTTPS requests directly through ZyVOP's global CDN edge with automated TLS provisioning.
Root / Apex Domains (yourcompany.com): When apex routing is enabled, traffic resolves via dedicated A records and cryptographic proxy headers (x-zyvop-vercel-gateway-secret), or via an ALIAS/ANAME root flattening record.

2. Step-by-Step Configuration Guide

Connecting a custom domain to your ZyVOP publication takes four simple steps:

Step 1: Open the Publication Routing Hub

Navigate to your ZyVOP settings at /settings?tab=publication and select the Domain & Routing sub-tab.

/settings?tab=publication
  ├── [General]           Identity & Socials
  ├── [Appearance]        Logos, Favicon & Layout Engine (Magazine / Stacked / Grid)
  ├── [Domain & Routing]  Custom Domains, DNS Records & Canonical Mode  <-- SELECT
  ├── [Pages & Nav]       Static Pages (/about) & 301 Redirect Rules
  ├── [SEO & Export]      Decoupled OpenGraph Cards & Markdown ZIP Export
  └── [Monetization]      AdSense Publisher ID & ads.txt

If you are on the Founding Pro tier, the domain management card will be unlocked and ready for input.

Step 2: Enter Your Domain

In the Custom domain input, enter the address you want to connect:

Recommended Subdomain: blog.yourname.com or dev.yourcompany.com
WWW Subdomain: www.yourbrand.com

Note: System domains ending in zyvop.com or zyvop.dev are managed internally and cannot be entered.

Step 3: Configure Your DNS Provider

Once you submit your hostname, ZyVOP calculates the exact DNS requirements for your provider (Cloudflare, Namecheap, AWS Route 53, Porkbun, or Google Cloud DNS).

Standard Subdomain Record (CNAME):

Type	Name / Host	Target / Value	TTL	Proxy Status
CNAME	blog (or full blog.domain.com)	cname.zyvop.com	Auto (or 300)	DNS-Only (Grey Cloud)

Crucial Cloudflare Rule: If your DNS is managed on Cloudflare, set the CNAME record to DNS-Only (Grey Cloud). Enabling the orange cloud during provisioning intercepts the HTTP/TLS ownership challenge, causing certificate validation to hang in VERIFYING.

Root / Apex Domain (When Direct Apex is Enabled):

If configuring a root domain (acme.dev), ZyVOP displays an A record pointing to the designated edge IP, plus an ownership TXT record (e.g. _zyvop-challenge.acme.dev). If direct apex is disabled on your cluster, configure www.acme.dev via CNAME and set a 301 forward rule from acme.dev to www.acme.dev at your registrar.

Step 4: Verify and Activate

Click Check DNS & SSL. ZyVOP verifies your CNAME target in real-time, confirms CA issuance, and sets your domain status to Verified (ACTIVE).

3. Edge Routing and First-Class Protocols

Once your domain is ACTIVE, ZyVOP's edge proxy automatically serves your entire publication ecosystem directly from your branded URL:

Dynamic Technical SEO (/sitemap.xml): Automatically generates an index of all published articles and static pages with correct <loc>, <lastmod>, and <changefreq> tags.
Crawler Directives (/robots.txt): Emits publication-scoped directives linking to your custom domain's sitemap and honoring your AI Crawler opt-in/opt-out settings.
Syndication Feeds (/rss.xml): Serves a full RSS 2.0 feed with complete syntax-highlighted code enclosures and publication branding, ready for Feedly, Inoreader, and newsletter parsers.
Instant Indexing (/<indexnow-key>.txt): Serves your unique IndexNow protocol key, notifying Bing, Yandex, and other search engines immediately when you publish a new article.
Brand Favicon (/favicon.ico): Dynamically redirects to your uploaded 32x32 publication favicon (or gracefully falls back to your profile avatar).
Monetization (/ads.txt): Outputs validated Google AdSense publisher declarations if monetization is enabled in your settings.

4. Canonical SEO: Mode A vs. Mode B

Developers often worry about splitting search authority when moving to a custom domain. ZyVOP solves this through an automated, centralized canonical resolution engine (resolveCanonicalUrl):

Mode A: Full 301 Permanent Migration

How it works: Any request to zyvop.com/@user/slug is immediately redirected via HTTP 301 to https://blog.yourdomain.com/slug.
When to use: When you want all past and future traffic to land exclusively on your independent website. Search engines transfer 100% of accumulated link equity to your new domain.

Mode B: Network-Integrated (Discovery + Canonical Ownership)

How it works: Your post remains readable on the ZyVOP community feed, trending tabs, and topic collections. However, the HTML source contains:
```
<link rel="canonical" href="https://blog.yourdomain.com/slug" />
```
When to use: When you want the viral reach, comments, and developer discovery of the ZyVOP network, while Google attributes 100% of the SEO search ranking to your personal custom domain.

5. Multi-Domain Support & Host Normalization

ZyVOP allows you to register secondary custom domains (e.g., holding both www.acme.dev and blog.acme.dev).

When multiple domains are connected:

One domain is marked Primary in the UI.
If a reader or bot arrives on a non-primary active domain, ZyVOP's edge proxy issues an immediate HTTP 308 Permanent Redirect to the primary host, strictly preserving the original pathname and query parameters:
```
Request:  http://www.acme.dev/system-design?ref=hackernews
Response: 308 Permanent Redirect -> https://blog.acme.dev/system-design?ref=hackernews
```

This prevents duplicate-content penalties across your brand aliases.

6. The Downgrade Grace Period: Zero Broken Backlinks

Most developer platforms ruthlessly disable custom domains the exact hour a subscription expires, instantly breaking inbound links, dropping search ranks, and serving generic 404 or certificate error pages.

ZyVOP protects your SEO through an automated Downgrade Grace Period (downgradeGraceEndsAt):

During Grace: Your custom domain and canonical headers remain active. No traffic is dropped while you resolve billing or plan transitions.
Post-Grace (REDIRECTING): If not renewed, the domain transitions to a managed redirect state, routing visitors and search spiders cleanly back to your verified author profile (zyvop.com/author/:username) via HTTP 308 instead of failing abruptly.
Instant Restoration: Reactivating Pro restores custom domain routing immediately without having to re-provision DNS records.

7. Custom Domain Pre-Flight Checklist

Before publicizing your new publication, run this quick pre-flight verification:

DNS CNAME Added: Host points to cname.zyvop.com and is marked DNS-Only (not proxied by intermediate CDNs).
Status Verified: Status in /settings?tab=publication displays a green Verified badge.
Primary Domain Set: Marked as Primary if multiple hostnames are connected.
Favicon & Logo Uploaded: Appearance tab configured with light/dark SVGs and a crisp favicon.
Technical Feeds Accessible:
- https://yourdomain.com/sitemap.xml returns valid XML.
- https://yourdomain.com/robots.txt points to your sitemap.
- https://yourdomain.com/rss.xml parses cleanly in your feed reader.
Canonical Verified: Inspect page source on an article to confirm <link rel="canonical"> points to your custom domain.

Conclusion: Build on Land You Own

Your custom domain is the single permanent digital asset in your engineering career. Publishing platforms, social networks, and algorithms inevitably change, but incoming backlinks, search engine rank, and reader bookmarks anchored to your personal domain remain yours forever.

With ZyVOP, you don't have to choose between managing fragile self-hosted infrastructure and being trapped in a closed blogging network. You get the discovery of a global developer feed with the complete authority and independence of your own custom domain.

Head to ZyVOP Publication Settings, add your DNS record, and connect your custom domain today.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Publish from Git to ZyVOP with GitHub Actions

Sanjay Singh — Mon, 19 Oct 2026 06:12:45 +0000

You can keep every ZyVOP article as a Markdown file in Git and let GitHub Actions publish it when you merge to main. No copy-pasting, and every change goes through a pull request.

Why publish from Git

Treating posts like code gives you things a web editor can't:

Review and history. Edits go through pull requests, and git log becomes your editorial history.
One source of truth. The Markdown file is the article. ZyVOP can cross-post it to Dev.to, Hashnode, Medium, WordPress and Bluesky, with canonical URLs handled for you.
Safe re-runs. Give each post a stable slug, zyvop_id or canonical_url, and later pushes update the existing article instead of creating another one.

What you need

A ZyVOP account, with any destinations you want (Dev.to, Hashnode and so on) connected in your settings.
A developer token. Generate one in ZyVOP under Settings → Integrations; tokens start with zv_.
A GitHub repository with a posts/ folder.

Step 1: Add a post with frontmatter

Each post is a Markdown file with YAML frontmatter at the top. A simple repository layout looks like this:

my-blog/
├── .github/
│   └── workflows/
│       └── publish.yml
└── posts/
    └── nodejs-logging-pino-vs-winston.md

And the post itself:

---
title: "The Best Logging Library for Node.js in 2026"
slug: nodejs-logging-pino-vs-winston
subtitle: "How to choose between Pino, Winston and the rest"
excerpt: A practical comparison of Node.js logging libraries, with code samples.
tags: [nodejs, logging, pino, winston, backend]
category: backend
draft: true
cross_post:
  devto: true
  hashnode: true
  medium: false
---

Write the article here in plain Markdown, with code blocks, tables and diagrams.

Two defaults matter. A post is published unless you say otherwise, and cross-posting is switched on for every connected platform. That is why the example starts with draft: true. The slug matters just as much: it is how a later push finds the post it should update.

These are the frontmatter fields you will use most:

Field	What it does
title	Headline (required, 3 to 200 characters)
slug, zyvop_id	Stable identifiers that let later pushes update this post instead of creating another
subtitle	Short line shown under the title
excerpt	Card preview and search snippet
tags	Topic tags, as a list or a comma-separated string
category	Category slug, such as backend, frontend, devops or ai
cover_image	Cover image URL or relative path
canonical_url	Original source URL, if the post lives elsewhere first; also identifies the post on later publishes
cross_post	Per-platform flags: devto, hashnode, medium, bluesky, wordpress
draft, status, scheduled_at	Save as a draft, or set DRAFT, PUBLISHED or SCHEDULED with an ISO 8601 date

Extra keys such as layout or featured are preserved and ignored by ZyVOP, so the same files can also feed a static site built with Astro or Next.js.

Step 2: Store your token as a secret

In your GitHub repository, open Settings → Secrets and variables → Actions and create a repository secret named ZYVOP_TOKEN with your developer token as the value. Never commit the token itself.

Step 3: Add the workflow

The simplest option is ZyVOP's own action. Save this as .github/workflows/publish.yml:

name: Publish with ZyVOP

on:
  push:
    branches: [main]
    paths:
      - "posts/**/*.md"
  workflow_dispatch:

permissions:
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: zyvop/publish-action@v1
        env:
          ZYVOP_TOKEN: ${{ secrets.ZYVOP_TOKEN }}

The action publishes only the Markdown files changed by a push. Checkout uses fetch-depth: 0 so the base commit is available; when it isn't, or on a manual run (workflow_dispatch) or a branch's first push, the action processes every post. It reads your token from the ZYVOP_TOKEN secret, and once you merge a change to main the run shows up under your repository's Actions tab.

Alternative: call the CLI yourself

If you want to own the changed-file logic, run the zyvop CLI yourself. It needs Node.js 20 or newer. This version, adapted from ZyVOP's CLI documentation, publishes only the files changed since the previous push, and falls back to all posts on a branch's first push or a force push:

name: Publish with ZyVOP CLI

on:
  push:
    branches: [main]
    paths:
      - "posts/**.md"

permissions:
  contents: read

# Do not let rapid pushes publish the same article concurrently.
concurrency:
  group: zyvop-publish-${{ github.ref }}
  cancel-in-progress: false

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Detect changed posts and publish
        env:
          ZYVOP_TOKEN: ${{ secrets.ZYVOP_TOKEN }}
        run: |
          set -euo pipefail

          before="${{ github.event.before }}"
          after="${{ github.sha }}"

          # A branch's first push has an all-zero before SHA. A force push can
          # also reference an unavailable commit, so publish all tracked posts.
          if [[ "$before" =~ ^0+$ ]] || ! git cat-file -e "$before^{commit}" 2>/dev/null; then
            mapfile -d '' files < <(git ls-files -z -- ':(glob)posts/**/*.md')
          else
            mapfile -d '' files < <(
              git diff --name-only -z --diff-filter=ACMR \
                "$before" "$after" -- ':(glob)posts/**/*.md'
            )
          fi

          if (( ${#files[@]} == 0 )); then
            echo "No Markdown files changed."
            exit 0
          fi

          for file in "${files[@]}"; do
            if [ -f "$file" ]; then
              echo "Deploying $file..."
              npx --yes zyvop@1.1.1 publish "$file"
            fi
          done

Two notes. The workflow only publishes added or modified files, so deleting a post from Git doesn't remove it from ZyVOP. And if you would rather keep your Dev.to, Hashnode, Medium, WordPress or Bluesky credentials in GitHub secrets than in ZyVOP, the CLI has a --local mode that publishes to those providers directly from the runner. Its documentation warns that Medium's API can't update a published story, so repeated local publishes to Medium can create another one.

Step 4: Check posts on pull requests

The CLI's --dry-run flag validates a post and previews the exact payload without authentication or publishing, which makes it a cheap check for every pull request. It runs locally, so it can't tell you whether a real publish would create or update the post.

name: Check posts

on:
  pull_request:
    paths:
      - 'posts/**'

permissions:
  contents: read

jobs:
  dry-run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Validate every post
        run: |
          set -euo pipefail
          mapfile -d '' files < <(git ls-files -z -- ':(glob)posts/**/*.md')
          for file in "${files[@]}"; do
            echo "Checking $file"
            npx --yes zyvop@1.1.1 publish "$file" --dry-run
          done

Habits that keep it safe

Start every post as a draft. Keep draft: true until the pull request that should make it live, and flip it in that PR. A first push or a manual run processes every post, so mark any back catalogue as drafts too.
Give every post a stable identity. Set a slug, zyvop_id or canonical_url once and keep it stable, so later pushes update the same article.
Schedule instead of racing. Set status: SCHEDULED and a scheduled_at timestamp to release a post later.
Mind the rate limit. ZyVOP documents 10 requests per minute per token on its REST API, so when you move a large back catalogue, publish it in small batches.
Pin the CLI version. ZyVOP's own examples pin it (zyvop@1.1.1 at the time of writing), so a new release can't change your pipeline unannounced.
Protect the token. Keep it in GitHub secrets only. If it ever leaks, revoke it in ZyVOP and create a new one.
Set base_url for relative images. ZyVOP resolves relative cover and body image paths against it, or against canonical_url.

Troubleshooting

The workflow doesn't run. Check that the branch is main and that the changed files match the paths filter.
Every post is republished on each run. Check that checkout uses fetch-depth: 0. When the base commit isn't available, the action processes all tracked posts.
A post was created twice. Add a stable slug, zyvop_id or canonical_url so ZyVOP can match the file to the existing article.
Authentication fails. Confirm the secret is named ZYVOP_TOKEN and that the token hasn't been revoked.
A platform didn't get the post. Connect that destination in ZyVOP and check the cross_post flags, because ZyVOP only syndicates to connected platforms.

Wrap-up

With one folder, one secret and one workflow file, publishing becomes a side effect of merging. Start with a draft, run the dry-run check on pull requests, and set draft to false only when the post is ready.

Docker vs PM2: Which One Does Your Node App Actually Need?

Sanjay Singh — Sun, 18 Oct 2026 07:01:20 +0000

Every few months someone asks the same question: should I use Docker or PM2 to run my Node app? It sounds like a fair comparison, but it's a bit like asking whether you need a toolbox or a screwdriver. They overlap in a few places, and that overlap is exactly why people get confused.

The way I make sense of it is to split the job into three layers:

Supervision: keep the process alive, restart it when it dies, use every core.
Packaging: make the environment reproducible and keep the app isolated from everything else on the machine.
Orchestration: run copies across several machines, roll out new versions safely, replace machines that die.

PM2 lives in layer one. Docker lives in layer two and borrows a little of layer one through its restart policy. Layer three is where Kubernetes, Swarm and managed container platforms live. Most of the confusion comes from tools reaching into each other's layer.

What PM2 does

PM2 is a process manager for Node.js. You install it with npm, hand it your app, and it keeps that app running.

npm install -g pm2
pm2 start server.js --name api -i max
pm2 startup   # prints a command; run it once (with sudo) to enable start on boot
pm2 save

Those commands get you a lot. Your app restarts if it crashes, it runs one worker per CPU core, and it comes back after a server reboot. You also get logs and a live dashboard with pm2 logs and pm2 monit. When you deploy new code, pm2 reload api restarts workers one at a time, so users don't see downtime as long as your app shuts down cleanly. That only works in cluster mode, which is what -i max turns on.

In practice you'll want this in a config file that lives in your repo, so the setup is versioned along with your code:

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'api',
    script: './server.js',
    instances: 'max',
    exec_mode: 'cluster',
    max_memory_restart: '400M',
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000,
    },
  }],
};

Start it with pm2 start ecosystem.config.js --env production. If your package.json sets "type": "module", name the file ecosystem.config.cjs instead.

For a single server and a single app, that's a very pleasant experience. No new concepts, no extra layer. It's just Node, supervised.

The catch is that PM2 only manages processes. It has no opinion about the machine they run on. Your server needs the right Node version, the right system libraries, the right environment variables. If staging has Node 22 and production has Node 24, PM2 will happily run your app on both and let you find out the hard way.

What Docker does

Docker solves a different problem: it packages your app together with everything it needs to run. The Node version, the OS libraries, your dependencies, your build output, all baked into an image. That image runs the same on your laptop, in CI, and on a production server.

FROM node:24-alpine
ENV NODE_ENV=production
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
EXPOSE 3000
CMD ["node", "server.js"]

docker run -d --restart unless-stopped -p 3000:3000 myapp

Two notes on that Dockerfile. Add a .dockerignore that lists node_modules and .git, otherwise COPY . . copies your local node_modules into the image on top of the clean install. And it assumes a plain JavaScript app; with TypeScript you'd add a build stage.

You also get isolation (your app can't trample other things on the box), resource limits, health checks, and a clean way to run a database or Redis next to your app with Docker Compose.

The price is a learning curve. Images, layers, volumes, networks, registries: there's a whole vocabulary to pick up, and debugging inside a container feels different from debugging on a plain server. Builds also add a step to your workflow.

Where they overlap

Both can restart a crashed app, start it on boot, collect logs, and react to runaway memory use. That's the core of the overlap, and it's why people treat them as substitutes. Here's the rest side by side:

	PM2	Docker
Main job	Supervise Node processes	Package and isolate an app and its environment
Environment consistency	No, depends on the host	Yes, the image is the environment
Multi-core usage	Built in (cluster mode)	Run several containers, or use cluster in the app
Zero-downtime deploys	pm2 reload	Needs a reverse proxy or orchestrator
Non-Node apps	Possible, but not its focus	Yes, anything
Learning curve	Gentle	Steeper
Scaling past one server	Not its job	Natural fit with Swarm, Kubernetes, managed container platforms

The cluster mode question

This is where PM2 feels a bit magical. Node runs your code on a single thread, so on an 8-core machine you're using one core unless you do something about it. pm2 start -i max forks a worker per core and load-balances between them. Done.

Docker has no equivalent built in. The usual approach is to run several containers behind a reverse proxy like Nginx, or let an orchestrator manage the replicas. In Kubernetes the convention is one process per container, and you scale by adding more of them. It's more moving parts, but it keeps working when you outgrow a single machine, which PM2 can't do.

Here's the Docker version of the same idea with Compose: two replicas of the app behind Nginx.

# docker-compose.yml
services:
  api:
    build: .
    restart: unless-stopped
    environment:
      NODE_ENV: production
    deploy:
      replicas: 2
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - api

The api service publishes no ports, so the replicas don't fight over one. Nginx reaches them by service name, using a small nginx.conf:

server {
  listen 80;
  location / {
    proxy_pass http://api:3000;
  }
}

The health check assumes your app has a /health route. One gotcha: Nginx looks up the name api when it starts, so reload it after you recreate the containers.

Deployments and zero downtime

With PM2, a deploy is: pull the code, install, pm2 reload. With Docker, it's: build an image, push it, pull it on the server, start the new container, switch traffic, stop the old one. By hand on one server, that means a few seconds of downtime. Doing it properly takes a rolling update from an orchestrator, or a proxy that can shift traffic between old and new, which is more work upfront.

When things go wrong

The feature lists look similar until something breaks. Here's what each tool does in the situations that actually page people at night:

Situation	PM2	Docker
App crashes	Restarts it. After too many quick crashes in a row, it gives up and marks the app errored.	Restarts it per the restart policy, waiting longer after each quick failure.
App hangs but doesn't exit	Doesn't notice.	A health check marks the container unhealthy, but plain Docker and Compose won't restart it. An orchestrator will.
Memory leak	max_memory_restart restarts the process once it passes the limit.	A memory limit, if you set one, kills the container when it's exceeded, and the restart policy brings it back.
Server reboots	Comes back if you ran pm2 startup and pm2 save.	Comes back through the restart policy (unless-stopped or always), as long as the Docker daemon starts on boot.
Bad deploy	Redeploy the old code and reload.	Start the previous image tag.
The machine dies	Your app is gone.	Your app is gone, unless an orchestrator moves it to another machine.

The hung-app row surprises people: a health check only reports status, so something else has to act on it.

Shutdown is your job

Both tools stop your app with a signal, and your code has to listen for it. docker stop sends SIGTERM and waits 10 seconds by default before killing the container. PM2 sends SIGINT and waits only 1.6 seconds by default, which you can change with kill_timeout. An app that ignores the signal drops whatever requests are in flight.

const server = app.listen(3000);

function shutdown() {
  // stop accepting new connections and let in-flight requests finish
  server.close(() => process.exit(0));
  // give up if that takes too long
  setTimeout(() => process.exit(1), 8000).unref();
}

process.on('SIGTERM', shutdown); // Docker
process.on('SIGINT', shutdown);  // PM2, and Ctrl+C

If you use PM2, set kill_timeout above that 8 seconds, or PM2 will kill the app first. In Docker, you may also want an init process (docker run --init, or init: true in Compose) so signals are forwarded properly and stray child processes get cleaned up.

Logs and monitoring

PM2 writes each app's output to files under ~/.pm2/logs, split into stdout and error logs. pm2 logs tails them, pm2 monit shows CPU and memory per process, and pm2 install pm2-logrotate keeps the files from eating your disk.

Docker flips the convention: your app writes to stdout and stderr, and Docker captures it. docker logs -f follows it, and a logging driver or plugin can ship it somewhere central like CloudWatch or Loki, so your logs stop living on one server's disk. One catch: the default log driver keeps growing its files unless you set max-size and max-file.

I use Dozzle for this. It's a small web UI that tails every container's logs live, and it only works because everything writes to stdout.

Using them together

You can run PM2 inside a container with pm2-runtime, which exists for exactly that:

CMD ["pm2-runtime", "start", "ecosystem.config.js", "--env", "production"]

It's a reasonable move if you want cluster mode on a single host and you like PM2's config file (you'll need to install pm2 in the image, since the base Node image doesn't ship with it). But it's often redundant. Docker's restart policy already handles crashes, and an orchestrator already handles scaling. Put PM2 on top and you have two things deciding when to restart your app, which gets confusing fast.

If you do combine them, set instances to a fixed number rather than 'max'. Inside a container, 'max' can count the host's cores instead of the CPU limit you gave the container.

So which one should you pick?

Here's how I'd decide.

Pick PM2 if you have one or two apps on a single VPS, you control the server, your team is small, and you want to ship today without learning a new toolchain. It's simple and it works, and there's no shame in that.

Pick Docker if you run more than one service, need a database or cache alongside your app, deploy through CI/CD, or work on a team where “it works on my machine” has come up. It's also the safer bet if you expect to move to a cloud platform or Kubernetes at some point, since plenty of hosting platforms expect a container anyway.

Use both if you want PM2's cluster mode and config inside a container on a single host. Just be sure you actually need it.

I run my own Node apps in Docker, and it's what I'd reach for by default on a new project. My setup is more than the app: a Postgres database, Dozzle for reading logs, Cloudflare Tunnels, and my background workers all run in Docker too. A worker is just another container, often the same image started with a different command. PM2 only manages the Node processes, so all of that would have lived outside it. The container has become the standard unit of deployment across the ecosystem, and the habit transfers everywhere. That said, if PM2 is already running your app happily and nothing is hurting, don't rip it out for the sake of it.

So it comes down to what you're missing. If you just need a Node process kept alive, PM2 has you covered. If you need your app to behave the same on every machine it touches, that's what Docker is for.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Zero-Friction Migration: How to Import Your Existing Developer Blog into ZyVOP

Sanjay Singh — Sun, 18 Oct 2026 05:28:49 +0000

Technical writing is one of the highest-leverage assets in software engineering. Over time, however, developer portfolios become fragmented: early articles on DEV, corporate posts on Medium, a custom domain on Hashnode, or Markdown files in static site generators like Hugo, Astro, or Ghost.

Switching platforms often leads to broken syntax highlighting, mangled math formulas, orphan image references, duplicate cover photos, and canonical SEO dilution.

ZyVOP was built as a sovereign developer publishing engine: write once, maintain canonical ownership, and distribute across ecosystems. But migrations are never one-size-fits-all.

This guide provides an honest, technical look at how ZyVOP's import engine works, what is natively supported versus partially adapted, and how to migrate your catalog cleanly.

1. Migration Support Matrix

Not every platform exposes identical APIs or export formats. ZyVOP supports migrations through four distinct ingestion pipelines:

Source	Migration Pathway	Level of Support	Key Technical Nuances
DEV.to	Native REST API	First-Class	Pulls published articles, markdown body, tags, canonical URLs, and original dates.
Hashnode	GraphQL API / Backup JSON	First-Class	Supports custom publication domains, backup JSON files, and RSS fallback.
Medium	Public RSS / Single URL	Partial	Ingests via public user feed; image re-hosting is disabled by default to avoid rate limits.
Ghost	Generic RSS / Single URL	Partial	Full text via RSS content:encoded. Native Ghost JSON archives are not yet parsed.
Substack	Generic RSS / Single URL	Partial	Imports published posts via RSS. Subscriber lists and paid tiers are not imported.
Hugo / Jekyll	Markdown ZIP Archive	Partial	Ingests .md and .markdown files with relative image re-hosting. Shortcodes require flattening.
Astro / Next.js	Markdown ZIP Archive	Partial	Supports standard Markdown. .mdx files and JSX/Astro components are ignored.

2. Ingestion Pipelines: How It Works Under the Hood

A. Direct APIs (DEV & Hashnode)

DEV.to: Connects via username or API key. Extracts raw Markdown directly, preserving original syntax fences, tags, and canonical links.
Hashnode: Queries Hashnode's GraphQL endpoint across either personal subdomains (user.hashnode.dev) or custom publication apex domains. Also accepts native Hashnode JSON export backups (readHashnodeJson).

B. Universal RSS / Atom (Ghost, Substack, Medium)

Parses standard RSS 2.0, Atom, and content:encoded payloads.
Image Re-hosting Nuance: For bulk RSS imports, image re-hosting is disabled by default (migrateImages = false) to prevent timeout failures and remote CDN rate-limiting across large archives. Remote image URLs are preserved as absolute URLs.

C. Direct Web Article Extractor

For standalone articles, ZyVOP executes an outbound fetch with Mozilla Readability, stripping boilerplate noise (.cookie-banner, .advertisement, .newsletter-signup, nav, footer).
Perceptual Image Deduplication (Sharp): Many CMSs duplicate the social og:image as the first image in the post body. The single-URL extractor creates a 32×32 sRGB luminance fingerprint of the cover image and compares it against body images:

// Bounded sRGB luminance and chromatic mean comparison in article-import-images.ts
async function createImageFingerprint(data: Buffer): Promise<ImageFingerprint> {
  const pixels = await sharp(data, { limitInputPixels: 40_000_000 })
    .resize(32, 32, { fit: 'fill' })
    .toColourspace('srgb')
    .removeAlpha()
    .raw()
    .toBuffer();
  // Evaluates luminance array and chromatic delta to strip duplicate hero images
}

D. Static-Site Markdown Archives (ZIP)

When migrating from static site generators like Hugo, Astro, Jekyll, or Obsidian:

Supported Formats: The reader accepts .md and .markdown files. Files with .mdx extensions or custom templates (.astro, .html) are ignored.
Asset Re-hosting: References like ./images/diagram.png or ../assets/flowchart.webp are normalized through resolveArchiveAssetPath, uploaded to persistent storage, and rewritten in the Markdown body.
Frontmatter Ingestion: Maps title, canonical_url (or canonicalUrl, url), cover_image, tags, and published_at.

3. Duplicate Detection: Preventing Content Overwrites

ZyVOP avoids duplicate drafts during repeated syncs or CLI runs. Rather than relying on fragile hashes, the database executes a scoped uniqueness query:

// Scoped duplicate check in markdown-zip-import.service.ts
if (canonicalUrl) {
  const normalized = canonicalUrl.replace(/[?#].*$/, '').replace(/\/+$/, '');
  query.andWhere(
    '(post.canonicalUrl = :canonicalUrl OR post.canonicalUrl = :normalized OR post.canonicalUrl = :slash)',
    { canonicalUrl, normalized, slash: `${normalized}/` },
  );
} else {
  query.andWhere('LOWER(TRIM(post.title)) = LOWER(TRIM(:title))', { title });
}

If an article matches an existing post owned by the author, it is safely skipped rather than duplicated or overwritten.

4. How to Migrate: Step-by-Step

Option 1: Web Dashboard (Zero Installation)

Go to Dashboard → Migrate (/migrate).
Select your source:

-   **DEV.to:** Enter your username (`devto/yourusername`).

-   **Hashnode:** Enter your publication domain (`blog.yourdomain.com`).

-   **Medium / Ghost / Substack:** Paste your public profile or RSS feed URL (`https://yourblog.com/rss.xml`).

-   **Single URL:** Paste a single article link to test readability extraction.

Preview extracted articles, tags, and publication dates before committing them as drafts.

Option 2: Uploading a Static Site ZIP

In your Hugo/Astro/Jekyll repository, locate your Markdown directory.
Ensure posts use standard Markdown (.md or .markdown). Convert .mdx component imports into standard code fences or markdown blocks.
Zip the directory containing your posts and local image assets:
```
zip -r blog-migration.zip content/posts/ assets/images/
```
Upload via Dashboard → Import → Upload Markdown ZIP.

Option 3: Terminal Migration via the CLI (`zyvop import`)

For developers who prefer terminal workflows:

# Authenticate
npx zyvop login

# Import from DEV
npx zyvop import devto yourusername

# Import from Hashnode
npx zyvop import hashnode blog.yourdomain.com

5. Preflight Audits: The ZyVOP Compatibility Lab

Before publishing or cross-posting imported drafts, inspect them in the ZyVOP Compatibility Lab (/compatibility-lab).

The Compatibility Lab parses your article in-browser without modifying the database and runs preflight checks across destinations:

Tag Truncation: Flags when your post exceeds destination limits (4 tags on DEV, 5 on Hashnode and Medium).
Social Announcement Limits: Checks title and excerpt lengths against announcement constraints (180 characters for Bluesky, 320 for Mastodon).
Local Asset Detection: Warns if an imported article still references non-public image paths (localhost or un-migrated relative paths).
Syntax Adaptation: Reports how Mermaid diagrams and KaTeX formulas will adapt across each destination.

6. Post-Migration: Establishing Sovereign GitOps

Once imported into ZyVOP, your articles are no longer locked into any single platform:

Sovereign Canonical URL: Your ZyVOP publication acts as the primary authoritative source (<link rel="canonical">).
Multi-Platform Distribution: Syndicate updates to DEV, Hashnode, Medium, and WordPress with one click or via npx zyvop publish.
Automated Git Backup: Connect your GitHub account to have every post automatically committed to your personal repository via GitHub's Git Database API.

Take sovereign ownership of your technical writing today without losing your hard-earned SEO equity or past article catalog.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Building Production Subscriptions with Razorpay: Webhooks, Signatures, and Edge Cases

Sanjay Singh — Fri, 16 Oct 2026 13:00:45 +0000

If you have integrated Stripe before, you might expect payment gateways to behave consistently: create a customer, attach a payment method, subscribe them to a price ID, and listen for customer.subscription.updated webhooks.

When you integrate Razorpay for the Indian market, that mental model breaks almost immediately.

Between Reserve Bank of India (RBI) e-mandate regulations on recurring card transactions, asynchronous webhook delivery delays, cryptographic signature quirks where parameters are silently inverted between endpoints, and Fastify/NestJS stream parsing bugs, getting Razorpay to run reliably in production requires defensive engineering that the official documentation barely touches.

In this guide, we break down the exact production architecture we built for ZyVOP: a dual-mode subscription engine in NestJS and Fastify that handles recurring e-mandates, falls back to fixed-term orders when cards fail, enforces constant-time signature verification, and guarantees idempotent webhook processing.

1. The Two Indian Payment Realities: Subscriptions vs. Orders

The single biggest mistake teams make when launching recurring billing in India is assuming every customer can be placed on an automated recurring subscription.

Under RBI guidelines:

Automated recurring debits require a compliant e-mandate registration.
Many Indian debit cards, prepaid cards, corporate credit cards, and UPI apps reject auto-debit mandates during checkout.
Mandates above ₹15,000 require additional factor authentication (AFA) for every single billing cycle.

If your checkout only supports Razorpay Subscriptions (/v1/subscriptions), you will encounter a 30% to 50% checkout drop-off rate simply because your users' bank instruments cannot register an e-mandate.

The Dual-Mode Architecture

To solve this, our backend implements a dual-mode strategy:

Recurring Subscriptions (sub_...): For users with auto-debit cards. The plan automatically renews every month or year.
Fixed-Term Orders (order_...): For users paying with UPI QR, NetBanking, or non-mandate debit cards. We generate a one-time order for the exact period amount (e.g., ₹499 or ₹4,999) and set an explicit expiration timestamp (currentPeriodEnd = Date.now() + 30 days). When the period ends, the user simply renews.

This single design decision eliminated failed payment drop-offs across Indian customers.

2. The Flipped Signature Verification Trap

To prevent clients from tampering with checkout outcomes, Razorpay returns a cryptographic HMAC-SHA256 signature when checkout completes in the browser. You must verify this signature on your backend before granting access.

Here is the trap: The payload format is inverted depending on whether you created an Order or a Subscription.

The Order Signature Payload

When verifying a one-time Order: $$\text{payload} = \text{order_id} + \text{"|"} + \text{payment_id}$$

const expected = createHmac('sha256', secret)
  .update(`${orderId}|${paymentId}`)
  .digest('hex');

The Subscription Signature Payload

When verifying a recurring Subscription: $$\text{payload} = \text{payment_id} + \text{"|"} + \text{subscription_id}$$

// Notice paymentId comes FIRST!
const expected = createHmac('sha256', secret)
  .update(`${paymentId}|${subscriptionId}`)
  .digest('hex');

If you use the order format (subscriptionId|paymentId) to verify a subscription, the signature will fail every time, even though all IDs are valid and the user was successfully charged.

Constant-Time Verification

Never compare cryptographic signatures using standard JavaScript equality (expected === signature). That creates a timing side-channel attack where an attacker can deduce bytes of your secret by measuring microsecond response latency. Always use timingSafeEqual:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifySubscriptionSignature(
  paymentId: string,
  subscriptionId: string,
  signature: string,
  keySecret: string,
): void {
  const expected = createHmac('sha256', keySecret)
    .update(`${paymentId}|${subscriptionId}`)
    .digest('hex');

  const expectedBuf = Buffer.from(expected, 'hex');
  const receivedBuf = Buffer.from(signature || '', 'hex');

  if (
    expectedBuf.length === 0 ||
    expectedBuf.length !== receivedBuf.length ||
    !timingSafeEqual(expectedBuf, receivedBuf)
  ) {
    throw new UnauthorizedException('Invalid Razorpay subscription signature');
  }
}

3. Fastify & NestJS: Preserving Raw Buffers for Webhooks

Webhooks are the ultimate source of truth for payment status. If a user closes their browser tab right after payment, the client-side checkout callback will never fire. Only the webhook can tell you that the payment succeeded.

Razorpay signs every webhook payload with the X-Razorpay-Signature header. The signature is calculated as: $$\text{HMAC-SHA256}(\text{rawRequestBody}, \text{RAZORPAY_WEBHOOK_SECRET})$$

Why Naive NestJS/Fastify Implementations Fail

In Fastify and Express, body parsers automatically parse incoming JSON payloads into JavaScript objects before your controller runs:

Raw Network Stream  -->  JSON.parse()  -->  req.body (JS Object)

If your controller attempts to verify the signature by re-serializing the body:

// ❌ CRITICAL BUG: This will fail verification randomly!
const raw = JSON.stringify(body);
const expected = createHmac('sha256', secret).update(raw).digest('hex');

This fails because JSON.stringify() does not preserve:

Whitespace or indentation from the original HTTP body.
The original key order of JSON fields.
Escaped Unicode characters or slash formatting.

Even a single missing space alters the SHA-256 hash entirely.

The Fix: Fastify Raw Body Preservation

In NestJS with the Fastify adapter (@nestjs/platform-fastify), you must enable raw body buffering at the application root:

// main.ts
import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter({
      bufferLogs: true,
      rawBody: true, // 👈 Required: Attaches raw Buffer to req.rawBody
    }),
  );
  // ...
}

Then in your billing controller, enforce that the raw buffer exists before passing it to verification:

// billing.controller.ts
@Post('webhooks/razorpay')
async razorpayWebhook(
  @Headers() headers: Record<string, any>,
  @Req() req: FastifyRequest,
  @Body() event: any,
) {
  const rawBody = (req as any).rawBody;

  if (!Buffer.isBuffer(rawBody)) {
    throw new BadRequestException('Raw Razorpay webhook body is unavailable');
  }

  return this.billing.handleRazorpayWebhook(headers, rawBody, event);
}

And in your verification service:

verifyWebhookSignature(rawBody: string | Buffer, signature: string): void {
  const secret = this.required('RAZORPAY_WEBHOOK_SECRET');

  const expected = createHmac('sha256', secret)
    .update(rawBody) // 👈 Digests the exact binary stream
    .digest('hex');

  const expectedBuf = Buffer.from(expected, 'hex');
  const receivedBuf = Buffer.from(signature || '', 'hex');

  if (
    expectedBuf.length === 0 ||
    expectedBuf.length !== receivedBuf.length ||
    !timingSafeEqual(expectedBuf, receivedBuf)
  ) {
    throw new UnauthorizedException('Invalid Razorpay webhook signature');
  }
}

4. The Client-Server Handshake & Race Conditions

When a payment succeeds, two events happen almost simultaneously:

Client-side: The Razorpay modal triggers the handler() callback with payment IDs and signature. The frontend calls POST /api/v1/billing/razorpay/verify.
Server-side: Razorpay's servers send an asynchronous webhook (payment.captured or subscription.activated) to POST /api/v1/billing/webhooks/razorpay.

The Race Condition Failure Modes

If the webhook arrives first and locks the subscription row, the frontend /verify call might throw a database lock conflict.
If the user has an aggressive ad-blocker or loses Wi-Fi right as the payment succeeds, the frontend /verify call never happens.
Razorpay retries webhooks on network failure. If your webhook handler isn't idempotent, you might trigger duplicate activation emails or miscount subscriptions.

Solution: Idempotent Webhook Storage with `23505` Handling

We maintain a dedicated webhook_events table in PostgreSQL with a unique constraint on (provider, provider_event_id):

// billing.service.ts
const eventId = event?.id || headers['x-razorpay-event-id'];
const eventType = event?.event || '';

// 1. In-memory / fast-path deduplication
const duplicate = await this.webhookEvents.findOne({
  where: { provider: BillingProvider.RAZORPAY, providerEventId: eventId },
});
if (duplicate) {
  return { received: true, duplicate: true };
}

// 2. Execute reconciliation
const providerSubscriptionId = 
  event?.payload?.subscription?.entity?.id || 
  event?.payload?.payment?.entity?.subscription_id;

if (providerSubscriptionId && eventType.startsWith('subscription.')) {
  await this.reconcileRazorpaySubscription(providerSubscriptionId);
}

// 3. Atomically persist event ID; catch concurrent duplicate insert race
try {
  await this.webhookEvents.save(
    this.webhookEvents.create({
      provider: BillingProvider.RAZORPAY,
      providerEventId: eventId,
      eventType,
      providerSubscriptionId: providerSubscriptionId || null,
    }),
  );
} catch (error: any) {
  // PostgreSQL 23505 = unique_violation. Concurrent worker already handled this.
  if (error?.code !== '23505') throw error;
}

return { received: true };

5. Preventing Configuration Drift on Startup

One of the nastiest production bugs in payment systems is currency or amount drift:

Someone edits the price on the marketing page to ₹499/mo.
In the Razorpay Dashboard, someone created a plan for ₹49.90 because they entered 499 instead of 49900 paise.
Or someone configured the plan as USD instead of INR.

Users will sign up, get charged ₹49.90, and your database will grant them full access while you lose revenue.

We prevent this by introducing an assertive configuration guard on boot:

// razorpay.service.ts
async assertPlanConfiguration(interval: BillingInterval): Promise<void> {
  const planId = this.planId(interval);
  if (this.validatedPlanIds.has(planId)) return;

  const plan = await this.request(`/plans/${encodeURIComponent(planId)}`);
  const expectedPeriod = interval === BillingInterval.MONTH ? 'monthly' : 'yearly';
  const expectedAmount = interval === BillingInterval.MONTH ? 49_900 : 499_900; // in paise

  const valid =
    plan?.entity === 'plan' &&
    plan?.period === expectedPeriod &&
    Number(plan?.interval) === 1 &&
    plan?.item?.currency === 'INR' &&
    Number(plan?.item?.amount ?? plan?.item?.unit_amount) === expectedAmount;

  if (!valid) {
    throw new ServiceUnavailableException(
      `Razorpay ${interval.toLowerCase()} plan must be ${expectedPeriod} at ₹${expectedAmount / 100} INR`,
    );
  }

  this.validatedPlanIds.add(planId);
}

When a user initiates checkout, the server verifies the plan with Razorpay's API before issuing the subscription ID. If an admin pasted the wrong Plan ID or configured the wrong currency, the transaction fails immediately with an actionable error rather than billing the customer incorrectly.

6. Prorations, Subunit Math, and Refunds

Like Stripe, Razorpay deals strictly in currency subunits:

1 INR = 100 paise.
₹499.00 must be passed as 49900.
₹4,999.00 must be passed as 499900.

Never Use Floating Point for Currency Math

In JavaScript:

0.1 + 0.2 === 0.3 // false (0.30000000000000004)

When calculating prorated refunds for downgraded subscriptions:

// proration.util.ts
export function calculateProratedRefund(
  totalPaidSubunits: number, // 49900
  periodStart: Date,
  periodEnd: Date,
  cancelDate: Date,
): number {
  const totalDurationMs = periodEnd.getTime() - periodStart.getTime();
  const remainingMs = Math.max(0, periodEnd.getTime() - cancelDate.getTime());

  if (totalDurationMs <= 0 || remainingMs <= 0) return 0;

  // Perform division last, truncate to integer paise
  const refundPaise = Math.floor((totalPaidSubunits * remainingMs) / totalDurationMs);

  // Enforce minimum transaction threshold (Razorpay requires >= 100 paise)
  return refundPaise >= 100 ? refundPaise : 0;
}

Issuing the Refund via API

To refund a Razorpay payment, query the payments or invoices linked to the subscription, find the captured payment ID, and issue the partial refund:

// razorpay.service.ts
async refundPayment(
  paymentId: string,
  amountPaise?: number,
  notes?: Record<string, string>,
): Promise<{ id: string; status: string } | null> {
  const body: Record<string, any> = {};
  if (typeof amountPaise === 'number' && amountPaise > 0) {
    body.amount = amountPaise;
  }
  if (notes) {
    body.notes = notes;
  }

  return this.request(`/payments/${encodeURIComponent(paymentId)}/refund`, {
    method: 'POST',
    body: JSON.stringify(body),
  });
}

7. Status Mapping & The "Halted" Trap

Razorpay subscription lifecycles do not map 1:1 to generic billing states. In particular, Razorpay has a status called halted.

A subscription moves to halted when recurring debit attempts fail repeatedly (e.g., customer had insufficient funds or expired card). A halted subscription is NOT active, but naive implementations check:

// ❌ WRONG
if (remote.status !== 'cancelled') {
  user.isPro = true;
}

This would grant free ongoing Pro access to users whose cards are declining!

Here is the authoritative status mapping:

private mapRazorpayStatus(status: string): SubscriptionStatus {
  const s = String(status || '').toLowerCase();

  // Authenticated = Mandate created, awaiting first cycle
  if (s === 'active' || s === 'authenticated') {
    return SubscriptionStatus.ACTIVE;
  }

  if (s === 'cancelled') {
    return SubscriptionStatus.CANCELLED;
  }

  if (s === 'completed' || s === 'expired') {
    return SubscriptionStatus.EXPIRED;
  }

  // Halted / Paused / Pending = Payment failure, revoke paid features immediately
  if (s === 'paused' || s === 'pending' || s === 'halted') {
    return SubscriptionStatus.SUSPENDED;
  }

  return SubscriptionStatus.APPROVAL_PENDING;
}

8. Summary Checklist for Production

Before taking your Razorpay integration live, run through this checklist:

Dual-Mode Checkout: Do you support one-time Orders as a fallback for users whose cards reject RBI recurring mandates?
Flipped Argument Verification: Are you using ${orderId}|${paymentId} for orders and ${paymentId}|${subscriptionId} for subscriptions?
Timing-Safe Equality: Are you comparing HMAC buffers using crypto.timingSafeEqual() instead of ===?
Fastify Raw Body: Is { rawBody: true } configured in your HTTP adapter so webhooks are verified against the pristine stream?
Idempotent Webhooks: Does your webhook handler catch PostgreSQL 23505 unique violations to handle concurrent delivery gracefully?
Currency Subunits: Are all amounts computed as integers in paise (₹499 = 49900) with no floating-point arithmetic?
Boot Plan Verification: Do you assert that remote Razorpay plans match local interval and currency configurations on initialization?
Status Mapping: Does your system suspend access when a subscription transitions to halted or paused?

Getting payment plumbing right is unglamorous, but handling these edge cases upfront ensures your billing engine runs autonomously without silent revenue leaks or angry customers.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

How to Publish One Technical Article to Dev.to, Hashnode, Medium, and WordPress (Without Losing Your SEO)

Sanjay Singh — Fri, 16 Oct 2026 12:56:59 +0000

TL;DR: Publishing across Dev.to, Hashnode, Medium, and WordPress maximizes developer discovery, but manual cross-posting introduces search engine cannibalization, mangled Markdown, stripped Mermaid diagrams, and tedious maintenance. Here is how to automate the entire syndication pipeline—via Web UI or headless GitOps (npx zyvop)—while anchoring full canonical SEO authority to your sovereign domain.

The 2-Hour Copy-Paste Tax

You just spent 15 hours on a technical deep dive. You benchmarked memory leaks under high concurrency, profiled heap allocations, built detailed architectural diagrams, and verified code snippets against the latest runtime release.

Your draft is crisp, authoritative, and finally finished in Markdown.

Now comes the part every engineer dreads: the distribution grind.

If you publish solely to your personal blog (Next.js, Astro, or Hugo), you hit the cold-start wall: near-zero discoverability without years of domain authority. But if you publish exclusively on walled platforms like Medium or Dev.to, you surrender your audience, brand equity, and content sovereignty.

The industry-standard solution is multi-platform syndication: publish on your primary home, then syndicate to Dev.to, Hashnode, Medium, and WordPress.

Yet in practice, doing this manually costs at least two hours per article:

Opening four browser dashboards and copy-pasting Markdown or HTML.
Fixing broken code fences and stripped syntax highlighting tags.
Manually re-uploading architecture diagrams because Medium and WordPress don't support Mermaid.
Digging through four distinct settings panels to set canonical links.
Praying you don't discover a typo ten minutes later, requiring you to repeat the cycle across all four platforms.

There is a much better way. Let’s break down the technical pitfalls of multi-platform publishing and explore how to automate the entire flow cleanly with ZyVOP.

The Four Mechanical Failure Points of Manual Syndication

Before looking at the solution, let’s diagnose why manual syndication breaks:

1. SEO Cannibalization & Canonical Disasters

Search engine algorithms penalize or consolidate duplicate content. If Google discovers your article on Dev.to or Medium before your personal blog, their domain authority (DA 80+) will outrank your site unless an explicit rel="canonical" tag tells Google: "Credit the original author URL as the definitive source."

Every platform implements this differently:

Dev.to: Requires canonical_url in YAML frontmatter or the article REST payload.
Hashnode: Requires originalArticleURL inside its GraphQL PublishPostInput mutation.
Medium: Accepts canonicalUrl only upon initial article creation (Medium's API does not permit updating published posts).
WordPress: Lacks a native canonical REST field out of the box, requiring either third-party plugin meta mapping (Yoast/RankMath) or structured HTML attribution.

2. AST Transformation & Code Fence Collisions

Markdown is not a single standard; it is a family of dialects. If your technical post includes Markdown code snippets with three backticks inside a fenced block, parsers like Dev.to's Forem misinterpret the fences, inject orphaned Liquid tags, and crash with Unknown tag 'endraw'.

3. Broken Architecture Diagrams (The Mermaid Problem)

Dev.to and Hashnode render code fences, but Medium and WordPress have zero native Mermaid or LaTeX support. When you copy-paste raw Mermaid syntax into Medium, it displays as an unreadable block of raw plaintext. High-grade syndication must automatically compile diagram code into vector SVGs or standalone high-resolution images.

4. The Maintenance Dilemma (Idempotency)

When an author patches a bug in a code example, manual syndication means hunting down URLs and editing four different CMS forms. If you automate via naive scripts, network retries risk spawning duplicate posts across your feeds.

The Sovereign Publishing Model with ZyVOP

ZyVOP was engineered from the ground up as a Developer Publishing Hub. It enforces a single guiding philosophy:

Own your canonical source of truth; treat third-party networks purely as distribution edges.

ZyVOP automates the entire conversion and publishing lifecycle:

Canonical Anchoring: Points all syndicated destinations back to your primary article on your custom domain (https://yourdomain.com/blog/slug) or your ZyVOP profile.
Dynamic Backtick Scaling: Detects nested backticks and scales fences (

``) so Dev.to and Forem never break.
Stateless Vector Diagram Compilation: Compiles mermaid code blocks into high-contrast diagram image URLs readable across light and dark themes.
Automated UTM Attribution: Tags backlinks with structured parameters (?utm_source=devto&utm_medium=crosspost) to track readership funnels.
Idempotent Updates: Recognizes existing articles by slug, updating live copies instead of duplicating them.

Method 1: The GitOps & CLI Workflow (`npx zyvop`)

For developers who live inside Neovim, VS Code, or Obsidian, leaving your terminal to open multiple browser tabs breaks flow. ZyVOP provides a headless CLI that publishes Markdown files directly.

Step 1: Install or Run Directly via `npx`

No global installation required:


bash
npx zyvop --help

Or install globally:


bash
npm install -g zyvop

Step 2: Configure YAML Frontmatter

Add syndication targets and metadata to your Markdown document:


`markdown
---
title: "Zero-Trust Architecture in Distributed Systems"
subtitle: "A deep dive into mTLS, ephemeral tokens, and SPIFFE/SPIRE"
slug: "zero-trust-architecture-distributed-systems"
canonical_url: "https://alex.dev/blog/zero-trust-architecture"
tags: [security, devops, distributed-systems, architecture]
category: backend
generate_toc: true
cross_post:
  devto: true
  hashnode: true
  medium: true
  wordpress: true
---

## 1. Threat Modeling in Modern Microservices

Here is an architectural overview of mutual TLS handshake verification:



![Mermaid Diagram](https://mermaid.ink/img/pako:eNp1ULFOw0AM_RXjlcuAxJQhUgktVIKFQKcuTuIkFpe7cOe2hKr_jtJ0KAOb7ffs956PWPmaMcXIXzt2FT8KtYH6rQMAyK2w0yTLnkj5QGMKaycqZOH9pbig8MzW-pl_oSVZNmMpFBz2HCDnoNJIRcpwC_kC8o6sZdfyf0KX49eLGw5zKd791bsSXLoqjINyDf3kseAYxTtYRqXSSuy4RoM9h56kxvSI2nE_5a-5oZ1VNPNkQ0GotBwnTuOdrqgXO2KKCQ2D5SSOUbk38GDFfb5SVZz7lXdqYIsFt57hY71FA2--9OrN9Kc9q1RkYBGErIFILiZxSoXmLFLIz-Tl7n74xtPJYNnm3vqAKd4cOlHG0y_woZOe?type=png)

`

When implementing cryptographic handshakes...



````markdown
#### Step 3: Preview with a Dry Run
Verify how ZyVOP parses your frontmatter, resolves relative images, and structures platform payloads without authenticating:

```bash
zyvop publish ./zero-trust.md --dry-run

Step 4: Authenticate and Publish

Authenticate once with your developer token:

export ZYVOP_TOKEN="zv_live_98a7f..."
zyvop publish ./zero-trust.md

Zero-Trust Local Mode (`--local`)

For security-conscious engineers or strict enterprise environments where third-party API credentials cannot be stored on external servers, ZyVOP offers a --local mode. Credentials are read from your local environment or CI secret manager, sent directly to providers, and never uploaded to ZyVOP:

export ZYVOP_DEVTO_API_KEY="dev_..."
export ZYVOP_HASHNODE_API_KEY="hn_..."
export ZYVOP_MEDIUM_API_TOKEN="med_..."
export ZYVOP_WORDPRESS_URL="https://wp.alex.dev"
export ZYVOP_WORDPRESS_USERNAME="alex"
export ZYVOP_WORDPRESS_APP_PASSWORD="xxxx xxxx xxxx xxxx"

zyvop publish ./zero-trust.md --local

Automating with GitHub Actions

You can trigger multi-platform distribution on every git push to main:

name: Publish Technical Articles
on:
  push:
    branches: [main]
    paths: ['posts/**.md']

jobs:
  syndicate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Publish to ZyVOP, Dev.to, Hashnode, Medium & WordPress
        env:
          ZYVOP_TOKEN: ${{ secrets.ZYVOP_TOKEN }}
        run: |
          npx zyvop publish ./posts/zero-trust.md

Method 2: The Web Studio & One-Click Publisher

If you prefer a rich visual authoring experience, ZyVOP’s Web Studio provides an author-first interface:

Connect Integrations Once: Navigate to Settings → Integrations and connect Dev.to, Hashnode, Medium, and WordPress with your API tokens or Application Passwords.
Distraction-Free Authoring: Write in a hybrid Tiptap editor that seamlessly blends Markdown shortcuts, syntax-highlighted code blocks, live KaTeX formulas, and real-time Mermaid previewing.
Syndication Drawer: Click Publish, select which platforms should receive the post, review canonical preview URLs, and hit confirm.
Real-Time Job Telemetry: Monitor queued workers, inspect external platform post URLs, or trigger retries if a third-party platform API encounters a rate limit.

Platform Syndication Matrix

Platform	Protocol	Canonical Mechanism	Diagram Handling	Idempotent Updates
Dev.to	REST API	canonical_url payload field	Auto-converts to high-res SVG embed	Full PUT /api/articles/:id updates
Hashnode	GraphQL	originalArticleURL input	Auto-converts to high-res SVG embed	Full updatePost mutation
Medium	REST API v1	canonicalUrl creation param	Auto-converts to high-res SVG embed	Initial creation only (API constraint)
WordPress	WP REST API	Head meta + structured HTML backlink	Auto-converts to high-res SVG embed	Full PUT /wp-json/wp/v2/posts/:id

The Result: Sovereign Reach Without the Friction

Technical writing is one of the highest-leverage investments in a software engineer's career. It sharpens your architectural thinking, opens doors to leadership roles, and establishes authority in your domain.

You should never have to sacrifice distribution to maintain ownership, nor should you spend two hours fighting copy-paste formatting bugs every time you publish.

By combining canonical SEO protection, automatic AST transformations, and GitOps workflows, ZyVOP gives you the best of both worlds:

Your content lives on your domain, building your personal search authority.
Your articles reach tens of thousands of developers across Dev.to, Hashnode, Medium, and WordPress on day one.
Your publishing pipeline is version-controlled, automated, and painless.

Write once. Own your canonical home. Syndicate everywhere.

Ready to streamline your technical writing workflow? Get started with ZyVOP or run npx zyvop publish --help in your terminal today.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Inside ZyVOP: The Modern Developer Publishing Engine

Sanjay Singh — Thu, 15 Oct 2026 04:53:15 +0000

Technical writing is one of the highest-leverage habits an engineer can build. It forces clarity of thought, documents hard-won architecture lessons, and builds career reputation.

Yet, the modern developer publishing experience has long been caught in a frustrating dilemma:

The Self-Hosted Island: You build a personal blog with Hugo, Astro, or Next.js. You get 100% control, but you face the cold-start reality: zero discovery and fragmented readership.
The Walled Gardens: You publish on centralized networks like Dev.to, Medium, or Hashnode. You get immediate audience discovery, but you surrender control, risk algorithm shifts, and battle third-party paywalls.
The Cross-Posting Grind: You try to do both. You write in Markdown, manually copy-paste into multiple CMS dashboards, re-format code blocks, fix broken image links, and manually set rel="canonical" tags so search engines don't penalize your original site.

We built ZyVOP to solve this dilemma once and for all: Write once, own your primary canonical source, and syndicate everywhere.

Here is a look under the hood at what ZyVOP offers today.

1. Developer-First Technical Authoring

Most blogging platforms are built for general prose, treating code snippets as second-class citizens. ZyVOP treats technical formatting as a core requirement:

Rich Hybrid Authoring: A distraction-free editing experience powered by Tiptap that seamlessly balances Markdown shortcuts with WYSIWYG convenience.
First-Class Code Syntax Highlighting: Native language detection and syntax highlighting for dozens of programming languages.
Native Mermaid Architecture Diagrams: Write diagram code directly in Markdown and have it render crisp, high-resolution architecture diagrams in real-time.
KaTeX Mathematical Notation: Built-in LaTeX rendering for equations, formulas, and academic write-ups.
Shareable Draft Previews & Scheduling: Generate private, revocable preview links for technical peer reviews before scheduling your publication date.

2. Multi-Platform Syndication with Canonical Protection

Cross-posting without canonical attribution is dangerous: search engines can rank an external copy above your original publication.

ZyVOP automates distribution across major developer ecosystems while actively safeguarding your SEO authority:

Full-Article Syndication: Push full article copies with one click to Dev.to, Hashnode, Medium, and WordPress.
Social Dispatches: Automatically broadcast social dispatches to decentralized networks like Bluesky and Mastodon.
Automated Canonical Attribution: Every syndicated article automatically receives a rel="canonical" link pointing back to your authoritative primary URL, consolidating search engine ranking signals to your home domain.
Resilient Background Processing: Built on an asynchronous queue architecture that handles platform API rate limits, temporary downtimes, and automatic retries gracefully.

3. GitOps & CLI Workflows (`npx zyvop`)

Developers shouldn't be forced to leave their code editors just to publish a blog post.

ZyVOP provides an open-source CLI and Git-native workflow:

# Publish or update an article directly from your terminal
npx zyvop publish ./posts/system-design.md --cross-post devto,hashnode

Frontmatter-Driven Config: Manage tags, canonical URLs, cover images, and cross-posting targets directly in standard YAML frontmatter.
GitHub Actions Integration: Commit Markdown files to your Git repository, push to main, and let CI/CD automatically syndicate your articles across every platform.
Automated Git Backup: Every post published through ZyVOP can automatically create versioned backup commits in your personal GitHub repository, guaranteeing you never lose your work.

4. Independent Publications & Custom Domains

You shouldn't have to choose between a personal social profile and an independent editorial brand. ZyVOP cleanly separates Human Identity from Publication Branding:

Custom Domain Support: Map your custom domain (blog.yourdomain.com or you.zyvop.dev) with automated SSL certification.
Decoupled Branding: Customize independent logos, favicons, navigation bars, and static pages (/about, /projects) without altering your personal profile.
Flexible Theme Layouts: Choose from multiple curated layout styles (Magazine, Stacked, or Grid) optimized for technical readability and dark mode.
Native Redirect Management: Manage 301 and 302 HTTP redirects to maintain search equity when migrating legacy paths.

5. Zero-Lock-In Migration

If you already have a body of work on existing platforms, moving should not take days of manual copy-pasting.

ZyVOP includes an automated migration pipeline:

1-Click Importer: Import published articles directly from Dev.to, Hashnode, Medium, RSS feeds, or standalone URLs.
Asset Preservation: Cleans up messy HTML, converts raw content into clean Markdown, and preserves original publishing dates and canonical sources.
Full Data Export: You own your data. Export your entire library of Markdown and media assets whenever you want.

6. Audience Ownership & Unified Analytics

When you publish on third-party networks, those networks own your audience. ZyVOP empowers creators to build direct relationships with their readers:

Built-In Author Newsletters: Double-opt-in email subscription engine that delivers your new articles directly to your readers' inboxes.
Exportable Subscriber Lists: Complete, portable CSV exports of your audience at any time.
Aggregated Performance Metrics: View unified engagement metrics—tracking reads, reactions, and cross-platform performance in one consolidated dashboard.
Community Engagement: Threaded technical discussions, accepted answers, bookmarks, reading streaks, and achievement badges for active learners.

7. Built for Modern Web Standards & AI Discovery

Content discoverability is changing rapidly. ZyVOP is architected from the ground up for modern search and answer engines:

Edge-Optimized Performance: Built with Next.js App Router for sub-second page loads and zero layout shift.
Dynamic Open Graph Images: Server-rendered social cards tailored with post titles, author branding, and reading times for maximum click-through on social feeds.
Structured Data & Sitemaps: Automatic JSON-LD schema generation, comprehensive XML sitemaps, and RSS feeds.
AI/LLM-Ready Endpoints: Optimized llms.txt and semantic discovery endpoints allowing modern AI answer engines to cite and source your original work accurately.

Summary: A Single Home for Your Writing

ZyVOP was created because technical writers shouldn't have to compromise between reach and ownership.

With developer-first authoring, native Git workflows, automated multi-platform distribution, and full canonical control, ZyVOP gives engineers the publishing leverage they need without the friction.

Ready to test the workflow? Run npx zyvop --help or explore ZyVOP today.

Frequently Asked Questions

What problem does ZyVOP aim to solve for developers?

It eliminates the trade‑off between self‑hosting control and the discovery offered by centralized networks by letting you write once, keep a canonical source, and syndicate everywhere.

How does ZyVOP handle code snippets and technical formatting?

It provides first‑class syntax highlighting with native language detection, Mermaid diagram rendering, KaTeX math support, and a hybrid Markdown/WYSIWYG editor powered by Tiptap.

Which platforms can ZyVOP automatically syndicate full articles to?

With one click it pushes full copies to Dev.to, Hashnode, Medium, and WordPress, and also dispatches social posts to Bluesky and Mastodon.

How does ZyVOP protect SEO authority when cross‑posting?

Each syndicated article receives an automatic rel="canonical" link pointing back to the primary URL, consolidating ranking signals to the home domain.

Can I publish or update articles without leaving my code editor?

Yes, the open‑source CLI (npx zyvop) lets you publish Markdown files directly from the terminal, using frontmatter for tags, canonical URLs, and cross‑post targets.

Does ZyVOP support custom domains and independent branding?

It allows mapping custom domains with automated SSL, separate logos, favicons, navigation, and multiple theme layouts without affecting personal profiles.

How can existing content be moved to ZyVOP?

A 1‑click importer brings articles from Dev.to, Hashnode, Medium, RSS feeds, or URLs, cleans HTML to Markdown, preserves dates and canonical sources, and lets you export the full library anytime.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Are Passkeys a Trap? Fact-Checking a Viral Warning

Sanjay Singh — Wed, 14 Oct 2026 05:38:37 +0000

A Substack post going around says passkeys are a trap and nobody should use them. I read it, then checked its claims against the specs, vendor docs and NIST guidance. Short version: the author spotted a real long-term risk and then oversold it. “Don’t use passkeys” is bad advice for most people. “Don’t trust them blindly” is fair.

What the post claims

Passkeys aren’t one thing. Some copy across devices, some don’t. Some sit in a secure chip, some are plain files. Websites can see which type you made, and through attestation they can verify what software made it. So, the author argues, sites could eventually accept only approved software, handing big tech, banks and governments a veto over what you run. The suggested fix: authenticator-app codes (TOTP) or a hardware key.

Where the post is right

Sites can see what kind of passkey you have. WebAuthn flags tell a site whether a credential is synced or device-bound. WebAuthn Level 3, which formalizes them, became a W3C Recommendation on August 25, 2026.
Sites can block providers. Auth vendors sell allow-lists and block-lists by authenticator model, and warn that switching them on can lock out users who are already enrolled. Banks are the target customer.
The people writing the rules aren’t you. FIDO’s board includes banks, payment networks and big platforms, and governments have had a seat since 2015. I found no consumer group on the public member list, though I only saw part of it.
Device checks already lock people out. GrapheneOS users report banking and ID apps refusing to run because of Google’s Play Integrity checks. That isn’t passkeys, but it shows the worry is real.
Moving passkeys has been painful. FIDO published a transfer standard (CXP and CXF) as a proposed standard in March 2026. I couldn’t confirm which providers actually ship it.

Where it falls apart

The claim that attestation is coming for everyone. Not on the evidence. The default is no attestation, and Apple and Google don’t send any for synced passkeys. Yubico’s own guidance says rejecting credentials without attestation will probably reject Apple, Google and Microsoft passkeys. Those providers hold over 90 percent of passkeys by one industry estimate, so a consumer site demanding attestation would shut out most of its own customers. That is a commercial brake, not a guarantee, but it is a real one.

The claim that attestation inspects your whole device. In the consumer flows I reviewed, it identifies the make and model of the authenticator. Whether your operating system is approved is checked by other systems, like Play Integrity or Apple’s App Attest. Some platform formats expose more, so the worry isn’t baseless, but I found no mainstream site using passkeys that way.

The claim that intelligence agencies are members. I couldn’t confirm it. The government members I could identify are standards and cybersecurity bodies such as NIST. That doesn’t prove no one else is involved, but the post doesn’t back the claim up.

The nudity scanner. The UK plan covers devices used by under-18s. The government describes on-device blocking with no data collection or reporting, and it doesn’t stop adults viewing anything. Nothing I found ties it to passkeys. The post’s wording implies a universal, mandatory scanner. That overstates what the policy says.

TOTP as the safe choice. TOTP gives you freedom, but it can be phished: a fake login page grabs your code and replays it in real time. A passkey is bound to the real site’s domain, so a fake site gets nothing. NIST treats that binding as what makes a credential phishing-resistant, and says properly deployed synced passkeys can meet its AAL2 level. The post mentions this only in a footnote, and admits the author would like to recommend passkeys. So the headline says one thing and the author’s own footnote says another.

The claim that you don’t control your passkeys. You have choices. 1Password, Bitwarden, Dashlane and Proton Pass all store passkeys. Few people use them, about 1 to 2 percent of new passkeys by one estimate, so platform defaults decide it for everyone else.

The risk the post barely touches

You can lose them. A passkey can’t be reset by email like a password. Lose every copy, or the account that syncs them, and you can be locked out. For ordinary users that is a more likely problem than attestation lockouts, which I found no consumer site enforcing.

So, trap or not?

Not today. The standard does contain hooks, such as attestation, backup flags and provider allow-lists, that could be used to narrow your choices, and that is worth watching. But the threat is policy, not cryptography, and so far it is speculation. Meanwhile phishing and reused passwords are happening right now, and passkeys are designed to close both holes.

What I’d actually do

Turn on passkeys for your email, banking, and Apple, Google or Microsoft account.
Register two: a second device, a security key, or a manager not tied to your phone. Save the recovery codes.
Pick a manager that can export, and check whether it supports FIDO’s transfer standard.
Keep a hardware key or TOTP as a backup. TOTP works, but remember it can be phished.
Watch for red flags: a site that rejects your passkey manager, forces its app, or demands a specific device. Tell the site, and look for alternatives.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Talorys: A Personal AI Agent in Your Own Cloudflare Account

Sanjay Singh — Tue, 13 Oct 2026 15:16:46 +0000

A closer look at the open-source project rociiu/talorys

Many AI assistants follow the same pattern. You sign up, hand your conversations to someone else's servers, and trust that your notes, tasks and personal details are handled well. Talorys takes the opposite approach. It is a personal AI agent that runs entirely inside your own Cloudflare account, with no server, database or account operated by its developers.

The pitch is short: one person, one Cloudflare account, one command.

npx create-talorys@latest

What you get

Talorys is a small, focused assistant rather than a sprawling platform. Out of the box it includes:

Chat with streaming responses, Markdown rendering and indicators that show when the agent is using a tool.
Memory for durable facts and preferences. You can view, edit and delete everything it remembers, and only the most relevant memories are sent to the model on each turn.
Tasks, notes and projects with full create, read, update and delete in the UI. You can also manage them from chat, for example by saying "Add a task to review my project tomorrow."
Automations such as one-time and recurring reminders, daily task digests and optional AI routines, all delivered to an in-app notification center.

It is single-user by design. There is no signup, no teams and no accounts. The installer asks you to set an owner password, and you sign in from any device with it.

One detail I like: it works without AI. If Workers AI is unavailable or you have used up your free daily quota, tasks, notes, memories and reminders keep working. Only chat pauses until the quota resets.

Deploying in one command

The installer does the tedious parts for you. It checks your Node.js version (20.18 or newer), verifies your Cloudflare login (or opens Cloudflare's authorization page in your browser), and lets you pick an account and an agent name. It then asks for an owner password, which is hashed locally with PBKDF2-SHA256 and stored only as a Cloudflare secret.

From there it generates a session secret, deploys a private Worker along with its SQLite-backed Durable Object, creates the Pages project, and verifies the live deployment before printing your pages.dev URL. The verification step checks the frontend, the auth endpoint and storage health without running any AI inference.

Here is the whole run at a glance, split by where each step happens:

The installer is also forgiving. If it gets interrupted, you run the same command again and it reconciles what already exists, with no duplicate resources and no data deleted. When you want the latest version later, npx create-talorys@latest update redeploys to the same resources and keeps your password and sessions. There are also status and doctor commands, plus a reset-password command if you get locked out.

How it works under the hood

The architecture is lean, and it shows how far Cloudflare's platform can go on its own:

A few design choices stand out:

The agent has no public URL. The Worker is deployed with workers_dev and preview URLs turned off. Your browser only talks to the Pages site, whose /api function forwards requests over a service binding.
Auth happens in the Worker, not the frontend. Sessions ride in an HttpOnly, SameSite=Strict cookie, the database stores only a keyed hash of each session token, and five failed logins from one IP within 15 minutes lock that client out.
All state lives in one SQLite-backed Durable Object. Conversations, memories, tasks, notes, projects, automations, sessions and usage data share a single store.
Scheduling uses Durable Object alarms. Reminders and routines fire without anything having to stay online. Per the architecture doc, each enabled automation holds one pending schedule, and a run missed by less than 24 hours still executes once.

One automation cycles like this, with nothing staying online in between:

On the AI side, chat runs on Workers AI using the @cf/zai-org/glm-4.7-flash model, with streaming and tool calling. Responses stream as Server-Sent Events from end to end, and reasoning is switched off to conserve Workers AI Neurons. Models sit behind a small provider interface, so adding another provider means implementing it in code rather than flipping a setting.

The agent's tools are tightly scoped, too. According to the security doc, destructive actions such as deleting a task or note need explicit confirmation in your latest message, enforced in code rather than only in the prompt. Scheduled AI runs get read-only tools plus a notify tool, and there are no shell, code-execution or outbound-HTTP tools at all.

Free-tier friendly, with honest caveats

Talorys is built to fit within the Cloudflare Workers Free plan. It uses only Pages, Workers, SQLite Durable Objects and Workers AI, and it does not provision R2, D1, KV, Vectorize or any paid service.

The README is refreshingly candid that this is not "unlimited free." Cloudflare sets account-level quotas, including a daily Workers AI allocation, and those can change. When the AI allocation runs out, chat tells you clearly and resumes after the daily reset. If your account is on a paid plan, usage beyond the included amounts is billed by Cloudflare.

To keep usage predictable, there are adjustable guardrails in Settings → AI: maximum output tokens, maximum context tokens (older history gets summarized), limits on tool calls and reasoning steps per request, and daily caps on AI requests and scheduled AI runs. Simple reminders and task digests never touch the model at all.

Privacy and data ownership

Talorys includes no telemetry, analytics, tracking or advertising code, and it sends nothing to its developers. Your data sits in your own Cloudflare account.

One thing to keep in mind is that Cloudflare itself processes your data to provide its services. That includes running Workers AI inference on your chat messages and the relevant memories included in each prompt. "Self-hosted on Cloudflare" is not the same as "never leaves your machine," so it is worth reading Cloudflare's privacy policy and Workers AI terms.

You also keep an exit. Settings → Privacy → Download backup exports conversations, memories, tasks, notes, projects, settings and automations as a single JSON file, never sessions or credentials. Importing validates the file and merges it in one transaction, so restoring the same backup twice is harmless.

Trying it locally

If you would rather poke around before deploying, local development needs only Node.js 20.18 or newer:

git clone https://github.com/rociiu/talorys.git
cd talorys
npm install
npm run dev

This starts the agent Worker, the Pages Function proxy and the Vite UI together, using a deterministic mock AI provider, so no Cloudflare login is required. The repo is a TypeScript monorepo with a Hono-based agent app, a React and Vite frontend, shared Zod schemas, the installer package, and Playwright end-to-end tests.

Who is it for?

Talorys fits people who want a private, low-maintenance assistant without running servers or paying for yet another subscription, and who already have, or are happy to create, a Cloudflare account. It is also a useful reference for anyone curious about building agents on Durable Objects, alarms and Workers AI.

A few things to weigh before adopting it. It is a small project so far, with 10 commits and 10 stars at the time of writing. It is deliberately single-user, so it will not suit teams. And chat quality depends on the Workers AI model it uses by default (GLM-4.7-flash) rather than a frontier model you pick yourself.

Still, the core idea is compelling: a personal agent you deploy in minutes, own completely, and can export or tear down whenever you like. If that appeals to you, the repository is at github.com/rociiu/talorys and it is MIT licensed.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

OpenAI's $20 Billion Revenue Gap: What the FT Report Means for the AI Race

Sanjay Singh — Sun, 11 Oct 2026 06:41:13 +0000

OpenAI's annualised revenue is about $20 billion lower than the figure that circulated last month, according to a Financial Times report published on 8 October. The company has recently told investors its revenue was approaching $50 billion on an annualised basis at the end of September, against the roughly $70 billion that the FT, Reuters and other outlets reported in late September.

The gap changes the AI revenue race. At $50 billion, OpenAI would sit below Anthropic's reported $65 billion annualised run rate; the earlier $70 billion figure would have put it ahead. Reuters said it could not independently verify the FT report, and OpenAI did not immediately respond to its request for comment.

How a $70 billion figure took hold

The FT traced the higher number to investors rather than to OpenAI. Reuters, summarising the FT report, said the discrepancy came from investors' attempts to compare OpenAI's annualised revenue directly with Anthropic's.

According to Yahoo Finance's summary of the FT report, investors first tried to work out whether OpenAI's sales had reached $40 billion in August. They then combined that estimate with the 70% revenue growth OpenAI had told them about, which landed them near $70 billion. Outlets including Reuters carried that figure in late September.

Why OpenAI's and Anthropic's numbers don't line up

The two companies do not count annualised revenue the same way. Per the FT, as relayed by Reuters, Anthropic includes revenue from sales made through cloud partners such as AWS and Google Cloud, while OpenAI does not.

Semafor reported in April, citing people familiar with the matter, that when a customer buys $1 of tokens through a cloud partner, OpenAI books its 20-cent cut while Anthropic books the whole dollar. One person familiar with the numbers put the gap at up to $8 billion in annualised revenue at the time. Because the partner percentages vary, Semafor noted normalising the two sets of figures is difficult.

The metric itself is also blunt. Reuters noted that annualised run rate often just multiplies one month's revenue by 12, and can mislead, even though fast-growing startups lean on it heavily.

Why it matters now

Both companies are heading towards public markets, where revenue claims face regulatory scrutiny. Reuters noted that listings could give Wall Street a clearer view of their finances, including whether their rapid growth is sustainable. Yahoo Finance reports that OpenAI's IPO is widely expected in early 2027, while Anthropic is rumoured to list before Thanksgiving, with its public S-1 prospectus expected any day.

TechCrunch framed the revenue question as part of a wider pressure on OpenAI to justify the scale of money behind it. The company raised $122 billion in a single round in March, and its leaked 2025 financials showed about $13 billion in revenue against much larger spending. Its IPO, once rumoured for this year, has been pushed back to early 2027.

What to watch

Even at $50 billion, OpenAI's latest figure is more than double the level its CFO, Sarah Friar, cited in January, when she said annualised revenue had passed $20 billion in 2025, up from $6 billion in 2024. The gap also shows how much these figures depend on who is counting, and how.

Three things will show how it settles:

OpenAI's response. OpenAI did not immediately respond to Reuters' request for comment, and Reuters could not verify the FT's account.
Anthropic's S-1. A public prospectus would show how it books revenue sold through AWS and Google Cloud.
A like-for-like basis. Whether analysts and the press start comparing the two companies on the same gross or net footing.

Sources

Figures come from press reports of the FT's account and have not been independently verified.

Reuters: OpenAI's annualized revenue $20 billion less than previously signaled, FT reports (8 October 2026)
Yahoo Finance: OpenAI's annualized revenue $20 billion lower than prior investor estimates (8 October 2026)
TechCrunch: OpenAI's revenue is reportedly $20 billion less than previously projected (8 October 2026)
Semafor: Anthropic is gaining on OpenAI's revenue, but hasn't yet eclipsed it (10 April 2026)
Reuters: OpenAI CFO says annualized revenue crosses $20 billion in 2025 (19 January 2026)
Financial Times original report (paywalled; summarised here via Reuters and TechCrunch)

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

NestJS Best Practices for 2026: A Practical Guide (Updated for NestJS 12)

Sanjay Singh — Sat, 10 Oct 2026 14:44:08 +0000

NestJS 12 came out on August 28, 2026, and it changes more than a normal major release. The core packages are now ESM. New projects get a different test and lint setup. You can validate requests with Zod. And the docs have a whole new section about reliability.

That means a lot of older "best practices" posts are now only half right.

So this is my list of what I'd do on a new NestJS project today. Each tip comes with the reason behind it and code you can copy. When something is my opinion and not an official rule, I'll tell you.

A quick note on the code: The examples use ESM style, which is what you get when you pick ESM in nest new. That means imports like ./app.module.js and a top-level await. If your project is CommonJS, drop the .js extensions and call bootstrap() without await.

Versions: To run a Nest 12 app you need Node.js 20.19+ or 22.12+. The CLI generators (nest new, nest generate, nest upgrade) need a newer Node: 22.22.3+, 24.15+ or 26+. The easy answer is to use the latest active LTS.

1. Set up the project on purpose

When you run nest new, the CLI now asks if you want a CommonJS or an ESM project. The choice changes your defaults:

	ESM project	CommonJS project
Test runner	Vitest	Jest
Linter	oxlint	oxlint or ESLint (sources disagree, see the note below)
Compiler	tsc	tsc
Bundler for monorepos	Rspack	Rspack

Heads up: The official sources don't fully agree on the linter. The migration guide says every generated project uses oxlint. The launch post says the CommonJS template keeps ESLint. Open your generated package.json and see what you actually got.

Here's how I'd decide:

New service, nothing legacy: pick ESM. You get the modern defaults from day one.
Existing app: upgrade the packages and stay on CommonJS until you have a real reason to switch.

Staying on CommonJS is fine because Nest's ESM packages can be loaded from CommonJS through require(esm). The upgrade command even leaves your module format alone.

# upgrade the CLI first, globally and locally
npm i -g @nestjs/cli@latest @nestjs/schematics@latest
npm i -D @nestjs/cli@latest @nestjs/schematics@latest

# see what would change without touching files
nest upgrade --dry-run

# then do it for real
nest upgrade

nest upgrade moves every @nestjs/* package to v12 at once. That part matters. Keep all Nest packages on the same major version, always. Mixed majors are a classic source of strange errors.

A few things can bite you during the upgrade:

Jest users: Jest can load the ESM-only v12 packages only on Node.js 24.9 or newer. Older versions fail with ERR_REQUIRE_ASYNC_MODULE. Use Node 24.9+ or move to Vitest.
AWS Lambda: The Node 20, 22 and 24 runtimes turn require(esm) off by default. A CommonJS Nest 12 app needs NODE_OPTIONS=--experimental-require-module.
TypeScript jumps to v6: nest upgrade raises typescript to ^6.0.0, and it bumps Jest to v30 and Joi to v18 as well. The upgrade schematic flags module: commonjs combined with legacy module resolution, and a missing rootDir in tsconfig.build.json (error TS5011). Budget time for new compiler errors.
Logger output changed: ConsoleLogger now treats extra object arguments as structured params by default. If anything parses your logs, set structuredParams: false to get the old output back.
Lifecycle hook order changed: Hooks like onModuleInit now run by component hierarchy level. If your code depends on the order between providers, test it.
@Optional() is no longer inherited: A subclass has to declare it again in its own constructor, or Nest throws UnknownDependenciesException.
Removed or replaced: the old Terminus health indicator API, subscriptions-transport-ws in GraphQL (use graphql-ws), and the old nats package (now @nats-io/transport-node).
Webpack is deprecated in CLI workflows. Rspack takes over for monorepos. tsc is still the default compiler.

And one rule I like: after upgrading, fix every deprecation warning in your console before you ship. They are cheap to fix now and expensive later.

2. Organize by feature, not by file type

The folder layout I'd start with:

src/
  main.ts
  setup-app.ts
  app.module.ts
  config/
    env.schema.ts
  auth/
    auth.guard.ts
    public.decorator.ts
  common/
    domain-error.ts
    domain-error.filter.ts
  database/
    ...
  users/
    users.module.ts
    users.controller.ts
    users.service.ts
    users.repository.ts
    db-users.repository.ts
    dto/
      create-user.dto.ts
  orders/
    ...
  payments/
    ...
  health/
    ...

Everything about "users" lives in users/. You don't hunt through controllers/, services/ and entities/ folders to change one feature.

Each feature is a module, and modules only talk through what they export:

My rules for modules:

Export as little as possible. Export the service other features need. Don't export repositories or internals.
Avoid one giant SharedModule. It slowly becomes a junk drawer that everything imports. Small, named modules age better.
Treat forwardRef() as a smell. If two modules need each other, the usual fix is a third module that holds what they share.

3. Put app-wide setup in one place

Here's a habit that saves a lot of "works on my machine" bugs. Put your global setup in one function, and call it from both main.ts and your end-to-end tests.

// src/setup-app.ts
import { ValidationPipe, type INestApplication } from '@nestjs/common';
import helmet from 'helmet';

/** App-wide setup. main.ts and the e2e tests both call this. */
export function setupApp(app: INestApplication) {
  app.use(helmet());
  app.enableCors({ origin: ['https://app.example.com'] });
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,
      forbidNonWhitelisted: true,
      transform: true,
    }),
  );
}

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { ConfigService } from '@nestjs/config';
import { AppModule } from './app.module.js';
import { setupApp } from './setup-app.js';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    routeConflictPolicy: { duplicate: 'error', shadow: 'warn' },
    routeResolutionStrategy: 'specificity',
  });

  setupApp(app);
  app.enableShutdownHooks();

  const config = app.get(ConfigService);
  await app.listen(config.getOrThrow<number>('PORT'));
}
await bootstrap();

I'll explain each line in the sections below. The reason for the shared function is simple: if your tests build the app without your global pipes, they test a different app than the one you ship.

Using Fastify? Use @fastify/helmet instead of helmet.

4. Keep controllers thin

A controller should do three things: read the input, call a service, return the result. No business rules. No database calls.

// src/users/users.controller.ts
import { Body, Controller, Get, Param, ParseUUIDPipe, Post } from '@nestjs/common';
import { Public } from '../auth/public.decorator.js'; // defined in the security section
import { CreateUserDto } from './dto/create-user.dto.js';
import { UsersService } from './users.service.js';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Public()
  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }

  @Get(':id')
  findOne(@Param('id', ParseUUIDPipe) id: string) {
    return this.usersService.findOne(id);
  }
}

// src/users/users.service.ts
import { ConflictException, Injectable, NotFoundException } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto.js';
import { UsersRepository } from './users.repository.js';

@Injectable()
export class UsersService {
  constructor(private readonly users: UsersRepository) {}

  async create(dto: CreateUserDto) {
    const existing = await this.users.findByEmail(dto.email);
    if (existing) {
      throw new ConflictException('Email is already in use', {
        errorCode: 'EMAIL_TAKEN',
      });
    }
    return this.users.insert(dto);
  }

  async findOne(id: string) {
    const user = await this.users.findById(id);
    if (!user) {
      throw new NotFoundException('User not found', { errorCode: 'USER_NOT_FOUND' });
    }
    return user;
  }
}

Careful with "check, then insert": Two requests can pass the findByEmail check at the same time. Keep a unique index on the email column and treat that database error as the real source of truth. The check in the service is just for a friendly message.

Know where each piece belongs

Nest gives you five tools that wrap a request. People mix them up all the time. This is how I think about them:

Tool	Its job	Typical use
Middleware	Low-level request work	Request IDs, raw body handling
Guard	"Is this caller allowed?"	Authentication, roles
Pipe	"Is this input valid? Convert it."	Validation, ParseUUIDPipe
Interceptor	Wrap the handler	Timing, response shaping, resilience
Exception filter	Turn errors into responses	A consistent error format

And this is the order they run in:

If you remember one thing from this picture: guards run before pipes. So a user who isn't allowed in never gets as far as validation.

The dotted lines show where errors go. An exception thrown by a guard, a pipe, an interceptor or the handler ends up in the exception filters. That's how the UnauthorizedException from the auth guard later in this post becomes a clean 401 response.

A route trap worth knowing

Nest registers routes in the order you declare them. On Express, this can quietly break a route:

@Get(':id')   // declared first, so it can swallow /users/me
findOne(@Param('id') id: string) {}

@Get('me')
me() {}

Version 12 adds two opt-in options to catch this, and I turned both on in main.ts above. routeConflictPolicy can warn or throw on shadowed and duplicate routes. routeResolutionStrategy: 'specificity' picks the most specific route. Both default to the old behavior, so nothing changes until you set them.

5. Let dependency injection stay boring

Nest providers are singletons by default, and that's what you want. This surprises people coming from other languages. Node.js doesn't handle each request in its own thread, so sharing one instance across requests is normally fine.

There is one rule: a singleton must not keep per-request state. If a provider stores "the current user" in a field, two overlapping requests will overwrite each other's value. Keep request data in method arguments, or use AsyncLocalStorage (more on that below).

Avoid request scope unless you really need it

You can make a provider request-scoped, so it gets a fresh instance per request. It's tempting. Here's why I avoid it.

Request scope bubbles up. If your CatsService is request-scoped, then the CatsController that uses it becomes request-scoped too. Now Nest creates and throws away that whole chain on every request. The docs say a well-designed app shouldn't pay more than about 5% latency for this, but "well-designed" is doing a lot of work in that sentence.

Most of the time you only want to read one value that belongs to the current request, like the user, the tenant or the locale. For that, use AsyncLocalStorage. Your providers stay singletons, and the value is still available anywhere downstream. It works the same in HTTP handlers, message handlers and queue jobs.

Multi-tenant app? Nest has "durable providers" for exactly this case. They let you share one DI sub-tree per tenant instead of rebuilding it per request. The docs warn it's not ideal with a very large number of tenants.

Inject by abstraction, not by concrete class

TypeScript interfaces disappear at runtime, so they can't be injection tokens. An abstract class works well instead, because it exists at runtime and still describes the contract:

// src/users/users.repository.ts
export interface User {
  id: string;
  email: string;
  displayName?: string | null;
}

export abstract class UsersRepository {
  abstract findById(id: string): Promise<User | null>;
  abstract findByEmail(email: string): Promise<User | null>;
  abstract insert(data: { email: string; displayName?: string }): Promise<User>;
}

DbUsersRepository is whatever implements that contract with your ORM. Here is the shape to fill in (the bodies are placeholders):

// src/users/db-users.repository.ts
import { Injectable } from '@nestjs/common';
import { type User, UsersRepository } from './users.repository.js';

@Injectable()
export class DbUsersRepository extends UsersRepository {
  // inject your ORM client here (Prisma, Drizzle, TypeORM, ...)

  async findById(id: string): Promise<User | null> {
    throw new Error('Implement with your ORM');
  }
  async findByEmail(email: string): Promise<User | null> {
    throw new Error('Implement with your ORM');
  }
  async insert(data: { email: string; displayName?: string }): Promise<User> {
    throw new Error('Implement with your ORM');
  }
}

// src/users/users.module.ts
import { Module } from '@nestjs/common';
import { DbUsersRepository } from './db-users.repository.js';
import { UsersController } from './users.controller.js';
import { UsersRepository } from './users.repository.js';
import { UsersService } from './users.service.js';

@Module({
  controllers: [UsersController],
  providers: [
    UsersService,
    { provide: UsersRepository, useClass: DbUsersRepository },
  ],
  exports: [UsersService],
})
export class UsersModule {}

Your service doesn't know or care which database sits behind UsersRepository. And in tests you swap it for a fake in one line. We'll use that in the testing section.

6. Validate every request at the edge

Rule: never trust anything that comes in over the network. Bind the validation pipe globally (we did that in setup-app.ts) so no endpoint is left unprotected by accident.

The three options in that pipe do real work:

whitelist: true strips any property that has no validation decorator.
forbidNonWhitelisted: true goes further and rejects the request instead of silently stripping.
transform: true turns plain payloads into DTO class instances and converts path and query values to the types you declared.

A DTO looks like this:

// src/users/dto/create-user.dto.ts
import { IsEmail, IsOptional, IsString, MaxLength } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsOptional()
  @IsString()
  @MaxLength(50)
  displayName?: string;
}

Four gotchas from the docs

Every property needs at least one decorator. With whitelist: true, a property with no decorator gets stripped. If your field "disappears," this is usually why.
Use concrete classes. TypeScript doesn't emit metadata for generics or interfaces, so the pipe can't validate them.
Don't use import type for DTO classes. Type-only imports are erased at runtime, and the pipe needs the real class. This rule is about classes. In the schema style below, the DTO is only a type and the schema is the real value, so import the schema normally and mark the type with the inline type modifier.
Arrays aren't validated by default. @Body() dtos: CreateUserDto[] skips the elements. Wrap the array in a class, or use ParseArrayPipe({ items: CreateUserDto }).

The new option in v12: schema validation

Nest 12 adds a second way to validate, built on the Standard Schema spec. That means Zod, Valibot, ArkType and others work out of the box. You pass the schema straight into the parameter decorator:

Zod version: These examples use the Zod 4 helpers like z.email() and z.url(). On Zod 3, write z.string().email() and z.string().url() instead.

// src/users/dto/create-user.dto.ts
// The schema-first version. Use this file instead of the class version above.
import { z } from 'zod';

export const createUserSchema = z.object({
  email: z.email(),
  displayName: z.string().trim().max(50).optional(),
});

export type CreateUserDto = z.infer<typeof createUserSchema>;

Now register the pipe. This step is not optional. The schema option only attaches the schema to the parameter. If you forget the pipe, the schema does nothing and the request goes through unchecked.

// src/setup-app.ts
import { StandardSchemaValidationPipe, ValidationPipe } from '@nestjs/common';

// Both pipes can be registered together. ValidationPipe checks class-typed
// parameters, and StandardSchemaValidationPipe checks parameters with a schema.
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
  }),
  new StandardSchemaValidationPipe(),
);

If a feature uses only schemas, the schema pipe alone is enough. Then use it in the controller:

// src/users/users.controller.ts
import { createUserSchema, type CreateUserDto } from './dto/create-user.dto.js';

@Post()
create(@Body({ schema: createUserSchema }) dto: CreateUserDto) {
  return this.usersService.create(dto);
}

The type comes from the schema, so you write the rules once and never keep a class and a type in sync. Coercion also works well for query strings:

export const listUsersQuerySchema = z.object({
  page: z.coerce.number().int().min(1).default(1),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  search: z.string().trim().optional(),
});

@Get()
findAll(@Query({ schema: listUsersQuerySchema }) query: z.infer<typeof listUsersQuerySchema>) {
  return this.usersService.findAll(query);
}

Notice the max(100) on limit. Always cap page sizes. An endpoint that lets a client ask for a million rows will eventually get that request.

One detail to remember: with Zod, z.object() strips unknown keys (like whitelist), and z.strictObject() rejects them (like forbidNonWhitelisted).

So which one should you pick?

	ValidationPipe + class-validator	StandardSchemaValidationPipe
Where the rules live	Decorators on a DTO class	A schema object
Where the type comes from	The class itself	Inferred from the schema
Making variants (create vs update)	PartialType, PickType, OmitType	.partial(), .pick(), .omit()
Fits best	Existing code and class-based DTOs (the Swagger CLI plugin reads classes)	Teams that already like schema-first, shared schemas

Choosing schemas doesn't mean giving up OpenAPI. Standard Schema schemas can feed OpenAPI generation too, so check the Swagger chapter for how to set that up.

The Nest team is clear that this is not a replacement. The docs still suggest class-validator as the default for most projects. According to the validation docs, both pipes can be registered at the same time. ValidationPipe only validates parameters typed with a class, and StandardSchemaValidationPipe only validates parameters that declare a schema. So you can adopt schemas one feature at a time. My opinion: pick one style per feature so your team doesn't have to switch mental models in the middle of a file.

Don't return your database objects

Whatever you validate on the way in, shape on the way out. Returning raw entities leaks columns like password hashes and internal flags. Use ClassSerializerInterceptor with class-transformer, or the new StandardSchemaSerializerInterceptor if you're going schema-first:

@UseInterceptors(StandardSchemaSerializerInterceptor)
@SerializeOptions({ schema: userResponseSchema })
@Get(':id')
findOne(@Param('id', ParseUUIDPipe) id: string) {
  return this.usersService.findOne(id);
}

7. Validate your config, too

A missing environment variable should crash your app at startup, not at 3 a.m. when the first request needs it.

@nestjs/config in v12 accepts any Standard Schema object for validationSchema, so Zod works directly. Keep the schema in its own file:

// src/config/env.schema.ts
import { z } from 'zod';

export const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.url(),
  JWT_SECRET: z.string().min(32),
});

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { envSchema } from './config/env.schema.js';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validationSchema: envSchema,
    }),
    // ...feature modules
  ],
})
export class AppModule {}

Then read values through ConfigService, not process.env:

const port = config.getOrThrow<number>('PORT');

Three habits I'd keep:

One place reads the environment. Everything else asks ConfigService.
Fail early and loudly. getOrThrow over get.
Never commit secrets. Real values come from your platform's secret store, not from a .env file in git.

Still using Joi? It keeps working, but you need Joi v18 or newer, and Joi-specific settings move under validationOptions.libraryOptions.

8. Make errors useful

Clients need to react to errors without parsing English sentences. Nest 12 helps with a new errorCode option on every HttpException:

throw new BadRequestException('Password is too weak', {
  errorCode: 'WEAK_PASSWORD',
});

The code is added to the response body. Your frontend can now do if (error.errorCode === 'WEAK_PASSWORD') and stop matching message strings. Message text can change. Codes shouldn't.

For bigger apps: keep HTTP out of your business code

If you want services that don't know about HTTP at all, throw your own domain errors and map them in one place:

// src/common/domain-error.ts
export class DomainError extends Error {
  constructor(
    message: string,
    readonly code: string,
    readonly httpStatus: number,
  ) {
    super(message);
  }
}

export class EmailTakenError extends DomainError {
  constructor() {
    super('Email is already in use', 'EMAIL_TAKEN', 409);
  }
}

// src/common/domain-error.filter.ts
import { ArgumentsHost, Catch, ExceptionFilter } from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';
import { DomainError } from './domain-error.js';

@Catch(DomainError)
export class DomainErrorFilter implements ExceptionFilter {
  constructor(private readonly httpAdapterHost: HttpAdapterHost) {}

  catch(error: DomainError, host: ArgumentsHost) {
    const { httpAdapter } = this.httpAdapterHost;
    const response = host.switchToHttp().getResponse();

    httpAdapter.reply(
      response,
      { statusCode: error.httpStatus, error: error.code, message: error.message },
      error.httpStatus,
    );
  }
}

// in a module, for example AppModule
import { APP_FILTER } from '@nestjs/core';

providers: [{ provide: APP_FILTER, useClass: DomainErrorFilter }],

Using HttpAdapterHost instead of response.status().json() keeps the filter working on both Express and Fastify.

My rule of thumb: small app, throw Nest's built-in exceptions with an errorCode. Growing app with lots of business rules, use domain errors and one filter.

9. Security basics you shouldn't skip

None of this is exciting. All of it matters.

Security headers and CORS. We set both in setup-app.ts. Always list your allowed origins. Don't leave CORS open "just for now."

Rate limiting. @nestjs/throttler is the official answer. In recent versions, ttl is in milliseconds:

import { APP_GUARD } from '@nestjs/core';
import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';

@Module({
  imports: [ThrottlerModule.forRoot([{ ttl: 60_000, limit: 100 }])],
  providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
})
export class AppModule {}

Use @Throttle() to set tighter limits on sensitive routes like login, and @SkipThrottle() for things like health checks.

Two traps. Behind a load balancer, every request can look like it comes from the proxy's IP. Fixing that takes two steps. First, tell the HTTP adapter to trust the proxy. Without this, req.ip and req.ips never contain the forwarded address, and no throttler override can use it:
// src/main.ts (Express)
import type { NestExpressApplication } from '@nestjs/platform-express';

const app = await NestFactory.create<NestExpressApplication>(AppModule, { /* ... */ });
app.set('trust proxy', 1); // the number of proxies in front of your app
Use a hop count or a subnet, not true. If your app is ever reachable without going through the proxy, clients can spoof X-Forwarded-For. On Fastify, set the adapter's trustProxy option instead. This goes in main.ts, not setupApp(), because INestApplication has no set() and your tests don't need it.

Second, have the throttler key on the forwarded address. Once trust proxy is set correctly, plain req.ip is often enough. If you need explicit control, extend the guard the way the docs do and register it in place of ThrottlerGuard:
// src/common/throttler-behind-proxy.guard.ts
import { Injectable } from '@nestjs/common';
import { ThrottlerGuard } from '@nestjs/throttler';

@Injectable()
export class ThrottlerBehindProxyGuard extends ThrottlerGuard {
  protected async getTracker(req: Record<string, any>): Promise<string> {
    return req.ips?.length ? req.ips[0] : req.ip;
  }
}
// providers: [{ provide: APP_GUARD, useClass: ThrottlerBehindProxyGuard }]
The other trap is that the default store is in memory, so with several instances each one counts on its own. For a shared limit, plug in a shared store.

Deny by default. Instead of remembering to protect every route, protect all of them and mark the open ones. This is the pattern from the official auth docs:

// src/auth/public.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

// src/auth/auth.guard.ts
import {
  CanActivate,
  ExecutionContext,
  Injectable,
  UnauthorizedException,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { JwtService } from '@nestjs/jwt';
import { IS_PUBLIC_KEY } from './public.decorator.js';

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,
    private readonly jwt: JwtService,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (isPublic) return true;

    const request = context.switchToHttp().getRequest();
    const [type, token] = request.headers.authorization?.split(' ') ?? [];
    if (type !== 'Bearer' || !token) throw new UnauthorizedException();

    try {
      request.user = await this.jwt.verifyAsync(token);
    } catch {
      throw new UnauthorizedException();
    }
    return true;
  }
}

Register it with { provide: APP_GUARD, useClass: AuthGuard }. Now a new endpoint is private until someone deliberately writes @Public(). That's the safe direction to fail in.

Two notes on this guard:

It assumes JwtModule is registered with a secret, for example with JwtModule.registerAsync reading JWT_SECRET from ConfigService. Without a secret, verifyAsync has nothing to check tokens against.
Global guards run in the order you register them. List ThrottlerGuard before AuthGuard, so a flood of bad requests gets rate-limited before you spend time verifying tokens.

A few more:

Hash passwords, don't encrypt them. Use a slow, salted hash like argon2 or bcrypt. The Nest docs have a chapter on this.
Authorization is not authentication. A valid token says who you are. It doesn't say you can touch this record. Check ownership in the service.
Turn on CSRF protection if you authenticate with cookies or sessions. Token-in-header APIs don't need it.
Keep secrets out of logs. Log IDs, not tokens or passwords.

10. Data access: a few habits that pay off

Nest doesn't force an ORM on you. The docs now have chapters for TypeORM, Prisma, Drizzle, MikroORM, Sequelize and MongoDB. Pick the one your team knows. These habits apply to all of them:

Hide the database behind a repository (like UsersRepository earlier). Services talk to the contract, not the library.
Use migrations. Never let the ORM auto-sync your schema in production. If you use TypeORM, make sure synchronize is off there.
Wrap multi-step writes in a transaction. If step two fails, step one should roll back.
Let the database enforce the rules. Unique indexes, foreign keys and not-null constraints are your last line of defense, and they never have race conditions.
Paginate everything that can grow, and cap the page size.
Select only the columns you need. It's less data over the wire and fewer accidental leaks.
Watch for N+1 queries. A loop that runs one query per item looks fine on 10 rows and falls over on 10,000.

11. Be kind to the things you call

Every app that calls another system will eventually meet one that is slow or down. Without a plan, your request handlers pile up waiting, and retries from every layer make the struggling service even worse.

The Nest docs now have a Reliability section, and its first chapter covers @nestjs/resilience. It gives you timeouts, retries, circuit breakers, bulkheads and fallbacks as decorators on your entry points (controllers, resolvers, message handlers and gateways).

npm i @nestjs/resilience

# only if you also want idempotency keys on POST routes (see the rules below)
npm i @nestjs/idempotency

Here's the idea in small form. Imagine checkout asks a shipping carrier for quotes. Import ResilienceModule once, in the root module (it's global):

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ResilienceModule } from '@nestjs/resilience';

@Module({
  imports: [
    ResilienceModule.forRoot({
      presets: {
        carrier: {
          timeout: '2s',
          retry: { attempts: 2 },
          circuitBreaker: {
            failureRateThreshold: 50,
            minimumCalls: 10,
            openDuration: '30s',
          },
        },
      },
    }),
    // ...feature modules
  ],
})
export class AppModule {}

// src/shipping/shipping.controller.ts
import { CircuitOpenError, Fallback, Resilience, Signal, Timeout } from '@nestjs/resilience';

@Get('quotes')
@Resilience('carrier')
@Timeout('1.5s')
@Fallback('flatRateQuotes', {
  handleIf: (error) => error instanceof CircuitOpenError,
})
getQuotes(@Query('orderId') orderId: string, @Signal() signal: AbortSignal) {
  return this.shippingService.getQuotes(orderId, signal);
}

flatRateQuotes() {
  return this.shippingService.flatRateQuotes();
}

What this does for you:

A slow carrier costs the route about 3.2 seconds at most (two 1.5-second attempts plus up to 200 ms of backoff), then it answers 504.
Once the carrier looks down, the breaker opens and calls fail fast instead of waiting.
While the breaker is open, customers see a flat shipping rate instead of an error.

The breaker moves between three states:

The rules that keep this safe

These come straight from the docs, and they're worth printing out:

The decorators only work on entry points. That means controllers, resolvers, message handlers and gateways. On a service method they do nothing, and Nest logs a warning at startup. The next section shows what to use inside services.
Pass the signal to every I/O call. When a timeout fires, the signal aborts. If your code ignores it, the work keeps running in the background.
Retries only apply to safe requests by default. On HTTP that's GET, HEAD and OPTIONS. A POST retry is skipped unless you say @Retry({ idempotent: true }), which means "running this twice is harmless."
Protect client retries with idempotency keys. @Idempotent() from @nestjs/idempotency returns the stored response when a client repeats a request with the same Idempotency-Key. Register IdempotencyModule before ResilienceModule, because the first global interceptor runs outermost. Also register a shared idempotency store before you go to production. Without one, the records live in each process's memory and are lost on every deploy, and the docs say production refuses to start.
Retry at one layer only. A route that retries 3 times, calling a service that retries 3 times, calling an SDK that retries 3 times, can send 27 requests to something that's already struggling.
State lives in each process. With several instances, every one has its own breakers and bulkheads.
Every breaker needs a timeout. A breaker only learns from calls that finish. A call that hangs forever is never counted.

Calls inside services

A background job, or any service that calls another system on its own, isn't an entry point. For those, get a policy object from ResilienceService. resilience.preset('carrier') gives you the same carrier preset, and it shares the breaker the routes use. So a job that finds the carrier failing also protects checkout, and the other way around.

// src/shipping/repricing.service.ts
import { Injectable } from '@nestjs/common';
import { ResilienceService, type ResiliencePolicy } from '@nestjs/resilience';
import type { Order } from '../orders/order.js'; // stand-in: your own order type
import { CarrierClient } from './carrier.client.js'; // stand-in: your own carrier client

@Injectable()
export class RepricingService {
  private readonly policy: ResiliencePolicy;

  constructor(
    resilience: ResilienceService,
    private readonly carrier: CarrierClient,
  ) {
    // Create the policy once, not on every call.
    this.policy = resilience.preset('carrier');
  }

  getQuotes(order: Order) {
    return this.policy.execute(
      ({ signal }) => this.carrier.getQuotes(order, signal),
      { source: 'RepricingService.getQuotes' },
    );
  }
}

One detail to know: a policy object has no GET or POST to look at, so the preset's retry always applies. Only wrap calls that are safe to repeat.

More official building blocks worth knowing

Need	Where to look
Write to your database and publish a message without losing either	Transactional outbox chapter
Run a scheduled job on only one instance	Distributed locks (@nestjs/locks)
Send transactional email	Mail (@nestjs/mail)
Store files on disk or S3-compatible storage	File storage (@nestjs/storage)

I haven't covered these in depth here. Check each chapter before you commit to one, since several are new.

12. Health checks, logs and a clean shutdown

Health checks

Add a health endpoint with @nestjs/terminus so your platform knows when to restart or stop sending traffic. In v12, custom indicators use HealthIndicatorService. The old approach of throwing HealthCheckError was removed.

// src/health/payments.health.ts
import { Injectable } from '@nestjs/common';
import { HealthIndicatorService } from '@nestjs/terminus';
import { PaymentsClient } from '../payments/payments.client.js';

@Injectable()
export class PaymentsHealthIndicator {
  constructor(
    private readonly healthIndicatorService: HealthIndicatorService,
    private readonly payments: PaymentsClient,
  ) {}

  isHealthy(key: string) {
    return this.healthIndicatorService
      .check(key)
      .attempt(() => this.payments.ping())
      .withTimeout(1000);
  }
}

// src/health/health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { HealthCheck, HealthCheckService } from '@nestjs/terminus';
import { SkipThrottle } from '@nestjs/throttler';
import { Public } from '../auth/public.decorator.js';
import { PaymentsHealthIndicator } from './payments.health.js';

@Controller('health')
export class HealthController {
  constructor(
    private readonly health: HealthCheckService,
    private readonly payments: PaymentsHealthIndicator,
  ) {}

  @Public()
  @SkipThrottle()
  @Get()
  @HealthCheck()
  check() {
    return this.health.check([() => this.payments.isHealthy('payments')]);
  }
}

// src/health/health.module.ts
import { Module } from '@nestjs/common';
import { TerminusModule } from '@nestjs/terminus';
import { PaymentsModule } from '../payments/payments.module.js'; // must export PaymentsClient
import { HealthController } from './health.controller.js';
import { PaymentsHealthIndicator } from './payments.health.js';

@Module({
  imports: [TerminusModule, PaymentsModule],
  controllers: [HealthController],
  providers: [PaymentsHealthIndicator],
})
export class HealthModule {}

Notice that the health route is @Public() and skips rate limiting. Your load balancer needs to hit it constantly without a token.

My opinion: split it into two routes. A liveness route that only says "the process is up," and a readiness route that also checks the database and other dependencies. That way a slow third party doesn't make your platform kill a perfectly healthy process.

Logs

Plain text logs are hard to search. Switch the built-in logger to JSON:

import { ConsoleLogger } from '@nestjs/common';

const app = await NestFactory.create(AppModule, {
  logger: new ConsoleLogger({ json: true }),
});

In v12 you can also attach structured data to a message, and it stays in one log entry. This is on by default (see the upgrade notes in section 1 if you need the old output back):

this.logger.log('User signed in', { userId: 1, method: 'oauth' });

In JSON mode the extra values sit under a params key. Turn on flattenParams if your log tool prefers them at the top level.

Whatever you log, add a request ID so you can follow one request across many lines. AsyncLocalStorage is a good home for it.

Tracing and error monitoring

If you want tracing and error monitoring, Nest 12 promotes @nestjs/observe. Know what you're opting into: the SDK sends telemetry to NestJS Observe, a hosted dashboard at observe.nestjs.com. You sign up, get an app key and secret (keep them in your secret store), and pick a plan. Features are tiered (for example, log forwarding needs Pro or above), so read the pricing page and the terms before you commit.

Two defaults are worth knowing before you turn it on:

Log forwarding is off by default.
Error source context is on by default. When the SDK captures an error, it attaches a few lines of your application source around each stack frame and sends them to the dashboard. If shipping any source code is not acceptable for your codebase, set sourceContext: false in createObserveModule().

It's optional. nest new --observe and nest upgrade --observe can set it up for you, and OpenTelemetry still works if that's already your setup.

Shutdown

Call app.enableShutdownHooks() (we did, in main.ts) so OnModuleDestroy and OnApplicationShutdown run when your platform sends SIGTERM. Without it, connections and queues may not close cleanly during a deploy.

New in v12: the Express adapter now drains in-flight requests before the process exits.

13. Test the way Nest wants you to

Nest's DI makes testing easy, as long as you actually use it. I split tests into two kinds.

Unit tests: the service and a fake

import { ConflictException } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import { beforeEach, describe, expect, it, vi } from 'vitest';
import { UsersRepository } from './users.repository.js';
import { UsersService } from './users.service.js';

describe('UsersService', () => {
  let service: UsersService;
  const repo = { findById: vi.fn(), findByEmail: vi.fn(), insert: vi.fn() };

  beforeEach(async () => {
    vi.resetAllMocks();
    const moduleRef = await Test.createTestingModule({
      providers: [UsersService, { provide: UsersRepository, useValue: repo }],
    }).compile();
    service = moduleRef.get(UsersService);
  });

  it('rejects a duplicate email', async () => {
    repo.findByEmail.mockResolvedValue({ id: '1', email: 'a@b.co' });

    await expect(service.create({ email: 'a@b.co' })).rejects.toBeInstanceOf(
      ConflictException,
    );
    expect(repo.insert).not.toHaveBeenCalled();
  });
});

No database, no network. This runs in milliseconds, so you can have hundreds of them.

End-to-end tests: the real app, with the outside world stubbed out

AppModule validates its config at startup (section 7), so the test process needs the variables your schema demands. With Vitest you can set them in the config:

// vitest config
test: {
  env: {
    NODE_ENV: 'test',
    DATABASE_URL: 'postgres://test:test@localhost:5432/test',
    JWT_SECRET: 'test-secret-that-is-at-least-32-characters',
  },
},

The database needs the same care. Replacing UsersRepository with a fake doesn't stop an imported database module from trying to connect. Either override its connection provider, as below, or point DATABASE_URL at a throwaway test database. The second is closer to production, and slower.

import type { INestApplication } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import request from 'supertest';
import { afterAll, beforeAll, describe, it } from 'vitest';
import { AppModule } from '../src/app.module.js';
import { DATABASE_CONNECTION } from '../src/database/database.constants.js'; // stand-in: use the token your database module exposes
import { setupApp } from '../src/setup-app.js';
import { UsersRepository } from '../src/users/users.repository.js';

describe('POST /users', () => {
  let app: INestApplication;
  const fakeRepo = {
    findById: async () => null,
    findByEmail: async () => null,
    insert: async (data: object) => ({ id: 'u1', ...data }),
  };

  beforeAll(async () => {
    const moduleRef = await Test.createTestingModule({ imports: [AppModule] })
      .overrideProvider(UsersRepository)
      .useValue(fakeRepo)
      .overrideProvider(DATABASE_CONNECTION)
      .useValue({})
      .compile();

    app = moduleRef.createNestApplication();
    setupApp(app); // same global setup as production
    await app.init();
  });

  afterAll(() => app.close());

  it('rejects fields we did not ask for', () =>
    request(app.getHttpServer())
      .post('/users')
      .send({ email: 'a@b.co', isAdmin: true })
      .expect(400));
});

This test only means something because of setupApp(app). Without it, the unknown isAdmin field would sail through.

A few notes:

@nestjs/testing is test-runner agnostic. Vitest, Jest, whatever you like.
If you set up Vitest by hand, remember that Nest's DI needs decorator metadata, and not every transformer emits it. Starting from a generated project saves you this headache.
Test the unhappy paths: invalid input, missing auth, duplicate data, a dependency that times out. The happy path usually works already.

14. Performance without drama

I'll keep this short, because most Nest performance problems aren't framework problems.

Keep request scope rare. We covered this in section 5.
Don't block the event loop. Heavy CPU work (image processing, big reports, password hashing in loops) should move to a queue or a worker. The docs have a Queues chapter.
Cache what's expensive and rarely changes, using Nest's caching module, and always decide how it expires.
Measure before switching to Fastify. Nest has an official Fastify adapter and a performance chapter. It can help, but profile first so you're fixing the real bottleneck.
Build faster in development with the SWC recipe if your compile times are slowing you down.

The checklist

Copy this into your team's wiki:

Area	Do this
Setup	Pick CJS or ESM on purpose. Keep all @nestjs/* on one major version.
Structure	Feature modules. Small exports. No giant SharedModule.
App setup	One setupApp() used by main.ts and tests.
Controllers	Thin. Input in, service call, result out.
DI	Singletons by default, with no per-request state. Abstract classes as tokens. AsyncLocalStorage over request scope.
Validation	Global pipe with whitelist, forbidNonWhitelisted, transform. If you use schemas, register StandardSchemaValidationPipe. Cap page sizes.
Config	Validated at startup. Read through ConfigService.
Errors	errorCode on exceptions, or domain errors with one filter.
Security	Helmet, explicit CORS, rate limiting (with trust proxy behind a load balancer), deny-by-default auth, hashed passwords.
Data	Repository, migrations, transactions, unique indexes.
Reliability	Timeouts (decorators on entry points, policy objects in services), safe retries, a breaker per dependency, idempotency keys with a shared store for POST.
Operations	Health route, JSON logs, shutdown hooks.
Testing	Fast unit tests, a few e2e tests that use setupApp() and a stubbed or throwaway database.

Wrapping up

If you only do three things after reading this, do these:

Put your setup in one setupApp() and use it in your tests.
Validate input and config, so bad data fails early and loudly.
Put a timeout on every call to something you don't control. Use the decorators on entry points and a policy object inside services.

NestJS 12 is a good moment to clean house. The framework is moving to ESM, the tooling is getting lighter, and the docs now cover production concerns that used to need extra research.

What would you add to this list? Let me know in the comments.

Sources and further reading

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

OpenAI Is Putting an Invisible Watermark on ChatGPT Text in the EU

Sanjay Singh — Thu, 08 Oct 2026 02:54:50 +0000

Soon, text written by ChatGPT for people in the EU will carry a mark you can't see.

OpenAI is adding an invisible watermark to text from ChatGPT and Codex for eligible users across the European Union. The rollout starts over the next few weeks, with no exact date given. It's the first time ChatGPT's text will carry a built-in mark. OpenAI has had a text watermarking method in the works since at least 2024 and held it back. What changed is the law.

Why now

The EU AI Act requires providers of generative AI to make their output identifiable by machines. That duty sits in Article 50, which started applying on August 2. Services that were already on the EU market before that date get until December 2 to start marking their output. Newer systems had to comply from launch.

OpenAI says the watermark is its response to the law. It doesn't point to a specific deadline.

It isn't the first to do this. Anthropic began marking text from its newer models in early August, and Google already ships SynthID for text. Until now, ChatGPT shipped without one.

What changes for you

If you use ChatGPT or Codex in the EU, on any plan, eligible text you generate will start carrying the mark. You won't notice anything. The words and formatting look the same.

If you're outside the EU, ChatGPT stays as it is for now. OpenAI says it isn't making watermarking a global default at launch and wants to learn from the EU rollout first.

For developers, API customers anywhere can switch watermarking on for select models starting now. It's off by default. OpenAI is also working with cloud partners to offer it through their platforms in the coming weeks.

How it works

OpenAI calls its method textGrain. A language model picks each word from a range of reasonable options. textGrain nudges those choices in a statistical pattern, and a matching detector looks for that pattern later.

The signal lives in the word choices themselves, not in hidden characters or file metadata. Copying and pasting the text won't remove it. Changing the words can.

OpenAI also says the watermark doesn't hurt quality. On its latest model, Astra, benchmark scores with and without the mark stayed within a few points of each other, some slightly up and some slightly down. On GPQA Diamond, for example, it scored 94.44% unmarked and 93.94% marked.

The limits

OpenAI is fairly direct about where this falls short.

Length matters. With the detector tuned to wrongly flag about 1% of unmarked text, it caught the watermark in roughly 80% of 200-token passages and 95% of 400-token passages (about 150 and 300 words). Those were explanatory answers on psychology. On math, where there's less freedom in word choice, detection was much lower.

Editing hurts more. On 400-token passages, swapping 10% of the words for synonyms dropped detection from about 92% to 66%. Swapping 25% dropped it to 17%. Translated text is also harder to detect.

So a missing watermark tells you very little. OpenAI says so itself: no detected watermark doesn't prove a human wrote the text. It could be short, edited, translated, from an older or unsupported model, or from another company's tool.

A watermark that is present has limits too. It can show that an OpenAI system generated or processed part of a passage. It can't tell you how much a person contributed, who owns the text, who is responsible for it, or whether it's accurate. It doesn't identify the user, and it isn't tied to any account, prompt or conversation.

Who can check for it

Not you, at least for now. The detector isn't public. OpenAI opened applications for approved researchers and expert organizations, and will grant access case by case. The tool reports whether it finds an OpenAI watermark, without identifying the user or revealing prompts.

OpenAI says it will widen access once results can be interpreted responsibly, and plans to release the technology as open source so others can build on it. Images and audio are different. OpenAI's verification tools for those are already public.

Why OpenAI waited

In 2024, the Wall Street Journal reported that OpenAI had a text watermark ready but hadn't launched it. OpenAI replied that the method worked well on unedited text but could be beaten by translation or by having another model reword the passage. It also worried about stigmatizing non-native English speakers who use AI as a writing aid. A survey reported at the time found about 30% of ChatGPT users said they'd use it less if it watermarked text.

The new announcement shows the same caution. The EU-only rollout follows the law, and the detector is locked down because of the reliability gaps above.

What to take from this

Users in the EU: nothing to do. Just don't read a watermark result, or its absence, as proof of who wrote something.
Teachers and editors: you can't run the detector, and OpenAI says a result wouldn't measure how much a person contributed anyway.
Businesses publishing for EU audiences: machine-readable provenance for text is now something to plan around.
Developers: the opt-in is available today. Decide whether your own transparency duties call for it.

A few things are still open: the exact EU rollout date, the updated technical report and open-source release, and whether OpenAI extends the mark beyond Europe. For now it's a first step, with limits spelled out, from a company that spent years deciding whether to ship it.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

DEV Community: Sanjay Singh

How to Use a Custom Domain for Your ZyVOP Publication

1. System Architecture: Decoupled Identity & Edge Ingress

The Dual-Engine Ingress Strategy

2. Step-by-Step Configuration Guide

Step 1: Open the Publication Routing Hub

Step 2: Enter Your Domain

Step 3: Configure Your DNS Provider

Standard Subdomain Record (CNAME):

Root / Apex Domain (When Direct Apex is Enabled):

Step 4: Verify and Activate

3. Edge Routing and First-Class Protocols

4. Canonical SEO: Mode A vs. Mode B

Mode A: Full 301 Permanent Migration

Mode B: Network-Integrated (Discovery + Canonical Ownership)

5. Multi-Domain Support & Host Normalization

6. The Downgrade Grace Period: Zero Broken Backlinks

7. Custom Domain Pre-Flight Checklist

Conclusion: Build on Land You Own

Publish from Git to ZyVOP with GitHub Actions

Why publish from Git

What you need

Step 1: Add a post with frontmatter

Step 2: Store your token as a secret

Step 3: Add the workflow

Alternative: call the CLI yourself

Step 4: Check posts on pull requests

Habits that keep it safe

Troubleshooting

Wrap-up

Further reading

Docker vs PM2: Which One Does Your Node App Actually Need?

What PM2 does

What Docker does

Where they overlap

The cluster mode question

Deployments and zero downtime

When things go wrong

Shutdown is your job

Logs and monitoring

Using them together

So which one should you pick?

Zero-Friction Migration: How to Import Your Existing Developer Blog into ZyVOP

1. Migration Support Matrix

2. Ingestion Pipelines: How It Works Under the Hood

A. Direct APIs (DEV & Hashnode)

B. Universal RSS / Atom (Ghost, Substack, Medium)

C. Direct Web Article Extractor

D. Static-Site Markdown Archives (ZIP)

3. Duplicate Detection: Preventing Content Overwrites

4. How to Migrate: Step-by-Step

Option 1: Web Dashboard (Zero Installation)

Option 2: Uploading a Static Site ZIP

Option 3: Terminal Migration via the CLI (zyvop import)

5. Preflight Audits: The ZyVOP Compatibility Lab

6. Post-Migration: Establishing Sovereign GitOps

Building Production Subscriptions with Razorpay: Webhooks, Signatures, and Edge Cases

1. The Two Indian Payment Realities: Subscriptions vs. Orders

The Dual-Mode Architecture

2. The Flipped Signature Verification Trap

The Order Signature Payload

The Subscription Signature Payload

Constant-Time Verification

3. Fastify & NestJS: Preserving Raw Buffers for Webhooks

Why Naive NestJS/Fastify Implementations Fail

The Fix: Fastify Raw Body Preservation

4. The Client-Server Handshake & Race Conditions

The Race Condition Failure Modes

Solution: Idempotent Webhook Storage with 23505 Handling

5. Preventing Configuration Drift on Startup

6. Prorations, Subunit Math, and Refunds

Never Use Floating Point for Currency Math

Issuing the Refund via API

7. Status Mapping & The "Halted" Trap

8. Summary Checklist for Production

How to Publish One Technical Article to Dev.to, Hashnode, Medium, and WordPress (Without Losing Your SEO)

The 2-Hour Copy-Paste Tax

The Four Mechanical Failure Points of Manual Syndication

1. SEO Cannibalization & Canonical Disasters

2. AST Transformation & Code Fence Collisions

Option 3: Terminal Migration via the CLI (`zyvop import`)

Solution: Idempotent Webhook Storage with `23505` Handling

Method 1: The GitOps & CLI Workflow (`npx zyvop`)

Step 1: Install or Run Directly via `npx`

Zero-Trust Local Mode (`--local`)

3. GitOps & CLI Workflows (`npx zyvop`)