Forem: Sumeet Shroff Developer

Deploy Next.js on cPanel/WHM with Phusion Passenger

Sumeet Shroff Developer — Sun, 08 Feb 2026 02:11:49 +0000

Step-by-step practical guide to host production Next.js apps on cPanel/WHM with Phusion Passenger — covers architecture, prerequisites, build/start scripts, deployment, SSL, and troubleshooting.

! Deploy Next.js on cPanel/WHM with Phusion Passenger

Quick summary

Use Passenger to run Next.js SSR or a custom server on cPanel/WHM without a separate Node host.
Choose SSR (next start / custom server) or static export (next export) depending on features and hosting limits.
Validate Node versions, prepare build/start scripts, set process.env.PORT, and use cPanel’s Node.js manager when available.

Why this approach

This guide shows practical, repeatable steps to run production Next.js on cPanel/WHM using Phusion Passenger. It targets developers with cPanel accounts and host admins running WHM. The goal: get SSR or a production Node server working reliably on shared or managed hosting when Passenger is available.

Architecture overview

Next.js: can run as SSR (Node server) or as a static export. SSR requires a Node runtime.
Node.js: executes the Next.js server code.
Phusion Passenger: spawns and manages Node processes behind Apache or nginx, forwarding HTTP requests.
cPanel/WHM: controls domains, SSL, and (sometimes) a Node.js app manager that hides Passenger details.

Request flow (typical Apache + Passenger)

Browser requests https://example.com.
Apache routes the request to Passenger, which manages the Node process.
Passenger starts your startup file; your app listens on process.env.PORT.
Next.js handles rendering and responds via Passenger.

Decide SSR vs static export

SSR: required for getServerSideProps, server-side APIs, or dynamic per-request rendering.
Static export: best for fully static sites (no Passenger needed, simplest on shared hosting).

Preparation checklist

Confirm Passenger is available via cPanel or WHM (ask support if unsure).
Confirm available Node versions match your Next.js requirements (Node 16/18/20 are common).
Prefer SSH access for builds and installs; cPanel UI can help but SSH simplifies reproducible deploys.
If you manage the server, plan to enable Passenger through WHM/EasyApache for a supported install.

Prepare your Next.js app for production

Repository layout (recommended):

next-app/
- package.json
- server.js <-- startup file for Passenger (SSR)
- next.config.js
- pages/ or app/
- public/
- .env.production

Add clear scripts in package.json so Passenger runs the correct production command. Example package.json snippets:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "NODE_ENV=production node server.js",
    "export": "next build && next export"
  }
}

A minimal server.js must honor process.env.PORT so Passenger can route requests to the correct socket/port. Example:

const http = require('http');
const next = require('next');

const app = next({ dev: false });
const handle = app.getRequestHandler();

app.prepare().then(() => {
  const server = http.createServer((req, res) => {
    handle(req, res);
  });

  const port = process.env.PORT || 3000;
  server.listen(port, (err) => {
    if (err) throw err;
    console.log(`> Next.js server started on port ${port}`);
  });
});

// Optional: Graceful shutdown hooks
process.on('SIGINT', () => process.exit(0));
process.on('SIGTERM', () => process.exit(0));

Notes:

Use NODE_ENV=production and build with next build before starting.
For fully static sites, run next export and upload the out/ folder into public_html; no Passenger needed.
Build locally or on the server. If native modules exist, building on the server avoids binary mismatches.

Enabling Phusion Passenger in WHM

Preferred: use WHM → EasyApache 4 to enable the Passenger Apache module. Steps:

Log into WHM, open EasyApache 4, Customize, add Passenger (if provided), and provision.
Restart Apache: sudo systemctl restart httpd

If EasyApache doesn’t provide the module, follow Phusion's official installer (advanced). Avoid mixing manual gem installs with EasyApache-managed modules.

Verify installation (root/WHM):

Check Apache modules and passenger utilities with passenger-status and passenger-memory-stats.
Tail Apache logs: see where errors land and confirm Passenger loaded successfully.

Deploy: upload, install deps, build, and run

Common flow (two options: cPanel Node manager or manual Passenger vhost):

1) Prepare start scripts

Either use next start -p $PORT or a server.js wrapper that listens on process.env.PORT.
Example start script in package.json: "start": "node server.js" or "next start -p $PORT".

2) Upload your project

Use Git (recommended), SFTP, or File Manager. Keep the app outside public_html when possible.

3) Install and build on the server (SSH):

Use package manager commands to install production deps and build the app:

cd ~/next-app
npm ci --only=production --no-audit --progress=false
npm run build

4) Configure the cPanel Node.js App manager (if available)

Create an app, select Node version, set app root and startup file (server.js or package.json start), add env vars, then Start.

5) Or configure Passenger via vhost include

Add PassengerAppRoot, PassengerNodejs (optional), and PassengerAppEnv to a vhost include and restart Apache.

6) Start and verify

cPanel: click Start or Restart.
Passenger spawns the app on first request (or on start depending on settings). Check logs for errors.

Useful server commands (root or account as allowed):

Tail webserver logs and Passenger status:

tail -f /usr/local/apache/logs/error_log

passenger-status
passenger-memory-stats
passenger-config restart-app /home/username/path/to/app --ignore-app-not-running

And to follow application logs:

cd ~/path/to/app
tail -f ./npm-debug.log ./next.log ./logs/*.log

Domains, env vars, and SSL

Map your domain/subdomain to the app root or symlink into the domain DocumentRoot.
Passenger provides process.env.PORT; your app must respect it.
Set environment variables via cPanel’s Node.js manager, SetEnv in vhost, or a secure server-side secret store. Avoid committing .env files.
Use cPanel/WHM AutoSSL to install certificates; Passenger works behind Apache’s SSL termination. Redirect 80 → 443 and add HSTS when appropriate.

Troubleshooting checklist

Common symptoms and fixes:

502/503: app failed to start — ensure npm install && npm run build ran and that the startup file listens on process.env.PORT.
Missing modules: reinstall node_modules on the server (npm ci) and match Node versions.
Dev server running: ensure you’re not running next dev; use next start or node server.js in production.
Permissions: set correct owner (chown -R username:username) and file modes (644/755).

Example package.json start scripts for clarity:

"scripts": {
  "build": "next build",
  "start": "next start -p $PORT"
}

If you cannot access required logs on a shared host, include log excerpts and steps taken when contacting support.

Case study: shared cPanel deploy (short)

Steps taken:

Clone or upload a minimal Next.js app to /home/username/nodeapps/my-next-app:

git clone https://github.com/vercel/next.js.git
cd next.js/examples/basic-css
npm install
npm run build

Build on the server:

npm ci
npm run build

Configure cPanel Node manager to use server.js or next start -p $PORT and start the app.
Example custom server (Express + Next) can be used if needed:

// server.js
const express = require('express')
const next = require('next')

const dev = false
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  const server = express()
  server.get('*', (req, res) => handle(req, res))

  const port = parseInt(process.env.PORT, 10) || 3000
  server.listen(port, err => {
    if (err) throw err
    console.log(`> Ready on http://localhost:${port}`)
  })
})

Common fixes discovered: avoid dev server, rebuild native modules on the server, fix file ownership and permissions.

Conclusion

Running Next.js on cPanel/WHM with Phusion Passenger is a practical option for smaller SSR apps when Passenger is available. Validate Node versions, prepare a production build, use a startup script that honors process.env.PORT, and prefer building on the server when native modules exist. For larger scale, consider migrating to a platform designed for Node.js scaling.

Call to action
Try the steps above on a staging subdomain first. If you need help adapting a project or automating deployment, reach out for assistance.

Home: https://prateeksha.com
Blog: https://prateeksha.com/blog
Canonical: https://prateeksha.com/blog/deploy-nextjs-cpanel-phusion-passenger

Next.js Advanced FAQs: Fonts, Images, i18n, Security & Headless Shopify

Sumeet Shroff Developer — Sun, 08 Feb 2026 02:10:16 +0000

Quick summary

Reduce CLS by using Next.js font optimization and proper font-display.
Configure next/image for remote CDNs and optimize product images for ecommerce.
Use i18n routing, hreflang, and translated meta for multilingual SEO.
Keep secrets out of the client, use HTTP-only cookies for auth, and prefer edge-safe Middleware.
Choose Server Actions or Route Handlers based on complexity; prefer direct-to-storage uploads for files.
For headless Shopify, combine SSG/SSR, canonical tags, structured data, and image optimizations.

Overview

This post collects practical solutions to advanced Next.js questions you’ll face as projects scale. Topics include performance (fonts/images), SEO for ecommerce, internationalization, security (env vars and auth), file uploads, Middleware guidance, and approaches for headless Shopify builds. Each section gives focused guidance you can apply quickly.

Fonts: reduce CLS and improve load

Why CLS happens: late-loading custom fonts cause layout shifts when the fallback text is replaced.

How to address it:

Use Next.js built-in font utilities (next/font) to load fonts locally or from Google Fonts.
Preload critical fonts so the browser fetches them early.
Use font-display: swap to show fallbacks until the custom font is ready.
Prefer subsets (latin, latin-ext) for lower payloads.
Consider variable fonts when appropriate for fewer files.

Result: fewer layout shifts and faster perceived rendering.

Remote images with next/image

To serve images from Shopify, Cloudinary, or other CDNs:

Whitelist domains in next.config.js via images.domains or use images.remotePatterns for complex patterns.
Example entries include your Shopify CDN host and any third-party image services.

Benefits:

next/image will handle automatic resizing, format negotiation (WebP/AVIF when available), and optimization.
Keep CDN and cache headers configured for long-lived caching where appropriate.

Ecommerce image optimization

Product pages are image-heavy; optimize with these rules:

Always set width and height (or use layout options) to avoid layout shifts.
Mark above-the-fold images with priority.
Use responsive sizes and srcset via next/image.
Serve modern formats (WebP/AVIF) while falling back to JPEG/PNG for older browsers.
Compress at source when possible (Cloudinary/Shopify transformations).
Lazy-load non-critical images.

These steps reduce page weight, speed render time, and help conversions.

i18n routing in the App Router

Next.js supports locale-aware routing through next.config.js i18n settings. With the App Router:

Define locales and defaultLocale.
Next.js generates locale-prefixed routes (e.g., /en/, /hi/).
Implement language switchers that update routes, not just UI strings.

SEO tips:

Add hreflang tags to pages to signal language/region versions to search engines.
Ensure your sitemap lists all localized URLs.
Translate meta tags and structured data for each locale.

Securing environment variables and secrets

Keep secrets out of your repository:

Use .env.local for local development and never commit it.
Only prefix variables with NEXT_PUBLIC_ when they must be exposed to the browser.
Store API keys, DB credentials, and other secrets without NEXT_PUBLIC_ so they remain server-only.
Use your host’s environment variable UI (Vercel, Netlify, etc.) for production values.
Rotate keys periodically and limit scope/permissions.

Authentication: cookies vs tokens

Best practices:

Prefer HTTP-only cookies to store session tokens to mitigate XSS exposure.
If using JWTs, store them in HTTP-only cookies rather than localStorage.
Use secure, SameSite, and proper expiration settings on cookies.
Consider NextAuth.js or a similar library for standard flows (OAuth, email, credentials).
Use refresh tokens and short-lived access tokens for better control.

Balance security and UX: choose approaches that fit your threat model and scale.

When to use Middleware

Good use cases:

Lightweight auth checks and redirects.
Locale detection and routing.
A/B tests or header-based experiments.

What to avoid:

Heavy CPU tasks, long-running database calls, or complex business logic. Middleware runs at the edge and needs to be fast.

Pattern: keep Middleware thin and push heavy operations to server functions or external services.

Server Actions vs Route Handlers

Pick based on needs:

Server Actions: convenient for simple forms and mutations tightly coupled to UI. They let you keep logic closer to components.
Route Handlers (API routes): preferred for complex APIs, heavy integrations, or when a clear backend contract is needed.

Guideline: use Server Actions for simple CRUD tied directly to UI; use Route Handlers for third-party APIs, complex validation, or when multiple clients will consume the endpoint.

Handling file uploads

Recommended approaches:

Direct-to-storage: have the client upload directly to S3, R2, or Cloudinary using signed URLs or SDKs. This reduces server load and improves reliability.
Server-mediated: accept files via a Route Handler if you need server-side validation or processing before storage.
Always validate file type, size, and use virus-scanning where necessary.
Provide progress feedback on the client for better UX.

Building a headless Shopify store without SEO regressions

Key practices:

Use SSG or SSR for product and category pages so content is crawlable and fast.
Emit correct canonical URLs and meta tags for all pages.
Attach structured product data (JSON-LD) for rich search results.
Optimize product images and feeds.
Generate an XML sitemap covering all storefront URLs.

Combining these keeps your headless store fast and search-friendly.

Conclusion

This FAQ covers practical, high-impact steps for advanced Next.js projects: performance optimizations, secure patterns, i18n and SEO, file uploads, and headless ecommerce. Apply these patterns incrementally — start with fonts and images, then secure secrets and authentication, and finally refine routing and uploads.

Want help implementing any of these items or building a headless Shopify site with Next.js? Reach out and mention which area you want to prioritize.

Home: Home: https://prateeksha.com

Blog: Blog: https://prateeksha.com/blog

Canonical: Canonical: https://prateeksha.com/blog/nextjs-faqs-beginner-to-advanced-part-5

Turbopack + Next.js: Setup, Troubleshooting, and Practical Fixes

Sumeet Shroff Developer — Thu, 01 Jan 2026 06:33:01 +0000

Setup and troubleshoot Turbopack for Next.js with step-by-step fixes for common errors, config pitfalls, and performance tips — focused on practical workflows and reproducible debugging.

Quick summary
- How to enable Turbopack in Next.js and when it helps.
- Common failure modes and concrete fixes for module resolution, CSS/PostCSS, and HMR.
- Practical performance tweaks, checklists, and debugging commands for repeatable results.

Why this matters

Turbopack aims to make development builds much faster by using a Rust-based bundler and smarter incremental rebuilds. The speed gains are real, but Turbopack's resolver and plugin compatibility differ from webpack. That creates predictable failure modes in projects that were tuned for webpack. This guide focuses on practical, reproducible fixes so you can adopt Turbopack without guessing.

Quick setup: enabling Turbopack in Next.js

Confirm your Next.js version supports Turbopack in dev mode.
Start the dev server with Turbopack enabled, for example:
- next dev --turbo
- Or enable the appropriate flag in your toolchain if your Next.js release uses a different option.
Start with a minimal app (one route, no custom webpack) to verify basic routing, Fast Refresh, and CSS behavior before adding customizations.

Tip: Re-introduce plugins and aliases one at a time so you can quickly identify what breaks.

When to use Turbopack

Use Turbopack when dev iteration time is your primary bottleneck (large codebases, many components).
Prefer it for client-heavy apps where webpack plugins aren’t essential to day-to-day iteration.
Keep webpack in CI/production builds or when you depend on a mature plugin ecosystem.

Turbopack vs Webpack — practical trade-offs

Cold start: Turbopack is usually much faster.
Incremental rebuilds: Turbopack is optimized for small changes.
Plugin ecosystem: webpack has far more plugins and loaders.
Source maps & debugger: Turbopack's mapping is improving but can behave differently.
Config compatibility: Expect to change some project config to be Turbopack-compatible.

Common errors and real fixes

This section covers three frequent failure modes and concrete steps to fix them.

App fails to boot with "module not found" for internal packages

Symptoms: Local packages (monorepo workspaces or aliased imports) resolve under webpack but fail with Turbopack.

Fixes:

Ensure each package.json in the monorepo has correct "exports", "main", and "module" fields and that source files are reachable.
Prefer relative/absolute imports or runtime-compatible aliases. Webpack-only aliases don’t always translate to Turbopack.
For workspace symlinks, make sure your package manager settings (nodeLinker, pnpm settings) and Next.js resolver can follow them.

CSS or PostCSS plugins are ignored in dev

Symptoms: Styles are different or PostCSS transforms aren’t applied when using Turbopack.

Fixes:

Use Next.js' built-in PostCSS support; avoid webpack loaders that depend on custom pipelines.
Place postcss.config.js at the repository root where Next.js/Turbopack will find it.
If a plugin is webpack-only, consider a hybrid workflow: Turbopack for day-to-day dev and webpack for builds that require that PostCSS plugin.

HMR not updating a component (Fast Refresh issues)

Symptoms: Code changes save but browser doesn’t reflect updates without a full reload.

Fixes:

Avoid module-level singletons or stateful side effects that break Fast Refresh semantics. Move state into React components or context providers that survive refresh.
Verify Fast Refresh is enabled for your Next.js/React version. Some older releases require specific flags or updates.
If you rely on library code that loses identity across HMR, consider hot-export-friendly patterns or small wrapper modules.

Warning: Don’t assume dev behavior equals production behavior. Always verify production builds separately.

Config pitfalls and how to avoid them

Heavy custom next.config.js/webpack hooks can break Turbopack. Minimize webpack-specific plugins.
TypeScript path aliases need runtime-resolvable alternatives; keep tsconfig paths mirrored in runtime imports or use a resolver plugin that Turbopack supports.
Experimental flags change between releases. Lock Next.js versions and test upgrades in a branch before adopting them widely.

Performance tips (practical)

Turn off expensive dev tasks (linting, type-checking) while iterating; run them in CI or pre-commit hooks.
Break up large pages with dynamic imports and code splitting.
Prefer ESM-first dependencies for faster parsing.
Keep route trees shallow while actively developing to reduce rebuild surface.

Real-world scenarios

Scenario 1 — Monorepo module resolution failure:

Problem: "module not found" for internal UI packages.
Root cause: missing "exports"/module config and a stale webpack alias.
Fix: publish correct fields in package.json and remove the alias; Turbopack resolved modules afterward.

Scenario 2 — CSS changes not reflected with HMR:

Problem: Global CSS variables updated but not hot-applied.
Root cause: a production-only PostCSS plugin not present in dev.
Fix: move postcss.config.js to repo root and simplify loader assumptions.

Scenario 3 — Intermittent source maps:

Problem: breakpoints don’t match source during debugging.
Root cause: pre-transforms (TS transforms) applied before Turbopack’s pipeline.
Fix: emit source maps in a Turbopack-friendly way in dev; restrict inline maps for CI/production builds.

Troubleshooting checklist

Before enabling Turbopack:

Confirm Next.js supports Turbopack in your version.
Test a baseline app with default config.

When you hit an error:

Reproduce with a minimal app.
Check package.json "exports", "main", and "module".
Simplify aliases and tsconfig mappings.
Inspect dev server logs and run verbose mode.

Debugging commands and tips

Start with verbose output: next dev --turbo --verbose (or the equivalent for your Next.js release).
Isolate config issues by temporarily removing custom next.config.js rules.
Binary-search by reverting recent package upgrades to find regressions.

Integration patterns: when to fall back

If a critical workflow requires a webpack plugin without a Turbopack alternative, use a hybrid setup:

Turbopack for daily development.
webpack-based builds in CI or for feature branches that require the plugin. Automate the switch via NPM scripts for developer convenience.

External resources

MDN Web Docs — JavaScript & devtools knowledge.
Google Lighthouse — performance auditing.
W3C WAI — accessibility guidance.
Cloudflare Learning Center — networking fundamentals.
OWASP — security best practices.

Latest trends

More ESM-first packages and explicit "exports" fields in packages.
Tooling shifting to faster incremental builds and better sourcemap fidelity.
Hybrid dev workflows are common while plugin compatibility improves.

Home: https://prateeksha.com
Blog: https://prateeksha.com/blog
Canonical: https://prateeksha.com/blog/turbopack-nextjs-faster-dev-builds-common-errors-fixes

Key takeaways

Turbopack can noticeably speed dev iteration but requires verification and small config changes.
Fixes usually involve making package exports explicit, avoiding webpack-only plugins, and simplifying aliasing.
Keep a minimal reproducible repo for any issue — it speeds community and vendor help.

Conclusion

Turbopack offers meaningful developer experience improvements, but it changes the failure modes you’ll encounter. Use the checklists and scenarios above to reproduce issues quickly and apply targeted fixes. Try Turbopack on a small branch, keep webpack in CI, and keep a tiny repro to get help fast.

Want help adopting this workflow or debugging a Turbopack problem? Contact us to set up a reproducible test or an audit of your Next.js config.

Home: https://prateeksha.com
Blog: https://prateeksha.com/blog

About Prateeksha Web Design

Prateeksha Web Design focuses on performance-first Next.js engineering and tooling support. We help teams adopt Turbopack, resolve build issues, and build hybrid workflows that balance fast iteration with production reliability.

Chat with us now Contact us today.

Reliable Shopify Webhooks: Idempotency, Retries, and Signature Verification

Sumeet Shroff Developer — Thu, 01 Jan 2026 06:31:09 +0000

Quick summary

Verify Shopify webhook HMACs before doing any work.
Acknowledge requests quickly and process asynchronously via queues.
Use idempotency keys, retry/backoff strategies, and a dead-letter queue (DLQ) to avoid duplicates and data loss.

Why webhook reliability matters

Webhooks drive critical flows: inventory updates, order imports, payment confirmations, and fulfillment. If your receiver drops, delays, or double-processes events you can get missed shipments, duplicate charges, or inconsistent data across systems.

Reliable handling is a combination of:

Authenticating the source (HMAC verification).
Fast acknowledgement (reduce retries from Shopify).
Safe asynchronous processing with idempotency and retries.
Observability and operational controls for failures.

Tip: Keep the HTTP response fast (ideally <500ms) and move heavy work to a worker queue.

Signature verification (authenticate the source)

Shopify signs webhooks using HMAC-SHA256. Always validate the signature before enqueuing or processing the payload. Use the raw request body and a timing-safe comparison to prevent replay and spoofing attacks.

Example (Node.js / Express):

// verify-signature.js
const crypto = require('crypto');

function verifyShopifyWebhook(req, shopifySecret) {
  const hmacHeader = req.get('X-Shopify-Hmac-Sha256');
  const rawBody = req.rawBody || Buffer.from(JSON.stringify(req.body));
  const hmac = crypto.createHmac('sha256', shopifySecret).update(rawBody).digest('base64');
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(hmacHeader));
}

module.exports = { verifyShopifyWebhook };

Notes:

Compute HMAC with your app secret against the raw body.
Use timing-safe comparisons (e.g., crypto.timingSafeEqual) to avoid leaking verification timing.
Reject or log invalid signatures; don’t enqueue them.

Basic webhook receiver pattern

A robust receiver follows a consistent pattern:

Capture raw body and relevant headers.
Verify HMAC signature.
Enqueue the event and return 200 OK quickly.
Process the job asynchronously with idempotency checks and controlled retries.

Example Express route using a Redis-backed queue:

const express = require('express');
const bodyParser = require('body-parser');
const { verifyShopifyWebhook } = require('./verify-signature');
const Queue = require('bull');

const webhookQueue = new Queue('shopify-webhooks', 'redis://127.0.0.1:6379');

const app = express();
app.use(bodyParser.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

app.post('/webhooks/shopify', async (req, res) => {
  const secret = process.env.SHOPIFY_SECRET;
  if (!verifyShopifyWebhook(req, secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Enqueue quickly
  await webhookQueue.add(req.body, { attempts: 1 });
  res.status(200).send('OK');
});

This separates the HTTP surface (which must be reliable and fast) from the processing surface (which can scale and retry independently).

Idempotency keys and deduplication

Shopify will retry deliveries on transient failures, and networks can duplicate requests. Deduplicate by computing a stable idempotency key for each webhook.

Common key sources:

Shopify event ID if present.
Resource ID combined with a timestamp or version.
A deterministic hash of relevant headers + body.

Pattern:

Compute an idempotency key like shopify:{shopId}:webhook:{event_id} or hash(payload).
Attempt to claim that key in a fast store (Redis) before processing.
If the claim succeeds, proceed and set a TTL (24–72 hours).
If the key exists, skip processing and acknowledge success.

Node.js sample:

// idempotency.js
const Redis = require('ioredis');
const redis = new Redis(process.env.REDIS_URL);

async function claimIdempotency(key, ttlSeconds = 86400) {
  const claimed = await redis.set(key, 'processing', 'NX', 'EX', ttlSeconds);
  return claimed === 'OK'; // true if key was set (not present before)
}

async function markDone(key) {
  await redis.set(key, 'done', 'EX', 86400);
}

module.exports = { claimIdempotency, markDone };

Worker-side check:

queue.process(async (job) => {
  const idKey = `shopify:webhook:${job.data.id}`; // choose stable identifier
  const claimed = await claimIdempotency(idKey);
  if (!claimed) return Promise.resolve(); // already processed

  try {
    // do work
    await handleWebhook(job.data);
    await markDone(idKey);
  } catch (err) {
    throw err; // let queue retry or move to DLQ
  }
});

This prevents double-processing when retries arrive while the original job is pending or being retried.

Retries, backoff, and dead-letter patterns

Don’t rely solely on Shopify’s retry schedule for long-running business work. Use your queue’s retry/backoff and DLQ features.

Choose a retry strategy based on failure type:

Immediate retries: for tiny transient errors.
Exponential backoff: for rate-limited third-party APIs.
Rate-limited workers: when you must guarantee throughput to downstream systems.
Dead-letter queue: when repeated attempts fail and manual intervention is needed.

Implementation tips:

Configure attempts and backoff per job type.
After N attempts, move jobs to a DLQ with error metadata.
Record last error, attempt count, and origin so operators can triage.

Warning: Never delete failing webhook events silently — push them to DLQ and alert operators.

Observability and monitoring

Track:

Webhook endpoint 4xx/5xx rates.
Acknowledgement latency.
Worker processing latency and success rate.
DLQ size and age.

Log structured events (shop ID, webhook ID, attempts) and add traces for workflows spanning services. Alerts should trigger on spikes in 4xx/5xx, DLQ growth, or increased processing lag.

Real-world scenarios

Payment duplicates: Teams used a request-hash idempotency key in Redis to avoid a double-capture after a transient 500. DLQ captured the failed item for replay.
Order spike: During flash sales, enqueueing plus autoscaled workers and exponential backoff prevented downstream API bans.
Key rotation mishap: A staging secret deployed to production caused verification failures. Alerts surfaced the issue quickly; rollback and a DLQ replay fixed missed orders.

Production checklist

Verify HMAC signatures with timing-safe comparisons.
Respond 200 quickly and enqueue heavy work.
Claim idempotency keys in a fast store before processing.
Configure queue retries, backoff, and DLQ handling.
Log structured events and instrument tracing.
Add alerts for endpoint error rates and DLQ growth.
Build a safe replay tool for DLQ items.
Rotate secrets securely and support multi-key verification during transitions.

Storage comparison for idempotency state

Redis: Low latency, TTL support, ideal for short-lived claims.
Postgres: Durable and auditable, better for long-term records and complex queries.
S3/Blob: High latency, used for mapping large payloads or archival references.

Use Redis for quick dedup checks and a DB for audit trails if needed.

Testing and operational scripts

Simulate retries, network errors, and signature failures in staging.
Test multi-key verification for secret rotations.
Provide a replay CLI/UI that re-validates signatures, rate-limits replays, and requires manual approval.

Short conclusion and CTA

Reliable Shopify webhook handling combines source verification, fast acknowledgement, idempotency, controlled retries, and clear operational tooling. Apply these patterns to reduce duplicates, avoid data loss, and make webhook failures visible and actionable.

Want help implementing a resilient webhook pipeline or reviewing your current setup? Contact us to audit or build a production-ready receiver.

Home: https://prateeksha.com
Blog: https://prateeksha.com/blog
Canonical: https://prateeksha.com/blog/shopify-webhooks-idempotency-signature-verification

Practical Next.js Caching: Routes, Data, Revalidation, and Tags

Sumeet Shroff Developer — Thu, 01 Jan 2026 06:26:33 +0000

A concise, practical guide to Next.js caching: how route and data caches differ, when to revalidate, and how tag-based invalidation reduces rebuild cost. Includes patterns, anti-patterns, and debugging tips.

Quick summary

Understand route (HTML) cache vs data (API) cache and when to prefer each.
Learn time-based, event-driven, and tag-based revalidation patterns.
See common anti-patterns and a checklist for production readiness.
Find debugging tips and operational commands to verify cache behavior.

Why caching matters in Next.js

Next.js apps mix server rendering, edge runtimes, and client fetching. Caching ties these pieces together by improving perceived speed, reducing origin load, and lowering costs. The right mix of route caching, data caching, and revalidation strategies helps you deliver fresh content efficiently.

Fact: Server-side caching plus correct revalidation reduces TTFB and origin cost when implemented safely and intentionally.

Overview: cache layers in Next.js

Common cache layers you’ll encounter:

Route cache: HTML responses cached at the edge or CDN (SSG / ISR).
Data cache: fetch() results or API responses cached by edge runtimes or CDNs.
Browser cache: Cache-Control headers that influence client-side caching.
Tag-based invalidation: group-based revalidation to refresh only affected pages or data.

Quick conceptual mapping

Route cache = fast full-page delivery (SSG, ISR).
Data cache = shared JSON or API responses used across routes/components.
Tags = fine-grained invalidation for entities referenced by many pages.

Core concepts and examples

1) Route cache (HTML)

Route caching applies when pages are served as static HTML or regenerated via ISR. Use getStaticProps + revalidate for periodic updates, or call on-demand revalidation for targeted invalidation.

Example pattern (getStaticProps + revalidate):

// pages/products/[id].js
export async function getStaticProps({ params }) {
  const product = await fetchProduct(params.id)
  return { props: { product }, revalidate: 60 } // seconds
}

A revalidate: 60 value instructs Next.js to serve the cached HTML and refresh the page in the background every 60 seconds.

2) Data cache (fetch + cache mode)

When multiple pages share the same API responses, cache results at the data layer. Next.js’s fetch supports cache modes that control how responses are stored and reused.

Example:

export async function getServerSideProps({ params }) {
  const res = await fetch(`${API}/products/${params.id}`, { cache: 'force-cache' })
  const product = await res.json()
  return { props: { product } }
}

Guidelines:

cache: 'no-store' for always-fresh responses (higher origin cost).
cache: 'force-cache' or default for long-lived results.
Tune TTLs to balance freshness and cost.

3) Revalidation strategies

Common approaches:

Time-based (ISR revalidate): predictable periodic refresh.
Event-driven (on-demand revalidation): trigger refresh when content changes.
Tag-driven: attach keys (tags) to pages/data and revalidate only those that reference an entity.

On-demand revalidation endpoint example:

// pages/api/revalidate.js
export default async function handler(req, res) {
  const { secret, path } = req.body
  if (secret !== process.env.MY_SECRET) return res.status(401).end()
  await res.revalidate(path)
  return res.json({ revalidated: true })
}

Use secure tokens for endpoints that trigger revalidation.

4) Tag strategies (grouped invalidation)

Tags help avoid brute-force site-wide rebuilds. Attach tags during render (e.g., product:123, author:alice). When an entity changes, revalidate the corresponding tag(s) to update all affected pages.

Pattern:

Add tags describing data dependencies at render time.
On data change, trigger revalidation for specific tags (and optionally related tags like category:shoes).

Tip: Tags are ideal when many pages reference the same entity.

Route cache vs Data cache vs Tag invalidation

Layer	What it caches	Best for	Control mechanisms
Route cache	HTML (pages)	Full-page speed, low compute	getStaticProps revalidate, ISR, on-demand revalidate
Data cache	JSON/API responses	Shared data across pages	fetch cache modes, edge cache headers
Tag invalidation	Groups of pages/data	Selective invalidation after updates	tags, tag-driven revalidate endpoints

Practical patterns

Read-mostly marketing pages
SSG + revalidate (300s–3600s depending on volatility).
Use tags for shared entities (authors, categories).
Frequently-updated product catalog
Data cache with short TTLs (30–60s) for APIs.
Trigger on-demand revalidation for affected product pages via tags.
Personal dashboards
Avoid long server/CDN caching. Use fetch with cache: 'no-store' and client-side updates for near-real-time data.

Anti-patterns to avoid

Long TTLs without any invalidation path — leads to stale data for real updates.
Global revalidation for small changes — wastes compute and slows deployments.
Conflicting TTLs across systems without documentation — causes unpredictable freshness.

Warning: Avoid very high revalidate values for moderately changing content unless you have reliable invalidation triggers.

Debugging tips

Reproduce locally with caching disabled to verify logic.
Inspect response headers (Cache-Control, Age, X-Nextjs-*) using curl -I.
Check CDN and origin logs for hit/miss patterns.
If on-demand revalidation fails, verify secret tokens and exact route paths.

Practical command:

curl -I https://your-site.com/page

Real-world scenarios

Scenario 1: E-commerce product update

Problem: Global revalidation after each inventory change caused rebuild spikes.
Solution: Tag product pages by ID and revalidate only affected tags, reducing rebuilds and improving shopper performance.

Scenario 2: Editorial publication

Problem: Long ISR intervals left headlines stale.
Solution: Shorten revalidate window for front page and call on-demand revalidation on publish.

Scenario 3: Internal dashboard

Problem: Aggressive caching caused stale analytics.
Solution: Use no-store for live widgets while keeping non-critical cards cached.

Latest trends

Edge runtimes and granular edge cache controls are maturing.
Declarative tags and partial revalidation are becoming more common in frameworks.
Observability for cache hit/miss metrics is gaining adoption.

Checklist

[ ] Decide SSG vs SSR vs client-only per page.
[ ] Define revalidation policy for each content type (TTL, tags, triggers).
[ ] Add tag-based invalidation for shared entities.
[ ] Implement a secure on-demand revalidation endpoint.
[ ] Instrument headers, CDN logs, and alerts for cache behavior.
[ ] Document caching policies for the team.

Key operational debugging commands

curl -I to inspect headers
Review CDN logs for origin requests
Check server logs for on-demand revalidation failures

Key takeaways

Use route cache (SSG/ISR) for full-page performance and data cache for shared API responses.
Prefer tags for selective invalidation over global busting on large sites.
Combine time-based and event-driven revalidation for predictable freshness.
Avoid anti-patterns like long TTLs without invalidation or global revalidation for small edits.
Instrument headers and logs to detect cache miss hotspots and unexpected behavior.

Conclusion

A sustainable Next.js caching strategy balances speed, freshness, and cost. Mix route caching, data caching, and tag-based invalidation according to content volatility and scale. Monitor cache behavior, document decisions, and automate revalidation where possible.

Interested in a caching review or audit? Reach out to discuss patterns and implementation details.

Home: https://prateeksha.com

Blog: https://prateeksha.com/blog

Canonical: https://prateeksha.com/blog/nextjs-caching-explained-route-cache-data-cache-revalidation-tags

Next.js 15 Upgrade Playbook: App Router, Caching Pitfalls, and Safe Migration Steps

Sumeet Shroff Developer — Thu, 01 Jan 2026 06:25:04 +0000

Quick summary

What changed: App Router behavior, caching defaults, middleware/header propagation, and image handling.
Risks: stale content, broken auth, and hydration errors from server/client boundary changes.
Goals: audit, migrate incrementally, verify caching and headers, and canary deploy with observability.

Why upgrade now?

Next.js 15 brings tightened App Router semantics, updated caching defaults, and runtime adjustments that can improve performance and security. Those same changes can also alter behavior in subtle ways — which is why the upgrade should be planned and tested, not rushed.

What changed in Next.js 15 (at a glance)

App Router boundaries are stricter: server vs client responsibilities are enforced earlier.
Caching model refined: more aggressive edge caching in some configs and finer fetch-level controls.
Middleware and headers: propagation and rewrite behavior changed in ways that can affect auth and proxies.
Assets and images: loader integrations and cache headers got updates that affect delivery.

Core technical differences (quick reference)

Server Components: calling browser-only APIs in server components now breaks sooner.
getServerSideProps: migration toward App Router patterns continues; consider server components + fetch.
Edge runtime: environment differences (no process/fs) require verification for edge-deployed code.

Pages Router vs App Router — quick comparison

Data fetching
- Pages: getStaticProps / getServerSideProps
- App: server components, fetch with cache control
File layout
- Pages: pages/
- App: app/ with nested layouts and templates
Streaming
- Pages: limited
- App: built-in streaming and partial rendering
Middleware
- Pages: older APIs
- App: updated header and rewrite behavior
Caching
- Pages: page-level declarations
- App: fetch-level cache controls and edge-oriented defaults

Common breaking issues and symptoms

Missing or stale content: default cache modes or edge rewrites not forwarding headers.
Hydration errors: browser APIs used in server components or mismatched component types.
Auth failures: cookies or authorization headers dropped by middleware or rewrites.
Over-caching: immutable or aggressive caching preventing content updates.

Recommended upgrade flow (safe and staged)

Inventory and audit
- List routes using getServerSideProps, getInitialProps, direct cookie reads, or dynamic headers.
- Identify custom middleware, rewrites, and any proxy logic.
Read migration docs and test locally
- Follow official changelogs and migration notes for Next.js 15.
- Build a branch environment and fix compile-time errors first.
Convert incrementally
- Migrate a few non-critical routes to app/ rather than converting the entire site.
- Replace server-side props patterns with server components + fetch where practical.
Verify caching and runtime behavior
- Exercise fetch cache modes (no-store, revalidate, default) and inspect Cache-Control headers.
- Test middleware header propagation and rewrites in staging.
Canary deploy and monitor
- Deploy to a subset of traffic, run E2E and smoke tests, and watch metrics.
Prepare rollback and runbooks
- Keep a rollback path and dashboards for errors, SSR latencies, and cache hit/miss rates.

Tip: Use feature flags or route-level toggles to limit the blast radius while migrating.

Testing and verification checklist

Unit & integration tests focused on cookie/header flows and API interactions.
End-to-end tests for login, personalization, and session refresh flows.
Load tests for SSR and edge functions to measure CPU and latency.
Cache verification: ensure Cache-Control values match expectations for static and dynamic routes.
Observability: track error rates, SSR time, and cache metrics for the first 48 hours post-rollout.

Helpful tools and references:

Google Search Central for SEO and crawlability.
Lighthouse for performance and accessibility checks.
MDN for web API behavior.
OWASP for header and cookie security guidance.

Real-world scenarios and fixes

Scenario: stale landing page after enabling edge caching

Cause: immutable cache policy served promotional content for hours.
Fix: add revalidate keys or switch to revalidate-based caching for marketing routes.

Scenario: login breaks after middleware migration

Cause: rewrites stopped forwarding set-cookie/authorization headers.
Fix: explicitly forward required headers in middleware and validate token refresh flow in staging.

Scenario: hydration mismatch from client-only code used in server component

Cause: library importing window.localStorage inside what became a server component.
Fix: move the code to a client component and add unit tests to prevent regressions.

Troubleshooting quick tips

Hydration errors: scan stack traces for "Hydration" and check for window/document usage.
Missing cookies: log request headers at middleware entry to confirm forwarding.
Stale responses: inspect Cache-Control and CDN/edge caching behavior with curl or a network tab.

Tip: Add CI assertions that validate Cache-Control headers on representative endpoints.

How Prateeksha Web Design approaches production upgrades

Prateeksha uses a phased approach: audit, convert low-risk routes first, add CI checks for headers and cache, canary deploy, and monitor closely. Runbooks and rollback plans are prepared before any production rollout.

Key verification commands and snippets

Local build and checks: npm run build && npx next build
Inspect headers: curl -I https://staging.example.com/path
Simulate edge behavior: run a staging environment that mirrors CDN/edge settings

Warning: local dev server behavior can differ from edge runtimes and CDNs — always validate in staging.

Key takeaways

Audit routes and middleware before upgrading — App Router and caching defaults are stricter.
Test header and cookie propagation; middleware rewrites can break auth flows.
Migrate incrementally and canary deploy to reduce risk.
Verify Cache-Control in staging and monitor cache hit/miss after rollout.
Prepare a rollback plan and observe the first 48 hours closely.

Conclusion

Upgrading to Next.js 15 offers performance and security benefits but introduces behavioral changes that can affect caching, headers, and component boundaries. Follow a staged plan: inventory, incremental migration, thorough testing, canary deployment, and observability. If you need hands-on help, document a rollback plan and monitor key metrics immediately after rollout.

Ready to plan an upgrade or run an audit? Contact Prateeksha for migration guidance and runbook help.

Home: https://prateeksha.com

Blog: https://prateeksha.com/blog

Canonical: https://prateeksha.com/blog/nextjs-15-upgrade-guide-app-router-caching-migration

Shopify Scripts Functions: A Practical Migration Playbook

Sumeet Shroff Developer — Thu, 01 Jan 2026 06:20:47 +0000

A concise, developer-focused playbook to move Script Editor logic into Shopify Functions: audit, prototype, test, and stage rollouts with QA, monitoring, and rollback steps.

Quick summary

Audit active scripts, map business intent, and prioritize by impact.
Prototype a single high-value Function, validate parity, then iterate.
Use staged rollouts, robust QA, and observability to reduce launch risk.

Introduction

Shopify is standardizing customization around Shopify Functions. If your store still relies on the Script Editor, planning a migration reduces the chance of customer-facing surprises. This guide presents a practical, developer-oriented workflow: audit, map use-cases, prototype, test, and roll out safely.

Why migrate now

Shopify Functions run as sandboxed WebAssembly modules and plug into Shopify’s native evaluation points (discounts, shipping, payments). The migration brings:

Better performance and scalability
Clearer extension boundaries and versioning
Reduced maintenance debt for long-term compatibility

Conceptual changes: Scripts vs Functions

Key differences to keep in mind:

Execution: Scripts ran in the Script Editor runtime; Functions are invoked by Shopify’s server-side evaluation and must be deterministic.
Language & tooling: Scripts were Ruby-based; Functions use languages that compile to WASM (Rust is the most common path).
Scope: Functions are tied to extension points (discounts, shipping, payments), not arbitrary checkout mutations.

Design with determinism and idempotence in mind: Functions should produce the same output for the same cart input every time.

Quick comparison

Deployment: Script Editor (per-shop) vs app extension + Shopify CLI (versionable).
Surface: General cart scripting vs specific extension points (discounts/shipping/payments).
Maintainability: Monolithic shop scripts vs modular, testable functions.
Performance: Legacy runtime vs sandboxed WASM with lower latency potential.

Migration overview — step-by-step

Follow this task-oriented flow.

Inventory & Audit
- Export every active script and note where it runs and which data it uses (line items, customer tags, shipping address).
- Capture business intent: discounts, bundling, conditional shipping, or payment routing.
- Flag scripts that rely on private or deprecated APIs.
Prioritize & Scope
- Tag scripts as High (revenue-critical), Medium (UX/ops), Low (infrequent).
- Choose one high-impact script for your pilot.
Map to Functions
- Match business intent to the right extension point (Discounts, Shipping Rates, Payment).
- Re-express logic as pure calculations that return updated pricing or rate objects.
Prototype
- Build a minimal Function that covers core behavior.
- Run locally with Shopify CLI and a dev store to confirm baseline parity.
Implement & Integrate
- Expand logic, introduce shared utilities, and add unit and integration tests.
- Add structured logging and feature flags to control rollout.
Test & QA
- Unit test every rule branch and edge case.
- Integration tests with product fixtures and end-to-end checkout flows.
- Validate rounding, tax interactions, and unusual cart compositions.
Staged Rollout
- Canary by percentage, storefront, or market.
- Monitor key metrics and hold a rollback window.
Post-launch
- Validate telemetry, monitor errors, and iterate.

Mapping common use-cases

How common Script patterns translate to Functions:

SKU or collection discounts → Discount Function with deterministic matching rules.
Buy X get Y / bundle promotions → Discount Function that groups line items and calculates line-level adjustments.
Conditional shipping (by tag, weight, destination) → Shipping Function that returns authorized shipping rates.
Payment routing or gating → Payments extension with server-side checks if needed.

Always replace side-effects with returned, repeatable data structures — Functions should not rely on mutable external state.

Real-world scenarios (short)

Holiday bundle: Prototype caught subtle rounding differences; staged rollout enabled quick fixes.
Tag-based free shipping: Added tests for international destinations that previous Scripts overlooked.
Legacy tiered pricing: Split logic between a Discount Function and app-side membership checks to simplify rules.

QA and testing checklist

Pre-migration

List active scripts and business intents
Capture analytics and revenue attribution per script
Document any API limitations

Development

Create Function prototype with unit tests
Add structured logs and feature flags
Build integration tests against a dev store

Staging & Rollout

Smoke test on limited storefront
Monitor AOV, conversion rate, discount application rate
Prepare clear rollback steps

Post-launch

Monitor errors, latency, and revenue math
Run periodic parity checks between legacy and Function outputs before retiring scripts

Tip: Keep a canonical test suite that runs both the old Script outputs (when possible) and the new Function outputs against the same cart fixtures to spot drift early.

Rollout strategy

Options to reduce blast radius:

Canary by session percentage or feature flag
Deploy to one storefront or market first
Schedule deployments during lower-traffic windows
Keep stakeholders (marketing, support, ops) informed and ready to respond

Monitoring & observability

Key signals to track:

Discount application rate vs historical baseline
Checkout conversion and abandonment
Average order value (AOV)
Function latency and error rate
Structured logs showing unmatched cases or unexpected inputs

Integrate with your centralized logging and alerting stack and define thresholds for automated alerts.

Common pitfalls and how to avoid them

Expecting a straight 1:1 code translation — instead, map business intent first.
Incomplete test coverage — build deterministic fixtures and automated checks.
Preserving clever one-off rules — refactor reusable parts into shared helpers.

Post-migration optimization

After parity is confirmed:

Consolidate duplicated rules into shared libraries
Tune telemetry to find performance bottlenecks
Consider warm-up strategies if cold starts are visible in latency

Conclusion

Migrating from Shopify Scripts to Shopify Functions reduces technical risk and aligns stores with Shopify’s supported extensibility. Start with an audit, prototype a high-value use-case, validate with rigorous tests, and roll out in stages with clear monitoring and rollback plans. Want help planning or executing a migration? Reach out and we can map a pilot together.

Home: https://prateeksha.com

Blog: https://prateeksha.com/blog

Canonical: https://prateeksha.com/blog/migrate-shopify-scripts-to-shopify-functions-playbook

Checkout UI Extensions 101 — Build Post-Purchase & Thank-You Page Customizations

Sumeet Shroff Developer — Thu, 01 Jan 2026 05:23:34 +0000

Quick summary

What Checkout UI Extensions are and where they run (checkout vs. post-purchase).
How to structure an extension: manifest, UI, and backend interactions.
Practical tips: limits, debugging steps, and a production checklist.

Introduction

Checkout UI Extensions let you inject small, purpose-built UIs into Shopify’s checkout and thank-you page surfaces. They’re intended for non-sensitive UI customizations — upsells, surveys, tracking snippets, or fulfillment instructions — while keeping payment rails untouched.

This article outlines the architecture, constraints, debugging techniques, a short tutorial for a post-purchase upsell, and a checklist for production readiness.

What are Checkout UI Extensions?

Checkout UI Extensions are sandboxed UI components that run inside Shopify’s checkout and post-purchase pages. They use a component runtime (React-like) and operate in a constrained environment to preserve performance and security.

Key characteristics:

Sandbox execution with strict resource and time constraints.
Predefined UI components and styling primitives.
No access to raw payment details or card data.

Where they run

Checkout (payment flow) — highly restricted surface; use only for light, non-blocking UI.
Post-purchase / Thank-you page — more flexible; best for upsells, surveys, and order follow-ups.

Important: do not attempt to perform sensitive payment logic inside the extension. Treat extensions as UI triggers that call secure backend services.

Architecture overview

Typical components of a Checkout UI Extension solution:

Extension package: UI code that Shopify injects at the extension point.
Manifest: metadata describing extension points, permissions, and runtime info.
Backend services (optional): APIs for personalization, order creation, or analytics.
Shopify runtime: injects the extension into the page and isolates it.

Common flow:

Merchant installs the extension through an app.
Shopify validates and injects the extension at declared extension points.
The extension runs in a sandboxed environment and renders UI.
For side-effects (create draft orders, save data), the extension calls your backend, which in turn calls Shopify Admin APIs.

Communication patterns

Use fetch from the extension to call your backend API, but keep calls short and non-blocking.
Implement server-side persistence for critical operations (orders, subscriptions).
Ensure CORS is configured correctly for allowed origins.
Prefer idempotent backend endpoints so repeated calls don’t cause duplicate orders.

Limits and considerations

Performance: extensions should render quickly; avoid heavy computation.
Styling and DOM: you work with provided components; direct DOM access is limited.
Security: no direct access to payment details or card numbers.
Network timeouts: treat network calls as unreliable — use retries and fallback UI.
Accessibility: extensions must be keyboard friendly and screen-reader accessible.

Comparison: when to use Extensions vs Apps vs Script Editor

Checkout UI Extensions: best for lightweight UI inside checkout/thank-you pages.
Embedded Shopify Apps: suitable for complex backend workflows, dashboards, and settings.
Script Editor / Shopify Functions: server-side logic for pricing and promotions (not for UI).

Tutorial: Build a Simple Post-Purchase Upsell Extension

This is a concise walkthrough showing the core steps to scaffold and wire a post-purchase upsell.

1) Scaffold the extension

Use Shopify CLI to create a Checkout UI Extension scaffold and run the dev preview.

2) Extension manifest (example snippet)

{
  "name": "post_purchase_upsell",
  "type": "checkout_ui_extension",
  "extension_points": ["PostPurchase"]
}

3) UI component (pseudo-code)

import {render, View, Button, Text} from '@shopify/checkout-ui-extensions-react';

function PostPurchaseApp({order}){
  return (
    <View padding="4">
      <Text as="h2">Special offer: add a warranty</Text>
      <Button onPress={() => addUpsell(order.id)}>Add warranty</Button>
    </View>
  );
}

render('Checkout::PostPurchase::Default', PostPurchaseApp);

4) Handling the upsell action

Let the extension trigger a backend call with the order ID and selected option.
The backend creates a draft order or subscription via the Admin API, and returns a customer-facing link or sends a follow-up email.
Keep the extension UI responsive: show optimistic states and surface errors clearly.

Tip: prepare your server-side flow first (draft order creation + checkout links). The extension should only trigger and report status to the user.

Debugging tips

Use Shopify CLI extension dev tools to preview in a staging checkout.
Inspect runtime logs via remote debugging in the injected iframe.
Add structured logging in your backend and map errors to concise messages in the UI.
Simulate slow networks to catch timeout issues and confirm graceful degradation.
Validate CORS headers and content-security policies.

Quick checklist when debugging:

Is the extension injected at the expected extension point?
Any console errors inside the injected frame?
Are API responses blocked or delayed by CORS or network issues?
Does the extension follow runtime method restrictions?

Best practices

Keep UI minimal and non-blocking; prioritize performance.
Move heavy lifting and sensitive operations to secure backend services.
Build idempotent server endpoints to avoid duplicates.
Verify accessibility: focus management, labels, and screen-reader support.
Use feature flags and canary rollouts to limit exposure.

Useful references: MDN for JS/CSS best practices, W3C WAI for accessibility, OWASP for security guidance.

Real-world scenarios

Subscription upsell: show subscription options on thank-you page and create a draft subscription server-side.
Warranty offer: accept fee in UI, call backend to add fulfillment notes and update order metadata.
Fulfillment survey: capture delivery preferences and post them to merchant analytics.

Production checklist

Test in a staging store using Shopify CLI preview.
Confirm all API endpoints and CORS headers are correct.
Run performance tests under slow network conditions.
Conduct keyboard and screen-reader accessibility tests.
Create rollback process and merchant support steps.
Monitor extension render time, backend latency, and error rates.

Monitoring & rollout

Use feature flags for gradual rollouts.
Track key metrics: conversion lift, error rate, and average render time.
Prepare merchant-facing toggle to disable the extension quickly if issues occur.

Key takeaways

Checkout UI Extensions are intended for UI-focused, non-sensitive enhancements in checkout and post-purchase surfaces.
Offload sensitive and heavy operations to backend services and ensure idempotency.
Test performance, accessibility, CORS, and error handling before production.
Use staged rollouts and monitoring to mitigate production risks.

Conclusion

Checkout UI Extensions provide a practical way to extend the post-purchase experience without touching payment processing. Follow a server-first approach for side-effects, keep the UI fast and accessible, and use staging, monitoring, and gradual rollouts to ship safely. Ready to build an extension? Start with the Shopify CLI preview and the production checklist above.

Home: https://prateeksha.com
Blog: https://prateeksha.com/blog
Canonical: https://prateeksha.com/blog/checkout-ui-extensions-101-post-purchase-thank-you-customizations

If you want help building or auditing an extension, contact Prateeksha Web Design to discuss implementation and production readiness.