DEV Community: Michał Miler

Auto-Translation in Payload CMS with Azure AI Translator: Complete 2026 Implementation Guide

Michał Miler — Tue, 14 Apr 2026 09:52:00 +0000

Manual translation in Payload CMS doesn't scale for production applications: it's slow, expensive, and error‑prone once you support multiple documents and locales. This comprehensive guide shows a production-tested automated approach using Azure AI Translator, Payload background jobs, and LRU caching to batch translations, preserve manual edits, and minimize API costs.

At u11d, we've implemented this solution across multiple high-traffic Payload CMS applications, processing millions of translations monthly. This guide covers everything from Azure setup to production deployment with real-world performance metrics.

Key features of this production-ready solution:

One-click batch translation for any Payload collection (100+ languages supported)
Async background jobs - No timeouts, scalable processing with Payload Jobs API
Intelligent caching - LRU cache to avoid duplicate API calls and reduce costs by 70%+
Preserves manual edits - Only empty fields are translated by default
Force mode - Re-translate all fields when needed (content updates, quality improvements)
Audit trail - Tracks translation metadata for compliance and debugging
Type-safe - Full TypeScript support with Payload's generated types
Production-tested - Handles millions of translations in real-world applications

Solution Overview

Architecture:

Translation Service: Azure + Cache
Payload Background Job: async, scalable
API Route Handler: secure job submission
Admin UI: button + modal for user control
Translation Metadata: audit what/when/force

This tutorial focuses on a single collection for clarity. For a full, type-safe, multi-collection solution, see the complete implementation on GitHub.

Prerequisites

Before implementing auto-translation, ensure you have:

Azure Account - Create free account ($200 credit included)
Azure Translator Resource - Setup guide
Payload Localization Enabled - See our localization best practices guide
Node.js 18+ - Required for Payload 3.0+
TypeScript 5+ - For type-safe implementation

Database Note: This tutorial uses SQLite for local development only. For production, configure DATABASE_URL to connect to PostgreSQL, MongoDB, or MySQL for better performance and reliability.

Step-by-Step Implementation

Step 1: Install Dependencies

First, install the Azure AI Translator SDK and the additional project dependencies:

npm install @azure-rest/ai-translation-text lru-cache radash

Step 2: Configure Environment Variables

Create or update your .env file:

# Azure Translator Configuration
AZURE_TRANSLATOR_KEY=your_azure_translator_key
AZURE_TRANSLATOR_REGION=your_azure_translator_region

Check .env.example to see what else can be configured.

Getting Azure Credentials:

Go to Azure Portal
Navigate to your Translator resource
Create Translator resource if it does not exist yet
Click "Keys and Endpoint" in the left menu
Copy KEY 1 and set AZURE_TRANSLATOR_KEY in .env
Copy Location/Region and set AZURE_TRANSLATOR_REGION in .env

Never commit API keys. Add .env.local to .gitignore, use secret managers or CI/CD secret stores, and rotate keys regularly.

Step 3: Create Translation Service

This service handles Azure API calls, batching, and caching:

// src/services/translationService.ts
import crypto from "crypto";
import TextTranslationClient, {
  isUnexpected,
} from "@azure-rest/ai-translation-text";
import { LRUCache } from "lru-cache";

export type TranslationEngine = "azure";

export interface TranslationResult {
  text: string;
  fromCache: boolean;
}

export interface BatchTranslationInput {
  id?: string;
  text: string;
  targetLocale: string;
}

export interface BatchTranslationResult {
  id?: string;
  text: string;
  translatedText: string;
  targetLocale: string;
  fromCache: boolean;
}

const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days

const translationCache = new LRUCache<string, string>({
  max: 10000,
  ttl: CACHE_TTL_MS,
  ttlAutopurge: true,
});

function createTextHash(text: string): string {
  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
}

function createCacheKey(locale: string, englishText: string): string {
  const hash = createTextHash(englishText);
  return `${locale}:${hash}`;
}

async function translateWithAzure(
  texts: string[],
  targetLocale: string,
): Promise<string[]> {
  const apiKey = process.env.AZURE_TRANSLATOR_KEY;
  const endpoint =
    process.env.AZURE_TRANSLATOR_ENDPOINT ||
    "<https://api.cognitive.microsofttranslator.com>";
  const region = process.env.AZURE_TRANSLATOR_REGION || "global";

  if (!apiKey) {
    throw new Error(
      "AZURE_TRANSLATOR_KEY is not configured in environment variables",
    );
  }

  const client = TextTranslationClient(endpoint, {
    key: apiKey,
    region: region,
  });

  const inputText = texts.map((text) => ({ text }));
  const translateResponse = await client.path("/translate").post({
    body: inputText,
    queryParameters: {
      to: targetLocale,
      from: "en",
    },
  });

  if (isUnexpected(translateResponse)) {
    throw new Error(
      `Azure translation failed: ${translateResponse.body.error?.message || "Unknown error"}`,
    );
  }

  return translateResponse.body.map((item) => item.translations[0].text);
}

export async function batchTranslate(
  inputs: BatchTranslationInput[],
): Promise<BatchTranslationResult[]> {
  const results: BatchTranslationResult[] = new Array(inputs.length);

  const inputsWithIndex = inputs.map((input, index) => ({ input, index }));

  const byLocale = inputsWithIndex.reduce<
    Record<string, typeof inputsWithIndex>
  >((acc, item) => {
    if (!acc[item.input.targetLocale]) {
      acc[item.input.targetLocale] = [];
    }
    acc[item.input.targetLocale].push(item);
    return acc;
  }, {});

  for (const [locale, localeInputs] of Object.entries(byLocale)) {
    const textsToTranslate: string[] = [];
    const itemsToTranslate: typeof inputsWithIndex = [];

    for (const item of localeInputs) {
      const cacheKey = createCacheKey(locale, item.input.text);
      const cached = translationCache.get(cacheKey);

      if (cached) {
        results[item.index] = {
          id: item.input.id,
          text: item.input.text,
          translatedText: cached,
          targetLocale: locale,
          fromCache: true,
        };
      } else {
        textsToTranslate.push(item.input.text);
        itemsToTranslate.push(item);
      }
    }

    if (textsToTranslate.length > 0) {
      const BATCH_SIZE_AZURE = 100;

      for (let i = 0; i < textsToTranslate.length; i += BATCH_SIZE_AZURE) {
        const batch = textsToTranslate.slice(i, i + BATCH_SIZE_AZURE);
        const batchItems = itemsToTranslate.slice(i, i + BATCH_SIZE_AZURE);

        const translations = await translateWithAzure(batch, locale);

        for (let j = 0; j < translations.length; j++) {
          const item = batchItems[j];
          const translatedText = translations[j];
          const cacheKey = createCacheKey(locale, item.input.text);

          translationCache.set(cacheKey, translatedText);

          results[item.index] = {
            id: item.input.id,
            text: item.input.text,
            translatedText,
            targetLocale: locale,
            fromCache: false,
          };
        }
      }
    }
  }

  return results;
}

export async function translate(
  text: string,
  targetLocale: string,
): Promise<TranslationResult> {
  const results = await batchTranslate([{ text, targetLocale }]);
  const result = results[0];

  return {
    text: result.translatedText,
    fromCache: result.fromCache,
  };
}

What This Does:

LRU Cache - Stores up to 10,000 translations in memory
Cache Key - SHA256 hash of source text + locale
7-Day TTL - Reasonable cache duration for production content
Batch Processing - Groups translations by locale for efficiency
Azure Integration - Sends up to 100 texts per request
Cache Hits - Returns cached translations instantly (< 1ms)
Cache Misses - Fetches from Azure and caches result
Type Safety - Full TypeScript interfaces for reliability

Caching reduces API calls, latency, and cost by reusing recent translations. Use the in-memory LRU cache for local development, but deploy a shared cache (for example, Redis) in production to persist entries across restarts, share results between instances, and scale capacity.

Step 4: Create Payload Background Job

Background jobs prevent timeout issues and allow progress tracking.

Payload's Jobs API runs translation work outside the request lifecycle so long-running batches won't block the admin UI or hit HTTP timeouts. Queued jobs can report progress, be retried on failure, and scale across worker processes, which makes them a reliable choice for large or repeated translation tasks. In this step we'll implement a job that fetches the English document, extracts fields to translate, batches calls to the translation service, and updates target locales in a safe, idempotent way.

// src/jobs/translateResource.ts
import { TaskConfig, TypedLocale } from "payload";
import { batchTranslate } from "../services/translationService";
import { retry } from "radash";
import { isValidLocale } from "@/locales";
import { Resource } from "@/payload-types";

interface FieldToTranslate {
  path: string;
  value: string;
  locale: string;
  id?: string;
}

function isEmpty(value: unknown): boolean {
  if (value === null || value === undefined) return true;
  if (typeof value === "string") return value.trim() === "";
  return false;
}

function shouldTranslate(
  force: boolean,
  sourceValue: string | null | undefined,
  targetValue: string | null | undefined,
): boolean {
  if (isEmpty(sourceValue)) return false;
  if (force) return true;
  return isEmpty(targetValue);
}

function extractFieldsToTranslate(
  englishDoc: Resource,
  targetDoc: Resource,
  force: boolean,
  targetLocale: TypedLocale,
): FieldToTranslate[] {
  const fieldsToTranslate: FieldToTranslate[] = [];

  // Extract title field
  if (shouldTranslate(force, englishDoc.title, targetDoc.title)) {
    fieldsToTranslate.push({
      path: "title",
      value: englishDoc.title,
      locale: targetLocale,
    });
  }

  // Extract list array fields
  if (Array.isArray(englishDoc.list)) {
    englishDoc.list.forEach((englishItem, index) => {
      if (!englishItem.id) return;

      const targetItem = Array.isArray(targetDoc.list)
        ? targetDoc.list.find((t) => t.id === englishItem.id)
        : null;

      if (shouldTranslate(force, englishItem.name, targetItem?.name)) {
        fieldsToTranslate.push({
          path: `list.${index}.name`,
          value: englishItem.name!,
          locale: targetLocale,
          id: englishItem.id,
        });
      }
    });
  }

  return fieldsToTranslate;
}

function buildUpdateData(
  englishDoc: Resource,
  targetDoc: Resource,
  translationsByPath: Record<string, string>,
): Partial<Resource> {
  const updateData: Partial<Resource> = {
    ...targetDoc,
  };

  // Update title
  if (translationsByPath["title"]) {
    updateData.title = translationsByPath["title"];
  } else if (isEmpty(targetDoc.title) && englishDoc.title) {
    updateData.title = englishDoc.title;
  }

  // Update list array
  if (Array.isArray(englishDoc.list)) {
    const targetItemsById = new Map(
      Array.isArray(targetDoc.list)
        ? targetDoc.list.map((item) => [item.id, item])
        : [],
    );

    updateData.list = englishDoc.list.map((englishItem, index) => {
      const targetItem = targetItemsById.get(englishItem.id);
      const mergedItem = {
        ...englishItem,
        ...(targetItem || {}),
        id: englishItem.id,
      };

      const namePath = `list.${index}.name`;
      if (translationsByPath[namePath]) {
        mergedItem.name = translationsByPath[namePath];
      } else if (isEmpty(targetItem?.name) && englishItem.name) {
        mergedItem.name = englishItem.name;
      }

      return mergedItem;
    });
  }

  return updateData;
}

async function executeBatchTranslation(
  fields: FieldToTranslate[],
): Promise<Record<string, string>> {
  const BATCH_SIZE_AZURE = 100;
  const translationsByPath: Record<string, string> = {};

  for (let i = 0; i < fields.length; i += BATCH_SIZE_AZURE) {
    const batch = fields.slice(i, i + BATCH_SIZE_AZURE);
    const translations = await retry({ times: 3, delay: 1000 }, () =>
      batchTranslate(
        batch.map((f) => ({
          id: f.path,
          text: f.value,
          targetLocale: f.locale,
        })),
      ),
    );
    translations.forEach((t) => {
      if (t?.id) translationsByPath[t.id] = t.translatedText;
    });
  }

  return translationsByPath;
}

export const translateResourceJob: TaskConfig<"translateResource"> = {
  slug: "translateResource",
  inputSchema: [
    {
      name: "documentId",
      type: "text",
      required: true,
    },
    {
      name: "locales",
      type: "array",
      required: true,
      fields: [
        {
          name: "locale",
          type: "text",
        },
      ],
    },
    {
      name: "force",
      type: "checkbox",
      defaultValue: false,
    },
  ],
  outputSchema: [
    {
      name: "success",
      type: "checkbox",
      required: true,
    },
    {
      name: "translated",
      type: "number",
      required: true,
    },
    {
      name: "details",
      type: "json",
    },
  ],
  handler: async ({ input, job, req }) => {
    const { payload } = req;
    const { documentId, force } = input;
    const locales = input.locales.map(({ locale }) => locale);

    console.log(
      `[Job ${job.id}] Translation started for resources:${documentId}`,
      { locales, force },
    );

    try {
      const englishDoc = await payload.findByID({
        collection: "resources",
        id: documentId,
        locale: "en",
        depth: 0,
      });

      if (!englishDoc) {
        throw new Error(`Resource not found: ${documentId}`);
      }

      const totalTranslatedCounts: Record<string, number> = {};

      for (const targetLocale of locales) {
        if (targetLocale === "en") continue;

        console.log(`[Job ${job.id}] Processing locale: ${targetLocale}`);

        if (!isValidLocale(targetLocale)) {
          console.warn(`[Job ${job.id}] Invalid locale: ${targetLocale}`);
          continue;
        }

        const targetDoc = await payload.findByID({
          collection: "resources",
          id: documentId,
          locale: targetLocale,
        });

        const fieldsToTranslate = extractFieldsToTranslate(
          englishDoc,
          targetDoc,
          force || false,
          targetLocale,
        );

        if (fieldsToTranslate.length === 0) {
          console.log(
            `[Job ${job.id}] No fields to translate for locale ${targetLocale}`,
          );
          continue;
        }

        console.log(
          `[Job ${job.id}] Translating ${fieldsToTranslate.length} fields for ${targetLocale}`,
        );

        const translationsByPath =
          await executeBatchTranslation(fieldsToTranslate);

        const updateData = buildUpdateData(
          englishDoc,
          targetDoc,
          translationsByPath,
        );

        updateData._translationMeta = {
          lastTranslatedAt: new Date().toISOString(),
          translatedBy: "auto",
        };

        await payload.update({
          collection: "resources",
          id: documentId,
          locale: targetLocale,
          data: updateData,
        });

        totalTranslatedCounts[targetLocale] = fieldsToTranslate.length;
      }

      const totalTranslated = Object.values(totalTranslatedCounts).reduce(
        (a, b) => a + b,
        0,
      );

      console.log(
        `[Job ${job.id}] Translation completed. Total fields translated: ${totalTranslated}`,
        totalTranslatedCounts,
      );

      return {
        output: {
          success: true,
          translated: totalTranslated,
          details: totalTranslatedCounts,
        },
      };
    } catch (error) {
      console.error(`[Job ${job.id}] Translation failed:`, error);
      throw error;
    }
  },
};

What This Does:

Simple & Focused - Handles only Resources collection for tutorial clarity
Selective Translation - Only translates empty fields by default
Force Mode - Option to re-translate all fields
Retry Logic - 3 attempts with 1-second delays
Structure Preservation - Maintains array order and IDs
Fallback - Uses English value if translation fails
Metadata Tracking - Records when and how translation occurred

Want to translate multiple collections? This tutorial simplifies the code for learning purposes. For a production-ready implementation with type-safe mappers, field extractors, and support for multiple collections, check out the complete codebase on GitHub. Don't forget to give it a star!

Step 5: Create API Route for Job Queueing

This endpoint triggers translation jobs. It validates the requesting admin session, sanitizes and checks the request body (documentId, locales, force), and queues the translateResource job with the provided input. The implementation below uses cookie-based Payload auth and returns the queued job's ID on success.

// src/app/api/translate/route.ts
import { NextRequest, NextResponse } from "next/server";
import { getPayload } from "payload";
import config from "@/payload.config";

export async function POST(request: NextRequest) {
  try {
    const payload = await getPayload({ config });

    const cookies = request.cookies;
    const payloadToken = cookies.get("payload-token");

    if (!payloadToken) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }

    try {
      const { user } = await payload.auth({ headers: request.headers });
      if (!user) {
        return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
      }
    } catch (authError) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }

    const body = await request.json();
    const { documentId, locales, force } = body;

    if (!documentId || !locales) {
      return NextResponse.json(
        {
          error: "Missing required fields: documentId, locales",
        },
        { status: 400 },
      );
    }

    if (!Array.isArray(locales) || locales.length === 0) {
      return NextResponse.json(
        { error: "locales must be a non-empty array" },
        { status: 400 },
      );
    }

    const job = await payload.jobs.queue({
      task: "translateResource",
      input: {
        documentId,
        locales: locales.map((locale: string) => ({ locale })),
        force: force || false,
      },
      queue: "translation",
    });

    console.log(
      `Translation job queued: ${job.id} for resources:${documentId}`,
      { locales },
    );

    return NextResponse.json({
      success: true,
      jobId: job.id,
      message: "Translation job queued successfully",
    });
  } catch (error) {
    console.error("Failed to queue translation job:", error);
    return NextResponse.json(
      {
        error: "Internal server error",
        message: error instanceof Error ? error.message : "Unknown error",
      },
      { status: 500 },
    );
  }
}

Step 6: Create Admin UI Components

This step adds an admin-side UI — a translate button and modal — that lets editors pick target locales, toggle force mode, and queue translation jobs without leaving the editor.

Translate Button:

// src/components/TranslateButton.tsx
"use client";

import React, { useState } from "react";
import { toast, Button, useModal, useDocumentInfo } from "@payloadcms/ui";
import { LOCALES_WITHOUT_EN, TranslateModal } from "./TranslateModal";

export const TranslateButton: React.FC = () => {
  const { id } = useDocumentInfo();
  const [isLoading, setIsLoading] = useState(false);
  const { openModal } = useModal();

  const handleTranslateClick = async () => {
    if (!id) {
      toast.error("Document ID is required");
      return;
    }

    setIsLoading(true);

    try {
      if (LOCALES_WITHOUT_EN.length === 0) {
        toast.error("No target locales available for translation");
        return;
      }

      openModal("translate-modal");
    } catch (error) {
      console.error("Error opening translate modal:", error);
      toast.error("Failed to open translation modal");
    } finally {
      setIsLoading(false);
    }
  };

  if (!id) {
    return null;
  }

  return (
    <>
      <Button
        buttonStyle="primary"
        onClick={handleTranslateClick}
        disabled={isLoading}
      >
        {isLoading ? "Loading..." : "Translate (BETA)"}
      </Button>
      <TranslateModal />
    </>
  );
};

Translate Modal:

// src/components/TranslateModal.tsx
"use client";

import React, { useState } from "react";
import {
  Button,
  toast,
  Modal,
  useModal,
  useDocumentInfo,
} from "@payloadcms/ui";
import { LOCALES_WITHOUT_EN } from "@/locales";

export const TranslateModal: React.FC = () => {
  const { closeModal } = useModal();
  const { id } = useDocumentInfo();
  const [selectedLocales, setSelectedLocales] = useState<Set<string>>(
    new Set(),
  );
  const [force, setForce] = useState(false);
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleLocaleToggle = (locale: string) => {
    const newSelected = new Set(selectedLocales);
    if (newSelected.has(locale)) {
      newSelected.delete(locale);
    } else {
      newSelected.add(locale);
    }
    setSelectedLocales(newSelected);
  };

  const handleSelectAll = () => {
    if (selectedLocales.size === LOCALES_WITHOUT_EN.length) {
      setSelectedLocales(new Set());
    } else {
      setSelectedLocales(new Set(LOCALES_WITHOUT_EN));
    }
  };

  const handleSubmit = async () => {
    if (selectedLocales.size === 0) {
      toast.error("Please select at least one locale");
      return;
    }

    if (!id) {
      toast.error("Document ID is required");
      return;
    }

    setIsSubmitting(true);

    const body = {
      documentId: id.toString(),
      locales: Array.from(selectedLocales),
      force,
    };

    try {
      const response = await fetch("/api/translate", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
        credentials: "include",
        body: JSON.stringify(body),
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message || "Failed to start translation job");
      }

      const result = await response.json();

      toast.success(
        `Translation job #${result.jobId} queued! Check the Jobs section for progress.`,
      );

      closeModal("translate-modal");

      // Reset form
      setSelectedLocales(new Set());
      setForce(false);
    } catch (error) {
      console.error("Translation error:", error);
      toast.error(
        error instanceof Error
          ? error.message
          : "Failed to start translation job",
      );
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <Modal slug="translate-modal">
      <div
        style={{
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          minHeight: "100vh",
          padding: "20px",
        }}
      >
        <div
          style={{
            background: "var(--theme-elevation-0)",
            borderRadius: "8px",
            padding: "32px",
            maxWidth: "600px",
            width: "100%",
            boxShadow: "0 0 16px rgba(0, 0, 0, 0.25)",
          }}
        >
          <h2 style={{ marginTop: "0", marginBottom: "24px" }}>
            Auto-Translate
          </h2>

          <div>
            <div
              style={{
                display: "flex",
                justifyContent: "space-between",
                alignItems: "center",
              }}
            >
              <label style={{ fontWeight: "bold" }}>Locales</label>
              <Button
                buttonStyle="secondary"
                size="small"
                onClick={handleSelectAll}
              >
                {selectedLocales.size === LOCALES_WITHOUT_EN.length
                  ? "Deselect All"
                  : "Select All"}
              </Button>
            </div>
            <div
              style={{
                border: "1px solid #ccc",
                borderRadius: "4px",
                padding: "12px",
                maxHeight: "200px",
                overflowY: "auto",
                gap: "8px",
                marginTop: "8px",
              }}
            >
              {LOCALES_WITHOUT_EN.map((locale) => (
                <div
                  key={locale}
                  style={{
                    display: "flex",
                    alignItems: "center",
                    marginBottom: "8px",
                  }}
                >
                  <input
                    type="checkbox"
                    id={`locale-${locale}`}
                    checked={selectedLocales.has(locale)}
                    onChange={() => handleLocaleToggle(locale)}
                    style={{ marginRight: "8px" }}
                  />
                  <label htmlFor={`locale-${locale}`}>{locale}</label>
                </div>
              ))}
            </div>
          </div>

          <div
            style={{ display: "flex", alignItems: "center", marginTop: "20px" }}
          >
            <input
              type="checkbox"
              id="force-translate"
              checked={force}
              onChange={(e) => setForce(e.target.checked)}
              style={{ marginRight: "16px" }}
            />
            <label htmlFor="force-translate">
              <strong>Force re-translate all fields</strong>
              <br />
              <span style={{ fontSize: "0.75em", color: "#666" }}>
                If unchecked, only empty fields will be translated
              </span>
            </label>
          </div>

          <div
            style={{
              display: "flex",
              justifyContent: "flex-end",
              gap: "10px",
              marginTop: "24px",
            }}
          >
            <Button
              buttonStyle="secondary"
              onClick={() => closeModal("translate-modal")}
              disabled={isSubmitting}
            >
              Cancel
            </Button>
            <Button onClick={handleSubmit} disabled={isSubmitting}>
              {isSubmitting ? "Starting..." : "Start Translation"}
            </Button>
          </div>
        </div>
      </div>
    </Modal>
  );
};

Step 7: Update Collection Configuration

Wire the translate button into the collection UI and add a _translationMeta group so automated translations and audit data are stored alongside your content.

// src/collections/Resources.ts
import type { CollectionConfig } from "payload";

export const Resources: CollectionConfig = {
  slug: "resources",
  admin: {
    useAsTitle: "title",
    components: {
      edit: {
        SaveButton: "@/components/TranslateButton",
      },
    },
  },
  fields: [
    {
      name: "title",
      type: "text",
      localized: true,
      required: true,
      admin: {
        components: {
          Field: "@/components/LocalizedTextField",
        },
      },
    },
    {
      name: "list",
      type: "array",
      fields: [
        {
          name: "name",
          type: "text",
          localized: true,
          admin: {
            components: {
              Field: "@/components/LocalizedTextField",
            },
          },
        },
      ],
    },
    {
      name: "_translationMeta",
      type: "group",
      admin: {
        description: "Metadata about automatic translations",
        condition: (_, siblingData) => !!siblingData._translationMeta,
      },
      fields: [
        {
          name: "lastTranslatedAt",
          type: "date",
          admin: {
            readOnly: true,
          },
        },
        {
          name: "translatedBy",
          type: "text",
          admin: {
            readOnly: true,
          },
        },
      ],
    },
  ],
};

Step 8: Update Payload Config

Register the translation job, enable localization settings, and ensure the job is included in Payload's jobs configuration so queued translations run reliably.

// src/payload.config.ts
import path from "path";
import { buildConfig } from "payload";
import { fileURLToPath } from "url";
import { sqliteAdapter } from "@payloadcms/db-sqlite";
import { lexicalEditor } from "@payloadcms/richtext-lexical";
import { Resources } from "./collections/Resources";
import { Users } from "./collections/Users";
import { translateResourceJob } from "./jobs/translateResource";
import { AVAILABLE_LOCALES } from "./locales";

const filename = fileURLToPath(import.meta.url);
const dirname = path.dirname(filename);

export default buildConfig({
  admin: {
    user: "users",
    importMap: {
      baseDir: path.resolve(dirname),
    },
  },

  // Localization config
  localization: {
    locales: AVAILABLE_LOCALES,
    defaultLocale: "en",
    fallback: true,
  },

  // Jobs config for auto-translation
  jobs: {
    tasks: [translateResourceJob],
  },

  collections: [Users, Resources],
  editor: lexicalEditor(),
  secret: process.env.PAYLOAD_SECRET || "dev-secret-change-me",
  typescript: {
    outputFile: path.resolve(dirname, "payload-types.ts"),
  },
  db: sqliteAdapter({
    client: {
      url: process.env.DATABASE_URL || "file:./payload.db",
    },
  }),
});

Step 9: Generate Import Map and Types

npm run generate:importmap
npm run generate:types

This registers your custom components and generates TypeScript types.

How It Works

Complete Translation Flow

User clicks "Translate" button in admin UI
Modal opens with locale selection and force mode option
User submits translation request
API route verifies authentication and validates parameters
Job is queued in Payload's background job system
Job handler fetches English document from database
For each target locale:
- Fetch existing locale document
- Identify fields needing translation
- Group by locale for batch processing
Translation service:
- Checks cache for each text
- Batches uncached texts (up to 100 per request)
- Calls Azure Translator API
- Stores results in cache
Job handler updates documents with translations
Metadata recorded (timestamp, auto-translated flag)
User sees success message with job ID

Monitoring and Debugging

View Job Status

Navigate to Admin → Jobs in Payload
Find your translation job by ID
View status: pending, processing, completed, or failed
Check output for translation counts

Console Logs

The job handler logs progress:

[Job abc123] Translation started for resources:65f7a...
[Job abc123] Processing locale: es
[Job abc123] Translating 15 fields for es
[Job abc123] Translation completed. Total: 15

Error Handling

Common errors and solutions:

Error	Cause	Solution
`AZURE_TRANSLATOR_KEY is not configured`	Missing env var	Add to `.env.local`
`Unauthorized`	Not logged into admin	Log in to Payload admin
`Document not found`	Invalid document ID	Verify document exists
`Translation failed: Rate limit`	Too many requests	Wait and retry

Advanced Customization

Adding More Locales

Update two places:

Locales file:

// src/locales.ts
export const AVAILABLE_LOCALES: string[] = ["en", "es", "fr", "de"];
export const LOCALES_WITHOUT_EN = AVAILABLE_LOCALES.filter(
  (value) => value !== "en",
);

Regenerate types:

npm run generate:types

The locales are automatically used by:

Payload's localization config (in payload.config.ts)
TranslateModal component (imports LOCALES_WITHOUT_EN)
Translation validation (in locales.ts)

Supporting More Field Types

Extend the job handler to support other localized fields:

// Add textarea support
if (englishDoc.description) {
  if (shouldTranslate(englishDoc.description, targetDoc.description)) {
    fieldsToTranslate.push({
      path: "description",
      value: englishDoc.description,
      locale: targetLocale,
    });
  }
}

// Add nested fields
if (englishDoc.metadata?.title) {
  if (shouldTranslate(englishDoc.metadata.title, targetDoc.metadata?.title)) {
    fieldsToTranslate.push({
      path: "metadata.title",
      value: englishDoc.metadata.title,
      locale: targetLocale,
    });
  }
}

Using Redis for Distributed Caching

For multi-server deployments, replace LRU cache with Redis:

import { createClient } from "redis";

const redis = createClient({
  url: process.env.REDIS_URL,
});

await redis.connect();

// Get from cache
const cached = await redis.get(cacheKey);

// Set in cache
await redis.set(cacheKey, translatedText, {
  EX: CACHE_TTL, // Expiration in seconds
});

Benefits:

Shared cache across server instances
Persistent cache across restarts
Higher capacity (GBs vs MBs)

Auto-Translate on Save (Delta Translation)

Use Payload hooks (for example beforeChange/afterChange) to detect which English fields were modified and queue translation jobs for only those deltas. This keeps translations in sync, reduces API usage, and avoids translating unchanged content. Consider UI indicators for in-progress translations, field-level locking, and debouncing to prevent rapid repeated jobs.

Multi-Provider Translation Support

Azure is a solid default, but it isn't the only option — some languages or content types can produce better results with DeepL, Google Cloud, OpenAI, or other services. Add a provider abstraction and selection rules so you can route specific locales or content categories to the best provider, implement fallbacks, and monitor costs/quotas to balance quality against price.

Production Checklist

Before deploying to production:

[ ] Environment variables configured in production
[ ] Azure Translator key has sufficient quota
[ ] Job queue working (test with small document)
[ ] Backup database before first bulk translation
[ ] Cache size appropriate for your data volume
[ ] Error monitoring set up (Sentry, etc.)
[ ] Rate limiting configured if needed
[ ] Cost alerts set in Azure portal
[ ] User permissions reviewed (who can translate?)

Troubleshooting Common Issues

Translations Not Appearing

Check job status: Admin → Jobs → Find your job ID
Review job logs: Look for errors in console output
Verify authentication: Ensure you're logged into Payload admin
Check document: Switch to target locale in admin UI
Validate locales: Ensure target locale exists in config

Cache Not Working

Verify LRU cache: Check import and initialization in service
Test cache hit: Translate same content twice, check logs for "fromCache: true"
Cache size limit: Increase max if needed (default: 10,000 entries)
Memory issues: Monitor Node.js heap usage with -max-old-space-size
Production caching: Consider Redis for multi-instance deployments

Azure API Errors

"Invalid API key": Double-check AZURE_TRANSLATOR_KEY in environment variables
"Rate limit exceeded": Wait 60 seconds or upgrade Azure plan (F0 → S1)
"Invalid language code": Verify locale codes match Azure supported languages
"Text too long": Azure limit is 50,000 characters per text - batch large content
"Authentication failed": Check AZURE_TRANSLATOR_REGION matches resource location

Performance Issues

Slow translations: Increase batch size or upgrade Azure tier
Job timeouts: Split large jobs into smaller batches
Memory leaks: Clear cache periodically or use Redis
Database locks: Add retry logic with exponential backoff
Network errors: Implement connection pooling and retry strategies

Conclusion: Production-Ready Azure AI Translation for Payload CMS 2026

You've successfully implemented an enterprise-grade, scalable auto-translation system for Payload CMS with:

Azure AI Translator - Enterprise-quality translation for 100+ languages with 99.9% uptime
LRU Cache (7-day TTL) - Minimize API costs with intelligent caching (70%+ cost reduction)
Payload Background Jobs - Reliable async processing without HTTP timeouts
Batch Translation (100 texts/request) - Optimal Azure API usage and performance
Selective Mode - Preserve manual edits, translate only empty fields by default
Force Mode - Re-translate all fields when needed for content updates
Metadata Tracking - Complete audit trail for compliance and debugging
Type-Safe Implementation - Full TypeScript support with zero runtime errors

Technical Stack Summary

Payload CMS: 3.79.0
Next.js: 15.4.11 (App Router + API Routes)
Azure AI Translator: @azure-rest/ai-translation-text v1.0.1
Caching: lru-cache v11.2.7 (7-day TTL)
Utilities: radash v12.1.1 (retry logic)
TypeScript: 5.7.2
React: 19.0.0

Real-World Performance Metrics

Based on our production implementations at u11d:

Translation Speed: 100 fields in ~3 seconds (with cache: <100ms)
API Cost: $10 per million characters (Azure S1 tier)
Cache Hit Rate: 70-85% for typical content updates
Uptime: 99.9% (Azure SLA)
Concurrent Jobs: 10+ simultaneous translations without issues
Database Impact: Minimal (batched updates, optimized queries)

Next Steps & Advanced Features

Consider these production enhancements:

Automatic translation triggers - Translate on document publish via hooks
Translation quality scoring - Flag low-confidence translations for review
Custom glossaries - Brand-specific term preservation (Azure feature)
Translation memory - Learn from manual corrections
Multi-provider support - Fallback to Google/DeepL/OpenAI
Batch document translation - Translate multiple documents in one job
Translation diff viewer - Compare original vs. translated side-by-side
Cost monitoring - Track Azure API usage and set budget alerts

Additional Resources for Payload CMS Translation

Azure AI Translator Documentation - Official Azure docs
Payload Jobs API Documentation - Background job implementation
Azure Supported Languages - 100+ language codes
Azure Custom Translator - Brand terminology glossaries
Azure Pricing Calculator - Estimate translation costs
LRU Cache Documentation - Caching implementation details
Payload Discord Community - Get help from Payload experts
Complete Code on GitHub - Full implementation

Need Payload CMS Experts?

u11d specializes in Payload CMS development, migration, and deployment. We help you build secure, scalable Payload projects, migrate from legacy CMS platforms, and optimize your admin, API, and infrastructure for production. Get expert support for custom features, localization, and high-performance deployments.

Talk to Payload Experts

How to Show Default Locale Hints in Localized Array Fields in Payload CMS (2026 Guide)

Michał Miler — Mon, 13 Apr 2026 08:34:57 +0000

When building multilingual applications with Payload CMS and Next.js, content editors face a critical UX challenge: localized array fields appear completely empty in secondary locales, making translation workflows frustrating and error-prone. This comprehensive guide shows how to implement default locale hints in Payload CMS.

Real-World Scenario: The Empty Field Problem

Imagine you're building a multilingual eCommerce product catalog or SaaS application with Payload CMS. Your schema includes localized array fields like this:

{
  name: 'list',
  type: 'array',
  fields: [
    {
      name: 'name',
      type: 'text',
      localized: true,
    },
  ]
}

What happens:

English editor fills in all product names
Spanish editor switches locale to Spanish
All fields appear completely empty
Editor has no context about what needs translation

This creates several problems:

Editors waste time - They can't see what content exists in the default locale
Translation errors - No context leads to inconsistent translations
Workflow bottlenecks - Constant back-and-forth between locales
Poor UX - Frustrating editing experience

Why This Happens

This is not a bug in Payload CMS - it's by design. Understanding why helps you implement the correct solution.

How Payload Stores Localized Data

Payload CMS handles localization at the field level, not the document level. When you mark a field as localized: true:

{
  name: 'title',
  type: 'text',
  localized: true,
}

Payload stores it like this in the database:

{
  "title": {
    "en": "English Title",
    "es": "Título en Español"
  }
}

The Admin UI Only Shows Current Locale

The admin interface only renders the value for the active locale. If es is empty, you see an empty field - even though en has data.

Arrays Are Shared Across Locales

Arrays themselves are not localized - only the fields inside them:

{
  "list": [
    {
      "id": "1",
      "name": {
        "en": "Item One",
        "es": ""
      }
    }
  ]
}

The array structure is shared, but field values are locale-specific.

Fallback Only Works in the API

Payload's fallback: true config ensures empty locale values return the default locale via the API:

// payload.config.ts
localization: {
  locales: ['en', 'es'],
  defaultLocale: 'en',
  fallback: true, // <- Only affects API responses
}

This protects your frontend from showing empty content, but doesn't help editors in the admin UI.

The Solution Architecture

Our solution has three components:

Payload Config: API-level protection
API Route Handler + Auth + Cache: Verify auth & fetch via SDK
Custom Field Component: Show fallback in admin UI

Key Design Decisions:

Use GET requests (RESTful for read operations)
Verify authentication to prevent unauthorized access
Use Next.js API Route Handlers for parallel request handling
Implement in-memory caching to minimize database queries
Use Payload SDK (not REST API) for better performance and type safety
Single reusable component that works everywhere
Zero configuration - component reads context automatically

Step-by-Step Implementation

Step 1: Enable Required Configuration

First, ensure your Payload config has fallback enabled and Next.js has the experimental useCache flag enabled:

Payload Config:

// src/payload.config.ts
import { buildConfig } from "payload";

export default buildConfig({
  // ... other config

  localization: {
    locales: ["en", "es"],
    defaultLocale: "en",
    fallback: true, // <- Essential for API protection
  },

  // ... collections, etc.
});

Next.js Config:

// next.config.ts
import { withPayload } from "@payloadcms/next/withPayload";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  cacheComponents: true,
  experimental: {
    useCache: true, // <- Required for "use cache" directive
  },
};

export default withPayload(nextConfig);

Why this matters:

Payload fallback prevents your production frontend from showing empty content when translations are missing
Next.js useCache flag enables the "use cache" directive for optimal performance

Step 2: Create API Route Handler with Next.js Native Caching

Create a Next.js API route that uses Payload SDK to fetch the default locale value. This endpoint uses GET (RESTful for read operations), includes authentication checks for security, and leverages Next.js native caching with the "use cache" directive for optimal performance:

// src/app/api/default-locale-value/route.ts
import { NextRequest, NextResponse } from "next/server";
import { unstable_cacheLife as cacheLife } from "next/cache";
import { CollectionSlug, getPayload } from "payload";
import config from "@/payload.config";
import { get } from "radash";

async function getDefaultLocaleValue(
  collectionSlug: CollectionSlug,
  documentId: string,
  fieldPath: string,
) {
  "use cache";
  cacheLife("minutes");

  const payload = await getPayload({ config });

  const doc = await payload.findByID({
    collection: collectionSlug,
    id: documentId,
    locale: "en",
    depth: 0,
  });

  if (!doc) {
    return null;
  }

  const pathParts = fieldPath.split(".");
  let value = doc;

  for (const part of pathParts) {
    if (value === null || value === undefined) {
      return null;
    }

    value = get(value, part);
  }

  return typeof value === "string" ? value : null;
}

export async function GET(request: NextRequest) {
  try {
    const searchParams = request.nextUrl.searchParams;
    const collectionSlug = searchParams.get("collectionSlug") as CollectionSlug;
    const documentId = searchParams.get("documentId");
    const fieldPath = searchParams.get("fieldPath");

    if (!collectionSlug || !documentId || !fieldPath) {
      return NextResponse.json(
        { error: "Missing required parameters" },
        { status: 400 },
      );
    }

    const cookies = request.cookies;
    const payloadToken = cookies.get("payload-token");

    if (!payloadToken) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }

    const payload = await getPayload({ config });

    try {
      const { user } = await payload.auth({ headers: request.headers });
      if (!user) {
        return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
      }

      const value = await getDefaultLocaleValue(
        collectionSlug,
        documentId,
        fieldPath,
      );

      return NextResponse.json({ value });
    } catch (authError) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }
  } catch (error) {
    console.error("Failed to fetch English value:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 },
    );
  }
}

Key Points:

Next.js "use cache" directive - Automatic function-level caching
cacheLife configuration - Cache duration set to 60 seconds
RESTful GET method - Semantically correct for read operations
Authentication required - Verifies user is logged into Payload admin
Cookie-based auth - Checks for payload-token and validates session
Uses getPayload() for direct database access
Handles nested paths like list.0.name automatically
Returns null gracefully on errors
Zero configuration caching - No manual cache management needed

Step 3: Create Localized Text Field Component

Create a custom field component that shows the English value as a reference:

// src/components/LocalizedTextField.tsx
"use client";

import {
  useField,
  useLocale,
  useDocumentInfo,
  TextInput,
} from "@payloadcms/ui";
import React, { CSSProperties, useEffect, useState } from "react";

const FALLBACK_STYLE: CSSProperties = {
  marginTop: "8px",
  padding: "4px 8px",
  backgroundColor: "#f5f5f5",
  borderRadius: "4px",
  fontSize: "12px",
};

interface LocalizedTextFieldProps {
  path: string;
}

export const LocalizedTextField: React.FC<LocalizedTextFieldProps> = ({
  path,
}) => {
  const locale = useLocale();
  const { id, collectionSlug } = useDocumentInfo();
  const { value, setValue } = useField<string>({ path });
  const [englishValue, setEnglishValue] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);

  const isEnglish = locale.code === "en";

  useEffect(() => {
    if (isEnglish || !id || !collectionSlug) {
      setEnglishValue(null);
      return;
    }

    const fetchEnglishValue = async () => {
      setLoading(true);
      try {
        const params = new URLSearchParams({
          collectionSlug,
          documentId: id.toString(),
          fieldPath: path,
        });

        const response = await fetch(`/api/default-locale-value?${params}`, {
          method: "GET",
          credentials: "include", // Include cookies for authentication
        });

        if (!response.ok) {
          throw new Error("Failed to fetch English value");
        }

        const data = await response.json();
        setEnglishValue(data.value);
      } catch (error) {
        console.error("Failed to fetch English value:", error);
      } finally {
        setLoading(false);
      }
    };

    fetchEnglishValue();
  }, [id, isEnglish, path, collectionSlug]);

  return (
    <div>
      <TextInput
        path={path}
        value={value || ""}
        onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
          setValue(e.target.value)
        }
      />

      {!isEnglish && englishValue && (
        <div style={FALLBACK_STYLE}>EN: {englishValue}</div>
      )}

      {loading && <div style={FALLBACK_STYLE}>Loading English value...</div>}
    </div>
  );
};

export default LocalizedTextField;

What This Component Does:

Reads current locale from Payload's context
Fetches English value via authenticated GET request
Includes credentials to pass authentication cookies
Shows reference below the input for editorial context
Handles loading states gracefully
Works automatically - no manual configuration needed
Benefits from caching - subsequent loads are instant

Step 4: Apply to Your Collection Fields

Update your collection to use the custom component:

// src/collections/Resources.ts
import type { CollectionConfig } from "payload";

export const Resources: CollectionConfig = {
  slug: "resources",
  admin: {
    useAsTitle: "title",
  },
  fields: [
    {
      name: "title",
      type: "text",
      localized: true,
      required: true,
      admin: {
        components: {
          Field: "@/components/LocalizedTextField",
        },
      },
    },
    {
      name: "list",
      type: "array",
      fields: [
        {
          name: "name",
          type: "text",
          localized: true,
          admin: {
            description: "Localized field with English fallback reference",
            components: {
              Field: "@/components/LocalizedTextField",
            },
          },
        },
      ],
    },
  ],
};

Notice:

Simple configuration - just reference the component path
No props needed - component reads everything from context
Works in top-level fields (title) and array fields (list.*.name)
Same component, no duplication

Step 5: Generate Import Map

Run Payload's import map generator to register your custom components:

npx payload generate:importmap

This updates Payload's admin UI to use your custom components.

For production deployments with multiple localized collections, consider implementing automated translation workflows to scale your multilingual content. Check our Auto-Translation with Azure AI guide for the complete implementation.

How It Works: Request Flow

Flow Diagram

Editor switches to Spanish locale
Component detects locale is not English
Component calls GET /api/default-locale-value with query params
Route verifies user authentication via Payload session
Route checks Next.js native cache layer
Cache miss: Executes getDefaultLocaleValue (cached function)
Fetches document with locale=en via Payload SDK
Navigates to field path (e.g., list.0.name)
Result cached automatically by Next.js for 60 seconds
Returns to component
Component displays English value below input field

Performance Benefits with Next.js 15 Caching:

When editing a document with 100 localized array fields:

First load: 100 API requests → cached by Next.js
Subsequent loads (within 60s): Instant cache hits
Automatic invalidation: Cache refreshes after TTL expires
Edge-optimized: Compatible with Vercel Edge Runtime

Example: Editing an Array Item

English Locale:

Title: [Product Overview]

Spanish Locale (before typing):

Title: [                    ]
EN: Product Overview

Spanish Locale (after typing):

Title: [Descripción del Producto]
EN: Product Overview

The English reference stays visible for context.

Conclusion: Production-Ready Payload CMS Localization UX for 2026

Localized fields in Payload CMS arrays work correctly by design, but the default admin UX doesn't support translation workflows well. By implementing this Next.js 15 + Payload CMS solution with native caching, you:

Solve the empty field problem for editors - No more context switching between locales
Use Next.js 15 native caching for optimal performance - Instant load times with use cache directive
Follow RESTful API design with GET requests - Semantically correct, cacheable endpoints
Implement authentication to secure your endpoints - Prevent unauthorized access to field data
Use Payload SDK for type-safe database access - Better performance than REST API
Enable automatic cache management - Zero-config caching with configurable TTL
Create a reusable component that works everywhere - Single component for all localized fields
Lay the foundation for translation automation - Ready for AI-powered workflows

Key Takeaways for Developers & AI Agents

Enable fallback: true in Payload config for API-level protection
Use GET requests for read operations (RESTful best practice)
Always verify authentication to prevent unauthorized data access
Leverage Next.js use cache directive for function-level caching
Use Payload SDK (not REST API) for better type safety and performance
Create reusable components that read context automatically via hooks
Include credentials in fetch requests for cookie-based authentication
Consider automation for large-scale translation - see Auto-Translation with Azure AI
Implement security best practices from our Payload CMS Security guide
Monitor performance with proper caching TTL and cache hit rates

Need Payload CMS Experts?

Talk to Payload Experts

AWS Amplify vs Vercel: Complete Pricing Comparison for Next.js Applications

Michał Miler — Thu, 12 Mar 2026 15:55:59 +0000

When choosing a hosting platform for your Next.js application, understanding the true cost is crucial for making an informed decision. Both Vercel and AWS Amplify offer powerful deployment solutions, but their pricing models differ significantly. This comprehensive comparison analyzes the actual costs based on official pricing from both platforms, helping you determine which solution fits your budget and requirements.

The Pricing Challenge

Both platforms have strengths, but understanding their pricing structures is essential:

Vercel's Challenge: The free Hobby tier is strictly for personal, non-commercial use. Any business use requires the Pro plan at $20/month per team member, creating immediate baseline costs regardless of traffic.

AWS Amplify's Challenge: While there's no per-seat cost, the pricing structure involves multiple components (builds, bandwidth, storage, compute) that can be complex to predict without understanding your usage patterns.

Key Question: Which platform offers better value for your specific use case?

Vercel Pricing Structure

Hobby Plan (Free Forever)

Cost: $0/month

Included Resources:

100 GB Fast Data Transfer
1M Edge Requests
1M Function Invocations
4 hours Active CPU (Vercel Functions)
360 GB-hrs Provisioned Memory
1M ISR Reads, 200K ISR Writes
5K Image Transformations
Unlimited deployments

Restrictions: Personal and non-commercial use only

Pro Plan ($20/month per seat)

Base Cost: $20/month per team member

Included Resources:

$20 usage credit (can offset overages)
100 GB Fast Data Transfer
1M Edge Requests
1M Function Invocations
4 hours Active CPU (Vercel Functions)
360 GB-hrs Provisioned Memory
10 GB Fast Origin Transfer
1M ISR Reads, 200K ISR Writes
5K Image Transformations
1 GB Blob Storage
Team collaboration + free viewer seats
Advanced spend management

Overage Pricing: Usage beyond included amounts is charged separately (pricing varies by resource type)

Key Consideration: Team costs scale with size. A 5-person team = $100/month base cost before any usage overages.

AWS Amplify Pricing Structure

Free Tier (First 12 Months)

Cost: $0/month (for eligible usage)

Included Resources:

1,000 build minutes
15 GB data served
5 GB storage
500,000 requests
100 GB-hours SSR compute

Note: New AWS customers starting July 15, 2025 receive up to $200 in AWS Free Tier credits usable within 12 months

Pay-As-You-Go Pricing

Build & Deploy:

Standard builds: $0.01/minute
Enhanced builds: $0.025/minute
Turbo builds: $0.10/minute

Hosting:

Data transfer: $0.15/GB served
Storage: $0.023/GB/month
Requests: $0.30 per million

SSR Compute (if applicable):

$0.20 per GB-hour

Firewall (optional):

$15/month per Amplify app + WAF costs

Key Advantages:

No per-seat pricing (unlimited team members)
No base monthly fee (pay only for usage)
Multiple sites per project included
Public SSL certificates included

Cost Comparison Methodology

To provide accurate comparisons, we'll analyze costs across different scenarios based on:

Team Size: Solo developer vs. team of 5
Traffic Levels: Small (10K visitors/month), Medium (100K visitors/month), Large (500K visitors/month)
Deployment Frequency: 1 build/week (typical for production)
Average Page Size: 2MB (including assets)
Build Time: 5 minutes per build (standard Next.js app)

Comparison 1: Solo Developer with Small Traffic

Scenario: 1 developer, 10,000 visitors/month, 20 GB data transfer/month, 4 builds/month

Vercel Hobby (Free)

Base cost: $0
Data transfer: 20 GB (within 100 GB free)
Edge requests: ~30K (within 1M free)
Total: $0/month
Limitation: Cannot be used for commercial projects

Vercel Pro

Base cost: $20/month (1 seat)
Data transfer: 20 GB (within 100 GB included)
All other usage within included limits
Total: $20/month

AWS Amplify

Builds: 4 builds × 5 min × $0.01 = $0.20
Data transfer: 20 GB × $0.15 = $3.00
Storage: 1 GB × $0.023 = $0.02
Requests: 30K × $0.30/million = $0.01
Subtotal: $3.23/month
With Free Tier (first 12 months): $0/month (all usage covered)
After Free Tier: $3.23/month

Winner: AWS Amplify (96% savings) - After free tier: $3.23 vs $20

Comparison 2: Solo Developer with Medium Traffic

Scenario: 1 developer, 100,000 visitors/month, 200 GB data transfer/month, 4 builds/month

Vercel Pro

Base cost: $20/month (1 seat)
Data transfer: 200 GB
- Included: 100 GB
- Overage: 100 GB (~$15 estimated based on typical CDN costs)
Usage credit: $20 applies to overages
Total: ~$20-35/month (depending on exact overage rates)

AWS Amplify

Builds: 4 builds × 5 min × $0.01 = $0.20
Data transfer: 200 GB × $0.15 = $30.00
Storage: 5 GB × $0.023 = $0.12
Requests: 300K × $0.30/million = $0.09
Subtotal: $30.41/month
With Free Tier (first 12 months): ~$28/month (15 GB data + other limits covered)
After Free Tier: $30.41/month

Winner: Comparable (Vercel $20-35 vs Amplify $28-30)

Comparison 3: Team of 5 with Medium Traffic

Scenario: 5 developers, 100,000 visitors/month, 200 GB data transfer/month, 20 builds/month

Vercel Pro

Base cost: $20/month × 5 seats = $100/month
Data transfer: 200 GB
- Included: 100 GB
- Overage: ~100 GB (~$15)
Usage credit: $20 applies to overages
Total: ~$100-115/month

AWS Amplify

Builds: 20 builds × 5 min × $0.01 = $1.00
Data transfer: 200 GB × $0.15 = $30.00
Storage: 5 GB × $0.023 = $0.12
Requests: 300K × $0.30/million = $0.09
Subtotal: $31.21/month
With Free Tier (first 12 months): ~$29/month
After Free Tier: $31.21/month

Winner: AWS Amplify (73% savings) - $31 vs $100-115

Comparison 4: Team of 5 with Large Traffic

Scenario: 5 developers, 500,000 visitors/month, 1 TB (1,000 GB) data transfer/month, 20 builds/month

Vercel Pro

Base cost: $20/month × 5 seats = $100/month
Data transfer: 1,000 GB
- Included: 100 GB
- Overage: 900 GB (~$135 estimated)
Usage credit: $20 applies to overages
Total: ~$215/month

AWS Amplify

Builds: 20 builds × 5 min × $0.01 = $1.00
Data transfer: 1,000 GB × $0.15 = $150.00
Storage: 10 GB × $0.023 = $0.23
Requests: 1.5M × $0.30/million = $0.45
Subtotal: $151.68/month
With Free Tier (first 12 months): ~$149/month
After Free Tier: $151.68/month

Winner: AWS Amplify (29% savings) - $152 vs $215

Quick Comparison Table

Scenario	Vercel Pro	AWS Amplify	Savings	Notes
Solo, 10K visitors	$20	$3 ($0 first year)	85-100%	Can't use Vercel Hobby commercially
Solo, 100K visitors	$20-35	$28-30	0-20%	Comparable costs
Team of 5, 100K visitors	$100-115	$29-31	73%	Per-seat cost dominates
Team of 5, 500K visitors	$215	$149-152	29%	Bandwidth becomes factor

Additional Cost Factors

SSL Certificates

Vercel: Included (free, automatic)
Amplify: Included (free, automatic via AWS Certificate Manager)

Custom Domains

Vercel: Unlimited (free)
Amplify: Unlimited (free)

Preview Deployments

Vercel: Unlimited (included in all plans)
Amplify: Free (included)

Build Concurrency

Vercel Pro: No queues, faster builds
Amplify: First-come-first-served, can be slower during high demand

Analytics & Monitoring

Vercel: 10K Speed Insights events, 50K Web Analytics events (included)
Amplify: Use CloudWatch (pay-per-use, typically $2-10/month)

Image Optimization

Vercel: 5K transformations/month included
Amplify: Not included (use CloudFront + Lambda@Edge or third-party CDN)

Key Pricing Insights

When AWS Amplify Wins on Cost

Teams with 3+ developers: The per-seat pricing on Vercel ($20/month per developer) quickly adds up. Amplify has zero per-seat costs.
Moderate to high traffic: Once you exceed Vercel's included limits, bandwidth costs become significant. Amplify's $0.15/GB is competitive but avoid the per-seat baseline.
Multiple projects: No per-seat cost means you can host multiple projects without multiplying team costs.
Predictable traffic patterns: You can accurately forecast Amplify costs based on bandwidth and build frequency.

When Vercel Wins on Cost

Solo developers with low traffic: If you're within Hobby plan limits and it's a personal project, Vercel is free.
1-2 person teams with moderate traffic: The $20-40/month base cost might be comparable to Amplify once you factor in bandwidth.
Included features matter: If you heavily use Image Optimization, Speed Insights, or Web Analytics, the included quotas add value.

The Hidden Cost Factor: Developer Time

Vercel's Value: Zero-config deployments, instant previews, seamless Next.js integration can save hours of setup and troubleshooting. Critically, Vercel offers exclusive Next.js optimizations including:

Edge Functions with ultra-low latency execution at the edge
Incremental Static Regeneration (ISR) with better caching and invalidation
Next.js-specific features like Image Optimization, Font Optimization, and automatic code splitting
Edge Middleware for advanced routing and personalization
Native support for latest Next.js features (often available before other platforms)

Amplify's Trade-off: More configuration required, less polished DX, potential troubleshooting time. Amplify doesn't support some advanced Next.js features like Edge Runtime, Edge Middleware, or Vercel's optimized ISR implementation. However, costs are dramatically lower for teams.

ROI Calculation: If Amplify saves your 5-person team $85/month ($1,020/year), but requires 5 extra developer hours/year at $100/hour, Vercel might win on total cost. However, if setup is one-time and hosting cost savings compound monthly, Amplify wins. Consider whether your app needs Vercel's exclusive Next.js optimizations - if you rely heavily on Edge Functions, ISR, or cutting-edge Next.js features, Vercel may be the only viable option regardless of cost.

When to Choose Vercel

Choose Vercel if:

You need advanced Next.js features (Edge Functions, Edge Middleware, optimized ISR, cutting-edge Next.js support)
Performance at the edge is critical (ultra-low latency with edge compute)
You're a solo developer with a personal project (Hobby plan is free)
Team is 1-2 people and traffic is low-moderate (costs are comparable)
Developer experience is paramount (zero-config, instant previews, seamless integration)
You heavily use included features (Image Optimization, Analytics, Speed Insights)
Time-to-market is critical (faster setup, less configuration)
Budget accommodates premium pricing for better DX and exclusive features

When to Choose AWS Amplify

Choose AWS Amplify if:

Your app doesn't require Edge Functions or advanced Next.js features (standard SSR/SSG is sufficient)
Team has 3+ developers (saves $40-80+/month in per-seat fees)
Cost optimization is a priority (especially for small-medium businesses)
Traffic is moderate to high (bandwidth costs dominate, no seat fees)
You're already using AWS services (S3, Lambda, DynamoDB, etc.)
You want infrastructure control (access to underlying S3/CloudFront config)
Multiple projects/sites (no per-seat multiplication)

Pricing Summary by Scenario

Solo Developer

Low traffic (personal project): Vercel Hobby (free) wins
Low traffic (commercial): Amplify wins (85% savings: $3 vs $20)
Medium traffic: Comparable ($28-35 both platforms)
High traffic: Amplify wins slightly (lower baseline)

Small Team (2-3 developers)

Any traffic level: Amplify wins (30-70% savings)
Per-seat fees become significant: $40-60/month baseline vs $0

Medium-Large Team (5+ developers)

Any traffic level: Amplify wins significantly (70%+ savings)
Example: 5 devs, 100K visitors = $100+ (Vercel) vs $30 (Amplify)

Enterprise Scale

Both become expensive: Consider custom solutions (ECS, CloudFront + S3 direct)
Amplify still wins on per-seat costs: But contact both for enterprise pricing

The Real Cost Comparison

Factor	Vercel Pro	AWS Amplify	Winner
Base monthly cost (1 dev)	$20	$0	Amplify
Per additional developer	+$20	$0	Amplify
Bandwidth (per GB)	~$0.15*	$0.15	Tie
Build time	Free	$0.01/min	Vercel
Setup complexity	Very easy	Moderate	Vercel
Free tier generosity	Good (Hobby)	Excellent (12 months)	Amplify
Edge Functions	Included	Not available	Vercel
Edge Middleware	Included	Not available	Vercel
Image optimization	Included	Extra cost	Vercel
Analytics	Included	Extra cost	Vercel
Infrastructure control	Limited	Full	Amplify

*Estimated based on typical overage patterns

Bottom Line Recommendations

Choose Vercel if: You need Edge Functions, Edge Middleware, or cutting-edge Next.js features; value developer experience over cost; have a small team (1-2 people); or need zero-config deployment.

Choose Amplify if: Your app works with standard SSR/SSG (no edge compute required), you have a team of 3+ developers, cost optimization matters, or you want to avoid per-seat pricing that scales with team size.

For most businesses with development teams: Amplify offers 30-75% cost savings, primarily by eliminating per-seat fees. The trade-off is more configuration, slightly less polished developer experience, and lack of support for advanced Next.js features like Edge Functions and Edge Middleware. Evaluate your technical requirements first - if you need Vercel's exclusive optimizations, cost savings may be secondary.

Next Steps

Ready to try AWS Amplify and see the cost savings yourself? Check out our step-by-step deployment guide for Next.js on AWS Amplify.

Note: Pricing information accurate as of January 2026. Always verify current pricing on Vercel's pricing page and AWS Amplify's pricing page before making decisions.

How to Deploy Next.js 16 SSG to AWS Amplify: Complete Guide

Michał Miler — Tue, 24 Feb 2026 07:02:03 +0000

Deploying Next.js Static Site Generation (SSG) applications to AWS Amplify can be challenging without the right configuration. While Vercel offers a seamless experience, AWS Amplify may provide a cost-effective alternative with up to 96% savings for smaller sites and 20-30% for medium-traffic applications. In this comprehensive guide, we'll walk through the exact steps to successfully deploy your Next.js 16 SSG site to AWS Amplify.

Why AWS Amplify for SSG?

AWS Amplify is particularly attractive for SSG deployments because:

Lower costs than Vercel, especially for commercial use (see our detailed cost comparison)
No per-seat pricing for team collaboration
Generous free tier for the first 12 months
Standard AWS infrastructure (S3 + CloudFront) with no vendor lock-in

Note on static export limitations: Static Site Generation pre-generates all pages at build time. This means no server-side rendering (SSR), no Incremental Static Regeneration (ISR), and no API routes. If you need these features, you'll need a different deployment strategy.

Prerequisites

Before we begin, ensure you have:

Node.js 22.x or later installed
Next.js 16 project using App Router
An AWS account (free tier eligible for 12 months)
Git repository (GitHub, GitLab, Bitbucket, or AWS CodeCommit)
Basic familiarity with Next.js App Router

Step 1: Configure Next.js 16 for SSG

Update `next.config.ts`

Create or modify your next.config.ts file to enable static export:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
  images: {
    unoptimized: true,
  },
};

export default nextConfig;

Key Points:

output: 'export' disables the Next.js runtime and enforces a full static export. This ensures your site can be deployed as plain static HTML/CSS/JS.
images.unoptimized: true disables Next.js Image Optimization API (required for static export)

Handle Image Optimization

Since Next.js Image Optimization doesn't work with static exports, choose one of these options:

Option 1: Unoptimized images (simplest for testing)

import Image from "next/image";

<Image src="/images/photo.jpg" width={500} height={300} alt="Description" />;

Option 2: Standard HTML img tags

<img src="/images/photo.jpg" width={500} height={300} alt="Description" />

Option 3: Third-party CDN (recommended for production)

Use services like Cloudflare Images, Cloudinary, or imgix. See our guide on optimizing S3 images with Cloudflare Images.

const imageLoader = ({
  src,
  width,
  quality,
}: {
  src: string;
  width: number;
  quality?: number;
}) => {
  return `https://your-cdn.com/${src}?w=${width}&q=${quality || 75}`;
};

<Image
  loader={imageLoader}
  src="photo.jpg"
  width={500}
  height={300}
  alt="Description"
/>;

Verify SSG Compatibility

Ensure your project doesn't use these incompatible features:

Cannot use:

Route Handlers (API Routes) - require server runtime
Server-Side Rendering (SSR) - e.g., cache: 'no-store' in fetches
Incremental Static Regeneration (ISR) - revalidate property
Dynamic data without generateStaticParams — including any data fetched from “dynamic APIs” that depend on runtime values (see Next.js guide on dynamic rendering)

Must implement:

All dynamic routes need generateStaticParams to pre-generate pages
Use cache: 'force-cache' for data fetching at build time

Example for dynamic routes:

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  return [{ slug: "first-post" }, { slug: "second-post" }];
}

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>Blog Post: {slug}</h1>;
}

Test Locally

Verify your static export works:

npm run build
npx serve out

Visit http://localhost:3000 to ensure everything renders correctly.

Step 2: Deploy to AWS Amplify

Push to Git

git add .
git commit -m "Configure Next.js for SSG deployment"
git push origin main

Access AWS Amplify Console

Log into AWS Console
Search for "Amplify" in the services search bar
Click "Get Started" under "Amplify Hosting"

Connect Your Repository

Select your Git provider (GitHub, GitLab, Bitbucket, or AWS CodeCommit)
Authorize AWS Amplify to access your repositories
Choose the repository and branch to deploy
Click "Next"

Configure Build Settings

Amplify should auto-detect Next.js, but verify your amplify.yml:

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: out
    files:
      - "**/*"
  cache:
    paths:
      - node_modules/**/*

Critical settings:

baseDirectory: out - Next.js static export directory
npm ci - Consistent, reproducible builds
Cache node_modules for faster builds

Add Environment Variables (Optional)

If your app needs environment variables, add them in "Advanced settings":

NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=G-XXXXXXXXXX

Remember: Only NEXT_PUBLIC_* variables are accessible in the browser. Server-side variables are available during build time only.

Deploy

Review settings
Click "Save and deploy"
Monitor the build progress (typically 3-5 minutes)

Once complete, you'll get a URL like: https://[branch].[app-id].amplifyapp.com

Step 3: Configure Redirects & Routing

Fix 404 Pages

Configure redirects in Amplify console under "Rewrites and redirects":

Rule 1: Custom 404 page

Source: </^[^.]+$|\\.(?!(css|gif|ico|jpg|js|png|txt|svg|woff|woff2|ttf|map|json|webp)$)([^.]+$)/>
Target: /404.html
Status: 404

Rule 2: Client-side routing fallback

Source: /<*>
Target: /index.html
Status: 200 (Rewrite)

Important: Place Rule 2 last - Amplify processes rules in order.

Step 4: Handle Common Considerations

Environment Variables

Client Components (with "use client"):

Can only access NEXT_PUBLIC_* variables
Variables are embedded in the build output

Server Components (default):

Can access all environment variables at build time
Never expose secrets in NEXT_PUBLIC_* variables

Forms and Interactive Features

SSG sites need external services for dynamic functionality:

Forms: Formspree, Web3Forms, AWS Lambda
Search: FlexSearch, Fuse.js, Algolia, Meilisearch
Comments: Giscus, Utterances, Disqus
Authentication: Clerk, Auth0, AWS Cognito

Next.js 16 App Router Features

Works perfectly with SSG:

Metadata API
Route Groups
Loading and Error UI
Server Components (data fetched at build time)

Requires pre-generation:

Dynamic routes (use generateStaticParams)
Parallel and Intercepting Routes (all combinations must be pre-generated)

Troubleshooting Common Issues

Build Fails: "Output directory not found"

Fix: Verify amplify.yml has baseDirectory: out and next.config.ts has output: 'export'

Images Not Loading

Fix: Ensure images.unoptimized: true in config. Images should be in public/ directory and referenced without the public prefix.

Blank Page After Deployment

Fix: Check browser console for errors. Usually means:

Missing NEXT_PUBLIC_ prefix on environment variables
Client-side JavaScript error
Incorrect build output

Dynamic Routes Return 404

Fix:

Implement generateStaticParams for all dynamic routes
Configure redirect rules in Amplify console

Environment Variables Not Working

Fix:

Client-side variables must use NEXT_PUBLIC_ prefix
Set in Amplify Console under "Environment variables"
Rebuild after adding new variables

When NOT to Use This Approach

Consider alternatives if you need:

Incremental Static Regeneration (ISR): Requires Node.js server
Server-Side Rendering (SSR): Real-time, per-request rendering
API Routes: Need serverless functions
On-demand Revalidation: Dynamic content updates without rebuilds
Edge Middleware: Complex routing logic at the edge

For these use cases, consider Vercel, AWS Amplify with SSR configuration, or AWS App Runner/ECS.

Next Steps

After deployment:

Add custom domain: In Amplify console under "Domain management"
Set up monitoring: Use CloudWatch for build and deployment alerts
Configure preview deployments: For pull requests and feature branches
Optimize costs: Review bandwidth usage and optimize images
Test thoroughly: Verify all pages and features work as expected

Conclusion

AWS Amplify provides a cost-effective platform for deploying Next.js 16 SSG applications with proper configuration. The key is understanding SSG limitations, configuring Next.js correctly, and setting up Amplify's build and routing properly.

While the setup requires more configuration than Vercel, the cost savings (up to 96% for small sites) and lack of per-seat pricing make it an excellent choice for businesses looking to optimize their hosting costs without sacrificing performance or reliability.

How We Built Seamless ERP Integration for Medusa: Base.com Case Study

Michał Miler — Mon, 15 Dec 2025 08:40:27 +0000

If you're running an e-commerce business, you know the pain: your products live in your ERP system, but your online store needs constant updates. Inventory changes, new products arrive, prices fluctuate, and orders need to flow back to your warehouse management system.

The manual approach is a nightmare:

Hours spent copying product data between systems
Inventory discrepancies leading to overselling
Order details manually entered into your ERP
Human errors causing fulfillment delays
Scaling becomes impossible as your catalog grows

For businesses using Medusa as their e-commerce platform, the challenge is finding the right integration that keeps everything in sync without breaking the bank or requiring a team of developers.

Why Medusa + ERP Integration Matters

Medusa is a powerful, modern e-commerce framework built for customization. However, Medusa is rarely the only system in your business — you often need to connect it with your existing business tools, especially your ERP.

Proper ERP integration transforms how your business operates. With real-time inventory accuracy, you'll never oversell products or waste time on manual stock updates. Automated product management means that when you add new products to your ERP, they appear in your store automatically with all their descriptions, images, and pricing intact. Orders flow seamlessly from checkout to your warehouse, eliminating the bottleneck of manual data entry and the costly errors that come with it. Perhaps most importantly, this automation enables true scalability — your business can grow from hundreds to thousands of products without requiring additional staff to handle the data synchronization.

What Can Be Synchronized

A proper Medusa-ERP integration should handle the complete product and order lifecycle. Starting with products, the integration synchronizes everything from product titles and descriptions to images, media assets, categories, collections, and custom attributes that make your catalog unique.

Pricing is another critical component — the system maintains base prices and sale prices across multiple currencies, handles tax configurations automatically, and applies volume discounts and pricing rules consistently across both platforms.

For inventory management, the integration tracks real-time stock levels across multiple warehouses, maps stock locations between systems, triggers low stock alerts when needed, and manages inventory reservations to prevent overselling.

Finally, order synchronization creates orders automatically in your ERP the moment they're placed in Medusa, transferring customer information and shipping details seamlessly. The integration keeps order statuses updated in real-time and tracks both payment and fulfillment progress throughout the entire order lifecycle.

Integrating Medusa with Base.com ERP

Base.com (formerly BaseLinker) is a popular ERP system used by thousands of e-commerce businesses. It provides comprehensive tools for inventory management, order processing, multi-channel sales, and warehouse operations.

The Challenge

Businesses running Medusa with Base.com face several synchronization challenges. Managing thousands of product variants across systems becomes overwhelming without automation. Keeping inventory accurate across multiple warehouses in real-time requires constant vigilance. Orders need to flow automatically from the storefront to the ERP for fulfillment. Product pricing and descriptions must stay synchronized without manual updates. The scale and complexity of modern e-commerce catalogs make manual synchronization impossible.

The Solution: @u11d/medusa-base Plugin

To address these challenges, we built an open-source Medusa plugin that handles bidirectional synchronization between Medusa and Base.com. The plugin provides automated product synchronization with a simple API endpoint that fetches everything from product information (titles, descriptions, images) to all product variants and options, pricing across different markets, and stock levels from all connected warehouses. An intelligent mapping system uses helper database tables to maintain relationships between Base.com and Medusa, ensuring data consistency and enabling fast lookups during synchronization. The real-time order creation feature automatically captures order details, maps Medusa products to Base.com product IDs, creates the order in Base.com with the correct status, and updates inventory across both systems. Finally, scheduled synchronization allows you to set up automated syncs on your preferred schedule, running continuously in the background.

How It Works in Practice

The workflow is straightforward. Your team manages the product catalog in Base.com ERP, where they add new products, update descriptions and specifications, manage inventory across warehouses, and set prices and promotional offers.

Product Synchronization

The plugin runs on schedule or on-demand, pulling all changes automatically — new products appear in your Medusa store, product details are updated, prices sync across all variants, and inventory levels reflect real-time warehouse data.

Order Flow

When a customer completes checkout, the order is captured in Medusa with all details.

The plugin automatically creates the order in Base.com, enabling the warehouse team to begin fulfillment immediately.

Results and Benefits

The integration delivers measurable benefits: synchronization handles over 10,000 products in minutes with 100% inventory accuracy, saves 20+ hours per week on manual data entry, scales seamlessly as your catalog grows, and creates orders in your ERP within seconds of checkout.

Beyond Base.com: Custom ERP Integrations

The Base.com integration is just one example of what's possible. The same approach works for virtually any ERP system, including enterprise-grade solutions like SAP Business One for mid to large businesses, Microsoft Dynamics as a comprehensive business management suite, and NetSuite for cloud-based ERP and financial management. We also work with Odoo, the popular open-source ERP for growing businesses, as well as custom proprietary or legacy systems. If your system has a REST API or any accessible interface, we can build an integration for it.

Extending the Base.com Plugin

Already using Base.com but need additional features? We can extend the plugin with custom field mappings to handle your unique product attributes, advanced pricing rules for complex business models, sophisticated multi-warehouse logic, B2B customer-specific pricing tiers, integration with additional Base.com modules beyond the core functionality, and custom synchronization schedules with filters to sync only what you need.

Why Choose u11d for Your ERP Integration

We bring deep expertise in the Medusa ecosystem as active contributors who understand the framework inside-out. Our integrations follow Medusa best practices and are built for long-term maintainability. Beyond technical skills, we understand e-commerce operations, inventory management, and the challenges of scaling an online business.

Our commitment to open source is evident in our Base.com plugin, which is fully available on GitHub and npm. We believe in transparency and community-driven development. With a proven track record of building integrations for payment providers, shipping carriers, ERP systems, and custom business logic for e-commerce brands around the world, we provide end-to-end support from initial consultation to deployment and ongoing maintenance.

Ready to Integrate Your ERP with Medusa?

Whether you need integration with Base.com using our plugin or with custom features, connection to your existing ERP system, custom synchronization logic for your unique business needs, migration from another platform to Medusa, or performance optimization of existing integrations — we're here to help.

Let's discuss your specific ERP integration needs. We'll review your current setup and provide a clear roadmap for integration.

👉 Contact us at https://u11d.com/contact/

Medusa Testing Guide: How to Test Your E-Commerce Store for Scalability and Reliability

Michał Miler — Wed, 03 Dec 2025 10:15:00 +0000

Testing your Medusa e-commerce store is more than a technical chore - it’s the foundation of a smooth customer experience and reliable revenue growth. Even a small bug in checkout or payments can lead to abandoned carts, lost trust, and thousands in missed sales. As your store scales, the stakes get higher.

In this guide, we’ll cover how to test your Medusa store effectively - from unit and integration tests to full end-to-end, performance, and security testing. You’ll learn the tools, best practices, and strategies that help Medusa-based stores handle real-world traffic, avoid regressions, and scale with confidence.

Why Testing Matters in E-Commerce

E-commerce platforms face unique challenges that make testing particularly critical:

Catching Regressions Early: A single breaking change in your checkout flow can cost thousands in lost sales before you even notice. Automated tests catch these issues during development, not in production.

Proving Requirements Are Met: Whether it's ensuring your platform can handle Black Friday traffic or validating that discount codes calculate correctly, tests provide objective proof that your system meets both functional and performance requirements.

Reducing Risk in Rapid Development: E-commerce platforms evolve constantly - new payment methods, shipping integrations, promotional campaigns. Without tests, each change becomes a potential disaster.

Maintaining Customer Trust: Cart abandonment, payment failures, or inventory sync issues erode customer confidence. Testing helps ensure the smooth experience that modern consumers expect.

Manual vs. Automated Testing

Both manual and automated testing have their place in a mature QA strategy:

Manual Testing excels at exploratory scenarios, usability evaluation, and edge cases that are difficult to predict. Your QA team can assess the actual user experience in ways that automated tests cannot fully replicate.

Automated Testing provides consistency, speed, and coverage at scale. Once written, automated tests can run on every code change, in every environment, without human intervention. This is where CI/CD pipelines become powerful - automatically running your test suite on every pull request ensures nothing broken reaches production.

The key is balance. Use automation for repetitive verification and regression prevention, while reserving manual testing for nuanced evaluation and new feature exploration.

Types of Testing for Medusa E-Commerce

1. Unit Testing

What it is: Testing individual components or functions in isolation to verify they behave correctly with various inputs.

Why it matters: Unit tests are your first line of defense. They're fast to run, easy to debug, and catch logic errors at the source. In e-commerce, this might mean testing price calculation functions, discount logic, or tax computation.

In Medusa:

Test your custom business logic components:

Jobs: Background tasks and scheduled operations
Services: Business logic like pricing strategies or custom inventory management
Workflows: Complex multi-step operations like order fulfillment or return processing
Subscribers: Event handlers that respond to system events
Utilities: Helper functions for currency formatting, validation, or calculations

Example Technology: Medusa starters include Jest out of the box, pre-configured for testing your backend components.

Best Practices:

Aim for high coverage on business-critical logic
Keep tests isolated - no database dependencies
Use mocks for external services
Test edge cases and error conditions

2. Integration Testing

What it is: Testing how multiple components work together, including interactions with databases, APIs, and external services.

Why it matters: Your discount service might work perfectly in isolation, but what happens when it interacts with inventory management and the order creation workflow? Integration tests reveal these real-world scenarios.

In Medusa:

Test complete API endpoints: Does POST /store/carts/:id/payment-sessions correctly create sessions with all configured payment providers?
Test database interactions: Does your custom repository correctly query and update related entities?
Test event subscribers: When an order is placed, do all necessary webhooks fire correctly?

Example Technology: Jest with Medusa's test utilities for setting up test databases, or Supertest for API endpoint testing.

3. End-to-End (E2E) Testing

What it is: Testing complete user workflows from start to finish, either at the API level (full route testing) or in a browser (full user flow testing).

Why it matters: E2E tests validate that all pieces of your system work together from the user's perspective. They catch issues that unit and integration tests miss, like authentication flows, multi-page interactions, or third-party integration failures.

In Medusa:

API-Level E2E: Test complete routes through your backend

Full customer journey: /store/carts → /store/carts/:id/line-items → /store/carts/:id/complete
Admin workflows: Create product → Update inventory → Publish → Verify in store API
For a detailed breakdown of the Medusa checkout flow and how to test each step, see our step-by-step Medusa checkout flow guide

Browser-Level E2E: Test the complete user experience in your storefront

Browse products → Add to cart → Checkout → Payment → Confirmation
Admin dashboard workflows: Login → Manage orders → Process returns

Example Technologies:

Playwright: Modern, reliable browser automation with excellent debugging
Cypress: Developer-friendly E2E testing with time-travel debugging
Postman/Newman: API testing with collection runners for CI/CD
REST Client: Simple HTTP file-based API testing

4. Load and Performance Testing

What it is: Testing how your system performs under stress - simulating hundreds or thousands of concurrent users to identify bottlenecks and capacity limits.

Why it matters: E-commerce traffic is unpredictable. A viral social media post or holiday sale can multiply your traffic 10x in minutes. Load testing helps you understand your limits before customers do.

In Medusa:

Backend Load Testing:

Test critical routes: /store/products, /store/carts/:id/complete
Test database query performance under load
Test rate limiting and caching strategies

Full Stack Load Testing:

Test your entire stack including Next.js storefront, Medusa backend, and database
Simulate realistic user behavior patterns
Measure actual user-perceived performance

Example Technologies:

k6: Modern, developer-friendly load testing with JavaScript (see our comprehensive Medusa checkout load testing with k6 guide)
Artillery: YAML-based load testing, great for quick scenarios
Gatling: Powerful JVM-based tool for complex scenarios
Apache JMeter: Traditional but feature-rich performance testing

5. Security Testing

What it is: Testing for vulnerabilities, authentication flaws, and data exposure risks.

Why it matters: E-commerce platforms handle sensitive customer data, payment information, and financial transactions. A security breach can be catastrophic - both financially and reputationally.

In Medusa:

Test authentication and authorization: Can customers access other users' orders?
Test input validation: Are you protected against SQL injection, XSS?
Test rate limiting: Can someone brute-force payment methods?
Test API key security: Are admin endpoints properly protected?

Example Technologies:

OWASP ZAP: Automated security scanner
Burp Suite: Professional security testing toolkit
npm audit / yarn audit: Dependency vulnerability scanning
Snyk: Continuous security monitoring

6. Accessibility Testing

What it is: Ensuring your e-commerce platform is usable by people with disabilities, meeting WCAG standards.

Why it matters: Beyond legal compliance, accessibility expands your customer base and improves usability for everyone. Plus, many accessibility improvements also boost SEO.

Testing Areas:

Keyboard navigation through checkout
Screen reader compatibility
Color contrast ratios
Form label associations
ARIA attributes

Example Technologies:

axe DevTools: Browser extension for automated accessibility checks
Pa11y: Command-line accessibility testing
Lighthouse: Includes accessibility scoring
NVDA/JAWS: Manual testing with actual screen readers

Building a Testing Strategy for Your Medusa Store

A mature testing strategy layers multiple approaches:

The Testing Pyramid

Base (Largest Layer) - Unit Tests: Fast, abundant, testing individual functions and services. Run on every code change. Target: 70-80% of your tests.

Middle Layer - Integration Tests: Testing component interactions and API endpoints. Run in CI pipeline. Target: 15-20% of your tests.

Top (Smallest Layer) - E2E Tests: Critical user paths tested in full. Run before releases and on schedule. Target: 5-10% of your tests.

Performance Tests: Run periodically and before major releases. Not part of the pyramid but essential for e-commerce.

Testing Best Practices for E-Commerce

Test Real Scenarios: Don't just test happy paths. Test abandoned carts, payment failures, out-of-stock situations, concurrent purchases of limited inventory.

Use Production-Like Data: Test with realistic product catalogs, customer data volumes (anonymized), and traffic patterns.

Test Third-Party Integrations: Payment gateways, shipping providers, and tax calculators fail. Test their failure modes too.

Monitor Test Performance: Slow tests don't get run. Keep your test suite fast or developers will skip it.

Maintain Your Tests: Flaky tests erode confidence. Treat test maintenance as seriously as production code.

Test Localization: If you support multiple regions, test currency formatting, tax calculations, and shipping logic for each.

Common Testing Pitfalls to Avoid

Over-mocking: Too many mocks mean you're not testing reality
Testing Implementation Instead of Behavior: Tests shouldn't break when you refactor
Ignoring Test Failures: Fix or remove failing tests immediately
No Test Data Strategy: Inconsistent test data leads to flaky tests
Testing in Production Only: By then it's too late

Conclusion

Comprehensive testing in Medusa isn’t just about catching bugs - it’s about safeguarding your revenue, scaling without fear, and delivering the seamless shopping experience your customers expect. By layering unit, integration, and E2E tests, and reinforcing them with performance and security checks, you create a testing strategy that grows with your business.

Start small: cover your business-critical services with unit tests, then expand into API integration and storefront E2E flows. Before major launches, run load and security tests to uncover bottlenecks and vulnerabilities early.

Ready to level up your QA strategy? Explore our Medusa load testing tutorial, or grab our pre-configured Medusa starter repo to hit the ground running with testing built-in.

Frequently Asked Questions (FAQ) about Medusa Testing

Q: How do I test my Medusa store before going live?

A: Start with unit tests for business-critical logic (like pricing and checkout), then add integration tests to verify API endpoints and database operations. Finally, run end-to-end tests with Playwright or Cypress to simulate real customer flows in your storefront.

Q: Does Medusa support automated testing out of the box?

A: Yes. Medusa ships with Jest pre-configured for backend testing. You can extend your setup with Supertest for API testing and Playwright or Cypress for browser-based workflows.

Q: What’s the best way to test Medusa performance under heavy traffic?

A: Use load testing tools like k6 or Artillery to simulate peak traffic scenarios (e.g., Black Friday). Focus on critical endpoints such as /store/carts/:id/complete to ensure your store can scale without downtime.

Q: Do I need manual testing if I already have automated tests?

A: Yes. Automated tests prevent regressions, but manual testing is still valuable for exploratory scenarios, usability evaluation, and edge cases that automation can’t cover.

Q: How do I ensure my Medusa store is secure?

A: Run security tests using tools like OWASP ZAP or Snyk. Validate authentication, authorization, input handling, and rate limiting. Also, keep dependencies updated with npm audit or yarn audit.

US Tax Calculations in E-Commerce: How to Get It Right

Michał Miler — Tue, 18 Nov 2025 07:30:13 +0000

If you're selling across multiple US states, you already know tax compliance isn't simple. Different rates for different states, varying rules for different product categories, and constantly changing nexus requirements create a compliance minefield. But the real cost isn't just about calculations — it's about what happens when you get them wrong.

The Hidden Price of Tax Errors

Incorrect tax calculations lead to customer complaints, revenue leakage, and audit penalties. The average audit penalty ranges from $10,000 to $50,000, not counting legal fees and staff time. Even worse, manual tax management scales poorly. As your business grows across states, the operational burden multiplies.

Why Manual Tax Calculations Fall Short

Relying on manual tax tables and static configurations creates significant risks, regardless of your platform. Manual tax management requires constant updates as rates change across 12,000+ jurisdictions, and even a single outdated rate can trigger compliance issues.

The real challenge isn't the platforms themselves — Shopify, WooCommerce, and Magento all support tax automation through integrations. The problem is managing taxes manually without automated solutions. Manual approaches struggle with complex scenarios: exemption certificate verification, origin-based taxation for multi-warehouse setups, shipping to multiple addresses, partial refunds with accurate tax adjustments, and tax-included pricing for international customers.

The Automation Advantage

Avalara AvaTax solves the accuracy problem with real-time calculations based on constantly updated tax rules, handling 12,000+ jurisdictions automatically. But Avalara needs a flexible platform to unlock its full potential.

This is where Medusa excels. As a headless, open-source e-commerce platform, Medusa offers the extensibility that Shopify lacks and the modern architecture that Magento can't match — without the enterprise price tag.

Complete Solution Features

The Medusa-Avalara integration handles:

Automated tax calculations for all US jurisdictions
Tax exemption certificate management
Address validation to prevent errors
Transaction management (commit on order completion, void on cancellation)
Multi-warehouse support for origin-based calculations
Tax-included pricing for international expansion

Automation doesn't just reduce errors — it eliminates the operational burden of tax management, letting you focus on growth instead of compliance.

Future-Proof Your Tax Compliance

Choosing an e-commerce platform today means choosing your compliance capabilities for years to come. Medusa's API-first architecture ensures you can adapt as regulations change, new sales channels emerge, or your business model evolves.

Tax compliance shouldn't be a barrier to growth. With the right platform and automation, it becomes a competitive advantage.

Need help with Avalara integration?

Looking to implement automated tax compliance with Avalara in your Medusa store? u11d specializes in e-commerce integrations and tax automation solutions. We can help you set up, customize, and optimize your Avalara integration for maximum compliance and efficiency. Our team has extensive experience with both Medusa e-commerce platforms and Avalara tax systems, ensuring seamless integration that meets your specific business requirements.

Contact Us

Medusa Tax Automation: Complete Guide to Integrating Avalara AvaTax for E-Commerce Compliance

Michał Miler — Wed, 08 Oct 2025 08:18:37 +0000

Tax calculations in e-commerce can be deceptively complex. What seems like a straightforward percentage calculation quickly becomes a maze of jurisdictional rules, product-specific rates, and compliance requirements. From varying state and local tax rates to different rules for digital goods, shipping taxes, and cross-border transactions, managing tax compliance manually is not only time-consuming but also risky from a legal standpoint.

This is where Avalara AvaTax shines. AvaTax is a cloud-based tax automation platform that handles real-time tax calculations, transaction recording, and compliance reporting across multiple jurisdictions worldwide. It takes the complexity out of tax management by providing accurate, up-to-date tax rates and handling the intricate details of tax law automatically.

Thanks to our @u11d/medusa-avalara plugin, integrating this powerful tax automation into your Medusa store is now straightforward. The plugin seamlessly connects your e-commerce store with Avalara's comprehensive tax platform, enabling automatic tax calculations during checkout and proper transaction lifecycle management for compliance purposes.

Prerequisites: Getting Ready for Tax Automation

Before diving into the integration, you'll need:

Medusa Store Setup

A working Medusa v2.8.0+ e-commerce store
Basic familiarity with Medusa configuration

Avalara Account

You can get started with Avalara in two ways:

Self-service: Sign up directly at Avalara's Get Started page
Assisted setup: Contact us - our team can help you set up your Avalara account and ensure optimal configuration for your specific use case

With an Avalara account, you'll have access to both sandbox and production environments, comprehensive tax code databases, and detailed transaction reporting.

Avalara Configuration: Setting Up Your Tax Foundation

Before integrating with Medusa, let's configure your Avalara account properly. In this example, we'll use Denmark as our business location, but Avalara supports tax calculations for businesses around the world.

1. Configure Company Location

Your company location is fundamental for accurate tax calculations. Navigate to Settings → Company locations in your Avalara dashboard:

Set up your primary business location with accurate address details. This information is used to determine your tax obligations and shipping origin for calculations.

2. Generate License Keys

API access requires license keys for authentication. Go to Settings → License and API keys:

Generate both sandbox and production license keys. Keep these secure as they provide access to your tax calculation services.

3. Configure Tax Reporting Jurisdictions

This step is crucial for compliance. Navigate to Settings → Where you report tax:

Important: For US-based businesses, you must configure all states where you have tax obligations. This determines where Avalara will calculate and report taxes for your transactions.

Medusa Integration: Bringing Tax Automation to Your Store

Now let's integrate the Avalara plugin with your Medusa store. We'll start by examining our demo products and then implement the complete integration.

1. Demo Store Overview

Let's look at our sample products before implementing tax calculations:

These products will serve as our test cases for different tax scenarios once we implement Avalara integration.

2. Install the Plugin

Add the Avalara plugin to your Medusa project:

yarn add @u11d/medusa-avalara

3. Configure Your Medusa Setup

Add the plugin to your medusa-config.ts file. The withAvalaraPlugin wrapper handles all the complex module registration automatically:

import { loadEnv, defineConfig } from "@medusajs/framework/utils";
import { AvalaraPluginOptions, withAvalaraPlugin } from "@u11d/medusa-avalara";

loadEnv(process.env.NODE_ENV || "development", process.cwd());

const avalaraPluginOptions: AvalaraPluginOptions = {
  accountId: 0, // your account ID
  licenseKey: "your_license_key",
  environment: "sandbox",
  companyId: 0, // your company ID
  companyCode: "DEFAULT",
};

module.exports = defineConfig(
  withAvalaraPlugin(
    {
      projectConfig: {
        databaseUrl: process.env.DATABASE_URL,
        http: {
          storeCors: process.env.STORE_CORS!,
          adminCors: process.env.ADMIN_CORS!,
          authCors: process.env.AUTH_CORS!,
          jwtSecret: process.env.JWT_SECRET || "supersecret",
          cookieSecret: process.env.COOKIE_SECRET || "supersecret",
        },
      },
    },
    avalaraPluginOptions
  )
);

Important Notes:

It's strongly recommended to call POST /store/carts/${cartId}/taxes (docs) before checkout to ensure taxes are recalculated correctly. Medusa doesn't automatically recalculate taxes when cart properties change (quantity, address, discounts), which can lead to incorrect amounts. See issue #13929

The withAvalaraPlugin wrapper handles plugin modules registration and dependency injection automatically.

You can use environment variables instead of hardcoding options, especially important for credentials like accountId and licenseKey

The plugin automatically syncs your Medusa stock locations with Avalara locations on startup for accurate tax calculations. However, since Medusa doesn't emit events for stock location changes, if you create or update a location after startup, you'll need to either restart the app or manually call POST /admin/avalara-cache/feed to refresh the cache

The plugin fully supports tax-inclusive pricing and automatically respects the region's tax-inclusive preferences

The region's Automatic Taxes configuration is critical for API efficiency. When enabled, Medusa calls the tax provider's getTaxLines method multiple times during the checkout flow (on shipping address updates, shipping method selection, etc.), which significantly increases the number of requests to the Avalara API. To optimize performance and reduce API calls, it's recommended to disable automatic taxes and instead manually trigger tax calculation by calling POST /store/carts/{id}/taxes from your storefront when the order is ready for review — typically after the shipping method has been selected.

Discounts should be used with caution. Medusa does not use the exact tax amounts returned by Avalara but instead calculates taxes using the rates provided, which may lead to minor differences in final tax calculations when discounts are applied.

4. Run Database Migration

The plugin requires database tables to manage product-specific tax codes:

npx medusa db:migrate

This creates the necessary avalara_product table for storing product-to-tax-code mappings.

5. Start Your Medusa Server

Run your Medusa server in development mode:

yarn dev

This starts both the backend API and admin panel, making them available for configuration and testing.

6. Configure Tax Provider in Admin Panel

Now let's enable Avalara as your tax provider:

Start your Medusa server and access the admin panel
Navigate to Settings → Tax Regions
Select your target country/region and click Edit
Choose Avalara as your tax provider
Save the configuration

7. Configure Product-Specific Tax Codes

Avalara needs to know which tax code applies to each product. Different products may require different tax treatments - for example, clothing might be taxed differently than electronics or digital goods.

First, get your authentication token:

curl -X POST <http://localhost:9000/auth/user/emailpass> \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your_email",
    "password": "your_password"
  }'

Then configure tax codes for your products using the token generated in the previous step:

curl -X PUT <http://localhost:9000/admin/avalara-products> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_auth_token>" \
  -d '{
    "avalara_products": [
      {
        "product_id": "prod_01K6AFSSSK3GQZN2704T0RAGX6",
        "tax_code": "PC030610"
      },
      {
        "product_id": "prod_01K6AFSSSKA844GATSJYC68QB7",
        "tax_code": "PC040100"
      },
      {
        "product_id": "prod_01K6AFSSSKDMAXDD33X8NS217Y",
        "tax_code": "PC030610"
      },
      {
        "product_id": "prod_01K6AFSSSKVP1ZECDJ1Z210RE2",
        "tax_code": "PC040100"
      }
    ]
  }'

You can find the complete list of Avalara tax codes at: https://taxcode.avatax.avalara.com/search

Testing Your Tax Integration

8. Storefront Tax Calculations

Let's test the integration by adding a product to the cart in your storefront:

Important: Ensure your storefront is configured with a valid Medusa publishable API key for proper authentication.

Notice that taxes aren't calculated yet because no shipping address has been provided. Avalara requires a destination address to determine the appropriate tax jurisdiction and rates.

9. Adding Shipping Address for Tax Calculation

Once you provide a shipping address, Avalara automatically calculates the appropriate taxes:

The tax amount is now calculated based on:

The destination address jurisdiction
The product's assigned tax code
Current tax rates for that location

10. Shipping Method Tax Calculation

When you select a shipping method, notice that shipping is also taxable, and the total tax amount increases accordingly:

This demonstrates that the plugin properly handles both product and shipping tax calculations.

Order Lifecycle and Avalara Transaction Management

11. Order Placement and Avalara Integration

When you place an order, the plugin automatically creates a corresponding transaction in Avalara. Let's examine this process:

The transaction is initially created as "uncommitted" - this represents a completed sale but allows for modifications before final recording for tax compliance purposes.

12. Transaction Lifecycle Management

The plugin manages the complete transaction lifecycle:

Order Placed: Creates a Sales Invoice in Avalara (permanent transaction record)
Order Completed: Commits the transaction in Avalara for final tax reporting
Order Canceled: Voids the transaction in Avalara to ensure accurate tax records

This automatic lifecycle management ensures your tax records in Avalara always reflect the actual state of your orders, maintaining compliance without manual intervention.

Conclusion

Implementing automated tax calculations with Avalara transforms your e-commerce tax management from a complex, error-prone manual process to a seamless, compliant automation. The @u11d/medusa-avalara plugin makes this integration straightforward while handling all the technical complexities behind the scenes.

Key benefits of this integration include:

Accurate Tax Calculations: Real-time rates from Avalara ensure precise tax amounts
Compliance Automation: Automatic transaction recording and reporting reduce compliance burden
Global Reach: Support for tax calculations across multiple jurisdictions worldwide
Developer Friendly: Simple configuration with comprehensive documentation and support

Whether you're launching a new e-commerce store or upgrading an existing tax system, this plugin provides a production-ready foundation for automated tax compliance.

If you need additional features or customizations for the plugin, we welcome contributions to the open-source project or feel free to contact us for professional development support.

Resources

Documentation: GitHub Repository
NPM Package: @u11d/medusa-avalara
Avalara Tax Codes: Tax Code Search
Getting Started with Avalara: Avalara Documentation

Need help with Avalara integration?

Our team has extensive experience with both Medusa e-commerce platforms and Avalara tax systems, ensuring seamless integration that meets your specific business requirements.

Let's discuss your Avalara integration needs

Load Testing Medusa.js Checkout Flow with k6: A Complete Performance Testing Guide

Michał Miler — Tue, 30 Sep 2025 11:26:49 +0000

When building an e-commerce platform with Medusa.js, ensuring your checkout process can handle high traffic loads is crucial for business success. A slow or failing checkout directly impacts revenue and customer satisfaction. In this article, we'll explore how to create comprehensive load tests for the Medusa checkout flow using k6, focusing on the complete customer journey from cart creation to order completion.

Understanding Medusa Checkout Flow and Load Testing Challenges

The Medusa checkout process involves multiple API calls and state transitions that must work seamlessly under load:

Cart Creation: Initialize a new shopping cart for the customer
Product Addition: Add items to the cart with inventory checks
Address Setting: Configure shipping and billing information
Shipping Selection: Choose delivery options and calculate costs
Payment Processing: Handle payment collection and authorization
Order Completion: Finalize the purchase and create the order

Each step depends on the previous one, creating a complex chain of operations that needs to be tested under realistic load conditions. The challenge is simulating authentic user behavior while maintaining data consistency and avoiding test interference.

Prerequisites

Before implementing load tests for your Medusa checkout flow, ensure you have the following setup:

Environment Setup

k6 installed: Follow the k6 installation guide for your operating system
Medusa instance running: Have a local or staging Medusa store accessible (typically at http://localhost:9000)

Medusa Store Configuration

Region created: At least one region configured in your Medusa admin (needed for cart creation)
Products and variants: Test products with available inventory and valid variant IDs
Shipping options: Configured shipping methods for your test region
Payment providers: At least one payment provider enabled (e.g., manual payment provider for testing)
Publishable API key: Generated from your Medusa admin dashboard for API authentication

k6 Executors

k6 offers various executors to simulate different load patterns. Understanding these helps design realistic test scenarios:

per-vu-iterations: Each virtual user runs a fixed number of iterations (great for checkout flows)
constant-vus: Maintains a constant number of virtual users for a duration
ramping-vus: Gradually increases/decreases virtual users over time
constant-arrival-rate: Maintains a steady request rate regardless of response times
ramping-arrival-rate: Gradually changes the arrival rate of new iterations

The choice of executor should align with your specific testing requirements, business goals, and target performance metrics. Each executor type provides different insights and simulates distinct real-world scenarios, so select based on your performance testing objectives.

Practical Example: Complete Medusa Checkout Load Test

Initial Setup

Here's our k6 script that demonstrates comprehensive checkout flow testing:

import { check } from "k6";
import http from "k6/http";

export const options = {
  scenarios: {
    placeOrder: {
      executor: "per-vu-iterations",
      vus: 5,
      iterations: 2,
      maxDuration: "10m",
    },
  },
};

const PRODUCT_VARIANT_ID = "variant_01234567890"; // Replace with actual variant ID
const REGION_ID = "reg_01234567890"; // Replace with actual region ID
const SHIPPING_OPTION_ID = "so_01234567890"; // Replace with actual shipping option ID
const PAYMENT_PROVIDER_ID = "pp_system_default";
const BASE_URL = "http://localhost:9000/store";
const PUBLISHABLE_API_KEY = "pk_01234567890"; // Replace with actual API key

const HEADERS = {
  "Content-Type": "application/json",
  "x-publishable-api-key": PUBLISHABLE_API_KEY,
};

function fetch(method, path, body = null) {
  const url = `${BASE_URL}${path}`;
  const payload = body ? JSON.stringify(body) : null;

  return http.request(method, url, payload, { headers: HEADERS });
}

export default function () {
  // Step 1: Create Cart
  const createCartRes = fetch("POST", "/carts", { region_id: REGION_ID });
  check(createCartRes, { "cart created": (r) => r.status === 200 });
  const cartId = createCartRes.json("cart.id");

  // Step 2: Add Item to Cart
  const addItemRes = fetch("POST", `/carts/${cartId}/line-items`, {
    variant_id: PRODUCT_VARIANT_ID,
    quantity: 1,
  });
  check(addItemRes, { "item added": (r) => r.status === 200 });

  // Step 3: Set Shipping Address and Email
  const setAddressRes = fetch("POST", `/carts/${cartId}`, {
    shipping_address: {
      first_name: "John",
      last_name: "Doe",
      address_1: "Nordmarksvej 9",
      city: "Billund",
      country_code: "dk",
      postal_code: "7190",
      phone: "1234567890",
    },
    email: "john.doe@example.com",
  });
  check(setAddressRes, { "address set": (r) => r.status === 200 });

  // Step 4: Set Shipping Method
  const setShippingRes = fetch("POST", `/carts/${cartId}/shipping-methods`, {
    option_id: SHIPPING_OPTION_ID,
  });
  check(setShippingRes, { "shipping set": (r) => r.status === 200 });

  // Step 5: Create Payment Collection
  const createPaymentCollectionRes = fetch("POST", "/payment-collections", {
    cart_id: cartId,
  });
  check(createPaymentCollectionRes, {
    "payment collection created": (r) => r.status === 200,
  });
  const paymentCollectionId = createPaymentCollectionRes.json(
    "payment_collection.id"
  );

  // Step 6: Initialize Payment Session
  const initPaymentSessionRes = fetch(
    "POST",
    `/payment-collections/${paymentCollectionId}/payment-sessions`,
    {
      provider_id: PAYMENT_PROVIDER_ID,
    }
  );
  check(initPaymentSessionRes, {
    "payment sessions initialized": (r) => r.status === 200,
  });

  // Step 7: Complete Cart (Place Order)
  const completeCartRes = fetch("POST", `/carts/${cartId}/complete`);
  check(completeCartRes, { "cart completed": (r) => r.status === 200 });
}

How It Works

Configuration Setup: The script defines essential configuration including virtual users (VUs), iterations, and API endpoints.
Medusa API Integration: Uses the Medusa Store API with proper authentication via publishable API keys.
Sequential Checkout Flow: Each step builds upon the previous one, simulating realistic user behavior.
Comprehensive Validation: Each API call includes checks to verify successful responses, ensuring the entire flow works under load.
Realistic Load Simulation: The test runs 10 concurrent virtual users, each performing 5 complete checkout iterations, simulating real-world traffic patterns.

Running the Tests

Execute your load tests with these commands:

# Test complete checkout flow performance
k6 run place-order.js

# Run with custom configuration
k6 run --vus 50 --iterations 100 place-order.js

Cloud-Based Load Testing

Consider running your k6 tests in the cloud environment to achieve more stable and reliable results. Cloud-based testing eliminates local system limitations and enables testing with thousands of concurrent users, providing consistent performance metrics across test runs.

For large-scale load testing that requires significant compute resources, you can deploy k6 tests on AWS infrastructure. Check out our comprehensive guide on E-commerce Load Testing with k6 and AWS ECS Fargate to learn how to set up scalable, distributed load testing infrastructure that can simulate thousands of concurrent users without the constraints of local hardware.

Interpreting Results

k6 provides comprehensive metrics to analyze your Medusa store's performance:

Response Times: Monitor API response times for each checkout step
Success Rates: Track the percentage of successful transactions
Throughput: Measure requests per second your store can handle
Error Analysis: Identify bottlenecks in specific checkout steps

Conclusion

Load testing your Medusa.js checkout flow with k6 is essential for ensuring reliable e-commerce operations. Through proper test implementation, monitoring, and continuous optimization, you can maintain high performance even during peak traffic periods. Regular load testing helps identify bottlenecks early, validate performance improvements, and build confidence in your store's ability to handle customer demand.

Looking for acceleration in e-commerce development?

u11d specializes in Medusa.js development, DevOps optimization, and performance engineering. We can help you build scalable e-commerce solutions, optimize existing stores, or implement comprehensive testing strategies. With our expertise, you can ensure your Medusa store performs excellently under any load.

Let's have a chat

Medusa Checkout Flow: Step-by-Step Guide to Building a Complete E-Commerce Checkout

Michał Miler — Thu, 25 Sep 2025 13:41:49 +0000

Building an e-commerce storefront requires implementing a robust checkout flow that handles cart management, shipping, and payment processing. Medusa.js provides a comprehensive set of Store APIs that make this process straightforward. In this article, we'll explore the complete Medusa checkout flow by walking through each API endpoint required to take a customer from an empty cart to a completed order.

Understanding the Medusa Checkout Process

The Medusa checkout flow consists of seven essential steps:

Cart Creation - Initialize a new shopping cart
Add Items - Add products to the cart
Set Shipping Address - Configure delivery information
Select Shipping Method - Choose delivery options
Payment Collection - Initialize payment processing
Payment Session - Set up payment provider
Complete Order - Finalize the purchase

Each step builds upon the previous one, creating a seamless user experience while maintaining data integrity throughout the process.

Prerequisites and Setup

Before diving into the implementation, ensure you have:

A running Medusa v2 application
Valid publishable API key
Product variants, regions, and shipping options configured
Payment provider set up (we'll use the system default)
curl and jq installed for making API requests and parsing JSON responses

`curl` and `jq` Installation

# macOS (using Homebrew)

brew install curl jq

# Ubuntu/Debian

sudo apt update
sudo apt install curl jq

# Windows (using Chocolatey)

choco install curl jq

Environment Variables

Set the following variables before running the checkout flow:

export BASE_URL="<http://localhost:9000>"
export PUBLISHABLE_KEY="pk_<your_publishable_key_here>"
export REGION_ID="reg_<your_region_id>"
export PRODUCT_VARIANT_ID="variant_<your_variant_id>"
export SHIPPING_OPTION_ID="so_<your_shipping_option_id>"
export PAYMENT_PROVIDER_ID="pp_system_default"

Note: The CART_ID and PAYMENT_COLLECTION_ID variables should be set during the checkout process after cart creation and payment collection initialization.

Step-by-Step Implementation

1. Create a New Cart

The checkout journey begins with creating a new cart associated with a specific region:

curl -X POST "$BASE_URL/store/carts" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "region_id": "'$REGION_ID'" }'

Key Points:

Each cart gets a unique identifier used in subsequent API calls
Regions define currency, tax rates, and fulfillment settings

2. Add Products to Cart

Once the cart exists, add product variants with specified quantities:

curl -X POST "$BASE_URL/store/carts/$CART_ID/line-items" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "variant_id": "'$PRODUCT_VARIANT_ID'", "quantity": 1 }'

Key Points:

Use variant_id rather than product_id for specific product configurations
Quantities can be updated by calling this endpoint again
Inventory levels are automatically checked during this step

3. Set Shipping Address and Customer Information

Configure the delivery address and customer contact details:

curl -X POST "$BASE_URL/store/carts/$CART_ID" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "Nordmarksvej 9",
      "city": "Billund",
      "country_code": "dk",
      "postal_code": "7190",
      "phone": "1234567890"
    },
    "email": "john.doe@example.com"
  }'

Key Points:

country_code must match the region's available countries
Email is required for order confirmation and customer account association
Billing address can be set separately if different from shipping address

4. Select Shipping Method

Choose from available shipping options for the cart's region and address:

curl -X POST "$BASE_URL/store/carts/$CART_ID/shipping-methods" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "option_id": "'$SHIPPING_OPTION_ID'" }'

5. Create Payment Collection

Initialize the payment processing system for the cart:

curl -X POST "$BASE_URL/store/payment-collections" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "cart_id": "'$CART_ID'" }'

6. Initialize Payment Session

Set up the payment provider session for processing:

curl -X POST "$BASE_URL/store/payment-collections/$PAYMENT_COLLECTION_ID/payment-sessions" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "provider_id": "'$PAYMENT_PROVIDER_ID'" }'

Key Points:

Payment providers (Stripe, PayPal, etc.) require specific session initialization
Provider ID must match configured payment providers in your Medusa setup
Session contains payment intent or equivalent for the provider

7. Complete the Order

Finalize the checkout process and create the order:

curl -X POST "$BASE_URL/store/carts/$CART_ID/complete" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY"

Key Points:

This step validates all cart information and processes payment
Inventory is reserved and order confirmation is triggered
The cart is converted to an immutable order record

Complete Implementation Example

Here's a complete shell script implementing the entire checkout flow:

#!/bin/bash

# Configuration
BASE_URL="<http://localhost:9000>"
PUBLISHABLE_KEY="pk_"
REGION_ID="reg_"
PRODUCT_VARIANT_ID="variant_"
SHIPPING_OPTION_ID="so_"
PAYMENT_PROVIDER_ID="pp_system_default"

# 1. Create cart
echo "Creating cart..."
CART_RESPONSE=$(curl -s -X POST "$BASE_URL/store/carts" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "region_id": "'$REGION_ID'" }')

CART_ID=$(echo $CART_RESPONSE | jq -r '.cart.id')
echo "Cart created with ID: $CART_ID"

# 2. Add item to cart
echo "Adding item to cart..."
curl -s -X POST "$BASE_URL/store/carts/$CART_ID/line-items" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "variant_id": "'$PRODUCT_VARIANT_ID'", "quantity": 1 }' > /dev/null

# 3. Set shipping address and email
echo "Setting shipping address..."
curl -s -X POST "$BASE_URL/store/carts/$CART_ID" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "Nordmarksvej 9",
      "city": "Billund",
      "country_code": "dk",
      "postal_code": "7190",
      "phone": "1234567890"
    },
    "email": "john.doe@example.com"
  }' > /dev/null

# 4. Set shipping method
echo "Setting shipping method..."
curl -s -X POST "$BASE_URL/store/carts/$CART_ID/shipping-methods" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "option_id": "'$SHIPPING_OPTION_ID'" }' > /dev/null

# 5. Create payment collection
echo "Creating payment collection..."
PAYMENT_COLLECTION_RESPONSE=$(curl -s -X POST "$BASE_URL/store/payment-collections" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "cart_id": "'$CART_ID'" }')

PAYMENT_COLLECTION_ID=$(echo $PAYMENT_COLLECTION_RESPONSE | jq -r '.payment_collection.id')
echo "Payment collection created with ID: $PAYMENT_COLLECTION_ID"

# 6. Initialize payment session
echo "Initializing payment session..."
curl -s -X POST "$BASE_URL/store/payment-collections/$PAYMENT_COLLECTION_ID/payment-sessions" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
  -d '{ "provider_id": "'$PAYMENT_PROVIDER_ID'" }' > /dev/null

# 7. Complete the cart
echo "Completing order..."
ORDER_RESPONSE=$(curl -s -X POST "$BASE_URL/store/carts/$CART_ID/complete" \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: $PUBLISHABLE_KEY")

ORDER_ID=$(echo $ORDER_RESPONSE | jq -r '.order.id')
echo "Order completed successfully: $ORDER_ID"

Troubleshooting

Check Service Health: Test if the service is responding by visiting http://localhost:9000/store/products in your browser. You should see a JSON response with available products.
Validate API Key: Confirm your publishable API key is correct and has proper permissions for store operations.
No Products Available: Verify products exist in your store by checking the /store/products endpoint. Ensure products are published and have available variants.
Invalid Shipping Address:
- Validate address format matches the expected country standards
- Ensure the country_code is listed under the region's allowed countries
- Check /store/regions/{region_id} to see available countries for your region
Shipping Option Not Available: Verify the shipping option is enabled for the selected region and address. Check /store/shipping-options for available options in your region.
Insufficient Inventory: Check stock levels before adding items. The API will return inventory errors if requested quantities exceed available stock.
Payment Provider Issues:
- Ensure the payment provider is properly configured in your Medusa setup
- Handle payment failures gracefully with appropriate error messaging
- Verify payment provider credentials are valid

Conclusion

The Medusa checkout flow provides a robust foundation for e-commerce applications with its well-structured API endpoints. By following this seven-step process, you can build reliable checkout experiences that handle modern e-commerce requirements.

Key takeaways:

Each step depends on the previous one's completion
Implement proper validation and retry logic
Track cart state throughout the process
Provide user feedback at each step

This approach supports various checkout scenarios including guest flows, multiple payment methods, and subscription purchases.

Medusa V1 Redis Caching Guide: Boost API Performance 77% Faster

Michał Miler — Thu, 18 Sep 2025 09:23:38 +0000

Building a high-performance e-commerce store isn't just about having great products - it's about delivering lightning-fast experiences that keep customers engaged. In the world of headless commerce, where API response times directly impact user experience, performance optimization becomes critical. This comprehensive guide shows you how to implement Redis caching in Medusa V1 to dramatically improve your store's performance, complete with real-world benchmarks and production-ready code.

Why Performance Matters in E-commerce

The Cost of Slow Stores

Modern e-commerce customers expect instant responses. Studies show that:

A 1-second delay can reduce conversions by 7%
53% of mobile users abandon sites that take longer than 3 seconds to load
Fast-loading stores have higher SEO rankings and better user engagement
Performance directly impacts revenue - especially during high-traffic periods like Black Friday

Common Performance Bottlenecks

Before diving into solutions, let's identify the typical performance challenges:

Database Query Overhead: Repeated queries for popular products, categories, and configurations
Complex Product Filtering: Multi-attribute searches that hit the database hard
Concurrent User Load: Multiple users accessing the same data simultaneously

Performance Baseline: Before Optimization

Let's establish our performance baseline using autocannon to simulate realistic e-commerce traffic:

Test Scenario

Endpoint: Product listing API (/store/products)
Load: 500 concurrent virtual users
Requests: 10,000 total product fetches
Environment: Standard Medusa V1 Starter (create-medusa-app) with PostgreSQL

Baseline Results (Without Caching)

Stat	Latency
2.5%	3430 ms
50%	4885 ms
97.5%	8397 ms
99%	9070 ms
Avg	5054.33 ms
Stdev	965.89 ms
Max	9452 ms

Analysis: The median response time of 4.8 seconds is unacceptable for modern e-commerce. Peak latencies approaching 10 seconds would result in massive customer abandonment.

Implementing Redis Caching: Architecture & Code

Redis Service Foundation

Our caching implementation starts with a robust Redis service that handles connection management and basic operations. You can find the complete implementation in our GitHub repository.

// src/services/redis.ts
import { Logger } from "@medusajs/medusa";
import { Lifetime } from "awilix";
import Redis from "ioredis";

export class RedisService {
  static LIFE_TIME = Lifetime.SINGLETON;
  private readonly client = new Redis(process.env.REDIS_URL);
  private logger: Logger;

  constructor({ logger }: { logger: Logger }) {
    this.logger = logger;
  }

  async set(key: string, value: string | number, ttl?: number) {
    try {
      if (ttl) {
        await this.client.set(key, value, "EX", ttl);
      } else {
        await this.client.set(key, value);
      }
      this.logger.debug(`[redis] Set key "${key}", TTL ${ttl || "infinite"}`);
    } catch (error) {
      this.logger.error(`[redis] Failed to set key "${key}": ${error}`);
    }
  }

  async get(key: string): Promise<string | null> {
    try {
      const value = await this.client.get(key);
      this.logger.debug(`[redis] Get key "${key}": ${value ? "HIT" : "MISS"}`);
      return value;
    } catch (error) {
      this.logger.error(`[redis] Failed to get key "${key}": ${error}`);
      return null;
    }
  }
}

Cache Provider with Advanced Features

The CacheProviderService implements sophisticated caching patterns including cache locking to prevent thundering herd problems:

// src/services/cache-provider.ts
export class CacheProviderService {
  private readonly locks: Map<string, Promise<any>> = new Map();
  private readonly keyPrefix = "medusa:cache";

  async withCache<T>(
    identifier: CacheIdentifier,
    dataProvider: () => Promise<T>,
    timeToLive: Seconds,
    lockTimeout: Seconds = 30
  ): Promise<T> {
    const resolvedKey = this.generateCacheKey(identifier);

    const cachedValue = await this.fetchFromCache<T>(resolvedKey);
    if (cachedValue) {
      return cachedValue;
    }

    let lockPromise = this.locks.get(resolvedKey);

    if (lockPromise) {
      return await this.waitForLockWithTimeout(
        lockPromise,
        resolvedKey,
        lockTimeout,
        dataProvider
      );
    }

    lockPromise = this.executeWithLock(identifier, dataProvider, timeToLive);
    this.locks.set(resolvedKey, lockPromise);

    try {
      const result = await lockPromise;
      return result;
    } finally {
      this.locks.delete(resolvedKey);
    }
  }
}

Why Cache Locking Matters: When multiple requests hit the same uncached endpoint simultaneously, without locking, each request would trigger a database query. With 500 concurrent users, this creates a "cache stampede" that can overwhelm your database.

Enhanced Product Service with Caching

Medusa V1 allows for overriding default services, which is demonstrated here by extending the core ProductService. This approach enables us to wrap Medusa's core product operations with intelligent caching. By leveraging the CacheProviderService, we ensure that product listing and counting operations are optimized with a 1-minute TTL, significantly reducing database load and improving response times.

// src/services/product.ts
export class ProductService extends MedusaProductService {
  constructor(container: InjectedDependencies) {
    super(container);
    this.cacheProviderService = container.cacheProviderService;
  }

  listAndCount(
    selector: ProductSelector,
    config?: FindProductConfig
  ): Promise<[Product[], number]> {
    return this.cacheProviderService.withCache(
      {
        namespace: CacheNamespace.PRODUCT,
        parameters: { selector, config },
      },
      async () => super.listAndCount(selector, config),
      60 // 1 minute TTL
    );
  }
}

Performance Results: After Optimization

After implementing Redis caching with the same test parameters we got the following results:

Stat	Latency
2.5%	1038 ms
50%	1103 ms
97.5%	1773 ms
99%	2278 ms
Avg	1158.78 ms
Stdev	223.06 ms
Max	3510 ms

Performance Improvements Summary

Metric	Before Caching	After Caching	Improvement
Median Latency	4,885 ms	1,103 ms	77% faster
Average Latency	5,054 ms	1,158 ms	77% faster
99th Percentile	9,070 ms	2,278 ms	75% faster
Max Latency	9,452 ms	3,510 ms	63% faster

Analysis:

Response times improved by about 70-80%
Latency variance decreased significantly (better consistency)
Maximum latency dropped below 4 seconds, keeping more users engaged

These dramatic improvements prove that proper Redis caching implementation is crucial for achieving production-grade performance in Medusa V1 stores.

Cache Strategy and Business Logic

Choosing the right Time To Live (TTL) for cached data is crucial for balancing performance and data freshness. For example, product listings can be cached for 60 seconds to ensure a good balance between freshness and performance, while individual products, which change less frequently, can have a TTL of 300 seconds. Categories and shipping options, being relatively static, can have longer TTLs of 600 and 1800 seconds, respectively. User sessions, on the other hand, require a balance between security and user experience, making a TTL of 3600 seconds appropriate.

Cache invalidation is another critical aspect of caching strategy. Time-based expiration works well for most e-commerce data where eventual consistency is acceptable. However, for critical updates like price changes or inventory adjustments, event-driven invalidation is necessary. This involves invalidating related cache entries in the update services to ensure data accuracy.

Holistic Performance Optimization

Caching is just one piece of the performance puzzle. Beyond caching, database optimization plays a vital role. Adding indexes on frequently queried columns, optimizing complex joins and queries, and using database connection pooling can significantly enhance performance. For heavy read workloads, implementing read replicas can further distribute the load.

Infrastructure scaling is another critical aspect. Using a Content Delivery Network (CDN) for static assets, load balancers for horizontal scaling, and monitoring tools for database performance can ensure your application scales effectively. Setting up a Redis Cluster can also provide high availability and fault tolerance.

At the application level, implementing pagination for large result sets and using GraphQL for precise data fetching can optimize data transfer. Additionally, optimizing image sizes and formats, along with lazy loading for non-critical data, can enhance the user experience.

Monitoring and observability are essential for maintaining performance. Tracking metrics like cache hit ratio, average response times, database query performance, Redis memory usage, and error rates can help identify and address performance bottlenecks proactively.

For frontend applications, set appropriate cache headers for static assets and configure API response caching in your Next.js storefront. Leverage CDN caching through services like CloudFlare or AWS CloudFront for global performance optimization. Consider implementing Static Site Generation (SSG) to pre-render product pages, significantly improving initial page load times and SEO performance. These frontend optimizations, combined with backend Redis caching, create a comprehensive performance strategy.

Conclusion

The results speak for themselves: implementing Redis caching in Medusa V1 can deliver 70%+ performance improvements with minimal code changes. However, remember that performance optimization is an ongoing process, not a one-time implementation.

NestJS Authentication with Stytch: Complete Starter Guide

Michał Miler — Tue, 16 Sep 2025 22:00:00 +0000

Implementing authentication in NestJS can be challenging, especially when ensuring security and scalability. Instead of building authentication from scratch, you can integrate Stytch, a modern authentication platform, to handle secure user management with ease. In this guide, we’ll walk through the stytch-nestjs-starter repository - a production-ready example that shows how to integrate Stytch authentication with NestJS using smart caching and session management.

Why Choose Stytch Over Building Your Own Auth?

Building authentication from scratch means dealing with:

Password hashing and salt management
Session security and token management
Account verification and password reset flows
Rate limiting and brute force protection
Compliance with security standards
Regular security updates and patches

Stytch eliminates these concerns by providing:

✅ Battle-tested security with enterprise-grade protection
✅ Comprehensive authentication methods (email/password, magic links, social login, MFA)
✅ Global infrastructure with 99.99% uptime SLA
✅ Developer-friendly APIs with excellent documentation
✅ Compliance certifications (SOC 2, ISO 27001, GDPR)

Understanding the Integration Approaches

Frontend or Backend Integration

Stytch offers two primary integration patterns, each suited for different application architectures:

Frontend Integration: Ideal for client-side applications where authentication logic runs in the browser. This approach uses Stytch's JavaScript SDK to handle authentication flows directly on the frontend, with the backend serving as a resource server that validates session tokens.

Backend Integration: Perfect for server-side rendered applications or when you need centralized authentication control. This is the approach demonstrated in our starter, where the NestJS backend handles all authentication logic using Stytch's server-side APIs, providing better security and session management control.

Our starter implements the backend integration pattern, giving you:

Enhanced Security: Sensitive operations happen server-side
Centralized Session Management: All authentication logic in one place
Better Performance: Server-side caching reduces API calls
Simplified Frontend: Frontend only needs to handle session tokens

Learn more about integration patterns: Stytch Architecture Guide

Consumer vs B2B

Stytch supports both Consumer (B2C) and Business (B2B) authentication models:

Consumer Authentication (B2C): Designed for applications serving individual users. Features include:

Individual user accounts with email/password authentication
Social login providers (Google, Apple, Facebook, etc.)
Magic links and SMS-based authentication
Self-service password reset and account management

Business Authentication (B2B): Built for applications serving organizations and teams. Includes:

Organization-based user management
Single Sign-On (SSO) with SAML and OIDC
Just-in-Time (JIT) provisioning
Advanced admin controls and member management
Multi-tenant architecture support

Our starter is configured for Consumer Authentication, making it ideal for SaaS applications, marketplaces, and consumer-facing platforms. However, the architecture can be easily adapted for B2B use cases by switching to Stytch's B2B APIs.

Learn more about the differences: B2B vs Consumer Auth

Architecture Deep Dive

System Architecture Overview

The Complete Authentication Flow

Let's visualize how authentication works in our starter:

Exploring the Starter Repository

Key Features Implemented

1. Smart Session Caching

One of the most critical optimizations in the starter is the Redis-based session caching:

// Storing sessions in Redis with TTL
private async storeSession(
  sessionToken: string,
  { session_id, user_id: stytchUserId, expires_at }: Session,
): Promise<SessionTokenModel> {
  const user = await this.userService.fetchByStytchId(stytchUserId);

  const value: CachedSession = {
    userId: user.id,
    stytchUserId,
  };

  const ttl = expires_at
    ? new Date(expires_at).getTime() - new Date().getTime()
    : this.stytchService.sessionDurationMinutes * 60 * 1000;

  const hashedSessionToken = this.hashSessionToken(sessionToken);
  await this.cacheManager.set(hashedSessionToken, value, ttl);

  return { sessionToken };
}

This approach means:

No Stytch API calls on every request
Sub-millisecond session verification
Automatic session expiration matching Stytch TTL
Reduced API costs and improved performance

2. Intelligent Session Refresh

The session refresh interceptor automatically extends sessions before they expire:

private async checkAndRefreshSession(
  request: RequestWithUser,
  response: Response,
): Promise<void> {
  const sessionToken = request.headers['authorization']?.split(' ')[1];

  const hashedSessionToken = this.authService.hashSessionToken(sessionToken);
  const sessionTtl = await this.cacheManager.ttl(hashedSessionToken);
  const expirationTime = new Date(sessionTtl);

  const shouldRefresh =
    expirationTime.getTime() - new Date().getTime() <=
    this.sessionRefreshThresholdMinutes * 60 * 1000;

  if (shouldRefresh) {
    const refreshResult = await this.authService.refreshSession({
      sessionToken,
    });

    response.setHeader('X-New-Session-Token', refreshResult.sessionToken);
  }
}

This ensures users never experience unexpected logouts while maintaining security.

3. Elegant Session Access with CurrentSession Decorator

The CurrentSession decorator provides a clean, type-safe way to access authenticated user data in your controllers:

@Controller('resources')
export class ResourceController {
  @Get()
  findAll(@CurrentSession() session: CachedSession): ResourceModel[] {
        this.logger.debug(`User ${session.userId} requested all resources`);
    return this.resourceService.findAll();
  }
}

How it works:

AuthGuard Integration: The guard validates the session token and attaches user data to the request
Type Safety: Returns strongly-typed CachedSession object with userId and stytchUserId
Automatic Extraction: Seamlessly extracts session data without manual request parsing
Null Safety: Returns undefined for unauthenticated requests, handled gracefully by the guard

export const CurrentSession = createParamDecorator(
  (data: unknown, ctx: ExecutionContext): CachedSession | undefined => {
    const request = ctx.switchToHttp().getRequest<RequestWithUser>();
    return request.user;
  },
);

This pattern eliminates boilerplate code and provides a consistent way to access user context across your application.

4. Flexible User Creation Methods

The starter supports two user creation approaches, though in most cases you'll only need one method depending on your application type.

Method A: Self Sign-up (Public Registration)

curl -X POST http://localhost:3000/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "JHFKhpe_t1VfBULE_IsMhWC5WN4yx0ke",
    "firstName": "John",
    "lastName": "Doe"
  }'

Method B: Admin Invitation (Dashboard Apps)

# Using the create-user script
yarn create-user admin@company.com

# Or via API with master key
curl -X POST http://localhost:3000/auth/invite \
  -H "X-Api-Key: your-master-key" \
  -d '{
    "email": "newuser@company.com",
    "firstName": "Jane",
    "lastName": "Smith"
  }'

The invitation method sends a magic link email, allowing users to set their password securely.

After executing the create-user script or calling the endpoint manually, you'll receive an email message with a magic link that should redirect you to your frontend application to complete the password setup. However, if your frontend is not built yet, you can use server endpoint directly to reset your password until the frontend is ready:

curl -X POST http://localhost:3000/auth/password \
  -d '{
    "sessionToken": "<token_from_magin_link>",
    "password": "JHFKhpe_t1VfBULE_IsMhWC5WN4yx0ke"
  }'

Learn more about password reset flows: Stytch Password Reset API

Getting Started with the Starter

1. Quick Setup

Clone and configure the repository:

git clone https://github.com/u11d-com/stytch-nestjs-starter.git
cd stytch-nestjs-starter
yarn install
cp .env.example .env

2. Stytch Configuration

Sign up at Stytch Dashboard
Create a new project
Copy your Project ID and Secret to .env:

STYTCH_PROJECT_ID=project-test-xxx
STYTCH_SECRET=secret-test-xxx
STYTCH_SESSION_DURATION_MINUTES=60
STYTCH_SESSION_REFRESH_THRESHOLD_MINUTES=30

3. Infrastructure Setup

Start the required services:

# Start PostgreSQL and Redis
docker compose up postgres redis -d

# Run database migrations
yarn migration:run

# Start the development server
yarn start:dev

4. Testing Authentication

Your API will be available at http://localhost:3000.

Create your first admin user (execute script and set password using magic link sent to email address):

yarn create-user admin@yourcompany.com

Then test the authentication flow:

# Login
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@yourcompany.com", "password": "YourPassword123!"}'

# Access protected resource
curl -X GET http://localhost:3000/resources \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Production Considerations

Security Best Practices

Environment Variables: Never commit real credentials to version control
Master Key: Generate a cryptographically secure master key
CORS Configuration: Restrict origins to your frontend domains
HTTPS: Always use HTTPS in production
Rate Limiting: Implement rate limiting for auth endpoints
Session Duration Strategy: Balance longer sessions for user experience with shorter sessions for stronger security

Performance and Scalability

Redis Configuration: Use Redis Cluster for high availability and scalability
Connection Pooling: Optimize database connection pools for stable performance under load
Extended Caching: Introduce additional caching layers (e.g., user profile caching) to reduce database load

Extending the Starter

The starter provides a solid foundation that can be extended with additional features:

Role-Based Access Control (RBAC): Add user roles and permissions
Multi-Factor Authentication (MFA): Implement TOTP, SMS, or other MFA methods
Social Authentication: Google, GitHub, and other OAuth providers

We can prepare detailed implementations for these extensions if the community is interested. Let us know which features would be most valuable for your projects!

Conclusion

Building secure, scalable authentication doesn't have to be complex. The stytch-nestjs-starter provides a production-ready foundation that combines Stytch's security expertise with NestJS's architectural excellence.

By leveraging this starter, you get:

✅ Enterprise-grade security without the complexity

✅ Optimized performance with intelligent caching

✅ Developer productivity with comprehensive tooling

✅ Production readiness with Docker and monitoring

✅ Extensibility for your specific requirements

Whether you're building a SaaS application, internal dashboard, or customer-facing platform, this starter eliminates weeks of authentication development while providing a secure, maintainable foundation for your project.

Ready to get started? Clone the repository and have secure authentication running in minutes.

Resources

📖 Repository: stytch-nestjs-starter
🔐 Stytch Documentation: stytch.com/docs
🏗️ NestJS Documentation: docs.nestjs.com

Have questions or suggestions? We'd love to hear from you! Open an issue or start a discussion on GitHub.