DEV Community: Syed Muhammad Ali

How to Send Newsletters & Bulk Emails with Resend in Next.js 16

Syed Muhammad Ali — Mon, 27 Jul 2026 05:38:41 +0000

If you've ever built a newsletter with Resend, you've probably hit this wall: everything works great for your first handful of subscribers, and then one day you're manually exporting a list from your CMS and pasting emails one by one because your "send to everyone" button either times out, hits a rate limit, or just silently stops partway through.

That's not a you-problem. It's what happens when resend.emails.send() — a function built to send one email to one person — gets asked to do a completely different job: blasting the same content to a list. The good news is Resend actually has purpose-built tools for this, most developers just don't reach for them because the docs default to the single-send example everywhere.

By the end of this guide, you'll know exactly why bulk sends break, which Resend feature to use for which situation, and how to send emails to hundreds (or thousands) of subscribers from Next.js 16 without your route handler timing out or your requests getting rate-limited into oblivion.

💡 Using an older Resend tutorial? Resend recently replaced Audiences with a Segments + Topics model — Contacts are now global (one Contact per email address across your whole account), Segments handle internal list organization, and Topics handle what recipients actually see when they manage their subscription preferences. The audienceId parameter is deprecated. This guide uses the current model throughout; see Resend's migration guide if you have an existing Audiences-based setup to move over.

Why `emails.send()` Stops Working for Newsletters

Three separate problems stack on top of each other the moment you try to "just loop over your users and call resend.emails.send()":

1. Resend rate-limits you. Every team has a request-per-second cap on the API (2–10 requests/sec by default, depending on your account). Fire off 100 send() calls in a tight loop and you'll start getting 429 Too Many Requests responses partway through — which is almost certainly what's been happening to your newsletter.

2. Your server has a time limit. A Next.js Route Handler or Server Action running on Vercel (or most serverless hosts) has a maximum execution time. Even if you avoided the rate limit by adding delays between sends, looping through 100+ emails one at a time can easily blow past that limit — the function gets killed mid-send, and you have no idea who actually got the email.

3. send() isn't the right tool for a list. It's designed for transactional, one-recipient-at-a-time emails — a password reset, a receipt. A newsletter going to your whole subscriber base is a fundamentally different shape of problem, and Resend has features specifically built for it that most tutorials skip.

Once you match the right tool to the job, all three problems mostly disappear on their own.

Which Resend Feature Should You Actually Use?

Before writing any code, pick based on what you're actually sending:

Your situation	Use this
Same newsletter content to your whole subscriber list	Contacts + Segments + Broadcast API
Different content per recipient (e.g. personalized order updates to 50 users)	Batch API
A single transactional email (welcome, password reset)	Plain `emails.send()` — you already have this from the original Resend setup guide

If you're the person who left that comment — resending a newsletter manually from a CMS — you want the first one. Broadcasts exist specifically so you never touch a manual send loop again: Resend's own infrastructure handles the queueing, throttling, and pacing for you.

The New Model in One Minute

Resend's Contacts system changed shape recently, and it affects almost every code sample below, so it's worth understanding upfront:

Contact — a global entity tied to one email address across your entire account. There's no such thing as "the same person in two Audiences" anymore; they're one Contact that can belong to multiple Segments.
Segment — an internal, team-facing way to group Contacts for sending (this is what Audiences used to do). Recipients never see Segment names.
Topic — a recipient-facing subscription category (e.g. "Weekly Newsletter," "Product Updates"). This is what powers the preference page a subscriber sees when they click unsubscribe, letting them opt out of one type of email without unsubscribing from everything.

Resend's own recommendation: use Segments purely for your internal sending organization, and use Topics for anything user-facing around subscribe/unsubscribe. That's the pattern this guide follows.

Prerequisites

This guide assumes:

Next.js 16 with the App Router
TypeScript in strict mode
A Resend account with a recent version of resend and a verified sending domain (covered in the Resend + Next.js 16 setup guide if you haven't done that yet)

npm install resend

// lib/resend.ts
import { Resend } from "resend";

export const resend = new Resend(process.env.RESEND_API_KEY);

Before writing any code, create two things in the Resend dashboard:

A Segment (Audience → Segments → Create Segment) — this is your internal newsletter list.
A Topic (Audience → Topics → Create Topic) — e.g. "Weekly Newsletter" with a default subscription of opt_in — this is what subscribers actually see and manage.

Copy both IDs into .env.local:

RESEND_SEGMENT_ID=seg_xxxxxxxxx
RESEND_NEWSLETTER_TOPIC_ID=top_xxxxxxxxx

Step 1: Stop Storing Subscribers Only in Your CMS

The root cause of "I have to resend manually from my CMS" is usually that your subscriber list lives somewhere Resend doesn't know about. Every send becomes a manual export-and-paste job.

The fix is to sync subscribers into Resend the moment they sign up, instead of only saving them in your CMS or database.

Since a subscribe form lives inside your own app (it's not an external service calling you), a Server Action is the better fit here — no separate API route, no manual fetch, just a function called directly from the form.

// actions/subscribe.ts
"use server";

import { resend } from "@/lib/resend";
import { isValidEmail } from "@/lib/helpers";

const SEGMENT_ID = process.env.RESEND_SEGMENT_ID!;
const NEWSLETTER_TOPIC_ID = process.env.RESEND_NEWSLETTER_TOPIC_ID!;

export async function subscribe(prev: unknown, formData: FormData) {
  const email = formData.get("email") as string;
  const firstName = formData.get("firstName") as string | undefined;

  if (!email || !isValidEmail(email)) {
    return { error: "Please enter a valid email address" };
  }

  const { error } = await resend.contacts.create({
    email,
    firstName,
    unsubscribed: false,
    segments: [{ id: SEGMENT_ID }],
    topics: [{ id: NEWSLETTER_TOPIC_ID, subscription: "opt_in" }],
  });

  if (error) {
    return { error: error.message };
  }

  return { success: true };
}

What's happening here: resend.contacts.create() creates the Contact and, in the same call, adds them to your Segment (internal list) and opts them into your Topic (what they'll see on their preference page). You still keep them in your own database if you want (for account features, etc.), but Resend now has its own copy it can send to, with unsubscribes tracked automatically. Call this from your signup form with useActionState, the same pattern used for the contact form in the original Resend guide.

💡 Tip: You don't need to create Segments or Topics programmatically for a single newsletter — create them once in the dashboard and reuse the IDs. If you do need to create them from code, it's resend.segments.create({ name }) and resend.topics.create({ name, defaultSubscription }).

⚠️ Common Mistake: Only saving subscribers to your own database and never syncing them to Resend. That's exactly what forces the manual CMS export-and-resend workflow — Resend can only send to Contacts it actually knows about.

If you already have an existing list sitting in your CMS or database, migrate it once with a loop against resend.contacts.create() (or a CSV import from the dashboard) — after that, every new signup stays in sync automatically.

Handling Duplicate Contacts

Someone submitting the signup form twice — or re-subscribing after months away — is a when, not an if. Worth knowing upfront so it doesn't surprise you: contacts.create() does not error on a duplicate email. It's easy to assume it would (and it's tempting to write a try/catch around an "already exists" message like the one below), but in practice, calling it again for an address that's already a Contact just succeeds quietly — no error, no second Contact created.

// ⚠️ This looks reasonable but the catch block never actually runs —
// contacts.create() doesn't throw on a duplicate email, it just succeeds.
const { error } = await resend.contacts.create({ email, firstName, segments: [...] });

if (error?.message.toLowerCase().includes("already exists")) {
  // dead code — this condition is never true in practice
}

That's convenient in one sense (you can't accidentally create two Contacts for one email — they're global entities keyed by address, so a second one isn't possible anyway), but it creates a different problem: the response doesn't tell you whether this call just created a brand-new Contact or silently matched an existing one. You can't safely assume a repeat signup refreshed that Contact's name, Segment membership, or Topic subscription — the API gives no signal either way, and relying on undocumented behavior here is asking for a subscriber who resubscribes and doesn't actually get re-added to your Segment.

The robust fix: stop trying to detect the duplicate case at all, and instead always reinforce the Contact's state after create(), regardless of whether it was new or existing. contacts.update(), contacts.segments.add(), and contacts.topics.update() are all safe to call unconditionally — an update on a field that's already correct is a no-op, and adding a Contact to a Segment it's already in doesn't duplicate anything.

There's one wrinkle in the current model worth knowing too: the contacts.update() endpoint only touches first_name, last_name, unsubscribed, and properties — it doesn't accept segments or topics, which is why those need their own calls.

// actions/subscribe.ts (continued)
const { error } = await resend.contacts.create({
  email,
  firstName,
  unsubscribed: false,
  segments: [{ id: SEGMENT_ID }],
  topics: [{ id: NEWSLETTER_TOPIC_ID, subscription: "opt_in" }],
});

if (error) {
  // A genuine failure — bad Segment/Topic ID, auth issue, etc. Not the
  // duplicate case, since that doesn't come back as an error at all.
  return { error: error.message };
}

// Reinforce the Contact's state either way — create() gives no signal
// about whether this address was brand-new or already existed, so don't
// assume its fields/Segment/Topic membership are already correct.
const { error: updateError } = await resend.contacts.update({
  email,
  firstName,
  unsubscribed: false, // treat a re-submission as an explicit re-opt-in
});

if (updateError) {
  return { error: updateError.message };
}

await resend.contacts.segments.add({ email, segmentId: SEGMENT_ID });
await resend.contacts.topics.update({
  email,
  topics: [{ id: NEWSLETTER_TOPIC_ID, subscription: "opt_in" }],
});

return { success: true };

⚠️ Common Mistake: Writing an if (error?.message.includes("already exists")) branch expecting it to handle duplicates. It won't — that branch is unreachable, because contacts.create() doesn't return an error for a duplicate email in the first place. If you want to handle "new vs. existing" differently for some reason (e.g. a different welcome email), you'll need to check your own database for whether you'd already seen that email before calling Resend at all — Resend's response won't tell you.

⚠️ Common Mistake: Blindly setting unsubscribed: false on every update, including ones triggered by something other than the person resubmitting the signup form (e.g. an internal sync job). Only flip someone back to subscribed when the update is actually the result of them opting in again — otherwise you can silently resubscribe someone who deliberately unsubscribed. The same caution applies to setting a Topic's subscription back to opt_in.

Step 2: Send the Newsletter with the Broadcast API

This is the step that replaces "manually resending from my CMS" entirely. A Broadcast is a single email sent to an entire Segment, and Resend's own infrastructure handles pacing the sends against the rate limit — you don't write any batching or delay logic yourself.

This is another case for a Server Action rather than a Route Handler — it's triggered by an admin clicking "Send" inside your own app, not by an external caller, so there's no need for a public API route.

// actions/send-newsletter.ts
"use server";

import { resend } from "@/lib/resend";

const SEGMENT_ID = process.env.RESEND_SEGMENT_ID!;
const NEWSLETTER_TOPIC_ID = process.env.RESEND_NEWSLETTER_TOPIC_ID!;

export async function sendNewsletter(prev: unknown, formData: FormData) {
  const subject = formData.get("subject") as string;
  const html = formData.get("html") as string;

  if (!subject || !html) {
    return { error: "Subject and content are required" };
  }

  const { data: broadcast, error } = await resend.broadcasts.create({
    segmentId: SEGMENT_ID,
    topicId: NEWSLETTER_TOPIC_ID,
    from: "Newsletter <newsletter@yourdomain.com>",
    subject,
    html: `${html}\n\n{{{RESEND_UNSUBSCRIBE_URL}}}`,
    send: true, // create and send in a single call — no separate broadcasts.send() needed
  });

  if (error || !broadcast) {
    return { error: error?.message ?? "Failed to send newsletter" };
  }

  return { success: true, broadcastId: broadcast.id };
}

What's happening here: broadcasts.create() builds the email against your Segment, and passing send: true sends it immediately in the same request — the older two-step create() then broadcasts.send() flow still works if you want to review a draft in the dashboard first, but for a straightforward newsletter this single call is all you need. Resend queues and throttles delivery on their end, respecting Topic opt-outs and global unsubscribes automatically. The action returns almost instantly, because it's just telling Resend "send this" — it isn't the thing looping over 100 recipients itself.

💡 Tip: The {{{RESEND_UNSUBSCRIBE_URL}}} placeholder gets replaced with a working, per-contact unsubscribe/preferences link. Gmail and Yahoo require a working one-click unsubscribe for bulk senders as of their 2024 sender guidelines — don't skip it.

Because this action returns fast and Resend does the heavy lifting asynchronously, this alone solves the timeout problem for a standard newsletter send — there's no long-running loop in your app to time out in the first place.

⚠️ Common Mistake: Setting send: true without realizing there's no undo — a Broadcast sent this way goes out immediately. If you want a review step, drop send: true, call resend.broadcasts.send(broadcast.id) separately once you've previewed it in the dashboard.

Scheduling Broadcasts

If you don't want to hit send manually at all — say you want every newsletter to go out at 9am the next day — pass scheduledAt alongside send: true:

const { data: broadcast, error } = await resend.broadcasts.create({
  segmentId: SEGMENT_ID,
  topicId: NEWSLETTER_TOPIC_ID,
  from: "Newsletter <newsletter@yourdomain.com>",
  subject,
  html: `${html}\n\n{{{RESEND_UNSUBSCRIBE_URL}}}`,
  send: true,
  scheduledAt: "tomorrow at 9am",
});

That single option covers "send tomorrow morning" without any extra infrastructure — Resend holds the broadcast and releases it at the scheduled time.

⚠️ Common Mistake: Passing scheduledAt without send: true. Resend's API requires the two together — scheduledAt on its own is silently ignored on a plain draft-only create() call.

For recurring or CMS-driven sends where you need to decide the content and trigger the call on a schedule (rather than just delaying a single send), a few options handle the triggering side:

Vercel Cron — simplest if you're already on Vercel; define a schedule in vercel.json that hits a Route Handler on a timer.
Trigger.dev — better once your scheduling logic gets more complex (retries, conditional sends, multi-step workflows).
GitHub Actions — a scheduled workflow that calls your app's API on a cron schedule, handy if you don't want another paid service.
Your CMS's own scheduler — if your CMS already supports "publish at" dates, have that trigger a webhook to your app when a newsletter post goes live, and kick off the broadcast from there.

For a single one-off "send this tomorrow morning," the native scheduledAt option above is all you need — reach for the others only once you're automating when new content gets sent, not just delaying a specific send.

Step 3: Bulk Sending Different Content Per Recipient

Broadcasts are for identical content sent to a Segment. If you're sending 80 different emails — say, personalized weekly stats to each user — you're back to needing multiple distinct emails, and that's what the Batch API is for. It sends up to 100 separate emails in a single API call, instead of 100 separate HTTP requests.

// lib/send-bulk-emails.ts
import { resend } from "@/lib/resend";

export interface BulkEmail {
  to: string;
  subject: string;
  html: string;
}

export interface BulkSendResult {
  sent: number;
  failed: number;
  batches: number;
}

const BATCH_SIZE = 100; // Resend's per-call limit

export const sendBulkEmails = async (
  emails: BulkEmail[],
  opts: { idempotencyPrefix?: string; delayMs?: number } = {}
): Promise<BulkSendResult> => {
  const batches: BulkEmail[][] = [];

  for (let i = 0; i < emails.length; i += BATCH_SIZE) {
    batches.push(emails.slice(i, i + BATCH_SIZE));
  }

  const result: BulkSendResult = { sent: 0, failed: 0, batches: batches.length };

  for (let i = 0; i < batches.length; i++) {
    const batch = batches[i];

    const sendOptions = opts.idempotencyPrefix
      ? { idempotencyKey: `${opts.idempotencyPrefix}-batch-${i}` }
      : undefined;

    const { data, error } = await resend.batch.send(
      batch.map((email) => ({
        from: process.env.RESEND_FROM_EMAIL,
        to: email.to,
        subject: email.subject,
        html: email.html,
      })),
      sendOptions
    );

    if (error) {
      console.error("Batch send failed:", error.message);
      result.failed += batch.length;
      continue;
    }

    result.sent += data?.data.length ?? 0;

    // Small pause between batches so consecutive batch calls stay
    // comfortably under the per-second rate limit — see the guide's
    // "Common Mistake" callout about Promise.all() on this same step.
    if (batches.length > 1 && i < batches.length - 1) {
      await new Promise((resolve) => setTimeout(resolve, opts.delayMs ?? 600));
      // The delay is only a simple example. In production, prefer 
      // handling 429 responses and Retry-After/rate-limit headers 
      // rather than relying on a fixed delay.
    }
  }

  return result;
};

What's happening here: BATCH_SIZE = 100 matches Resend's own limit — one batch API call can carry up to 100 individual emails, each with its own to, subject, and html. Splitting into chunks of 100 means a 350-person send becomes 4 API calls instead of 350. The 600ms pause is a simple conservative example for sequential requests. Your actual limit depends on your account, so production code should handle rate-limit responses rather than relying on a fixed delay.

⚠️ Common Mistake: Using Promise.all() to fire every batch at once "for speed." That's exactly what triggers 429 rate-limit errors — batches still count as one request each against your per-second limit, so send them sequentially, not concurrently.

Step 4: Preventing Timeouts on Larger Sends

For a few hundred recipients, the batching above usually finishes well inside a normal request timeout. For genuinely large lists (thousands of emails), you have two solid options:

Option A: Run the send after the response, with `after()`

Next.js's after() API lets you return a response to the caller immediately, while your code keeps running in the background for a bit longer — useful for kicking off a bulk send without making an admin wait on a spinner. It works the same way inside a Server Action as it does in a Route Handler, so this stays a Server Action too — triggered by an admin button inside your app.

// actions/send-personalized-batch.ts
"use server";

import { after } from "next/server";
import { sendBulkEmails } from "@/lib/send-bulk-emails";
import { getAllSubscribers, appendSendLog } from "@/lib/db";

export type SendBatchState = {
  error?: string;
  message?: string;
};

export const sendPersonalizedBatch = async (
  _prev: SendBatchState,
  formData: FormData
): Promise<SendBatchState> => {
  const subjectLine = (formData.get("subjectLine") as string) || "This week's update";

  const subscribers = await getAllSubscribers();

  if (subscribers.length === 0) {
    return { error: "No local subscribers yet — add one on the Subscribe page first." };
  }

  const id = crypto.randomUUID();

  // Fire-and-return: the caller gets an instant response, the actual
  // send keeps running after the response has been flushed.
  after(async () => {
    const result = await sendBulkEmails(
      subscribers.map((s, i) => ({
        to: s.email,
        subject: subjectLine,
        html: renderPersonalizedHtml(s.firstName, subjectLine), // Your function to render HTML
      })),
      { idempotencyPrefix: `personalized-${id}` }
    );
    await appendSendLog({
      kind: "batch",
      detail: `Personalized batch finished: ${result.sent} sent, ${result.failed} failed, ${result.batches} batch(es).`,
    });
  });

  return { message: `Send started for ${subscribers.length} local subscriber(s).` };
};

What's happening here: after() schedules the callback to run once the response has been sent, but the platform keeps the function alive long enough to finish it — so the admin triggering the send gets an instant "started" response instead of waiting on hundreds of emails to go out synchronously.

⚠️ Common Mistake: Assuming after() gives you unlimited extra time. It still runs within your platform's function execution ceiling — it just moves the work after the response is sent, it doesn't remove the ceiling entirely. For truly large lists, see Option B.

Option B: Offload to a real queue for very large lists

Once you're sending to thousands of people reliably and repeatedly, reach for a dedicated queue like Upstash QStash or Trigger.dev instead of doing it inline at all. You publish one message per batch (or per recipient), the queue calls your endpoint back with automatic retries, rate-limit-aware pacing, and delivery guarantees — so a mid-send crash or a Vercel redeploy can't silently lose part of your list the way a bare loop can.

Kicking off the enqueue is still admin-triggered from inside your app, so it can be a Server Action. The endpoint QStash calls back to, however, is a different story — that request comes from an external service hitting a public URL, which is exactly what Route Handlers exist for, not Server Actions (which have no callable URL of their own).

// actions/enqueue-newsletter.ts
"use server";

import { Client } from "@upstash/qstash";
import { getAllSubscribers } from "@/lib/db";

export type EnqueueState = {
  error?: string;
  message?: string;
};

const BATCH_SIZE = 100;
const qstashToken = process.env.QSTASH_TOKEN!;
export const enqueueNewsletter = async (
  _prev: EnqueueState,
  formData: FormData
): Promise<EnqueueState> => {
  if (!qstashToken) {
    return {
      error:
        "QSTASH_TOKEN is not set. This step is optional — most newsletters don't need a queue. " +
        "Set it in .env.local if you want to test QStash locally (requires a public URL via ngrok/tunnel for the callback).",
    };
  }

  const subjectLine = (formData.get("subjectLine") as string) || "Queued update";
  const subscribers = await getAllSubscribers();

  if (subscribers.length === 0) {
    return { error: "No local subscribers yet — add one on the Subscribe page first." };
  }

  const batches: { to: string; subject: string; html: string }[][] = [];
  for (let i = 0; i < subscribers.length; i += BATCH_SIZE) {
    batches.push(
      subscribers.slice(i, i + BATCH_SIZE).map((s) => ({
        to: s.email,
        subject: subjectLine,
        html: `<p>Hi ${s.firstName || "there"}, ${subjectLine}</p>`,
      }))
    );
  }

  const qstash = new Client({ token: qstashToken, baseUrl: process.env.QSTASH_BASE_URL });
  const newsletterId = crypto.randomUUID();

  for (const [i, batch] of batches.entries()) {
    await qstash.publishJSON({
      url: `${process.env.NEXT_PUBLIC_APP_URL}/api/newsletter/send-batch-worker`,
      body: { batch, newsletterId, batchIndex: i },
    });
  }

  return { message: `Queued ${batches.length} batch(es) via QStash.` };
};

// app/api/newsletter/send-batch-worker/route.ts
// Route Handler on purpose — QStash calls this URL directly, from outside
// this app. Server Actions have no callable URL, so this piece has to stay
// a Route Handler even though everything else in the guide is an action.
import { NextResponse } from "next/server";
import { sendBulkEmails, type BulkEmail } from "@/lib/send-bulk-emails";

export const POST = async (request: Request) => {
  const body: unknown = await request.json();

  if (
    typeof body !== "object" ||
    body === null ||
    !("batch" in body) ||
    !Array.isArray((body as { batch: unknown }).batch)
  ) {
    return NextResponse.json({ error: "Invalid payload" }, { status: 400 });
  }

  const { batch, newsletterId, batchIndex } = (body as { batch: BulkEmail[]; newsletterId: string; batchIndex: string; });
  const result = await sendBulkEmails(batch, { idempotencyPrefix: `newsletter-${newsletterId}-${batchIndex}` });

  const success = result.failed === 0;
  return NextResponse.json({ received: success, result }, { status: success ? 200 : 500 });
};

This is more infrastructure than most newsletters need — for a straightforward list, Step 2's Broadcast API already solves the problem without a queue. Reach for QStash only once you're past a few thousand recipients or need guaranteed retries on failure.

Broadcast vs. Batch vs. Queue: Quick Comparison

	Broadcast API	Batch API	Batch API + Queue (QStash)
Best for	Identical newsletter content to a whole Segment	Different content per recipient, small–medium lists	Different content per recipient, thousands+
Recipients per call	Entire Segment	Up to 100	Up to 100 per queued batch
Handles pacing for you	Yes — Resend's own infrastructure	No — you chunk and delay manually	Yes — the queue paces callbacks
Retries on failure	Handled by Resend	Manual (idempotency keys)	Automatic, built into the queue
Native scheduling	Yes (`scheduledAt` + `send: true`)	No	Yes (via the queue's own scheduling)
Setup complexity	Low	Low–Medium	Medium–High
Trigger from	Server Action	Server Action / `after()`	Server Action (enqueue) + Route Handler (callback)

Step 5: Avoid Duplicate Sends on Retry

If a batch call fails partway through and you retry it, you don't want to double-email anyone who already received it. Pass an idempotency key so Resend recognizes a retried request and returns the original result instead of sending again.

await resend.batch.send(emailPayload, {
  idempotencyKey: `newsletter-${newsletterId}-batch-${batchIndex}`,
});

What's happening here: as long as the same key is reused for a retry of that exact batch, Resend treats it as the same request rather than a new send — so a network blip on your end doesn't turn into duplicate inboxes for your subscribers.

Step 6: Track Bounces and Complaints with Webhooks

A healthy sender reputation depends on removing bad addresses, not just sending and hoping. Set up a webhook endpoint so Resend tells you when something goes wrong with a specific email.

This one has to stay a Route Handler no matter what — Resend's servers are the ones calling it, so it needs a real, public URL.

// app/api/webhooks/resend/route.ts
// Route Handler on purpose — Resend's servers call this URL directly, so it
// needs a real, public URL. This can't be a Server Action.
import { NextRequest, NextResponse } from "next/server";
import { resend } from "@/lib/resend";
import { markEmailBounced, unsubscribeContact } from "@/lib/db";
import type { WebhookEventPayload } from "resend";

export const POST = async (req: NextRequest) => {
  const payload = await req.text(); // must be the raw body — signature check needs it exactly as sent

  let event: WebhookEventPayload;
  try {
    event = resend.webhooks.verify({
      payload,
      headers: {
        id: req.headers.get("svix-id") ?? "",
        timestamp: req.headers.get("svix-timestamp") ?? "",
        signature: req.headers.get("svix-signature") ?? "",
      },
      webhookSecret: process.env.RESEND_WEBHOOK_SECRET,
    });
  } catch {
    return new NextResponse("Invalid webhook signature", { status: 400 });
  }

  switch (event.type) {
    case "email.bounced": {
      for (const to of event.data.to) await markEmailBounced(to);
      break;
    }
    case "email.complained": {
      // Recipient marked it as spam — unsubscribe them immediately
      for (const to of event.data.to) await unsubscribeContact(to);
      break;
    }
    default:
      break;
  }

  return NextResponse.json({ received: true });
};

What's happening here: resend.webhooks.verify() checks the svix-* headers Resend attaches to every webhook request against your RESEND_WEBHOOK_SECRET, throwing if the signature doesn't match. That's what proves the request actually came from Resend and not from someone who found your webhook URL and is spoofing bounce events to unsubscribe your whole list. Register the URL under Webhooks in your Resend dashboard to get the secret and start receiving events.

Bounced or complained-about addresses should stop receiving future sends — repeatedly emailing dead or complaining addresses is one of the fastest ways to tank deliverability for your whole domain.

⚠️ Common Mistake: Calling req.json() before verifying. The signature is computed against the exact raw body Resend sent — parsing it first and re-serializing breaks the check. Always read with req.text(), same as with Stripe webhooks.

💡 For the full breakdown of the signature algorithm and manual verification without the SDK helper, see Resend's own webhook verification docs.

A Quick Pre-Send Checklist

[ ] A Segment exists for internal sending, and a Topic exists for the recipient-facing subscription preference
[ ] Subscribers are synced into Resend as Contacts, not just kept in your own database
[ ] Every signup reinforces state with contacts.update() + contacts.segments.add() + contacts.topics.update(), rather than trying to catch an "already exists" error that never comes
[ ] Newsletter content goes through broadcasts.create({ segmentId, topicId, send: true }), not a manual loop
[ ] Recurring or future-dated sends use scheduledAt with send: true (or a scheduler triggering the action) instead of you remembering to click send
[ ] Personalized bulk sends use resend.batch.send() in chunks of 100, sent sequentially
[ ] Long-running sends are kicked off with after() or a real queue, not run synchronously in the request
[ ] Idempotency keys are set on batch sends you might retry
[ ] Subscribe and send actions are Server Actions; only the webhook and any queue callback stay as Route Handlers
[ ] The webhook endpoint verifies the signature with resend.webhooks.verify() before trusting the payload
[ ] Domain has SPF, DKIM, and DMARC configured (see the Resend setup guide if not)

Frequently Asked Questions

Do I still need `resend.emails.send()` for anything?

Yes — keep using it for one-off transactional emails like password resets or order confirmations. Broadcasts and the Batch API are specifically for sending to multiple people at once; a single transactional email doesn't need either.

What happened to Audiences?

Resend replaced Audiences with a Segments + Topics model. Contacts used to be scoped to one Audience each; now every Contact is a single global entity per email address that can belong to multiple Segments (internal organization) and Topics (recipient-facing subscription preferences). The audienceId parameter on Contacts and Broadcasts is deprecated in favor of segments/segmentId — see Resend's migration guide if you're moving an existing project over.

How many subscribers can a Broadcast actually handle?

Resend's Broadcast infrastructure is built to scale with your Segment size — you're not limited to 100 the way you are with a single Batch API call. It handles the internal pacing against rate limits for you, which is exactly the problem this guide is solving.

What's the real difference between Batch and Broadcast?

Batch sends up to 100 different emails (different recipients, potentially different content) in one API call — you're still the one deciding what goes to whom. Broadcast sends one email to an entire Segment and manages delivery pacing itself. Use Batch for personalized bulk sends, Broadcast for newsletters.

Will my subscribers get duplicate emails if something fails halfway through?

Not if you're using idempotency keys on retried batch calls, and not with Broadcasts at all, since Resend's own infrastructure owns the send rather than your code retrying a loop. This is the exact failure mode manual CMS resending runs into — no idempotency, so a partial failure often means re-sending to people who already got it.

Do I need a database of my own if I'm using Resend Contacts?

Not strictly, but it's still a good idea to keep your own record of subscribers for anything beyond email — account linking, analytics, exporting. Just make sure every subscriber that exists in your database also gets synced to Resend, or you're back to the manual-export problem this guide fixes.

What happens if someone subscribes twice?

Resend Contacts are global entities keyed by email, so you can't end up with two Contacts for the same address — but contacts.create() won't error on a duplicate either, it just succeeds silently without telling you whether it created or matched an existing Contact. Don't write an "already exists" error branch expecting it to catch this case; it won't fire. Instead, always follow create() with contacts.update() + contacts.segments.add() + contacts.topics.update(), which is what Step 1's code does — those calls are safe to run unconditionally on every signup, new or repeat.

Can I schedule a newsletter to go out tomorrow morning?

Yes — pass send: true and scheduledAt: "tomorrow at 9am" (or any natural-language time) to broadcasts.create() and Resend holds it until then. You don't need Vercel Cron, Trigger.dev, or any external scheduler for a single scheduled send; those tools are for automating when the send gets triggered in the first place, like a recurring weekly newsletter tied to your CMS's publish schedule.

Why are some endpoints Server Actions and others Route Handlers?

Server Actions are for code triggered from inside your own app — a signup form, an admin's "send" button. Route Handlers are for anything an external service needs to call over a real URL — Resend's bounce/complaint webhooks, or a queue like QStash calling back into your app. If nothing outside your app needs to hit it directly, a Server Action is simpler; if something external does, it has to be a Route Handler.

Should I use Broadcast or Batch for newsletters?

Almost always Broadcast. Only use Batch if every recipient receives different content.

Wrapping Up

The "resending manually from my CMS" problem almost always comes down to one thing: treating a list-send like a loop of single sends instead of reaching for the tools Resend built specifically for it. Sync subscribers into a Segment the moment they sign up, send newsletters through the Broadcast API instead of a manual loop, and fall back to the chunked Batch API only when every recipient genuinely needs different content.

From here, a natural next step is wiring up the webhook-based bounce handling so your list stays clean automatically, or building out a proper Topics-based preference page so subscribers can pick exactly what they want to hear from you.

📦 Source Code: View on GitHub

Continue Learning

Route Handlers Explained in Next.js 16 (Beginner's Guide)

Syed Muhammad Ali — Fri, 24 Jul 2026 04:57:56 +0000

You've built pages, you've built layouts, and now you need something that isn't a page at all — a webhook endpoint for Stripe, a JSON API for a mobile app, or a route that generates a CSV file on demand. None of that fits inside a page.tsx. That's exactly the gap Route Handlers fill in the Next.js App Router.

If you've used the old Pages Router, Route Handlers are the direct replacement for pages/api. If you're coming from Express or another Node framework, think of them as your app.get() and app.post() — just organized by folder structure instead of a router file.

By the end of this guide, you'll know exactly how Route Handlers work in Next.js 16, how they're different from Server Actions, how caching behaves with the new Cache Components model, and how to build a real, typed API endpoint — including handling dynamic routes and webhooks.

Here's the whole picture at a glance before we dive in step by step:

What Are Route Handlers, Exactly?

A Route Handler is a function that runs on the server and responds to an HTTP request — no HTML, no React, just data. You define one inside a special file named route.ts, and it can live anywhere inside your app directory.

// app/api/hello/route.ts
export async function GET() {
  return Response.json({ message: "Hello from Next.js 16!" })
}

Visit /api/hello in your browser, and you'll get back that JSON — no page rendered, just a raw HTTP response.

💡 Tip: Route Handlers use the standard Web Request and Response APIs — the same ones built into browsers and modern JavaScript runtimes — not the old Express-style req/res objects. That means the skills you learn here also apply outside Next.js.

Why This Is Tricky (For Beginners)

New Next.js developers usually hit two points of confusion:

"Isn't this just an API Route?" — Sort of, but Route Handlers live in app/ and use a completely different file convention (route.ts instead of pulling from pages/api).
"Should I use a Route Handler or a Server Action?" — Both let you run server-side code, but they solve different problems, and picking the wrong one leads to unnecessary complexity later.

Let's clear both of those up before touching any code.

Route Handlers vs. Pages Router API Routes

If you're migrating from the Pages Router, pages/api/hello.ts becomes app/api/hello/route.ts. The concept is identical — a folder-based endpoint — but the syntax changes from a single default export to named exports per HTTP method.

Good to know: You never need to mix API Routes and Route Handlers in the same project. If your project uses the app directory, Route Handlers are your only option for API-style endpoints — the Pages Router pattern doesn't apply anymore.

Route Handlers vs. Server Actions

This is the question that trips up almost everyone, so here's the short version:

	Route Handlers	Server Actions
Called from	Anywhere (browser, mobile app, another server, `curl`)	Only from inside your own React components
Best for	Public APIs, webhooks, third-party integrations	Form submissions, internal data mutations
HTTP control	Full — you choose methods, headers, status codes	Handled for you automatically
URL	Has a real, callable URL	No public URL of its own

Rule of thumb: if something outside your Next.js app (a webhook from Stripe, a mobile client, a public API consumer) needs to call this code, use a Route Handler. If it's a form or button inside your own app calling a server function, a Server Action is simpler and does less boilerplate for you.

Prerequisites

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
React Compiler enabled (not directly relevant to Route Handlers, but assumed as the project default)

You don't need any extra packages — everything here ships with Next.js out of the box.

Step 1: The `route.ts` File Convention

A Route Handler is created by adding a route.ts (or route.js) file inside any folder in app/. The folder path becomes the URL.

app/
└── api/
    └── hello/
        └── route.ts       → /api/hello

// app/api/hello/route.ts
export async function GET(request: Request) {
  return Response.json({ message: "Hello, world!" })
}

What's happening here: exporting a function named GET tells Next.js "handle GET requests to this route with this function." The function receives the standard Web Request object and must return a Response (or NextResponse, which extends it).

⚠️ Common Mistake: A route.ts file cannot live in the same folder as a page.tsx at the same segment. app/page.tsx and app/route.ts together will throw a build error — Next.js doesn't know whether that URL should render a page or run an API handler. Nest your Route Handler under a different segment, like app/api/..., instead.

Step 2: Supported HTTP Methods

Route Handlers support the standard HTTP verbs as named exports in the same file: GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.

// app/api/todos/route.ts
export async function GET() {
  const todos = await getTodosFromDb()
  return Response.json(todos)
}

export async function POST(request: Request) {
  const body = await request.json()
  const newTodo = await createTodo(body)
  return Response.json(newTodo, { status: 201 })
}

What's happening here: one file now handles two different behaviors depending on the incoming HTTP method — a GET request lists todos, a POST request creates one. If a client sends a method you haven't exported (like DELETE on a file with only GET/POST), Next.js automatically responds with a 405 Method Not Allowed — you don't need to handle that yourself.

💡 Tip: Next.js also auto-implements a sensible OPTIONS response for you if you don't define one, which is useful for CORS preflight requests (more on that below).

Response vs. NextResponse, Request vs. NextRequest

Before going further, it's worth clearing up which object to reach for — they show up interchangeably in examples online, which confuses a lot of beginners.

Request / Response — the plain Web APIs, built into the JavaScript runtime itself, not Next.js-specific. Use these when you don't need anything extra — a simple JSON response, or reading a body with request.json().
NextRequest (from next/server) — extends Request with Next.js-only conveniences, most notably request.nextUrl (an already-parsed URL object) and request.cookies. Reach for this the moment you need query params or cookies without manually parsing the URL string.
NextResponse (from next/server) — extends Response with helpers like NextResponse.redirect(), NextResponse.rewrite(), and easier cookie-setting via response.cookies.set(). Use this when you need to redirect, rewrite, or set cookies on the way out.

💡 Tip: A good default: start with plain Request/Response.json() for simple handlers, and upgrade to NextRequest/NextResponse only when you actually need one of their extra features. Both pairs are fully interoperable — a function typed to accept NextRequest still works fine if you never end up using the extra methods.

Step 3: Reading Data From the Request

Most real endpoints need to read something — a JSON body, a query parameter, or a header.

// app/api/search/route.ts
import { NextRequest } from "next/server"

export async function GET(request: NextRequest) {
  // Reading a query param: /api/search?q=nextjs
  const query = request.nextUrl.searchParams.get("q")

  if (!query) {
    return Response.json({ error: "Missing 'q' parameter" }, { status: 400 })
  }

  const results = await searchDatabase(query)
  return Response.json(results)
}

What's happening here: NextRequest (imported from next/server) extends the standard Request with convenience helpers — request.nextUrl gives you an already-parsed URL object, so searchParams.get("q") is easier than manually parsing request.url with the native URL class.

For a JSON body on a POST or PUT request, use request.json():

// app/api/contact/route.ts
export async function POST(request: Request) {
  const { email, message } = await request.json()

  if (!email || !message) {
    return Response.json(
      { error: "Email and message are required" },
      { status: 400 }
    )
  }

  await sendContactEmail({ email, message })
  return Response.json({ success: true })
}

⚠️ Common Mistake: Never trust that email and message exist just because your frontend form requires them. Anyone can send a raw POST request straight to /api/contact with curl, skipping your form entirely — always validate on the server, ideally with a schema library like Zod.

Step 4: Dynamic Route Segments

Just like pages, Route Handlers support dynamic segments using square brackets.

app/
└── users/
    └── [id]/
        └── route.ts        → /users/123, /users/456, etc.

In Next.js 16, the recommended way to type the dynamic segment is the built-in RouteContext helper — it's generated automatically for you based on your actual route structure.

// app/users/[id]/route.ts
import type { NextRequest } from "next/server"

export async function GET(
  request: NextRequest,
  ctx: RouteContext<"/users/[id]">
) {
  const { id } = await ctx.params
  const user = await getUserById(id)

  if (!user) {
    return Response.json({ error: "User not found" }, { status: 404 })
  }

  return Response.json(user)
}

What's happening here: ctx.params is a Promise — this matches the same async params convention used in page.tsx files throughout Next.js 16, so you must await it before reading id. RouteContext<"/users/[id]"> gives you full type-safety without manually writing an interface for every dynamic route.

Good to know: These types are generated when you run next dev, next build, or next typegen — if your editor shows a type error right after creating a new dynamic route, running one of those commands usually fixes it.

Step 5: Caching Behavior

This trips up a lot of people coming from the Pages Router, where API Routes were never cached. In the App Router, it's a little more nuanced.

The short version: Route Handlers are not cached by default. Only GET handlers can opt into caching — every other method (POST, PUT, DELETE, etc.) is always dynamic, even if you configure caching in the same file.

To force a GET handler to be cached as static:

// app/items/route.ts
export const dynamic = "force-static"

export async function GET() {
  const res = await fetch("https://data.example.com/items")
  const data = await res.json()
  return Response.json({ data })
}

If You're Using Cache Components (`"use cache"`)

If your project has Cache Components enabled, GET Route Handlers behave exactly like a normal page: they run dynamically by default, but can be pre-rendered at build time if they don't touch anything request-specific.

// app/api/project-info/route.ts
// No dynamic data — this gets pre-rendered at build time
export async function GET() {
  return Response.json({ projectName: "DevStacked" })
}

// app/api/user-agent/route.ts
import { headers } from "next/headers"

// Reads a request-specific header — this forces the route to run per-request
export async function GET() {
  const headersList = await headers()
  const userAgent = headersList.get("user-agent")
  return Response.json({ userAgent })
}

If you need to mix cached data with per-request logic, pull the cached part into its own function using "use cache" — you can't put "use cache" directly inside the Route Handler body itself.

// app/api/products/route.ts
import { cacheLife } from "next/cache"

export async function GET() {
  const products = await getProducts()
  return Response.json(products)
}

async function getProducts() {
  "use cache"
  cacheLife("hours")

  return await db.query("SELECT * FROM products")
}

💡 Tip: Prerendering for a GET handler stops the moment it touches anything non-deterministic — a database call without "use cache", Math.random(), or runtime APIs like cookies() and headers(). If a route you expected to be static is showing up dynamic in your build output, one of these is almost always why.

A Quick Word on the Edge Runtime

By default, Route Handlers run on the Node.js runtime — the full Node environment, with access to everything you'd expect (the fs module, native npm packages, longer execution limits). You can opt a specific route into the lighter-weight Edge Runtime instead:

// app/api/geo/route.ts
export const runtime = "edge"

export async function GET() {
  return Response.json({ message: "Running on the Edge" })
}

The Edge Runtime starts faster and runs closer to the user geographically, but it's a stripped-down environment — no fs, no full Node API surface, and not every npm package supports it. Reach for it for small, latency-sensitive handlers (geolocation checks, lightweight redirects); stick with the Node.js default for anything doing real database work, file access, or using Node-only packages like the Stripe or AWS SDKs.

Step 6: Handling Webhooks (Raw Body Access)

Webhooks — like Stripe payment confirmations — are one of the most common real-world uses for Route Handlers. The key detail: webhook signature verification needs the raw, unparsed request body, not JSON.

// app/api/webhook/route.ts
import { NextResponse } from "next/server"
import { headers } from "next/headers"
import Stripe from "stripe"
import { stripe } from "@/lib/stripe"

const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!

export async function POST(req: Request) {
  const payload = await req.text() // raw text, NOT req.json()
  const signature = (await headers()).get("stripe-signature")

  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 400 })
  }

  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(payload, signature, endpointSecret)
  } catch (err) {
    const message = err instanceof Error ? err.message : "Unknown error"
    return NextResponse.json({ error: `Webhook Error: ${message}` }, { status: 400 })
  }

  // event is now verified — safe to trust
  return NextResponse.json({ received: true })
}

What's happening here: req.text() reads the body exactly as Stripe sent it. If you call req.json() first, the body gets re-serialized slightly differently, and the cryptographic signature check fails — a classic gotcha that has nothing to do with your actual secret key.

Step 7: Adding CORS Support

If your Route Handler needs to be called from a different domain (a separate frontend, a browser extension, another app), you need to explicitly allow it with CORS headers.

// app/api/public-data/route.ts
export async function GET() {
  return Response.json(
    { data: "available to any origin" },
    {
      headers: {
        "Access-Control-Allow-Origin": "*",
      },
    }
  )
}

export async function OPTIONS() {
  return new Response(null, {
    status: 204,
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  })
}

⚠️ Common Mistake: Setting CORS headers on GET/POST but forgetting OPTIONS. Browsers send a "preflight" OPTIONS request before certain cross-origin requests, and if that preflight doesn't return the right headers, the browser blocks the real request before it's ever sent — even if your GET handler would have worked fine.

If you need CORS applied consistently across many routes at once, handling it in proxy.ts (formerly middleware.ts) instead of repeating this in every file is usually cleaner.

Route Resolution Rules to Know

A few quick rules worth keeping in mind as your API grows:

A route.ts file cannot exist at the same segment as a page.tsx — pick one per route.
Route Handlers do not participate in layouts or client-side navigation the way pages do. They're the lowest-level routing primitive — pure request in, response out.
Each route.ts takes over every HTTP verb for that exact segment. A nested dynamic segment like app/[user]/page.tsx next to app/api/route.ts is perfectly valid, since they're different paths.

Page	Route	Result
`app/page.tsx`	`app/route.ts`	✗ Conflict
`app/page.tsx`	`app/api/route.ts`	✓ Valid
`app/[user]/page.tsx`	`app/api/route.ts`	✓ Valid

Frequently Asked Questions

Can I use Route Handlers with the Pages Router?

No — Route Handlers only work inside the app directory. If your project still uses pages/, you'd build API endpoints with the older pages/api convention instead, which behaves differently (Express-style req/res rather than Web Request/Response).

Do I need Route Handlers if I'm already using Server Actions?

Not necessarily — plenty of apps only use Server Actions for internal mutations. Reach for a Route Handler specifically when something outside your React component tree needs a callable URL: a webhook, a public API, or a request from a non-Next.js client like a mobile app.

Why isn't my GET Route Handler getting cached?

Route Handlers are dynamic by default. You need to explicitly opt in with export const dynamic = "force-static", or — if you're on Cache Components — make sure the handler doesn't touch runtime APIs like cookies(), headers(), or an uncached database call.

Can I return something other than JSON?

Yes. Response and NextResponse can return any body type — plain text, HTML, a file buffer, even a streamed response. Just set the appropriate Content-Type header so the client knows how to interpret it.

How do I protect a Route Handler so only logged-in users can call it?

Check the session inside the handler itself, the same way you would inside a Server Action — never rely on proxy.ts/middleware alone as your only line of defense. Most auth libraries (Clerk, Auth.js) expose a server-side helper you can call at the top of your GET/POST function to verify the request before doing any real work.

💡 If you haven't set up auth yet, see our guides on Clerk or Auth.js (NextAuth) for the full setup.

Wrapping Up

Route Handlers are the App Router's answer to "I need a real, callable HTTP endpoint" — whether that's a public API, a Stripe webhook, or a small internal utility route. The mental model is simple once it clicks: a route.ts file, named exports per HTTP method, and the standard Request/Response APIs doing the actual work. Layer in dynamic segments, caching with "use cache", and CORS headers as your API grows, and you've got everything you need to build a production-ready backend without leaving your Next.js project.

From here, a natural next step is pairing your Route Handlers with Zod validation for safer request parsing, or wiring one up as a real webhook receiver following the Stripe pattern above.

Image Optimization in Next.js 16: The Complete 2026 Guide

Syed Muhammad Ali — Wed, 22 Jul 2026 09:59:34 +0000

If you've ever shipped a page with a 2.5MB hero image and watched your Lighthouse score crash to single digits, you already know why this matters. A slow, unoptimized image is one of the fastest ways to lose a visitor — most people won't wait more than a couple of seconds for a page to feel usable, and a giant JPEG sitting above the fold is usually the culprit.

The good news: Next.js has had a built-in fix for this since version 10, and Next.js 16 makes it stricter, safer, and a little different from what you might remember. If you've been using priority or skipping qualities config, some of that has changed.

By the end of this guide, you'll know exactly how the next/image component works in Next.js 16, how to configure it correctly for local and remote images, and how to avoid the security-related gotchas that were added in this version.

`<img>` vs `next/image` at a Glance

Before diving in, here's what you actually get by switching:

Feature	`<img>`	`next/image`
Automatic resizing per device	❌ Manual	✅ Automatic
Format conversion (WebP/AVIF)	❌ Manual	✅ Automatic
Lazy loading	⚠️ Basic (`loading="lazy"` only)	✅ Built-in, smarter defaults
Layout shift (CLS) prevention	❌ Manual	✅ Enforced via `width`/`height`
Responsive `srcset` generation	❌ Manual	✅ Automatic
Blur-up placeholder	❌ Manual	✅ Built-in for local images
Caching of optimized variants	❌ None	✅ Disk cache with configurable TTL
Remote source security	❌ None	✅ `remotePatterns` allowlist

That table alone is the reason next/image exists — everything on the right side would otherwise be work you'd have to build and maintain yourself.

Why Image Optimization Is Tricky

Browsers don't know how big your users' screens are ahead of time. Serve one giant image and you're wasting bandwidth on mobile. Serve a tiny one and desktop users get blurry visuals. On top of that, modern formats like WebP and AVIF can shrink file sizes by 30–70% compared to JPEG/PNG — but only if you actually generate and serve them.

Doing all of this by hand (multiple sizes, multiple formats, lazy loading, layout shift prevention) is a lot of manual work. The next/image component automates it: one component, and Next.js generates the right size, right format, and right loading behavior automatically.

💡 Tip: Every layout-shift issue you've seen from images loading in late is what the width/height requirement on <Image> is designed to prevent.

Prerequisites

This guide assumes:

Next.js 16 with the App Router
TypeScript (strict mode)
Basic familiarity with React components

If you're on an older version, run the upgrade codemod first:

npx @next/codemod@canary upgrade latest

Step 1: Replace `<img>` with `next/image`

Instead of a plain <img> tag, import Image from next/image.

// app/page.tsx
import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

What's happening here: src points to a file in your public/ folder. width and height are the image's intrinsic dimensions (in pixels) — not the size it renders at on screen. Next.js uses these to calculate the aspect ratio and reserve space in the layout before the image finishes loading, which prevents the page from jumping around (this jumping is called Cumulative Layout Shift, or CLS — a metric Google uses to judge page experience).

⚠️ Common Mistake: Beginners often skip width/height because "the image already has a size." Next.js still needs these numbers explicitly, unless you use a static import or the fill prop (both covered below).

Step 2: Local vs. Static Imports

There are two ways to reference a local image, and they behave differently.

Option A — string path (you provide width/height manually):

<Image src="/hero.jpg" width={1200} height={600} alt="Hero banner" />

Option B — static import (Next.js infers width/height automatically):

// app/page.tsx
import Image from 'next/image'
import hero from '../public/hero.jpg'

export default function Page() {
  return <Image src={hero} alt="Hero banner" />
}

What's happening here: With a static import, Next.js reads the file at build time, figures out its real dimensions, and even auto-generates a small blurred placeholder (blurDataURL) for JPG, PNG, WebP, or AVIF files — with zero extra config. This is the easiest and safest way to handle local images.

Step 3: Configure Remote Images with `remotePatterns`

If your image comes from an external URL (a CMS, S3 bucket, CDN), Next.js won't optimize it by default — for security reasons, you have to explicitly allow it.

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        pathname: '/uploads/**',
      },
    ],
  },
}

export default nextConfig

// app/page.tsx
<Image
  src="https://assets.example.com/uploads/profile.png"
  alt="Picture of the author"
  width={500}
  height={500}
/>

What's happening here: remotePatterns is a strict allowlist. Any external image URL that doesn't match one of these patterns gets rejected with a 400 Bad Request. Since remote images aren't available at build time, you must supply width and height manually — Next.js can't inspect a file it doesn't have locally.

⚠️ Common Mistake: Don't leave remotePatterns wide open (e.g. matching ** with no protocol or pathname) — that lets anyone route arbitrary external URLs through your server's image optimizer. Be as specific as possible with hostname and pathname.

⚠️ Common Mistake: If your src image requires authentication (a private bucket, a signed CMS endpoint), the default loader won't work — for security reasons, Next.js does not forward headers when fetching the source image. In that case, set the unoptimized prop on that image instead of trying to pass auth headers through.

Step 4: Responsive Images with `sizes`

By default, if you don't tell Next.js how wide the image will actually render, it assumes it could be as wide as the entire viewport — and generates a larger srcset than necessary.

<Image
  src="/banner.jpg"
  alt="Banner"
  fill
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>

What's happening here: sizes tells the browser: "on small screens, this image is roughly full width; on medium screens, half width; otherwise a third of the width." The browser then picks the most appropriately sized file from the generated srcset instead of always downloading the largest version.

Use sizes whenever:

You're using the fill prop, or
The image is styled to be responsive via CSS

Step 5: `fill` for Unknown Dimensions

Sometimes you don't know an image's dimensions ahead of time — a user-uploaded avatar, for example.

<div style={{ position: 'relative', width: '400px', height: '300px' }}>
  <Image
    src="/uploaded-photo.jpg"
    alt="User upload"
    fill
    sizes="400px"
    style={{ objectFit: 'cover' }}
  />
</div>

What's happening here: fill makes the image expand to match its parent container, so the parent must have position: relative, absolute, or fixed. objectFit: 'cover' crops the image to fill the container without distorting it — similar to CSS background-size: cover.

Step 6: Choose the Right Loading Strategy

Not every image on a page deserves the same treatment. Next.js gives you four levers, and picking the right one per image matters more than most beginners realize.

Strategy	How to set it	When to use it
Lazy (default)	Nothing — `loading="lazy"` is automatic	Any image below the fold: galleries, article body images, footer content
Eager	`loading="eager"`	An above-the-fold image you want loaded immediately, without waiting for scroll distance to trigger it
High fetch priority	`fetchPriority="high"`	Your actual LCP candidate in most cases — this is what Next.js itself recommends reaching for first
Preload	`preload`	A narrower case: you specifically want the browser to start fetching the image from the `<head>`, before it's even discovered in the HTML body — and you're certain only one image qualifies

// Below the fold — do nothing, lazy is default
<Image src="/gallery-1.jpg" width={400} height={300} alt="Gallery photo" />

// Above the fold but not the LCP element — load immediately, don't wait for lazy trigger
<Image src="/secondary-banner.jpg" width={800} height={300} alt="Banner" loading="eager" />

// The confirmed LCP element — Next's own recommendation for most cases
<Image src="/hero.jpg" width={1200} height={600} alt="Hero" fetchPriority="high" />

What's happening here: Lazy loading defers off-screen images until the browser gets close to them, saving bandwidth on page load. Eager loading forces an image to load immediately regardless of position — useful just below the fold. fetchPriority="high" bumps an image's priority in the browser's normal fetch queue without the stricter constraints of preload.

⚠️ Correction worth noting: It's tempting to reach for preload as the default "make my hero load fast" fix, but Next.js's own docs say the opposite: "In most cases, you should use loading='eager' or fetchPriority='high' instead of preload." Reserve preload for cases where you're certain exactly one image is the LCP element and you specifically need the <head> preload behavior — and never combine it with loading or fetchPriority on the same image, since Next.js explicitly warns against that combination.

💡 Real example from the docs: If you're swapping images based on light/dark theme (two <Image> components, one hidden via CSS), you can't use preload or loading="eager" on either one — both would end up loading. fetchPriority="high" is the only safe option there, since it doesn't force an eager fetch the way the other two do.

Step 7: Controlling Quality — `qualities` Is Now Required Config

Another Next.js 16 change: the qualities array in next.config.ts is now required if you want to use any quality value other than the default.

// next.config.ts
const nextConfig: NextConfig = {
  images: {
    qualities: [25, 50, 75, 100],
  },
}

<Image src="/photo.jpg" width={800} height={600} alt="Photo" quality={90} />

What's happening here: Previously, you could pass any quality value (1–100) freely. Starting in Next.js 16, the value you pass to quality must match one of the values listed in qualities in your config — otherwise Next.js snaps to the closest allowed value. This exists because unrestricted quality values could be abused to generate an unlimited number of cached image variants, wasting server resources.

💡 Tip: If you don't configure qualities at all, the default allowed value is [75] — meaning quality={90} would silently be clamped down to 75.

Step 8: Choosing Output Formats — AVIF vs. WebP

// next.config.ts
const nextConfig: NextConfig = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
}

What's happening here: Next.js checks the browser's Accept header and serves whichever format is listed first in your array that the browser supports. AVIF compresses roughly 20% smaller than WebP but takes about 50% longer to encode on first request (subsequent requests are cached, so this only affects the very first visitor per image size/format combination). For most projects, WebP alone is a solid, faster-to-generate default — add AVIF if you want to squeeze out extra savings on high-traffic pages.

⚠️ Common Mistake: Enabling both formats doubles your optimized-image storage, since Next.js caches AVIF and WebP versions separately. Keep an eye on maximumDiskCacheSize if disk space is a concern.

Step 9: Blur Placeholders for a Smoother Load

<Image
  src="/photo.jpg"
  alt="Photo"
  width={800}
  height={600}
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,/9j/4AAQSk..."
/>

What's happening here: placeholder="blur" shows a blurred, low-res version of the image while the full one loads, which feels smoother than a blank space. For statically imported local images, Next.js generates blurDataURL for you automatically. For remote or dynamic images, you need to generate a small base64 placeholder yourself (a tool like Plaiceholder can do this).

Step 10: SVGs and Skipping Optimization

SVGs are vector graphics — resizing them losslessly means there's nothing for the optimizer to do. Next.js skips optimizing them by default and recommends the unoptimized prop:

<Image src="/logo.svg" width={120} height={40} alt="Logo" unoptimized />

What's happening here: unoptimized tells Next.js to serve the file exactly as-is, skipping resizing, format conversion, and quality adjustment. This also applies to tiny images (under 1KB) and animated GIFs, where optimization overhead outweighs any benefit.

Step 11: Preserving SEO Rankings with `overrideSrc`

By default, next/image rewrites the rendered src attribute to point at Next's optimization endpoint (/_next/image?url=...) instead of the original file path. For a brand-new site that's irrelevant — but if you're migrating an already-live, already-indexed site from <img> to <Image>, it's worth knowing this changes the URL search engines see for that image.

To be precise about what this does and doesn't mean: changing an image's URL doesn't erase or "reset" its rankings — search engines are perfectly capable of discovering and reindexing a new URL on their own, and image search visibility isn't tied to the URL string itself. What it does mean is a gap while the new URL gets recrawled and reindexed, and any direct backlinks or bookmarks pointing at the old file path stop resolving to the same indexed result unless you redirect them. For a high-traffic image ranking well in image search, that gap is often reason enough to avoid it.

<Image
  src="/uploads/dental-clinic-hero.jpg"
  overrideSrc="/uploads/dental-clinic-hero.jpg"
  width={1200}
  height={600}
  alt="Modern dental clinic reception area"
/>

What's happening here: Next.js still generates the optimized srcset behind the scenes, but overrideSrc forces the final src attribute in the rendered HTML to stay exactly what you specify — so the URL search engines already have indexed doesn't change, and there's no recrawl gap to wait out. Users still get the responsive, optimized images either way.

💡 Tip: This is mainly worth reaching for on pages that already get meaningful image search traffic. For most other migrations, letting the URL change and get reindexed naturally is completely fine.

Step 12: Custom Markup with `getImageProps()`

Sometimes you don't want Next.js to render the <img> tag for you — maybe you need a <picture> element for art direction, or want to set a CSS background image using an optimized source. getImageProps() gives you the computed props without rendering anything.

// app/components/theme-image.tsx
import { getImageProps } from 'next/image'

const { props } = getImageProps({
  src: '/mountain.jpg',
  alt: 'A scenic mountain view',
  width: 1200,
  height: 800,
})

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>A scenic mountain view</figcaption>
    </figure>
  )
}

What's happening here: getImageProps() runs the same logic <Image> uses internally — generating srcset, src, and sizing — and just hands you the resulting props object instead of a component. This is the tool to reach for with <picture> elements, CSS image-set() backgrounds, or any case where you need full control over the rendered markup while still getting optimized URLs.

💡 Tip: getImageProps() can't be combined with the placeholder prop, since there's no component lifecycle to remove the placeholder once the image loads.

Advanced Configuration

The following options aren't things you'll touch on day one, but they're worth knowing about once your app is live and you run into a specific problem.

Custom Image Loaders (Skipping Next's Built-In Optimizer)

If you're already using a CDN that does its own image optimization — Cloudinary, Imgix, a headless CMS's built-in image API — you don't need Next.js to optimize on top of it. A loader function builds the URL yourself instead of using Next's /_next/image endpoint:

// lib/cloudinary-loader.ts
export default function cloudinaryLoader({ src, width, quality }: { src: string; width: number; quality?: number }) {
  return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`
}

// next.config.ts
const nextConfig: NextConfig = {
  images: {
    loader: 'custom',
    loaderFile: './lib/cloudinary-loader.ts',
  },
}

What's happening here: loaderFile applies this URL-building function to every <Image> in the project, so you don't need to configure remotePatterns or lean on Next's own optimizer at all — the CDN handles resizing and format conversion on its end.

Caching Behavior with `minimumCacheTTL`

Optimized images are cached on disk with a default TTL of 4 hours (minimumCacheTTL in next.config.ts). If you've replaced an image file but the old version is still showing, this is usually why — the actual expiry used is whichever is larger: minimumCacheTTL or the upstream image's own Cache-Control header. There's no built-in way to manually invalidate a specific cached image, so keeping this value low is safer if your images change often.

Self-Hosting Behind a Proxy or CDN

If you self-host Next.js behind your own reverse proxy or CDN, AVIF/WebP format negotiation can silently stop working — Next.js decides which format to serve based on the request's Accept header, and if your proxy doesn't forward that header through, every browser ends up getting the original format regardless of what it actually supports. Worth checking if you notice formats config seemingly having no effect in production.

Real-World Example: A Blog Post Page

Here's how several of these pieces come together on an actual page — a blog post with one hero image (the LCP element) and a few inline body images that can load lazily.

// app/blog/[slug]/page.tsx
import Image from 'next/image'
import heroImage from '../../../public/blog/hero.jpg'

export default function BlogPost() {
  return (
    <article>
        {/* Hero — above the fold
            Uses a static import
            Automatically gets blurDataURL
            Marked as high priority
        */}

      <Image
        src={heroImage}
        alt="Team collaborating around a whiteboard"
        sizes="100vw"
        fetchPriority="high"
        style={{ width: '100%', height: 'auto' }}
      />

      <h1>How We Scaled Our Front-End Team</h1>
      <p>Some intro text about the article...</p>

        {/* Inline content images
            Lazy-loaded by default
            Remote URLs
            Need remotePatterns
        */}

      <Image
        src="https://assets.devstacked.tech/blog/diagram-1.png"
        alt="Team structure diagram"
        width={800}
        height={450}
        sizes="(max-width: 768px) 100vw, 800px"
      />

      <p>More article content...</p>

      {/* Another inline image, further down */}
      <Image
        src="https://assets.devstacked.tech/blog/screenshot-1.png"
        alt="Dashboard screenshot"
        width={800}
        height={500}
        sizes="(max-width: 768px) 100vw, 800px"
      />
    </article>
  )
}

What's happening here: Only the hero gets fetchPriority="high", since it's the confirmed LCP element — following Next's own guidance to reach for fetchPriority over preload in the common case. The static import means Next.js already knows its dimensions and generates a blur placeholder automatically. The two inline images come from a remote CMS bucket (so they'd need a matching remotePatterns entry in next.config.ts), have manually supplied width/height, and are left with the default lazy loading since they're further down the page — no fetchPriority, no eager, just sensible defaults.

Image Optimization Checklist

Run through this before shipping a page with images:

[ ] Every <img> tag replaced with next/image, or a documented reason why not (e.g. a tiny inline icon)
[ ] width and height set on every image, or a static import / fill used instead
[ ] External image domains added to remotePatterns — as narrow as possible, not wildcarded
[ ] sizes set on any image using fill or styled to be responsive
[ ] LCP image marked with fetchPriority="high" (Next's preferred approach), with preload reserved for the narrower case where you need <head>-level preloading and are certain only one image qualifies
[ ] qualities configured in next.config.ts if you use any quality value besides 75
[ ] formats set to ['image/webp'] at minimum; add AVIF only if the extra storage/encoding cost is worth it for your traffic
[ ] alt text is descriptive and meaningful for every image (empty string only for purely decorative images)
[ ] SVGs and tiny/animated images marked unoptimized instead of routed through the optimizer
[ ] blurDataURL provided for remote/dynamic images where a blur placeholder is used
[ ] overrideSrc considered for high-traffic, already-indexed images where you want to skip the recrawl gap entirely

Frequently Asked Questions

Do I still need to use the `priority` prop?

priority still technically works but is deprecated as of Next.js 16. That said, don't just swap it 1:1 for preload — Next.js recommends fetchPriority="high" (or loading="eager") for most LCP images, and reserves preload for narrower cases. See Step 6 for the breakdown.

Should I use `preload` for my hero/LCP image?

Usually not directly — Next's own docs say to use loading="eager" or fetchPriority="high" in most cases instead. preload is meant for a narrower situation: when you're certain exactly one image is the LCP element and specifically want it fetched from the <head> before the rest of the page is parsed.

How do I keep my image SEO rankings when migrating from `<img>` to `next/image`?

Changing an image's URL doesn't reset or erase its rankings — search engines can rediscover and reindex a new URL fine on their own. What it does mean is a recrawl/reindex gap, and any existing backlinks pointing at the old file path won't resolve the same way. Use the overrideSrc prop to keep the original file path as the rendered src attribute (Next.js still serves the optimized srcset behind the scenes) if you want to skip that gap entirely — mainly worth it for pages already getting real image search traffic.

Why is my `quality` prop being ignored?

As of Next.js 16, quality values must match an entry in your qualities array in next.config.ts. If you haven't configured it, the only allowed value is 75, so anything else gets rounded to the nearest allowed value.

Can I use `next/image` with images from an external CMS?

Yes, but you must add the CMS's domain to remotePatterns in next.config.ts, and you'll need to supply width and height manually since Next.js can't inspect a remote file at build time.

💡 Tip: If your CMS provides image dimensions in its API response, pass those directly instead of hardcoding fixed values.

Should I always use AVIF for the best compression?

Not necessarily. AVIF gives smaller files but takes longer to encode on first request. For most sites, WebP alone (the default) is a good balance of speed and size — add AVIF if performance budgets are tight and you can absorb the extra caching cost.

What's the difference between `width`/`height` and the actual rendered size?

width and height only tell Next.js the image's intrinsic aspect ratio, used to prevent layout shift — they don't control how big the image appears on screen. Actual rendered size is controlled by CSS (style or className).

Wrapping Up

That's the full picture of image optimization in Next.js 16: swap <img> for <Image>, lock down remote sources with remotePatterns, allowlist your quality values with qualities, and reach for fetchPriority="high" over preload for your LCP image in most cases. These changes exist mostly to close security gaps from earlier versions, so if you're migrating an older project, qualities and remotePatterns are the two configuration changes developers most commonly encounter when migrating to Next.js 16 — with overrideSrc worth a look too if you're migrating a page that already ranks in image search.

Next up, it's worth pairing this with a proper Metadata API setup for full page-level SEO, or diving into Cache Components to control how those optimized images and pages get cached at the edge.

Continue Learning

Free SEO Tools

Stripe Payment Element in Production: Webhooks, Idempotency & Testing (2026)

Syed Muhammad Ali — Tue, 21 Jul 2026 03:53:46 +0000

If you followed our guide on integrating Stripe Payment Element with Next.js 16, you already have a working checkout flow — a Payment Intent gets created, the user pays, and everyone's happy.

Except "it works on my machine" and "it works in production, forever, under real traffic" are two very different bars. What happens when a webhook arrives twice? What happens when your server retries a failed request and accidentally creates a duplicate charge? What happens when a card gets declined mid-checkout, or a webhook signature check silently fails and nobody notices for three weeks?

This guide picks up exactly where the last one left off. We'll cover the four things that separate a demo from a production-grade Stripe integration: verifying webhooks properly, using idempotency keys to prevent duplicate charges, handling failed payments gracefully, and testing all of it locally with the Stripe CLI before it ever touches real money.

Why "It Works" Isn't the Same as "It's Production-Ready"

Here's the uncomfortable truth about payment integrations: the happy path is easy. Card succeeds, webhook fires once, database updates, done. Tutorials (including our own Payment Element guide) usually stop there, because covering every failure mode in a beginner-friendly walkthrough would bury the core concept.

But in production, none of these things are guaranteed:

A webhook might arrive more than once for the same event — Stripe explicitly documents that webhooks aren't exactly-once delivery.
A network blip might make your server retry a request that Stripe already received the first time, risking a duplicate charge.
Cards fail — expired, insufficient funds, flagged for fraud — and your app needs to tell the user something useful instead of a blank error.
Your webhook endpoint might be hit by anyone, not just Stripe, unless you actually verify the request came from them.

Each of these has a specific, well-documented fix. Let's go through them one at a time.

Here's the shape of what we're building toward — keep this in mind as a mental map while we go step by step:

                     ┌────────────────────┐
                     │   User clicks Pay  │
                     └──────────┬─────────┘
                                ↓
                 ┌───────────────────────────────┐
                 │  Your Next.js Server          │
                 │  (idempotency key generated)  │
                 └──────────────┬────────────────┘
                                ↓
                     ┌────────────────────┐
                     │   Stripe API       │
                     │ (Payment Intent)   │
                     └──────────┬─────────┘
                                ↓
                     ┌────────────────────┐
                     │  Customer submits  │
                     │  payment           │
                     └──────────┬─────────┘
                                ↓
                     ┌────────────────────┐
                     │   Stripe Webhook   │
                     │  (signed event)    │
                     └──────────┬─────────┘
                                ↓
              ┌───────────────────────────────────┐
              │  Your /api/webhook route          │
              │  1. Verify signature              │
              │  2. Check event ID (dedupe)       │
              │  3. Fulfill order / handle failure│
              └───────────────────────────────────┘

Prerequisites

This guide continues directly from the Payment Element integration guide and assumes you already have:

Next.js 16 with the App Router
TypeScript in strict mode
The stripe Node SDK installed and a stripe server client set up (lib/stripe/server.ts)
A working Payment Intent + Payment Element checkout flow

If you haven't built that yet, go set that up first — everything below assumes it's already in place.

Step 1: Verify Every Webhook Signature

Your webhook endpoint (/api/webhook) is a public URL. Nothing stops someone from sending a fake POST request to it that looks like a payment_intent.succeeded event, claiming an order was paid when it wasn't. Signature verification is what proves a request actually came from Stripe, not an attacker.

💡 Tip: Think of a webhook signature like a wax seal on a letter. Anyone can write a letter that says it's from the king, but only the king has the seal to prove it. Stripe signs every webhook request with a secret only you and Stripe know.

The Rule: Always Use the Raw Body

// app/api/webhook/route.ts
import { NextResponse } from "next/server";
import { headers } from "next/headers";
import Stripe from "stripe";
import { stripe } from "@/lib/stripe/server";

const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(req: Request) {
  const payload = await req.text(); // MUST be raw text, not parsed JSON
  const signature = (await headers()).get("stripe-signature");

  if (!signature) {
    return NextResponse.json({ error: "Missing signature" }, { status: 400 });
  }

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(payload, signature, endpointSecret);
  } catch (err) {
    const message = err instanceof Error ? err.message : "Unknown error";
    console.error("Webhook signature verification failed:", message);
    return NextResponse.json({ error: `Webhook Error: ${message}` }, { status: 400 });
  }

  // event is now verified — safe to trust
  return NextResponse.json({ received: true });
}

What's happening here:

req.text() reads the raw, unparsed request body. This matters because constructEvent() recalculates the signature from the exact bytes Stripe sent — if you call req.json() first, the body gets re-serialized slightly differently, and the signature check fails with a confusing error that has nothing to do with your actual secret key.
stripe.webhooks.constructEvent() does the actual cryptographic check, comparing the stripe-signature header against a signature it computes itself using your STRIPE_WEBHOOK_SECRET.
If verification fails, we return a 400 — Stripe will not retry a request that got a 400 for a bad signature, since it assumes the sender misconfigured something, not that the endpoint is temporarily down.

⚠️ Common Mistake: Adding any global middleware or body-parser that touches the request body before it reaches your webhook route. In Next.js App Router route handlers this usually isn't an issue since there's no default body parser, but if you add custom middleware that reads req.json() anywhere in the chain, the raw body is gone by the time your webhook handler needs it.

Where Does `STRIPE_WEBHOOK_SECRET` Come From?

Each webhook endpoint you register in Stripe — one for local testing via the CLI, one for production — gets its own signing secret. Don't reuse your local whsec_... value in production; grab the real one from Stripe Dashboard → Developers → Webhooks → your endpoint → Signing secret.

# .env.local (development, from `stripe listen`)
STRIPE_WEBHOOK_SECRET=whsec_dev_xxxx

# Vercel production environment variable
STRIPE_WEBHOOK_SECRET=whsec_live_xxxx

⚠️ Common Mistake: Forgetting that the CLI's stripe listen command generates a different signing secret every time you run it (unless you use a fixed one). If your local webhook suddenly starts failing signature checks after restarting stripe listen, check that .env.local has the newest secret it printed.

Stripe Retries Webhooks Automatically — On Purpose

Here's something a lot of developers don't realize until it bites them: if your endpoint doesn't respond with a 2xx status — because your server timed out, threw an error, or was mid-deploy — Stripe automatically retries that same webhook, on a backing-off schedule, for up to three days.

This isn't a bug in Stripe, and it isn't rare. It's a deliberate design choice: Stripe would rather risk sending you an event more than once than risk you missing it entirely. That means duplicate webhook deliveries aren't an edge case you might hit — they're an expected, documented part of how webhooks work, and your handler has to be written assuming they will happen, not hoping they won't.

That's exactly the problem idempotency solves, and it's worth understanding why before looking at the fix.

Step 2: Prevent Duplicate Processing with Idempotency

Two separate problems live under "idempotency," and it's worth keeping them distinct:

Idempotent requests you send to Stripe — so a network retry on your end doesn't create two charges.
Idempotent webhook handling — so processing the same event twice (which Stripe's docs explicitly say can happen) doesn't double-fulfill an order.

Idempotency Keys for Outgoing Requests

Imagine this: your server calls stripe.paymentIntents.create(), the request succeeds on Stripe's end, but the response times out before it reaches your server. Your code sees an error and retries. Without protection, you've now created two Payment Intents for one checkout.

The fix is an idempotency key — a unique string you generate per logical operation. If Stripe sees the same key twice, it returns the original result instead of creating a new object.

// src/actions/create-payment-intent.ts
"use server";

import { randomUUID } from "crypto";
import { stripe } from "@/lib/stripe/server";
import { PACKAGES, PkgTierType } from "../constants/package-tier";

export async function createPaymentIntent(
  prev: unknown,
  formData: FormData
): Promise<{ clientSecret?: string; error?: string }> {
  try {
    const pkgTier = formData.get("packageTier");

    if (typeof pkgTier !== "string" || !(pkgTier in PACKAGES)) {
      return { error: "Invalid package tier" };
    }

    const pkg = PACKAGES[pkgTier as PkgTierType];

    // Generate once per checkout attempt, not per network call
    const idempotencyKey = randomUUID();

    const paymentIntent = await stripe.paymentIntents.create(
      {
        amount: pkg.price * 100,
        currency: "usd",
        automatic_payment_methods: { enabled: true },
        metadata: { packageTier: pkgTier },
      },
      { idempotencyKey } // second argument: request options
    );

    if (!paymentIntent.client_secret) {
      return { error: "Failed to create payment intent" };
    }

    return { clientSecret: paymentIntent.client_secret };
  } catch (err) {
    return { error: err instanceof Error ? err.message : "Something went wrong" };
  }
}

What's happening here: the idempotencyKey is passed as a second argument, separate from the actual request body — this is a Stripe SDK convention across almost every method. As long as the same key is reused within Stripe's 24-hour idempotency window, a retried request returns the exact same Payment Intent instead of creating a duplicate.

⚠️ Common Mistake: Generating a new randomUUID() inside a retry loop. That defeats the entire point — the key has to be generated once per user action (e.g. once per "Pay Now" click) and reused across retries of that same action, not regenerated on every attempt.

💡 Tip: For form submissions, a good pattern is generating the idempotency key on the client when the form first renders (e.g. with useId() or a useState(() => randomUUID()) initializer) and passing it along as a hidden field — that way even a page refresh mid-submission doesn't invent a new key.

Idempotent Webhook Handling

Idempotency keys solve outgoing duplicate requests. They don't stop Stripe from sending you the same webhook event twice — which happens for reasons entirely outside your control (a slow response, a network hiccup on Stripe's side, an at-least-once delivery guarantee that intentionally favors duplicates over silently dropped events).

The fix: track which event IDs you've already processed, and skip anything you've seen before.

// app/api/webhook/route.ts (continued)
switch (event.type) {
  case "payment_intent.succeeded": {
    const paymentIntent = event.data.object as Stripe.PaymentIntent;

    // Check if we've already processed this exact event
    const alreadyProcessed = await hasProcessedEvent(event.id);
    if (alreadyProcessed) {
      return NextResponse.json({ received: true, duplicate: true });
    }

    // Do the actual work: mark order paid, send email, etc.
    await fulfillOrder(paymentIntent);

    // Record that this event is now handled
    await markEventProcessed(event.id);

    break;
  }
}

What's happening here: event.id is a unique identifier Stripe generates for every event it sends — evt_1AbCdE.... Storing processed event IDs (in a database table, or even a Redis set with a TTL) and checking against it before doing real work is the standard pattern. It doesn't need to be fancy — a single table with a unique constraint on stripe_event_id is enough for almost any app's scale.

-- Minimal schema for tracking processed webhook events
create table processed_webhook_events (
  id uuid primary key default gen_random_uuid(),
  stripe_event_id text unique not null,
  processed_at timestamptz default now()
);

💡 Tip: Insert the event ID before doing the risky part of the work (charging, emailing, fulfilling), inside the same transaction if your database supports it. If the insert fails because the ID already exists (unique constraint violation), you know it's a duplicate and can safely bail out. This matters because a plain "check, then act" approach still has a gap: two webhook deliveries arriving milliseconds apart can both pass the existence check before either one has inserted its row, so both proceed to fulfill the order. A database unique constraint (or inserting the event ID first, inside a transaction) closes that race condition, since the second insert fails outright instead of silently succeeding.

A Real Example of What Goes Wrong Without This

Imagine Stripe sends the same payment_intent.succeeded webhook three times because your server happened to return a 500 the first two times — maybe a deploy was mid-rollout, maybe your database had a brief connection hiccup. Without idempotent handling, each of those three deliveries independently runs your fulfillment logic: your customer receives three confirmation emails, and if fulfillment also decrements stock, your inventory count drops by three units for a single item sold. Nothing about this requires bad luck or an attacker — it's just Stripe's normal retry behavior meeting a webhook handler that assumed "one event equals one delivery."

Step 3: Handle Failed Payments Gracefully

A failed payment isn't a bug — it's a normal, expected outcome that happens to a meaningful percentage of real transactions. The difference between an amateur and production integration is what happens next.

Listen for the Right Webhook Events

// app/api/webhook/route.ts (continued)
switch (event.type) {
  case "payment_intent.succeeded": {
    const paymentIntent = event.data.object as Stripe.PaymentIntent;
    await fulfillOrder(paymentIntent);
    break;
  }

  case "payment_intent.payment_failed": {
    const paymentIntent = event.data.object as Stripe.PaymentIntent;
    const reason = paymentIntent.last_payment_error?.message ?? "Unknown reason";

    console.warn(`Payment failed for ${paymentIntent.id}: ${reason}`);

    // TODO: notify the user (email), mark the order as failed in your DB
    await markOrderFailed(paymentIntent.id, reason);

    break;
  }

  case "payment_intent.requires_action": {
    // Card needs 3D Secure or another extra verification step.
    // Usually handled automatically client-side by stripe.confirmPayment(),
    // but useful to log for support/debugging visibility.
    break;
  }

  default:
    break;
}

What's happening here: last_payment_error is where Stripe attaches the human-readable reason a charge failed — insufficient funds, an expired card, a fraud block, and so on. Logging and surfacing this (instead of a generic "something went wrong") is what actually helps users fix the problem and retry.

Surface Errors on the Client, Not Just the Server

Your CheckoutForm component (from the original guide) already catches result.error from stripe.confirmPayment() — that's your first line of defense, giving instant feedback without waiting for a webhook round-trip.

// components/checkout-form.tsx (excerpt)
const result = await stripe.confirmPayment({
  elements,
  confirmParams: {
    return_url: `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`,
  },
  redirect: "always",
});

if (result.error) {
  // result.error.message is safe to show directly to users —
  // Stripe writes these messages to be customer-facing
  setError(result.error.message || "Payment failed");
}

💡 Tip: result.error.message from Stripe.js is specifically designed to be shown to end users — it says things like "Your card was declined" rather than exposing internal error codes. You don't need to sanitize or reword it.

Common Decline Reasons Worth Handling Explicitly

`decline_code`	What it means	What to tell the user
`insufficient_funds`	Card has no available balance	"Your card was declined for insufficient funds. Try another card."
`expired_card`	Card's expiration date has passed	"Your card has expired. Please use a different card."
`incorrect_cvc`	Security code doesn't match	"The security code you entered is incorrect."
`fraudulent` / `lost_card` / `stolen_card`	Issuer flagged the card	"Your card was declined. Please contact your bank or try another card."

⚠️ Common Mistake: Retrying a declined charge automatically without user input. Silent retries on a genuinely declined card usually just fail again (and can look like fraud pattern behavior to the card issuer). Let the user decide whether to try a different card.

Don't Forget: Webhooks Are the Source of Truth

Never mark an order as "paid" purely because the client-side stripe.confirmPayment() call succeeded. A user could close the tab right after payment but before the redirect finishes, or the success page could fail to load. Only your webhook handler — specifically payment_intent.succeeded — should flip an order to "paid" in your database. The client-side success page is just a UX nicety, not your source of truth.

Step 4: Test Everything Locally with the Stripe CLI

None of the above matters if you're only testing the happy path. The Stripe CLI lets you simulate real webhook events and failure scenarios without ever touching production or waiting for a real card decline.

Install and Log In

# macOS
brew install stripe/stripe-cli/stripe

# Windows (via Scoop)
scoop install stripe

# Or download directly: https://docs.stripe.com/stripe-cli

stripe login

This opens a browser window to link the CLI to your Stripe account in test mode.

Forward Webhooks to Your Local Server

stripe listen --forward-to localhost:3000/api/webhook

This prints a webhook signing secret — copy it into .env.local as STRIPE_WEBHOOK_SECRET, then restart your dev server so it picks up the new value.

> Ready! Your webhook signing secret is whsec_xxxxxxxxxxxxx (^C to quit)

Keep this terminal running in a separate tab while you develop — every event Stripe would normally send gets forwarded here in real time.

Trigger Specific Events on Demand

Instead of manually clicking through a checkout every time you want to test a webhook handler, trigger events directly:

stripe trigger payment_intent.succeeded
stripe trigger payment_intent.payment_failed
stripe trigger charge.refunded

💡 Tip: stripe trigger --help lists every event you can simulate this way. It's the fastest way to test edge-case webhook logic — refunds, disputes, failed renewals — without manually reproducing each scenario in the Stripe dashboard.

Test Real Card Declines with Test Cards

For testing the actual checkout form (not just webhooks in isolation), Stripe provides dedicated test card numbers that simulate specific outcomes:

Card number	Simulates
`4242 4242 4242 4242`	Successful payment
`4000 0000 0000 0002`	Card declined (generic)
`4000 0000 0000 9995`	Declined — insufficient funds
`4000 0000 0000 0069`	Declined — expired card
`4000 0025 0000 3155`	Requires 3D Secure authentication

Use any future expiration date, any 3-digit CVC, and any postal code — none of it is validated in test mode.

Verify Duplicate-Event Handling With the CLI

You can also manually resend an event to confirm your idempotency logic actually works:

# List recent events to get an event ID
stripe events list --limit 5

# Resend a specific event
stripe events resend evt_1AbCdEfGhIjKlMnO

If your webhook handler is correctly idempotent, resending an already-processed event should return { received: true, duplicate: true } (or your equivalent) and not re-run fulfillment logic — check your logs to confirm.

A Simple Local Test Checklist

[ ] stripe listen running and forwarding to your local webhook route
[ ] .env.local has the CLI's current STRIPE_WEBHOOK_SECRET
[ ] Successful payment with 4242 4242 4242 4242 triggers payment_intent.succeeded and marks the order paid
[ ] Declined card (4000 0000 0000 0002) shows a clear error on the client
[ ] stripe trigger payment_intent.payment_failed logs the failure and updates the order status
[ ] Resending an already-processed event doesn't double-fulfill the order
[ ] A request with a tampered/missing stripe-signature header gets rejected with a 400

Production Checklist

Before flipping your webhook endpoint and API keys over to live mode, run through this list. Each item maps directly back to a section above:

[ ] Webhook route reads the raw body (req.text()), never a parsed JSON body
[ ] STRIPE_WEBHOOK_SECRET in production is the live endpoint's signing secret, not the one stripe listen printed locally
[ ] Webhook handler returns 400 on a bad/missing signature, and 500 (not 200) on genuine internal failures so Stripe retries
[ ] Outgoing requests that create money-moving objects (Payment Intents, refunds, transfers) pass an idempotencyKey
[ ] Idempotency keys are generated once per user action, not regenerated on every retry
[ ] Processed webhook event IDs are stored with a unique database constraint, not just an in-memory check
[ ] Order fulfillment is gated on the payment_intent.succeeded webhook, never on the client-side redirect alone
[ ] payment_intent.payment_failed is handled — logged, and the user/order status reflects it
[ ] Decline reasons shown to users come from result.error.message / last_payment_error, not a generic fallback
[ ] You've manually resent a webhook event with the Stripe CLI and confirmed it does not double-fulfill
[ ] Dashboard alerting (or equivalent monitoring) is set up for repeated webhook delivery failures
[ ] Live-mode API keys and webhook secrets are only in server-side environment variables, never NEXT_PUBLIC_

Putting It All Together

Here's roughly how the pieces fit relative to each other:

User clicks "Pay Now"
        ↓
Server generates idempotency key → creates Payment Intent
        ↓
stripe.confirmPayment() on the client (instant UX feedback)
        ↓
Stripe sends webhook → signature verified → event ID checked against processed table
        ↓
   New event?                        Duplicate event?
        ↓                                    ↓
Fulfill order, mark event processed    Return 200, skip fulfillment
        ↓
payment_intent.payment_failed → log reason, notify user, mark order failed

Every box in that diagram maps to something covered above: idempotency keys stop duplicate Payment Intents, signature verification stops forged webhooks, event-ID tracking stops duplicate fulfillment, and the failed-payment handler stops silent, confusing failures.

Frequently Asked Questions

Do I need idempotency keys if I already have webhook signature verification?

Yes — they solve different problems. Signature verification proves a webhook came from Stripe. Idempotency keys prevent your own server from accidentally creating duplicate Payment Intents when a request gets retried. You need both.

How long should I keep processed webhook event IDs in my database?

Stripe's own idempotency window is 24 hours, but webhook redelivery can technically happen for longer in rare cases (e.g. you re-enable a disabled endpoint after days). Keeping event IDs indefinitely, or at minimum for 30 days, is a safe default and costs very little storage.

What's the difference between `payment_intent.succeeded` and the client-side success redirect?

The client-side redirect (return_url) is a UX signal — it tells the user "looks like it worked," but it's not guaranteed to fire (closed tabs, network drops). The webhook is the authoritative signal from Stripe's servers. Always gate order fulfillment on the webhook, never the redirect alone.

My webhook signature verification keeps failing locally — what's wrong?

The most common cause is an outdated STRIPE_WEBHOOK_SECRET — stripe listen generates a new one every time you restart it unless you pin it. The second most common cause is something in your code calling req.json() before req.text() runs, which consumes the raw body Stripe's signature check needs.

Should I return a 200 even when my webhook handler hits an internal error?

No — only return 200 once you've genuinely handled the event successfully. If your database write fails, return a 500 so Stripe retries the webhook later. Returning 200 for genuine failures makes your system silently drop events, which is worse than a few retries.

Can I test 3D Secure authentication flows with the CLI?

Yes — use the test card 4000 0025 0000 3155, which forces a 3D Secure challenge in Stripe's test checkout modal. Combine it with stripe listen running to confirm your webhook still fires correctly once the (simulated) authentication completes.

Wrapping Up

A checkout flow that only handles the happy path is a demo, not a product. Verifying webhook signatures keeps forged requests out, idempotency keys and event-ID tracking keep duplicate charges and duplicate fulfillment from ever happening, graceful failed-payment handling keeps users informed instead of confused, and the Stripe CLI lets you prove all of this actually works before a real customer ever hits it.

None of these are exotic techniques — they're the small, boring safeguards that quietly separate a side project from something you'd trust with real money.

From here, natural next steps include setting up Stripe's Dashboard alerting for repeated webhook failures, and reviewing Stripe's own webhook best practices as your integration grows.

Useful Resources

Continue Learning

The Complete Technical SEO Checklist for Next.js Developers (2026 Guide)

Syed Muhammad Ali — Mon, 20 Jul 2026 03:14:54 +0000

You can write the best blog post in your niche, ship a beautifully designed landing page, and still get zero organic traffic — because Google never properly crawled it, never understood what it was, or ranked a slower competitor above it instead. That's the frustrating part of SEO nobody warns you about: content quality is only half the battle. The other half is technical SEO — the plumbing that decides whether search engines can find, understand, and trust your pages in the first place.

The good news is that technical SEO isn't a mystery box. It's a checklist. Once you know what to check, most of it takes an afternoon to fix in a Next.js app — no marketing degree required.

By the end of this guide, you'll have a complete, practical checklist covering crawlability, metadata, structured data, Core Web Vitals, and content quality — with real Next.js 16 App Router code for each item.

Why Technical SEO Is Different From "Writing Good Content"

Content SEO is about what you say. Technical SEO is about whether search engines can even reach what you said. A page can have perfect content and still fail because:

It's blocked in robots.txt by accident
It has no canonical URL, so Google indexes three duplicate versions of it
It loads so slowly that Google deprioritizes it in rankings
It has no structured data, so it never qualifies for rich results

None of these are content problems — they're implementation problems. And implementation problems are exactly what a developer is best positioned to fix.

Why Technical SEO Matters for AI Search Too

In 2026, "search" doesn't just mean the Google results page anymore. Tools like ChatGPT, Gemini, Claude, and Perplexity all crawl and cite web pages when answering questions — and the exact same fundamentals that help Google rank you are what let these AI systems find, parse, and trust your content in the first place.

Structured data gives AI systems an unambiguous, machine-readable summary of what a page is — an article, a product, a FAQ — instead of forcing them to guess from raw HTML.
Semantic HTML (real <h1>–<h3> headings, <article>, <nav>, proper list elements instead of div soup) makes it far easier for any crawler, AI or otherwise, to understand a page's structure and pull an accurate answer out of it.
Crawlable pages — no accidental noindex, no content trapped behind client-side-only rendering with nothing in the initial HTML — matter just as much to an AI crawler as to Googlebot. If a bot can't fetch it, it can't cite it.

The practical takeaway: none of this requires a separate "AI SEO" strategy. Everything in this checklist already does double duty — it's the same groundwork that gets a page indexed by Google, ranked well, and eligible to be cited by an AI assistant.

1. Crawlability & Indexing

Before Google can rank your page, it has to find it and be allowed to index it. This is the foundation — get it wrong and nothing else on this list matters.

Add a `robots.txt`

robots.txt tells search engine crawlers which parts of your site they're allowed to visit. In Next.js, you don't write raw text — you export a config from a special file.

// app/robots.ts
import { MetadataRoute } from "next";

export default function robots(): MetadataRoute.Robots {
  return {
    rules: {
      userAgent: "*",
      allow: "/",
      disallow: ["/admin", "/api"], // block anything that shouldn't be crawled
    },
    sitemap: "https://yourdomain.com/sitemap.xml",
  };
}

What's happening here: Next.js automatically generates a working /robots.txt route from this file. allow: "/" lets crawlers visit everything by default, while disallow blocks specific paths like admin dashboards or internal API routes that have no business being indexed.

⚠️ Common Mistake: Accidentally leaving disallow: "/" in a robots.txt after moving from staging to production. This single line blocks your entire site from every search engine — always double-check this file right after deploying.

Add a `sitemap.xml`

A sitemap is a map of every URL on your site that you want indexed. It doesn't force Google to index anything, but it makes discovery much faster — especially for new pages that have no other links pointing to them yet.

// app/sitemap.ts
import { MetadataRoute } from "next";
import { getAllPosts } from "@/lib/posts";

export default function sitemap(): MetadataRoute.Sitemap {
  const baseUrl = "https://yourdomain.com";

  const posts = getAllPosts().map((post) => ({
    url: `${baseUrl}/blog/${post.slug}`,
    lastModified: new Date(post.updatedAt || post.publishedAt),
    changeFrequency: "weekly" as const,
    priority: 0.8,
  }));

  const staticRoutes = ["", "/about", "/blog", "/contact"].map((route) => ({
    url: `${baseUrl}${route}`,
    lastModified: new Date(),
    changeFrequency: "monthly" as const,
    priority: route === "" ? 1 : 0.6,
  }));

  return [...staticRoutes, ...posts];
}

What's happening here: this generates every blog post URL dynamically from your data source, plus a handful of static pages, and outputs them at /sitemap.xml automatically. lastModified helps Google know when to re-crawl a page; priority is a soft hint about relative importance, not a guarantee.

💡 Tip: Submit your sitemap URL directly inside Google Search Console → Sitemaps after deploying. It won't guarantee faster indexing, but it removes any ambiguity about where your sitemap lives.

Check Your Robots Meta Tag

Even if robots.txt allows crawling, an individual page can still say "don't index me" via a meta tag. This matters most for things like thank-you pages, internal search results, or draft content.

// app/some-page/page.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  robots: {
    index: false, // don't show this page in search results
    follow: true, // but still crawl the links on it
  },
};

⚠️ Common Mistake: Setting index: false on your root layout "just to be safe" during development, then forgetting to remove it before launch. This is one of the most common reasons a brand-new site gets zero organic traffic — always verify your homepage's robots meta in production.

Verify With Google Search Console

Search Console is free and non-negotiable. It tells you, directly from Google, which pages are indexed, which are excluded (and why), and whether your sitemap was actually read. Set it up early — indexing issues are invisible until you check.

The single most-used feature here is the URL Inspection Tool. Paste any URL from your site into it and Google tells you exactly whether that page is indexed, when it was last crawled, and — if it's not indexed — why not. After a major change to a page (new metadata, fixed structured data, a rewritten intro), use it to request reindexing instead of waiting for Google to notice on its own.

💡 Tip: URL Inspection is also the fastest way to debug "why isn't my new blog post showing up in search" — it'll tell you plainly if it's still queued, blocked, or already indexed but just not ranking yet (which is a different problem).

Don't Forget Bing Webmaster Tools

Google isn't the only search engine worth indexing on. Bing powers Bing search itself, plus Yahoo, DuckDuckGo (partially), and is the underlying index behind Microsoft Copilot's web results — meaningful traffic that's easy to pick up for almost no extra work.

Sign up at Bing Webmaster Tools and verify your site
Submit the exact same sitemap.xml you already built for Google — no separate file needed
Bing also offers a URL Inspection-style tool and a URL Submission option for faster indexing of new pages

💡 Tip: Bing Webmaster Tools lets you import your verified site directly from Google Search Console in a couple of clicks, which skips most of the manual verification steps entirely.

2. Metadata: Titles, Descriptions & Canonical URLs

Metadata doesn't change how your page looks — it changes how search engines describe and rank it, and how it appears when shared.

Related: How to Add Metadata in Next.js 16 (2026 Beginner's Guide) covers the full Metadata API in more depth if you want a deeper dive after this section.

Set a Title Template Once, Not on Every Page

// app/layout.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  metadataBase: new URL("https://yourdomain.com"),
  title: {
    default: "YourSite — Tagline Here",
    template: "%s | YourSite",
  },
  description: "A clear, honest description of what your site does.",
};

What's happening here: metadataBase resolves every relative URL elsewhere in your metadata (like Open Graph images) into an absolute URL automatically. title.template means any page that sets title: "My Post" automatically renders as "My Post | YourSite" — you never repeat the suffix manually.

⚠️ Common Mistake: Manually typing "My Post | YourSite" as the title on individual pages while also having a template set in the root layout. This doubles the suffix into something like "My Post | YourSite | YourSite". Let the template do the work — pages should only set the unique part.

Write Unique Titles and Descriptions Per Page

// app/blog/[slug]/page.tsx
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { slug } = await params;
  const post = getPostBySlug(slug);

  return {
    title: post.title,
    description: post.description,
    alternates: {
      canonical: `https://yourdomain.com/blog/${post.slug}`,
    },
  };
}

Length guidelines to actually stick to:

Title: ~50–60 characters (roughly 580px) before Google truncates it
Description: ~150–160 characters — treat it as ad copy for your own page, not a summary

Canonical URLs

A canonical tag tells Google "this is the one true version of this page" when the same content is reachable through multiple URLs — with or without a trailing slash, with query params, or duplicated across categories.

export const metadata: Metadata = {
  alternates: {
    canonical: "https://yourdomain.com/blog/my-post",
  },
};

💡 Tip: Next.js already infers a canonical URL from your route and metadataBase in most cases. Set this explicitly only when you have genuine duplicate content — like a product reachable at two different category paths.

3. Structured Data (JSON-LD)

Structured data doesn't change what a page looks like to a human — it tells search engines and AI assistants explicitly what kind of content a page is: an article, a product, an FAQ, a business. This is what unlocks rich results like star ratings, breadcrumbs, and FAQ dropdowns directly in search listings.

// app/blog/[slug]/page.tsx
import Script from "next/script";

<Script
  id="blog-post-jsonld"
  type="application/ld+json"
  dangerouslySetInnerHTML={{
    __html: JSON.stringify({
      "@context": "https://schema.org",
      "@type": "BlogPosting",
      headline: post.title,
      description: post.description,
      datePublished: post.publishedAt,
      dateModified: post.updatedAt || post.publishedAt,
      author: { "@type": "Person", name: "Your Name" },
      publisher: {
        "@type": "Organization",
        name: "YourSite",
        url: "https://yourdomain.com",
      },
    }),
  }}
/>

What's happening here: this injects a <script type="application/ld+json"> block with zero visible UI impact. Google's crawler parses it separately from your rendered content to understand the page's structure.

⚠️ Common Mistake: Assuming valid JSON-LD automatically means eligible for rich results. Google layers its own required-field requirements on top of the schema.org spec — an Article missing an author, for instance, is valid JSON-LD that Google will still ignore for rich-result purposes. Always test with Google's Rich Results Test before assuming it's working.

Common types worth adding depending on your page:

Page type	Schema type
Blog post	`Article` / `BlogPosting`
FAQ section	`FAQPage`
Product page	`Product`
Local business	`LocalBusiness`
Software/SaaS tool	`SoftwareApplication`
Nav trail	`BreadcrumbList`

💡 Save time: use the JSON-LD Generator to generate any of these schema types with a live eligibility checklist scored against Google's actual Rich Results requirements, instead of hand-writing and second-guessing the JSON.

4. Open Graph & Twitter Cards

This is technically a "social sharing" feature, but it directly affects click-through rate from search and social — and CTR is a real ranking signal.

export const metadata: Metadata = {
  openGraph: {
    title: post.title,
    description: post.description,
    url: `https://yourdomain.com/blog/${post.slug}`,
    siteName: "YourSite",
    type: "article",
    images: [{ url: "/og-image.png", width: 1200, height: 630 }],
  },
  twitter: {
    card: "summary_large_image",
    title: post.title,
    description: post.description,
  },
};

💡 Tip: 1200×630px is the sweet spot for Open Graph images — smaller images get stretched and look blurry on most platforms. Reuse the same image for both openGraph and twitter unless you have a specific reason not to.

Not sure how Open Graph and Twitter Cards actually differ, or whether you need both? Open Graph vs Twitter Cards: What's the Difference? breaks down the exact syntax differences and when each one is read. And if you'd rather generate all of this instead of hand-writing it, the Meta Tag Generator outputs SEO tags, Open Graph, Twitter Cards, and JSON-LD from one set of inputs.

5. Core Web Vitals & Performance

Google explicitly uses Core Web Vitals as a ranking signal. These aren't vague "make it fast" advice — they're three specific, measurable metrics.

Metric	What it measures	Good threshold
LCP (Largest Contentful Paint)	How fast the main content loads	Under 2.5s
INP (Interaction to Next Paint)	How responsive the page feels to input	Under 200ms
CLS (Cumulative Layout Shift)	How much the layout jumps around while loading	Under 0.1

The Next.js-Specific Fixes That Matter Most

// Always use next/image instead of <img>
import Image from "next/image";

<Image
  src="/hero.jpg"
  alt="Descriptive alt text" // required — also helps SEO and accessibility
  width={1200}
  height={630}
  priority // only for above-the-fold images
/>

Why this matters: next/image automatically serves resized, modern-format (WebP/AVIF) images and reserves layout space before the image loads — directly improving both LCP and CLS. priority should only go on the one or two images visible without scrolling; overusing it defeats lazy loading for everything else.

// Load fonts through next/font to avoid layout shift
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"], display: "swap" });

Why this matters: next/font self-hosts Google Fonts at build time, eliminating the render-blocking network request to Google's font CDN and preventing the "flash of invisible/unstyled text" that causes layout shift.

⚠️ Common Mistake: Reserving no space for ads, embeds, or dynamically loaded content. Every element that pops in after initial render without a reserved size pushes content around — that's exactly what CLS measures.

Run Lighthouse (built into Chrome DevTools) for quick local lab data, but don't stop there — Google PageSpeed Insights runs the same Lighthouse audit and layers in real-user field data (from the Chrome User Experience Report) when enough traffic exists for your URL. That field data is what actually matters, since lab data and field data can disagree, and Google ranks based on the field data your real visitors generate — not your local Lighthouse score. Cross-check both there and in Search Console's Core Web Vitals report.

6. Mobile-Friendliness

Google indexes the mobile version of your site first (mobile-first indexing), not desktop. If your mobile layout is broken, that's the version Google evaluates for ranking — even for desktop searches.

Quick checklist:

Responsive layout at all breakpoints (test with Tailwind's sm:/md:/lg: prefixes actually rendering correctly)
Tap targets at least 44×44px
No horizontal scrolling
Text readable without zooming (16px minimum for body text)

💡 Tip: Test with Chrome DevTools' device toolbar set to an actual mid-range device profile, not just "responsive" mode dragged to a guess-width.

7. URL Structure & Internal Linking

Keep URLs Short, Readable, and Keyword-Relevant

Good:  /blog/nextjs-metadata-guide
Bad:   /blog/post?id=48291&ref=xyz

Next.js's file-based routing makes this almost automatic — just name your route folders and slugs sensibly.

Link Between Related Pages Deliberately

Internal links help Google understand which pages are related and pass authority between them. They also keep users (and crawlers) moving deeper into your site instead of bouncing after one page.

<p>
  Once auth is set up, check out our{" "}
  <Link href="/blog/stripe-checkout-guide">Stripe Checkout guide</Link> to
  add billing next.
</p>

⚠️ Common Mistake: Building tool pages or landing pages with almost no surrounding prose or internal links. Thin, isolated pages are exactly what tools like Google AdSense and Search Console's coverage report flag as low-value content — a page with substantial explanatory text and links to related pages reads as more legitimate to both crawlers and ad review systems.

8. HTTPS & Basic Security

This one's usually already handled if you're on Vercel, Netlify, or similar — but confirm it:

Every page loads over https://, with no mixed-content warnings (images/scripts loaded over plain http://)
www vs non-www redirects to one canonical version, not both serving live content
No broken SSL certificate warnings

HTTPS has been a confirmed Google ranking signal since 2014 — it's small, but it's free, so there's no reason to skip it.

9. Content Quality & Thin Content

Technical SEO gets your page crawled and indexed. It does not make a page worth ranking if there's nothing substantial on it. This matters especially for:

Tool pages (calculators, generators) — pair the actual tool with real explanatory prose about what it does and why it matters, not just a bare form
Category/index pages — a list of links with zero context reads as thin to both search engines and human reviewers
Duplicate boilerplate — if ten pages share 90% identical copy with one variable swapped, consolidate or genuinely differentiate them

💡 Tip: A useful gut check: if you deleted the interactive/dynamic part of a page, would there still be a paragraph or two of genuinely useful content left? If not, that page is a thin-content risk.

The Full Checklist at a Glance

[ ] robots.txt exists and isn't accidentally blocking the whole site
[ ] sitemap.xml exists and is submitted in Search Console
[ ] No unintended noindex on pages that should rank
[ ] Site verified and sitemap submitted in Bing Webmaster Tools too
[ ] Every page has a unique title (50–60 chars) and description (150–160 chars)
[ ] Canonical URLs set where duplicate content is possible
[ ] JSON-LD structured data added for articles, FAQs, products, or business info
[ ] Open Graph + Twitter Card tags on every shareable page
[ ] Images use next/image with descriptive alt text
[ ] Fonts loaded through next/font
[ ] Core Web Vitals checked in Search Console (not just Lighthouse locally)
[ ] Mobile layout tested on a real device profile
[ ] URLs are short, readable, and keyword-relevant
[ ] Related pages link to each other with real anchor context
[ ] Site is fully on HTTPS with no mixed content
[ ] No thin, boilerplate-only, or near-duplicate pages

Frequently Asked Questions

How long does it take for technical SEO changes to affect rankings?

Indexing changes (like fixing robots.txt) can show up in days. Ranking changes from Core Web Vitals or content improvements typically take weeks, since Google needs to re-crawl and re-evaluate the page relative to competitors.

Do I need a sitemap if my site is small?

Technically no — Google can discover a handful of linked pages without one. But it costs almost nothing to add and removes any doubt about discovery, so there's no real reason to skip it even on small sites.

Is Core Web Vitals a huge ranking factor?

It's one signal among many, and generally a tiebreaker rather than a dominant factor — strong content with mediocre performance usually still outranks weak content with perfect performance. That said, "mediocre" has a floor; genuinely poor Core Web Vitals can hold a page back.

Can I check all of this without Google Search Console?

Not fully. Lighthouse and third-party tools give you lab data, but Search Console gives you real user field data and actual indexing status — which is what Google uses for ranking decisions. It's free and essential, not optional.

Does technical SEO matter if I'm not writing much content yet?

Yes — technical SEO is largely a one-time setup cost (metadata patterns, sitemap, structured data templates) that pays off on every future page automatically. It's far easier to build it into your app's foundation now than to retrofit dozens of pages later.

Wrapping Up

Technical SEO isn't a mysterious marketing skill — it's a checklist of implementation details that a developer is uniquely positioned to get right: correct metadata exports, a real sitemap, valid structured data, and a page that actually loads fast. Get the foundation right once in your layout.tsx, sitemap, and robots files, and every page you ship afterward inherits it for free.

From here, a natural next step is auditing your existing pages against the checklist above one by one, starting with your highest-traffic pages first — small technical fixes there tend to move the needle fastest.

Useful Resources

How to Add Metadata in Next.js 16 (2026 Beginner's Guide)

Syed Muhammad Ali — Sun, 19 Jul 2026 19:00:00 +0000

You've built your Next.js app, it looks great, it works great — and then you share the link on Twitter or Slack and it shows up as a bare, ugly URL with no title, no image, nothing. Or worse, Google indexes your page with a title that just says "Home."

That's what happens when metadata is an afterthought. The good news: Next.js 16's App Router has a built-in, type-safe way to handle all of this — no next/head, no manual <meta> tag juggling. In this guide, you'll learn exactly how metadata works in the App Router, how to set it per-page, how to make it dynamic for things like blog posts, and the mistakes that trip up almost everyone the first time.

Why Metadata Matters

Metadata is the stuff that doesn't show up on your page, but controls how it's represented everywhere else:

The tab title and description in search results
The preview card when someone shares your link on X, LinkedIn, or Discord
Whether search engines are even allowed to index the page

Skip it, and your app might work perfectly for people already on it, while being invisible or unappealing to everyone who hasn't found it yet.

The Old Way vs the App Router Way

If you've used the Pages Router before, you probably reached for next/head and manually wrote <meta> tags inside a <Head> component. The App Router replaces this entirely with a Metadata API — you export a plain object (or a function) from your page or layout file, and Next.js generates all the right tags for you at build or request time, including merging metadata from parent layouts.

💡 Tip: You never import anything for basic metadata — no next/head, no <Head> component. Just export metadata (or generateMetadata) from the file.

Step 1: Static Metadata on a Page

For a page with fixed content — an About page, a Contact page — export a metadata object directly:

// app/about/page.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "About Us",
  description: "Learn more about our team and what we build.",
};

export default function AboutPage() {
  return <h1>About Us</h1>;
}

What's happening here: Next.js scans your app directory at build time, finds this exported metadata object, and injects the corresponding <title> and <meta name="description"> tags into the <head> automatically. No manual DOM manipulation, no client-side JavaScript needed.

Step 2: Metadata in the Root Layout (Site-Wide Defaults)

Your root layout.tsx is the place to set defaults that apply across the whole site — things like your site name and a fallback description.

// app/layout.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  metadataBase: new URL("https://example.com"),
  title: {
    default: "DevStacked",
    template: "%s | DevStacked",
  },
  description: "Practical Next.js, React, and Supabase tutorials.",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Understanding title.template: this is one of the most useful (and most missed) features. Once you set a template in the root layout, any page that sets its own title gets automatically wrapped in that pattern.

So if a blog post page sets:

export const metadata: Metadata = {
  title: "Stripe Checkout Guide",
};

The actual rendered <title> becomes "Stripe Checkout Guide | DevStacked" — you never have to type "| DevStacked" on every single page.

⚠️ Common Mistake: Setting a full title like "Stripe Checkout Guide | DevStacked" on every page manually. If you've set a template in the root layout, this doubles up or looks inconsistent. Let the template do the work — just set the page-specific part.

What Does `metadataBase` Do?

Notice the metadataBase field above. Any relative URL you use elsewhere in your metadata — an openGraph.images path, a canonical URL — gets resolved against this base automatically. Without it, Next.js falls back to http://localhost:3000 in development and can log a warning in production, or worse, ship a broken relative URL to a social platform that needs an absolute one.

export const metadata: Metadata = {
  metadataBase: new URL("https://devstacked.tech"),
  openGraph: {
    images: ["/og/cover.png"], // resolves to https://devstacked.tech/og/cover.png
  },
};

Set it once, in the root layout, and every nested page and layout can use short relative paths instead of repeating the full domain everywhere.

Metadata Inheritance

Metadata in the App Router isn't isolated per file — it's merged down the layout tree. A field set in app/layout.tsx applies to every page unless a more specific layout.tsx or page.tsx overrides it. So app/blog/layout.tsx could add a shared openGraph.siteName, and each app/blog/[slug]/page.tsx only needs to set the fields that actually change per post, like title and description.

The merge is shallow per key, not a deep object merge — if a page sets its own openGraph object, that whole object replaces the parent's openGraph, it doesn't merge field-by-field inside it. Keep that in mind if a nested page's Open Graph tags seem to be missing fields you set higher up.

Example:

// layout.tsx

openGraph: {
  siteName: "DevStacked",
  images: [...]
}

// page.tsx
openGraph: {
  title: "Stripe Guide"
}

Result? People often expect:

siteName
+
images
+
title

But actually

openGraph
↓
entire object replaced

Step 3: Dynamic Metadata with `generateMetadata`

Static objects work fine when you already know the content. But what about a blog post page at /blog/[slug] — the title and description depend on which post is being viewed, and that's only known at request time. For this, Next.js gives you generateMetadata, an async function that runs before the page renders.

// app/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { getPostBySlug } from "@/lib/posts";
import { notFound } from "next/navigation";

interface Props {
  params: Promise<{ slug: string }>;
}

export async function generateMetadata({
  params,
}: Props): Promise<Metadata> {
  const { slug } = await params;
  const post = getPostBySlug(slug);

  if (!post) {
    notFound();
  }

  return {
    title: post.title,
    description: post.description,
  };
}

export default async function BlogPostPage({ params }: Props) {
  const { slug } = await params;
  const post = getPostBySlug(slug);

  return <article>{/* ... */}</article>;
}

Why this matters: generateMetadata runs on the server, separately from your page component, and Next.js waits for it to resolve before streaming the <head> to the browser — so search engines and social crawlers always see the correct, post-specific title and description, not a generic fallback.

⚠️ Common Mistake: Forgetting params is a Promise in Next.js 16. Just like inside the page component itself, you must await params before reading slug — reading it directly (params.slug) will throw a type error or return undefined.

Step 4: Open Graph Tags (Rich Link Previews)

Open Graph tags control how your link looks when shared on LinkedIn, Slack, Discord, or Facebook — the title, description, and preview image shown in the card.

export const metadata: Metadata = {
  title: "Stripe Checkout Guide",
  description: "Learn how to integrate Stripe Checkout with Next.js 16.",
  openGraph: {
    title: "Stripe Checkout Guide",
    description: "Learn how to integrate Stripe Checkout with Next.js 16.",
    url: "https://example.com/blog/stripe-checkout-guide",
    siteName: "DevStacked",
    images: [
      {
        url: "https://example.com/og/stripe-checkout.png",
        width: 1200,
        height: 630,
        alt: "Stripe Checkout Guide",
      },
    ],
    type: "article",
  },
};

Why a separate openGraph object instead of reusing title/description? Because you often want slightly different copy for a social preview card versus a search result snippet — a social card benefits from being punchier, while a search description often needs to match user search intent more literally. Next.js lets you diverge, but falls back to the top-level title/description if you don't specify openGraph values.

💡 Tip: The recommended Open Graph image size is 1200×630px. Anything smaller gets stretched and looks blurry on most platforms.

Step 5: Twitter Card Tags

X (formerly Twitter) can technically fall back to your Open Graph tags, but adding explicit Twitter Card metadata gives you more reliable control:

export const metadata: Metadata = {
  twitter: {
    card: "summary_large_image",
    title: "Stripe Checkout Guide",
    description: "Learn how to integrate Stripe Checkout with Next.js 16.",
    images: ["https://example.com/og/stripe-checkout.png"],
  },
};

card: "summary_large_image" is what you want almost every time — it renders a large, prominent image above the title and description, instead of a small square thumbnail next to the text.

Step 6: Generating Open Graph Images Dynamically

Instead of designing a static OG image for every single blog post, Next.js lets you generate one on the fly using next/og. Drop a special file named opengraph-image.tsx right next to your page.tsx:

// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from "next/og";

export const runtime = "edge";
export const alt = "Blog Post Preview";
export const size = { width: 1200, height: 630 };
export const contentType = "image/png";

export default async function Image({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const title = slug.replace(/-/g, " ");

  return new ImageResponse(
    (
      <div
        style={{
          height: "100%",
          width: "100%",
          display: "flex",
          alignItems: "center",
          justifyContent: "center",
          backgroundColor: "white",
          fontSize: 64,
          fontWeight: 700,
          textTransform: "capitalize",
        }}
      >
        {title}
      </div>
    ),
    { ...size }
  );
}

What's happening here: Next.js automatically detects this file, renders the JSX into a PNG using the Edge Runtime, and serves it at a route matching the page — then automatically wires it up as the og:image for that page. No manual linking required.

💡 Tip: runtime = "edge" matters here — image generation is CPU-light but benefits from edge deployment for fast, globally distributed rendering.

Step 7: Canonical URLs and Robots

Two smaller but important fields:

export const metadata: Metadata = {
  alternates: {
    canonical: "https://example.com/blog/stripe-checkout-guide",
  },
  robots: {
    index: true,
    follow: true,
  },
};

Canonical URLs tell search engines "this is the one true version of this page" — useful if the same content is reachable through multiple URLs (with/without trailing slash, query params, etc.), so you don't get penalized for duplicate content.

💡 Tip: Next.js already auto-generates a canonical URL for a page based on its route and your metadataBase, so in many straightforward cases you don't have to set alternates.canonical at all. Setting a custom value matters when you have genuine duplicate content — the same product reachable at two different URLs, paginated pages that should all canonicalize back to page 1, or a query-string variant of a page that shouldn't be indexed separately.

Robots controls whether search engines should index the page at all. Set index: false for things like admin pages, thank-you pages, or draft content you don't want showing up in search results.

Step 8: File-Based Metadata

Not all metadata comes from a metadata object or generateMetadata function. Next.js also supports file-based metadata — special file names inside your app folder that Next.js automatically detects and turns into the correct tags, no export required:

File	What it generates
`favicon.ico`	The browser tab icon
`icon.tsx` / `icon.png`	App icons (including dynamically generated ones via `next/og`)
`apple-icon.png`	Icon used on iOS home screens
`opengraph-image.tsx` / `.png`	The `og:image` tag, as shown in Step 6
`twitter-image.tsx` / `.png`	The Twitter Card image, if different from Open Graph
`sitemap.ts`	Your `sitemap.xml`
`robots.ts`	Your `robots.txt`

Just like opengraph-image.tsx, you can drop any of these next to a page.tsx to scope them to that route, or in the root app folder for site-wide defaults. Next.js wires up the correct <link> or <meta> tag automatically — you never manually reference these files anywhere else in your code.

Frequently Asked Questions

Do I need `generateMetadata` for every page?

No — only for pages where the metadata depends on data you don't know until request time (a slug, a database lookup, etc.). Static pages like About or Contact should just export a plain metadata object; it's simpler and doesn't need to run on every request.

What happens if I set metadata in both the layout and the page?

Next.js merges them, with the page's metadata taking priority for overlapping fields. Non-overlapping fields (like a description only set in the layout) still apply. This is what lets title.template work — the layout sets the pattern, the page sets the specific title.

Can I use `generateMetadata` and `generateStaticParams` together?

Yes, and you should for statically generated dynamic routes. generateStaticParams tells Next.js which slugs exist at build time; generateMetadata runs for each of those and produces the right metadata per page — both commonly pull from the same data source.

Why isn't my Open Graph image showing up when I share the link?

Most likely the image URL isn't absolute, or the platform cached an old preview. Always use a full https:// URL in openGraph.images, and if you're testing, use each platform's own debugger tool (like Facebook's Sharing Debugger) to force a re-scrape.

Does metadata affect Core Web Vitals or performance?

No — metadata is just <head> tags, not render-blocking scripts or styles. generateMetadata running on the server also doesn't block your page's own data fetching, since Next.js can run them in parallel.

Why isn't Google showing my description?

Google often rewrites meta descriptions if it thinks another page excerpt better matches the user's search query.

What's the ideal title length?

Aim for roughly 50–60 characters (or about 580–600 pixels) so titles are less likely to be truncated in search results.

Wrapping Up

Next.js 16's Metadata API takes what used to be manual, error-prone <head> management and turns it into a small, typed export at the top of your file. Static pages get a plain object, dynamic pages get generateMetadata, and layouts let you set sensible defaults once instead of repeating them everywhere.

From here, a natural next step is wiring up JSON-LD structured data for rich search results, or building out per-post dynamic OG images across your whole blog if you haven't already.

💡 Save time: Use our Meta Tag Generator to instantly generate a complete Metadata object, Open Graph tags, Twitter Cards, and JSON-LD for any page — fill in a page's title, description, URL, and image once, and it outputs both raw HTML <meta> tags and a ready-to-paste Next.js Metadata object.

Useful Resources

Continue Learning

Open Graph vs Twitter Cards: What's the Difference? (2026 Guide)

Syed Muhammad Ali — Sun, 19 Jul 2026 05:41:09 +0000

You share a link on Slack, and it shows up as a beautiful card with a title, description, and image. You share a link on X, and it shows up... as bare text. Same website, two totally different results. What's going on?

The short answer: those preview cards aren't magic, and they're not one single system. They're powered by two separate sets of meta tags — Open Graph and Twitter Cards — and if you only add one of them, some platforms simply won't know what to show.

By the end of this guide, you'll know exactly what each one does, how they're different, when you actually need both, and how to add them correctly in a Next.js 16 App Router project.

Why This Confuses Almost Everyone

Here's the thing that trips people up: Open Graph and Twitter Cards look almost identical. Both control a title, a description, and an image. Both live in your page's <head>. Both were designed for the exact same job — making a shared link look good.

So why do we need two of them?

Because they were built by two different companies, at two different times, for two different platforms — and neither one fully committed to just using the other's format.

Open Graph vs Twitter Cards: The Real Differences

	Open Graph	Twitter Cards
Created by	Facebook	Twitter (now X)
Attribute used	`property`	`name`
Prefix	`og:`	`twitter:`
Used by	Facebook, LinkedIn, Slack, Discord, WhatsApp, and most others	X (Twitter)
Controls layout?	Not really — mostly fixed	Yes, via `twitter:card`
Required if you already have OG tags?	—	Technically no, X can fall back to OG — but see below

Does X Really Fall Back to Open Graph?

Yes, X can fall back to Open Graph tags for several fields, but relying on the fallback means you can't explicitly control twitter:card, so providing Twitter Card tags is still recommended.

⚠️ Common Mistake: Assuming "X reads Open Graph tags anyway, so I don't need Twitter tags." Technically true for basic fields, but you'll usually get a worse-looking card. If X previews matter for your traffic, add both.

What Is Open Graph?

Open Graph (often shortened to "OG") is a protocol created by Facebook in 2010. It defines a set of <meta> tags that tell any platform reading your page: "here's the title, description, image, and type of content this page represents."

<meta property="og:title" content="Stripe Checkout Guide" />
<meta property="og:description" content="Learn how to integrate Stripe Checkout with Next.js 16." />
<meta property="og:image" content="https://example.com/og-image.png" />
<meta property="og:url" content="https://example.com/blog/stripe-checkout-guide" />
<meta property="og:type" content="article" />

💡 Tip: Notice the tags use property, not name, for the attribute. That's an Open Graph convention — it's part of the original protocol spec, not a typo you'll see in other meta tags.

Open Graph became the industry default. Facebook, LinkedIn, Slack, Discord, WhatsApp, and dozens of other platforms all read Open Graph tags to build their link preview cards. If you only add one type of meta tag to your site, this is the one to add — it covers the widest range of platforms.

What Are Twitter Cards?

Twitter Cards (still called that even though the platform is now X) are a separate set of meta tags created by Twitter, also released around 2010–2012, specifically for how links preview inside tweets.

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Stripe Checkout Guide" />
<meta name="twitter:description" content="Learn how to integrate Stripe Checkout with Next.js 16." />
<meta name="twitter:image" content="https://example.com/twitter-image.png" />

💡 Tip: Unlike Open Graph, Twitter Card tags use the standard name attribute — this is one of the small syntax differences that catches people copy-pasting between the two.

The one genuinely unique piece here is twitter:card, which controls the layout of the preview:

Value	What it does
`summary`	Small square image, text beside it
`summary_large_image`	Large image above the title and description (the one you want almost every time)
`player`	Embeds video/audio directly in the tweet
`app`	Links to a mobile app store listing

Adding Both in Next.js 16

Next.js's App Router Metadata API handles both tag types through one typed object — no manual <meta> tags needed.

// app/blog/[slug]/page.tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Stripe Checkout Guide",
  description: "Learn how to integrate Stripe Checkout with Next.js 16.",

  openGraph: {
    title: "Stripe Checkout Guide",
    description: "Learn how to integrate Stripe Checkout with Next.js 16.",
    url: "https://example.com/blog/stripe-checkout-guide",
    siteName: "DevStacked",
    type: "article",
    images: [
      {
        url: "https://example.com/og-image.png",
        width: 1200,
        height: 630,
        alt: "Stripe Checkout Guide",
      },
    ],
  },

  twitter: {
    card: "summary_large_image",
    title: "Stripe Checkout Guide",
    description: "Learn how to integrate Stripe Checkout with Next.js 16.",
    images: ["https://example.com/og-image.png"],
  },
};

What's happening here: the openGraph object generates every og:* tag, and the twitter object generates every twitter:* tag — Next.js writes the correct property or name attributes for you under the hood. You're writing one object; Next.js is producing two separate tag sets.

💡 Tip: You can reuse the same image for both. There's no rule requiring separate images — most sites use one 1200×630px image for both og:image and twitter:image.

Can I Skip the Twitter Object Entirely?

If you set openGraph but skip twitter, Next.js does not automatically duplicate your OG tags into Twitter tags — it just omits twitter:* tags from the page entirely, relying on X's own (imperfect) fallback behavior described above.

// This works, but X's preview may not use the large-image layout
export const metadata: Metadata = {
  openGraph: {
    title: "My Post",
    images: ["/og-image.png"],
  },
  // no twitter object — X falls back to og: tags, but loses twitter:card
};

If you want a guaranteed summary_large_image layout on X, always set the twitter object explicitly.

Image Size: One Size Fits (Almost) Both

Both formats recommend the same dimensions, which is why one image usually works everywhere:

Recommended size: 1200×630px
Aspect ratio: roughly 1.91:1
Format: PNG or JPEG, keep it under ~5MB

⚠️ Common Mistake: Using a square logo as your og/twitter image. It gets stretched or cropped awkwardly on most platforms — build a proper wide banner image instead, even a simple one with your title text on a solid background.

Frequently Asked Questions

If I only have time to add one, which should I pick?

Open Graph. It covers Facebook, LinkedIn, Slack, Discord, WhatsApp, and (partially) X. Twitter Cards only improve the experience on one platform — X — but that improvement (the large image layout) is significant enough to add both if you can.

Does Google use Open Graph or Twitter Cards for search results?

Neither, directly. Google Search mostly relies on your page's <title>, meta description, and structured data (JSON-LD) — not OG or Twitter tags. OG/Twitter tags are purely for social link-preview cards, not search rankings or snippets.

Why isn't my preview updating after I changed the image?

Almost every platform caches link previews aggressively. Facebook has a Sharing Debugger to force a re-scrape, and X's card validator works similarly — always test with these tools instead of just re-sharing the link and hoping.

Do I need `og:type` set to something other than "website"?

Only if you want to be precise. article is common for blog posts, product for e-commerce pages, video.other for video content. Most platforms treat website as a safe default and won't visibly change your card's appearance.

Can I test my tags without actually posting them?

Yes — use Facebook's Sharing Debugger for Open Graph and Twitter's Card Validator for Twitter Cards. Both let you paste a URL and preview exactly how the card will render before you share it anywhere.

Wrapping Up

Open Graph and Twitter Cards solve the same problem — making your links look good when shared — but they're two separate protocols from two separate companies, with slightly different syntax and slightly different platform support. The safest move is simple: always set both openGraph and twitter in your Next.js metadata, reuse one well-sized image for both, and test with each platform's debugger before you trust it in production.

From here, a natural next step is wiring up JSON-LD structured data for richer search results, or generating dynamic OG images per page with next/og if you haven't already.

If you're new to metadata, first read How to Add Metadata in Next.js 16 (2026 Beginner's Guide).

💡 Save time: use the Meta Tag Generator to generate both Open Graph and Twitter Card tags — plus canonical URLs and JSON-LD — from one set of inputs, in both raw HTML and Next.js Metadata API format.

Useful Resources

Continue Learning

How to Build Usage-Based Billing with Stripe (2026 Guide)

Syed Muhammad Ali — Sat, 11 Jul 2026 09:17:54 +0000

Flat monthly pricing works great until it doesn't. If you're building an AI tool, an API product, or anything where one customer might use 10x more than another, charging everyone the same $29/month either underprices your power users or overprices your casual ones. That's exactly the problem usage-based billing solves — customers pay for what they actually use.

The tricky part? Stripe changed how this works. If you've searched "Stripe usage-based billing" and found tutorials using usage_type: 'metered' with createUsageRecord(), that API is deprecated. Since Stripe API version 2025-03-31.basil, every metered price needs a backing Meter object instead.

In this guide, you'll learn how to build usage-based billing with Stripe's current Meters API in a Next.js 16 app — from creating your first meter to sending usage events and letting Stripe handle the invoicing automatically.

Why Usage-Based Billing Is Tricky

The confusing part isn't the concept — it's that Stripe has three different usage-based billing systems depending on when you read the docs:

Legacy usage records (subscriptionItems.createUsageRecord) — deprecated, don't use this anymore
Meters API — the current, stable, GA approach for straightforward metered billing (what this guide covers)
Advanced usage-based billing (pricing plans) — a newer preview system for complex hybrid pricing with credits and multiple usage dimensions, aimed at larger AI/SaaS platforms

For most beginners adding "pay for what you use" pricing to a SaaS product, the Meters API is the right tool. It's simpler, it's stable, and it covers the vast majority of real use cases: API calls, AI tokens, storage, emails sent, whatever unit your product bills on.

💡 Tip: One genuinely useful change with Meters — you don't need a subscription to exist before recording usage. You can track usage during a free trial and attach the customer to a subscription later.

             User
              │
              ▼
        Makes API Call
              │
              ▼
         Your Server
              │
              ▼
stripe.billing.meterEvents.create()
              │
              ▼
        Stripe Meter
              │
              ▼
      Aggregates Usage
              │
              ▼
        Subscription
              │
              ▼
        End of Month
              │
              ▼
           Invoice

What You'll Need

This guide uses:

Next.js 16 with the App Router
TypeScript in strict mode
Stripe Node SDK (latest version)
A Stripe account in test mode

We'll build a simple example: an app that charges $0.01 per API call, with the first 100 calls free each month.

Step 1: Install Stripe

npm install stripe

Create a reusable Stripe client:

// src/lib/stripe.ts
import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2026-06-24.dahlia",
});

⚠️ Common Mistake: Never import this file into a Client Component. The secret key must stay server-side only — treat it the same way you'd treat a database password.

Add your keys to .env.local:

STRIPE_SECRET_KEY=sk_test_xxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxx
NEXT_PUBLIC_APP_URL=http://localhost:3000

Step 2: Understand the Four Building Blocks

Before writing code, it helps to know what each Stripe object actually does — this is where most beginners get lost.

Meter — defines what you're tracking and how to add it up (sum, count, or last value). Think of it as a labeled counter.
Price — attaches to a Meter and sets the cost per unit (e.g. $0.01 per event).
Subscription — links a customer to that Price, so Stripe knows to bill them for it.
Meter Event — the raw usage data you send to Stripe every time something billable happens (e.g. "customer X made 1 API call").

Here's how they connect:

Meter (tracks "api_calls")
   ↓
Price ($0.01 per unit, references the Meter)
   ↓
Subscription (customer subscribed to that Price)
   ↓
Meter Events (you send these as usage happens)
   ↓
Stripe aggregates → generates invoice at period end

Example SaaS Pricing

Suppose you're building an AI writing application.

First 100 prompts free
$0.02 per prompt afterwards
Monthly billing cycle

Each prompt sends

await stripe.billing.meterEvents.create(...)

Stripe counts every prompt and invoices the customer automatically at the end of the month.

Step 3: Create a Stripe Meter

You only need to create a Meter once for each type of billable usage (for example, API calls, AI tokens, or storage), either in the Stripe Dashboard or via the API. Let's use the API so it's repeatable:

// scripts/create-meter.ts
import { stripe } from "@/lib/stripe";

async function createMeter() {
  const meter = await stripe.billing.meters.create({
    display_name: "API Calls",
    event_name: "api_call", // you'll use this exact name when sending events
    default_aggregation: {
      formula: "sum", // add up every event's value during the billing period
    },
    customer_mapping: {
      type: "by_id",
      event_payload_key: "stripe_customer_id",
    },
    value_settings: {
      event_payload_key: "value",
    },
  });

  console.log("Meter created:", meter.id);
}

createMeter();

What's happening here:

event_name: "api_call" is the label you'll reference every time you record usage — it must match exactly.
default_aggregation.formula: "sum" tells Stripe to add up every event's value during the billing period. Meters support sum, count, and last — pick sum for most metered billing (API calls, tokens, storage GB), count when every event is worth exactly 1 unit, and last for snapshot-style metrics (like "current number of seats").
customer_mapping tells Stripe which field in your event payload identifies the customer.

Run it once with npx tsx scripts/create-meter.ts and save the returned meter ID — you'll need it in the next step.

Step 4: Create a Stripe Metered Price

Now attach a Price to that Meter:

// scripts/create-price.ts
import { stripe } from "@/lib/stripe";

async function createPrice() {
  const product = await stripe.products.create({
    name: "API Usage",
  });

  const price = await stripe.prices.create({
    currency: "usd",
    product: product.id,
    billing_scheme: "per_unit",
    unit_amount_decimal: "1", // 1 cent per API call
    recurring: {
      interval: "month",
      usage_type: "metered",
      meter: "mtr_xxxxx", // the meter ID from Step 3
    },
  });

  console.log("Price created:", price.id);
}

createPrice();

💡 Tip: Want the first 100 calls free every month? Use billing_scheme: "tiered" with tiers_mode: "graduated" instead of per_unit, and set the first tier's up_to to 100 with unit_amount: 0.

const price = await stripe.prices.create({
  currency: "usd",
  product: product.id,
  billing_scheme: "tiered",
  tiers_mode: "graduated",
  tiers: [
    { up_to: 100, unit_amount: 0 },       // first 100 calls free
    { up_to: "inf", unit_amount_decimal: "1" }, // then 1 cent each
  ],
  recurring: {
    interval: "month",
    usage_type: "metered",
    meter: "mtr_xxxxx",
  },
});

Save this price ID as STRIPE_METERED_PRICE_ID in your .env.local.

Step 5: Create a Stripe Subscription for Metered Billing

When a user signs up, create a Stripe customer and subscribe them:

// src/actions/create-subscription.ts
"use server";

import { stripe } from "@/lib/stripe";

export async function createMeteredSubscription(email: string) {
  const customer = await stripe.customers.create({ email });

  const subscription = await stripe.subscriptions.create({
    customer: customer.id,
    items: [{ price: process.env.STRIPE_METERED_PRICE_ID! }],
    payment_behavior: "default_incomplete",
    payment_settings: { save_default_payment_method: "on_subscription" },
  });

  // TODO: save customer.id and subscription.id against your user in your database

  return { customerId: customer.id, subscriptionId: subscription.id };
}

What's happening here: unlike one-time payments, you don't specify a quantity upfront — the metered price has no fixed amount because you haven't reported usage yet. Stripe will calculate the invoice total at the end of the billing period based on the events you send.

⚠️ Common Mistake: Forgetting to store customer.id in your own database. You'll need it every time you send a usage event, so save it right after creating the customer — don't rely on looking it up from Stripe later.

Step 6: Record Usage with Meter Events

This is the core of usage-based billing — every time your customer does something billable, send an event:

// src/lib/record-usage.ts
import { stripe } from "@/lib/stripe";

export async function recordApiCall(stripeCustomerId: string, quantity = 1) {
  await stripe.billing.meterEvents.create({
    event_name: "api_call",
    payload: {
      stripe_customer_id: stripeCustomerId,
      value: quantity.toString(),
    },
  });
}

Then call it wherever the billable action happens — for example, inside an API route:

// src/app/api/generate/route.ts
import { NextResponse } from "next/server";
import { recordApiCall } from "@/lib/record-usage";

export async function POST(req: Request) {
  const { stripeCustomerId } = await req.json();

  // ... do the actual work (call an AI model, process a file, etc.) ...

  // Report 1 unit of usage to Stripe
  await recordApiCall(stripeCustomerId);

  return NextResponse.json({ success: true });
}

What's happening here: event_name must match the meter's event_name from Step 3 exactly, or Stripe won't know which meter to attribute this to. Every event is timestamped automatically, and Stripe aggregates them in the background — you don't need to do any math yourself.

⚠️ Common Mistake: Sending a meter event before the customer's subscription exists doesn't fail — Stripe accepts it and attributes it to the customer. But if that customer never gets subscribed to a metered price, the usage just sits there unbilled. Always double-check your signup flow actually creates the subscription.

💡 Production Tip: Only report usage after the billable action succeeds. For example, if an AI request fails or an API call returns an error before completing, don't send a meter event. Otherwise customers could be billed for work that never happened.

Step 7: Handle Webhooks for Invoicing

Stripe automatically generates an invoice at the end of each billing period based on aggregated usage. You still need webhooks to know when that happens and keep your app in sync:

// src/app/api/webhook/route.ts
import { NextResponse } from "next/server";
import { headers } from "next/headers";
import Stripe from "stripe";
import { stripe } from "@/lib/stripe";

const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(req: Request) {
  const payload = await req.text();
  const sig = (await headers()).get("stripe-signature")!;

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(payload, sig, endpointSecret);
  } catch (err) {
    const message = err instanceof Error ? err.message : "Unknown error";
    return NextResponse.json({ error: `Webhook Error: ${message}` }, { status: 400 });
  }

  switch (event.type) {
    case "invoice.created": {
      const invoice = event.data.object as Stripe.Invoice;
      console.log("Usage invoice generated:", invoice.id, invoice.amount_due);
      // TODO: notify the customer, or flag it for review before auto-finalizing
      break;
    }

    case "invoice.paid": {
      const invoice = event.data.object as Stripe.Invoice;
      console.log("Usage invoice paid:", invoice.id);
      // TODO: mark the billing period as settled in your database
      break;
    }

    case "invoice.payment_failed": {
      const invoice = event.data.object as Stripe.Invoice;
      console.log("Usage invoice payment failed:", invoice.id);
      // TODO: notify the customer, restrict access if needed
      break;
    }
  }

  return NextResponse.json({ received: true }, { status: 200 });
}

Why req.text() instead of req.json()? Stripe's signature verification needs the raw, unparsed request body. Parsing it first breaks the signature check.

Step 8: Test Usage-Based Billing Locally

Use the Stripe CLI to forward webhooks and simulate the billing cycle:

stripe listen --forward-to localhost:3000/api/webhook

Send a test meter event directly with the CLI:

stripe billing meter_events create \
  --event-name=api_call \
  --payload stripe_customer_id=cus_xxxx \
  --payload value=1

To see how the invoice looks without waiting a full month, use a test clock — it lets you fast-forward time in test mode so you can preview an end-of-period invoice in minutes instead of weeks.

💡 Tip: Always test with stripe listen running in a separate terminal tab. If your webhook handler isn't receiving events, 90% of the time it's because this command isn't running.

Common Metered Billing Patterns

A few real-world pricing shapes you can build on top of what we've covered:

Pure pay-as-you-go — no free tier, unit_amount per event (what we built above with per_unit)
Free tier + overage — first N units free, then a per-unit charge (the tiered example above)
Hybrid subscription — a flat monthly base fee (a normal recurring Price) plus a metered Price as a second subscription item, so customers pay a base amount and usage on top

For hybrid pricing, just add both prices to the same subscription:

const subscription = await stripe.subscriptions.create({
  customer: customer.id,
  items: [
    { price: "price_flat_base_fee" },   // e.g. $29/month base
    { price: "price_metered_overage" }, // usage-based on top
  ],
});

Frequently Asked Questions

Do I need a subscription before I can record usage?

No. Meter events are attributed to a customer as soon as you send them, even before a subscription exists. This is useful for tracking free-trial usage before a customer converts to paid.

Can I bill multiple products on separate meters?

Yes. Create a separate Meter and Price for each usage type (e.g. api_calls and storage_gb), then attach both prices to the customer's subscription as separate items.

What's the difference between `sum`, `count`, and `last` aggregation?

sum adds up every event's value — use this for things like tokens or API calls where each event carries a quantity. count treats every event as worth 1, regardless of payload. last only keeps the most recent value in the period — useful for snapshot metrics like "current active seats."

What happens if I accidentally send duplicate meter events?

Stripe bills exactly what you report — it won't automatically detect or filter out duplicate events for you. If your server retries a failed request and ends up sending the same usage event twice, that customer gets billed twice for the same action. To avoid this, use idempotency keys when calling meterEvents.create(), and make sure your application logic only records a usage event once per successful billable action, not once per attempt.

Does Stripe charge extra fees for usage-based billing?

Yes, Stripe Billing adds a small percentage fee on top of standard payment processing for metered subscriptions. Check Stripe's current pricing page before committing, since it affects your margins at scale.

Should I use the Meters API or the newer advanced usage-based billing (pricing plans)?

For most SaaS apps with one or two usage dimensions, the Meters API covered in this guide is simpler and fully stable. Advanced usage-based billing (pricing plans) is aimed at more complex cases — multiple pricing components, prepaid credits, and enterprise contracts — and is still rolling out as a newer offering.

Wrapping Up

You now have a working usage-based billing setup in Next.js 16 using Stripe's current Meters API — a Meter to track usage, a metered Price to set the cost, a subscription to link it to a customer, and meter events to report usage as it happens. Stripe handles the aggregation and invoicing automatically from there.

From here, natural next steps are adding usage dashboards for your customers (so they can see their consumption before the bill arrives), setting up usage alerts, and combining metered pricing with a flat base fee for a hybrid SaaS pricing model.

Helpful Resources

Continue Learning

How to Add Auth.js (NextAuth v5) Authentication in Next.js 16 (2026)

Syed Muhammad Ali — Fri, 10 Jul 2026 04:46:18 +0000

Every real app eventually needs to answer one question: who is this user? The moment you add a dashboard, a settings page, or anything that shouldn't be public, you need authentication — and rolling your own login system from scratch (password hashing, sessions, CSRF protection, OAuth flows) is a rabbit hole most developers don't have time for.

That's exactly what Auth.js (the project formerly known as NextAuth) solves. It's free, open source, and gives you production-ready authentication — email/password, GitHub, Google, and dozens of other providers — without owning any of that security-critical code yourself.

In this guide, you'll set up Auth.js v5 in a Next.js 16 App Router project from scratch: installing it, configuring a provider, protecting routes with proxy.ts, and reading the logged-in user inside Server Components. By the end, you'll have a working "Sign in with GitHub" flow you can extend to any provider you want.

What you'll learn

By the end of this guide you'll know how to:

✓ Install Auth.js v5

✓ Configure GitHub OAuth

✓ Protect routes

✓ Read sessions

✓ Use auth() inside Server Components

✓ Secure Server Actions

What Is Auth.js, Exactly?

Auth.js is an authentication library built specifically for full-stack JavaScript frameworks. If you've read older tutorials, you've probably seen it called NextAuth — that's the same project. It was renamed to Auth.js when the team expanded support beyond Next.js to other frameworks like SvelteKit and Express, while the npm package name stayed next-auth for backwards compatibility.

Think of Auth.js as a middleman between your app and the identity providers (GitHub, Google, your own database, etc.). Instead of you writing the OAuth handshake, generating secure session cookies, and validating tokens by hand, Auth.js handles all of it — you just tell it which providers to use.

💡 Tip: If you've seen getServerSession() in an older tutorial, that's the Auth.js v4 API. In v5 (what this guide uses), everything is exported from a single auth() function instead — much simpler.

What We're Building

By the end of this guide, you'll have:

Auth.js v5 installed and configured in a Next.js 16 App Router app
A working GitHub OAuth sign-in flow (the pattern is the same for Google, Discord, etc.)
A proxy.ts file that protects private routes automatically
A Navbar that shows "Sign in" or the user's avatar depending on auth state
Access to the logged-in user inside Server Components using auth()

Prerequisites

Before we start, make sure you have:

Next.js 16 with the App Router
TypeScript (strict mode)
Tailwind CSS for styling
Basic familiarity with React and the App Router

If your project doesn't have these yet, scaffold one first:

npx create-next-app@latest my-app

For this guide, we're using the src/ directory layout (choose Yes when the CLI asks). Everything works the same without it — just drop the src/ prefix from the file paths below.

Folder Structure

src/
├── app/
│   └── api/
│       └── auth/
│           └── [...nextauth]/
│               └── route.ts
├── actions/
│   └── create-post.ts
├── components/
│   └── auth-buttons.tsx
├── lib/
│   └── auth.ts
├── proxy.ts
.env.local

How does Auth.js work?

User clicks "Sign in"
        ↓
Redirect to GitHub
        ↓
User approves
        ↓
GitHub redirects back
        ↓
Auth.js validates
        ↓
Session cookie created
        ↓
auth() can now read the user

Step 1: Install Auth.js

Auth.js v5 is still installed under its old package name, next-auth, using the beta tag:

npm install next-auth@beta

⚠️ Common Mistake: Installing next-auth without @beta gives you the old v4 API, which uses a completely different setup ([...nextauth].ts pages, authOptions, getServerSession()). This guide is written entirely for v5.

Step 2: Create a GitHub OAuth App

We're using GitHub as our sign-in provider in this guide. In one sentence: OAuth lets users sign in using an existing account (like GitHub or Google) without ever sharing their password with your application. Instead, GitHub itself confirms the user's identity and hands your app a token proving it — your app never sees or stores their GitHub password.

Since we're using GitHub, GitHub needs to know about your app before it'll let anyone sign in with it.

Go to github.com/settings/developers
Click New OAuth App
Fill in:
- Application name: anything, e.g. My App (Dev)
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/api/auth/callback/github
Click Register application
Copy the Client ID, then generate and copy a Client Secret

💡 Tip: The callback URL pattern /api/auth/callback/<provider> is fixed by Auth.js — don't change it, or GitHub won't be able to redirect back to your app correctly.

Step 3: Add Environment Variables

Create a .env.local file in your project root:

# .env.local
AUTH_SECRET=replace-this-with-a-random-string
AUTH_GITHUB_ID=your_github_client_id
AUTH_GITHUB_SECRET=your_github_client_secret

AUTH_SECRET is used to sign and encrypt session tokens — it must stay private. Generate a strong random value with:

npx auth secret

This command (from the auth CLI that ships with next-auth) automatically writes a secure AUTH_SECRET into your .env.local file for you.

⚠️ Common Mistake: Forgetting to add .env.local to .gitignore. If AUTH_SECRET or your OAuth secret leaks into a public repo, attackers can forge valid sessions for your app.

Step 4: Configure Auth.js

This is the heart of the setup. Create an auth.ts file inside src/lib/:

// src/lib/auth.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub],
});

What's happening here?

NextAuth(...) takes a config object and returns everything you need: handlers (for the API route), signIn/signOut (Server Actions you can call from forms or buttons), and auth() (a function to read the current session anywhere on the server).
providers: [GitHub] tells Auth.js to use GitHub OAuth. Since our environment variables follow the AUTH_GITHUB_ID / AUTH_GITHUB_SECRET naming convention, Auth.js picks them up automatically — no need to pass them manually.

💡 Tip: Want to add Google too? Just import Google from next-auth/providers/google, add matching AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET env variables, and drop it into the providers array. Auth.js supports 80+ providers this way.

Step 5: Create the API Route Handler

Auth.js needs a route to handle sign-in, sign-out, and OAuth callbacks. Create this file:

// src/app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/lib/auth";

export const { GET, POST } = handlers;

Why a catch-all route?

The [...nextauth] folder name is a catch-all dynamic route — it matches every path under /api/auth/, like /api/auth/signin, /api/auth/callback/github, and /api/auth/session. Instead of writing a route for each one, Auth.js's handlers object already knows how to respond to all of them internally.

Step 6: Add the Proxy (Middleware)

In Next.js 16, what used to be called middleware.ts is now named proxy.ts — same concept, same file conventions, just a renamed file. This is the ideal place to check authentication before a request even reaches your page.

// src/proxy.ts
export { auth as proxy } from "@/lib/auth";

export const config = {
  matcher: [
    "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

What's happening here?

Think of proxy.ts like a security guard standing at the entrance of your app — every matching request passes through it before reaching a page. By exporting auth as proxy, every request now has access to the session, which you can use to redirect unauthenticated users.

By default, this doesn't block anything yet — it just makes auth checking available. Let's actually protect a route next.

Step 7: Protect a Route

Let's say you have a /dashboard page that only logged-in users should see, and you also want to bounce already-logged-in users away from your login/home page. Update proxy.ts:

// src/proxy.ts
import { NextResponse } from "next/server";
import { auth } from "@/lib/auth";

export default auth((req) => {
    const isLoggedIn = !!req.auth;
    const { nextUrl } = req

    // Define routes that logged-in users shouldn't see
    const isAuthPage = nextUrl.pathname === "/login" || nextUrl.pathname === "/"

    if (isAuthPage) {
        if (isLoggedIn) {
            // Redirect authenticated users to the dashboard
            return NextResponse.redirect(new URL("/dashboard", nextUrl))
        }
        return NextResponse.next()
    }

    // Protect private routes
    if (!isLoggedIn && nextUrl.pathname.startsWith("/dashboard")) {
        return NextResponse.redirect(new URL("/", nextUrl))
    }
});

export const config = {
    matcher: [
        "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
    ]
};

Breaking this down

auth((req) => {...}) wraps your proxy function, giving you req.auth — the current session, or null if nobody's logged in.
isAuthPage covers routes a logged-in user has no reason to revisit (like /login or your home page) — if they're already signed in, we send them straight to /dashboard instead.
The second check does the opposite: if someone isn't logged in and tries to visit /dashboard, we redirect them back to / instead of letting the request through.

⚠️ Common Mistake: Relying on proxy.ts alone for security. Middleware-level checks are great for UX (redirecting before a page even loads), but you should also verify the session inside Server Actions and Route Handlers that touch sensitive data — never trust the frontend redirect as your only line of defense.

Step 8: Add Sign In / Sign Out Buttons

Auth.js exposes signIn and signOut as Server Actions, so you can call them directly from a <form> without any client-side JavaScript.

// src/components/auth-buttons.tsx
import { auth, signIn, signOut } from "@/lib/auth";

export default async function AuthButtons() {
  const session = await auth();

  if (!session?.user) {
    return (
      <form
        action={async () => {
          "use server";
          await signIn("github");
        }}
      >
        <button
          type="submit"
          className="rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground"
        >
          Sign in with GitHub
        </button>
      </form>
    );
  }

  return (
    <form
      action={async () => {
        "use server";
        await signOut();
      }}
    >
      <button
        type="submit"
        className="rounded-lg border px-4 py-2 text-sm font-medium"
      >
        Sign out
      </button>
    </form>
  );
}

What's happening here?

AuthButtons is an async Server Component — it calls auth() directly to check whether someone's logged in, no useEffect or loading state needed.
The inline "use server" function inside action={...} is an inline Server Action. When the form is submitted, this function runs on the server and calls signIn("github") or signOut().
signIn("github") tells Auth.js exactly which provider to start the OAuth flow with — useful once you add more than one provider.

Drop this component into your navbar, and you've got a fully working auth toggle with zero client-side JavaScript.

Step 9: Read the Session in a Server Component

Anywhere on the server — a page, a layout, another component — you can call auth() to get the current user:

// src/app/dashboard/page.tsx
import { auth } from "@/lib/auth";

export default async function DashboardPage() {
  const session = await auth();

  return (
    <div>
      <h1 className="text-2xl font-bold">Dashboard</h1>
      <p className="text-muted-foreground">
        Welcome back, {session?.user?.name}!
      </p>
    </div>
  );
}

Since we already protect /dashboard in proxy.ts, session is guaranteed to exist by the time this page renders — but it's still good practice to use optional chaining (session?.user?.name) in case that logic ever changes.

Step 10: Protect a Server Action Directly

Even with proxy.ts in place, always double-check authentication inside anything that mutates data:

// src/actions/create-post.ts
"use server";

import { auth } from "@/lib/auth";

export async function createPost(formData: FormData) {
  const session = await auth();

  if (!session?.user) {
    return { error: "You must be signed in to do that." };
  }

  const title = formData.get("title") as string;

  // Your database logic here
  // await db.post.create({ data: { title, authorId: session.user.id } })

  return { success: true };
}

This is the same idea as validating input on the server even though your form already validates on the client — never trust that a request only came from your UI.

Frequently Asked Questions

Is Auth.js free?

Yes, completely. Auth.js is open source and has no usage limits, unlike some hosted auth providers that charge per monthly active user. You're only responsible for hosting and maintaining your own database if you want persistent user records.

Why is Auth.js still installed as `next-auth`?

Because the npm package name never changed, even though the project itself rebranded. Renaming a package that thousands of projects already depend on would break every existing install, so the team kept next-auth as the package name and just changed the project's public name and docs to Auth.js. You'll see both names used interchangeably — they refer to the exact same library.

Why did NextAuth become Auth.js?

NextAuth started out Next.js-only, but the maintainers wanted the same authentication core to work with other frameworks too — SvelteKit, Express, and more, via a shared @auth/core package. "NextAuth" no longer described what the project did, so it was renamed to the framework-agnostic Auth.js, with next-auth continuing on as the Next.js-specific package built on top of that shared core.

Do I need a database?

Not for OAuth-only sign-in like the GitHub example above — Auth.js can run in a stateless JWT session mode with zero database. You'll need a database (with an Auth.js adapter, like the Drizzle or Prisma adapter) if you want persistent user records, email/password login, or multiple linked accounts per user.

What's the difference between Auth.js and Clerk?

Auth.js gives you full ownership of your data — everything lives in your own database (or nowhere, if you're stateless) — but you build your own UI. Clerk is a hosted service with prebuilt sign-in components and a dashboard, which is faster to set up but means your user data lives on Clerk's infrastructure. If data ownership matters for compliance reasons, Auth.js is the safer default.

💡 If you're deciding between the two, see Clerk vs NextAuth (Auth.js) in 2026 for a full comparison.

Can I add email/password login instead of OAuth?

Yes, using the Credentials provider. It requires you to write your own password hashing and verification logic (Auth.js won't do this for you, since it's security-sensitive), and you'll need a database to store user records.

Why is my session `null` even after signing in?

This is almost always a mismatched AUTH_SECRET or an incorrect callback URL. Double-check that your GitHub OAuth app's callback URL exactly matches http://localhost:3000/api/auth/callback/github (or your production domain), and that .env.local was loaded — restart your dev server after any environment variable change.

Wrapping Up

You've now got a complete Auth.js v5 setup in Next.js 16 — GitHub OAuth sign-in, route protection via proxy.ts, and session access in both Server Components and Server Actions. This same pattern extends cleanly: add more providers, connect a database adapter for persistent users, or layer role-based access control on top of the session object.

From here, a natural next step is wiring up a database adapter so user accounts persist across sign-ins, or adding a second provider like Google for more sign-in options.

📦 Source Code: View on GitHub

Useful Resources

Continue Learning

Helpful Free Tools

Meta Tag Generator for Next.js & HTML — generate SEO meta tags, Open Graph tags, Twitter Cards, canonical URLs, and JSON-LD structured data instantly. Handy for wiring up per-post metadata like the generateMetadata() function above.
Supabase RLS Policy Generator — if your next project pairs this blog setup with a Supabase backend, generate secure, performance-optimized Row Level Security policies in seconds.
Zod Schema Generator — generate Zod schemas instantly from JSON or TypeScript. Includes smart inference, live validation, React Hook Form, Next.js API Routes, and Server Actions.

Stripe vs 10 Alternatives: Which One Is Right for Your Business? (2026)

Syed Muhammad Ali — Thu, 09 Jul 2026 05:33:16 +0000

You've decided to accept payments on your app. Naturally, you reach for Stripe — everyone does. But then you notice the 2.9% + 30¢ fee, or you realize you're selling to customers in 40 countries and have no idea how sales tax works in each one, or your client specifically asked for PayPal because "that's what their customers trust."

Suddenly "just use Stripe" isn't such an easy call anymore.

Stripe is the default answer for a reason — great docs, clean API, huge ecosystem. But it's not always the right answer. Some businesses need lower fees at scale, some need someone else to handle global tax compliance for them, some need better support for a specific region, and some just need something simpler than Stripe's flexibility gives them.

By the end of this guide, you'll know exactly how Stripe stacks up against 10 real alternatives — what each one costs, who it's actually built for, and which one fits your specific situation.

Worth noting upfront: since acquiring Lemon Squeezy, Stripe has also entered the Merchant of Record space with Stripe Managed Payments, making this comparison even more interesting in 2026 — Stripe is now competing with its own alternatives on this list. More on that later.

Why This Comparison Is Tricky

Payment processors aren't one thing. They fall into a few different categories, and comparing them apples-to-apples only works within a category:

Payment gateways / processors (Stripe, Square, Braintree, Authorize.net) — you're the merchant of record, you handle your own tax compliance, they just move the money.
Merchant of Record (MoR) platforms (Paddle, Lemon Squeezy) — they become the legal seller, they handle sales tax and VAT for you, and they take a bigger cut for it.
Wallet-first checkout (PayPal) — optimized for buyer trust and one-click checkout rather than developer flexibility.
Enterprise-grade processors (Adyen, Checkout.com) — built for large-scale, multi-region businesses with complex routing needs.
Regional specialists (Razorpay, Mollie) — dominant in specific geographies where global players are weaker.

Keep this in mind as you read — "cheaper than Stripe" doesn't matter if the platform doesn't fit your business model in the first place.

Stripe: The Baseline

Before comparing anything, here's what you're actually comparing against.

Pricing: 2.9% + 30¢ per successful card charge (US), with volume discounts available on custom plans
Best for: SaaS products, developer-first products, subscriptions, marketplaces
Strengths: Best-in-class docs, huge library ecosystem, Stripe Checkout/Elements/Payment Element for pre-built UI, strong webhook system, excellent for Next.js/React apps
Weaknesses: You're the merchant of record — you handle your own sales tax and VAT (Stripe Tax helps calculate it, but you still remit it), support can be slow for smaller accounts, standard fees aren't the cheapest at scale

💡 Tip: If you've used Stripe before, you already know most of the vocabulary in this post — Checkout Sessions, webhooks, Payment Intents. Every alternative below borrows the same mental model to some degree.

Who Should NOT Use Stripe?

Stripe isn't the right fit for everyone. Skip it (or at least don't use it alone) if:

You sell digital products globally and don't want to deal with tax registration — Stripe Tax calculates VAT/sales tax, but you're still the one registering and remitting it in every country. A Merchant of Record like Paddle removes that burden entirely.
Your customers are mostly in India — Stripe's support for UPI and local Indian payment rails is weaker than Razorpay's.
You need in-person, physical card readers — Stripe has Terminal hardware, but Square's combined online + in-person experience is more mature.
You're processing enterprise-scale volume across many countries — at that scale, Adyen or Checkout.com's negotiated interchange-plus pricing usually beats Stripe's standard rates.
Your audience specifically expects PayPal or Venmo at checkout — Stripe supports some wallets, but Braintree's PayPal/Venmo integration is more native.

1. PayPal

The one every non-technical customer already recognizes.

Pricing: ~2.99% + fixed fee per transaction (varies by country), similar ballpark to Stripe
Best for: E-commerce stores where buyer trust and one-click checkout matter more than API elegance
Strengths: Massive brand recognition — some customers only buy if PayPal is an option, built-in buyer/seller protection, works well for one-off purchases
Weaknesses: Developer experience is noticeably behind Stripe, account holds and freezes are a common complaint, less flexible for subscription billing logic

⚠️ Common Mistake: Choosing PayPal instead of Stripe. Most stores that succeed with PayPal actually offer both — PayPal as a trust-building option alongside a primary Stripe or Square integration, not as a replacement.

2. Square

Best known for physical point-of-sale, but its online payments API has matured a lot.

Pricing: 2.6% + 10¢ for in-person, ~2.9% + 30¢ for online — comparable to Stripe
Best for: Businesses that need both online and in-person payments under one system (restaurants, retail, service businesses)
Strengths: Unified dashboard for online + POS + invoicing, no monthly fees on the base plan, solid inventory and appointment tools bundled in
Weaknesses: Online-only developer experience is less polished than Stripe's, less suited to complex SaaS billing logic

Choose Square over Stripe if: you also need physical card readers or in-person sales alongside your website.

3. Braintree (a PayPal company)

Braintree is essentially "Stripe for people who also want PayPal and Venmo in one integration."

Pricing: 2.59% + 49¢ typically — slightly cheaper per-transaction than Stripe on paper
Best for: Apps that want PayPal, Venmo, and card payments through a single SDK
Strengths: Owned by PayPal, so PayPal/Venmo integration is native rather than bolted on, solid mobile SDKs (iOS/Android)
Weaknesses: Documentation and community support are noticeably smaller than Stripe's, fewer prebuilt UI components

Choose Braintree over Stripe if: your audience skews toward PayPal/Venmo as a primary payment method (common in US consumer apps).

4. Adyen

The processor institutional fintechs and large marketplaces actually use.

Pricing: Interchange-plus pricing (you pay the real card network fee + a small Adyen markup) — cheaper at high volume, but not built for small businesses
Best for: Large-scale, multi-country businesses processing serious volume (Uber, Spotify, eBay-scale)
Strengths: Single platform for 40+ payment methods across regions, excellent fraud detection (RevenueProtect), true global reach
Weaknesses: Not self-serve — you talk to a sales team, overkill (and often not even available) for early-stage products

Choose Adyen over Stripe if: you're already processing millions per month across multiple countries and need custom pricing.

5. Authorize.net

The processor that's been around since the dot-com era and quietly still works fine.

Pricing: $25/month gateway fee + 2.9% + 30¢ per transaction — more expensive than Stripe once you add the monthly fee
Best for: Traditional businesses already on legacy e-commerce platforms (older WooCommerce/Magento setups)
Strengths: Extremely stable, works with a huge number of existing shopping cart integrations
Weaknesses: Developer experience feels dated compared to Stripe, extra monthly fee makes it a worse deal for low-volume stores

Choose Authorize.net over Stripe if: you're integrating into an existing legacy e-commerce stack that already expects it.

6. Paddle

A true Merchant of Record — Paddle becomes the legal seller so you don't have to.

Pricing: ~5% + 50¢ per transaction (no separate monthly fee) — higher than Stripe, but that fee includes global tax handling
Best for: SaaS companies selling internationally who don't want to deal with VAT/sales tax registration in every country
Strengths: Handles sales tax, VAT, and invoicing compliance automatically, built specifically for SaaS subscription billing, strong checkout localization (currency, language)
Weaknesses: Noticeably higher fees than a raw payment processor, less low-level control over the checkout flow

💡 Tip: The right way to think about the extra ~2% over Stripe is: you're paying Paddle to be your tax accountant and legal seller in every country. For a solo founder, that trade is often worth it.

Where Stripe Managed Payments fits in: since acquiring Lemon Squeezy, Stripe has been building its own Merchant of Record product — Stripe Managed Payments — which entered public preview in early 2026. It's Stripe's answer to exactly what Paddle already does: Stripe becomes the seller of record and handles global tax for you, at a similar ~5% fee. Paddle still has the longer track record and a more mature product for now, but this is a space to watch — you may eventually be able to get MoR-style tax handling without leaving the Stripe ecosystem at all.

7. Razorpay

The dominant payment processor for businesses operating in India.

Pricing: ~2% per transaction domestically, higher for international cards — meaningfully cheaper than Stripe within India
Best for: Businesses primarily serving Indian customers (UPI, Indian net banking, RuPay cards)
Strengths: Deep support for local payment methods Stripe doesn't handle well (UPI, India-specific wallets), strong local compliance and support
Weaknesses: Not the right choice if your customers are mostly outside India, less relevant for Western SaaS products

Choose Razorpay over Stripe if: a meaningful share of your revenue comes from Indian customers.

8. Mollie

A European-focused processor that's become the default for a lot of EU-based SaaS and e-commerce.

Pricing: Pay-per-transaction with no monthly fees, competitive with Stripe in the EU
Best for: Businesses primarily serving European customers who want strong support for local payment methods (iDEAL, Bancontact, SOFORT)
Strengths: Excellent support for European-specific payment rails Stripe supports less natively, simple, clean API
Weaknesses: Smaller ecosystem and community outside Europe, fewer advanced billing features than Stripe Billing

Choose Mollie over Stripe if: your customers are mostly European and rely on local bank-transfer-style payment methods.

9. Checkout.com

An enterprise-grade processor competing directly with Adyen for large global merchants.

Pricing: Custom, interchange-plus — negotiated per contract, not published
Best for: Large enterprises and marketplaces with global, high-volume payment needs
Strengths: Strong presence in Europe/Middle East, excellent uptime and fraud tooling, flexible routing for high-risk industries
Weaknesses: Sales-led onboarding, not something you sign up for and integrate in an afternoon — not built for indie developers or early-stage startups

Choose Checkout.com over Stripe if: you're an enterprise processing serious volume and need a dedicated account manager and custom terms.

10. Lemon Squeezy

Worth including, with an important caveat: Stripe acquired Lemon Squeezy in 2024, and in 2026 Stripe is actively rolling out "Stripe Managed Payments" — its own native Merchant of Record product built using what it learned from that acquisition.

Pricing: 5% + 50¢ per transaction, no monthly fee
Best for: Indie SaaS founders and digital product creators who want MoR-style tax handling with a simpler, more creator-focused feature set (affiliates, license keys, digital delivery) than Paddle offers
Strengths: Very fast to set up, built specifically for solo founders and small teams, handles global tax compliance like Paddle does
Weaknesses: Its long-term roadmap is now tied to Stripe's own Managed Payments product, so some indie-specific features may not carry over if you're forced to migrate down the line

⚠️ Common Mistake: Assuming Lemon Squeezy is a fully independent alternative to Stripe. Since the acquisition, it's best thought of as "Stripe's on-ramp into the Merchant of Record space" rather than a true competitor — worth knowing before you build a long-term dependency on it.

Quick Comparison Table

Platform	Merchant of Record?	Typical Fee	Best For
Stripe	No	2.9% + 30¢	Developer-first SaaS, subscriptions
PayPal	No	~2.99% + fee	Buyer trust, one-off e-commerce
Square	No	2.9% + 30¢	Online + in-person combined
Braintree	No	2.59% + 49¢	PayPal/Venmo-heavy audiences
Adyen	No	Interchange-plus	Large-scale global enterprises
Authorize.net	No	$25/mo + 2.9% + 30¢	Legacy e-commerce stacks
Paddle	Yes	~5% + 50¢	Global SaaS avoiding tax registration
Razorpay	No	~2% domestic	India-focused businesses
Mollie	No	Pay-per-transaction	EU-focused businesses
Checkout.com	No	Custom	Enterprise, high volume
Lemon Squeezy	Yes	5% + 50¢	Indie SaaS, digital products

How to Actually Choose

Instead of picking based on fees alone, walk through these questions in order:

Do you want to handle sales tax/VAT yourself, or pay someone else to? If you'd rather not deal with tax registration in every country you sell to, go with Paddle or Lemon Squeezy. If you're fine using Stripe Tax to calculate (and then remitting it yourself), stick with Stripe or another raw processor.
Where are your customers? Mostly India → Razorpay. Mostly Europe → Mollie. Global and card-based → Stripe.
Do you need in-person payments too? If yes, Square is the only one on this list that does both well out of the box.
Are you doing enterprise-scale volume? If you're processing millions per month, Adyen or Checkout.com's custom pricing will beat any of the self-serve options.
Does your audience specifically expect PayPal? Add it as a secondary option — don't make it your only processor for a SaaS product.

For most Next.js SaaS builds, Stripe remains the safest default: best documentation, largest community, and the easiest to actually ship with. Reach for an alternative only when you have a specific, concrete reason — a region Stripe serves poorly, a tax burden you want off your plate, or a scale where custom pricing genuinely saves money.

Which Stripe Alternative Is Best for...

Quick answers if you already know your use case and just want the pointer:

...SaaS? Stick with Stripe — it's still the most complete toolkit for subscription billing, and its ecosystem of libraries and guides is unmatched.
...Subscriptions? Stripe Billing is the most flexible for custom subscription logic. If you'd rather offload tax compliance too, Paddle is purpose-built for SaaS subscriptions specifically.
...Marketplaces? Stripe Connect is the standard here, but Adyen is worth evaluating once you're processing serious volume across many countries.
...Digital Products? Paddle or Lemon Squeezy — both act as Merchant of Record, which matters a lot for indie creators selling ebooks, courses, or software licenses globally.
...Small Business? Square, if you also sell in person. Stripe or PayPal if you're online-only and want the fastest setup.
...Enterprise? Adyen or Checkout.com — both offer negotiated pricing and dedicated support that self-serve platforms don't.
...International Payments? Mollie for Europe, Razorpay for India, Paddle if you want tax compliance handled everywhere at once.
...Physical Stores? Square, hands down — it's the only option on this list built for combined online + in-person payments from day one.

Frequently Asked Questions

Is Stripe still the best choice for a first-time SaaS product?

For most cases, yes. The documentation, community support, and prebuilt components (Checkout, Payment Element) make it the fastest path to actually shipping payments in a Next.js app.

What's the real difference between a payment processor and a Merchant of Record?

A processor (Stripe, Square, Braintree) just moves money — you're legally the seller and responsible for your own tax compliance. A Merchant of Record (Paddle, Lemon Squeezy) legally becomes the seller on your behalf, which means they handle VAT/sales tax registration and remittance for you, at a higher fee.

Can I use more than one payment processor at once?

Yes, and many businesses do — for example, Stripe as the primary processor plus PayPal as a secondary option for customers who specifically prefer it. Just be aware this adds complexity to your webhook and reconciliation logic.

Are Paddle and Lemon Squeezy worth the extra fees for a solo founder?

Often, yes. If you're a single developer selling globally, the ~2% extra fee can be far cheaper than the time (or accountant fees) it would take to register and file sales tax in dozens of countries yourself.

Does switching payment processors later require rebuilding my whole app?

Not necessarily, if you've kept your payment logic reasonably isolated (a single lib/payments module, for example) rather than scattering Stripe-specific calls across your codebase. It's still real migration work — expect to touch checkout flows, webhooks, and any stored customer/subscription IDs.

Choosing a payment processor isn't a one-time decision carved in stone — plenty of companies start with Stripe and add or switch processors as their business changes shape. The important thing is picking based on your actual constraints (tax burden, region, scale) rather than just going with whichever name is most familiar.

Continue Learning

If you've decided Stripe is still the right call (it usually is), these guides walk through the actual implementation in Next.js 16:

Next.js 16 AWS S3 File Upload Guide: Presigned URLs, Proxy & Multipart

Syed Muhammad Ali — Tue, 07 Jul 2026 19:00:00 +0000

At some point, almost every real app needs file uploads — profile pictures, PDFs, videos, CSV imports. The tempting move is to just POST the file straight to your Next.js server and save it somewhere. That works great in a tutorial and falls apart the moment a real user uploads a 200MB video, because your serverless function times out, hits its body size limit, or just burns money streaming bytes it didn't need to touch.

The fix is almost always Amazon S3 (Simple Storage Service) — a place built specifically to store files cheaply and reliably, so your Next.js app doesn't have to. But "just use S3" isn't one pattern, it's three, and picking the wrong one is why most S3 upload tutorials online feel incomplete or break in production.

In this guide, you'll build all three real-world upload patterns in Next.js 16:

Server-side proxying — the file passes through your Next.js server on its way to S3
Direct-to-S3 presigned URLs — the browser uploads straight to S3, skipping your server entirely
Multipart uploads — for large files, split into chunks so they upload reliably and can resume

By the end, you'll know exactly which pattern to reach for and have working code for each.

Why This Is Tricky

Here's the core tension: your Next.js server (especially on serverless platforms like Vercel) is not a good place for large files to pass through.

Body size limits — most hosting platforms cap how much data a single request can carry (Vercel's default is 4.5MB for serverless functions).
Function timeouts — a slow upload over a weak connection can outlive your function's execution limit.
You pay for time, not just requests — every second your function spends waiting on a file transfer is a second you're billed for, even though your server isn't doing any real work.

So the real skill here isn't "how do I upload to S3" — it's "how much of this upload actually needs to touch my server?" That question is what decides which of the three patterns you reach for.

💡 Tip: As a rule of thumb — small files (avatars, documents under a few MB) are fine to proxy through your server. Anything user-facing and potentially large (videos, zip files, high-res images) should go direct-to-S3.

Prerequisites & Setup

This guide assumes:

Next.js 16 with the App Router
TypeScript in strict mode
Tailwind CSS for the (minimal) UI examples
An AWS account with an S3 bucket

Step 1: Create an S3 Bucket

In the AWS Console:

Click Create bucket
Give it a globally unique name, e.g. devstacked-uploads-demo
Pick a region close to your users
Leave Block all public access checked — you don't need a public bucket for any of these three patterns

⚠️ Common Mistake: Making the bucket public "to make uploads easier." None of the patterns in this guide need a public bucket. Presigned URLs grant temporary, scoped access without ever exposing the bucket itself.

Step 2: Create an IAM User for Programmatic Access

Your Next.js server needs credentials to talk to S3.

Go to IAM → Users → Create user
Name it something like nextjs-s3-uploader
Attach a policy scoped to just this bucket — not full AmazonS3FullAccess:

// s3-upload-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": "arn:aws:s3:::devstacked-uploads-demo/*"
    }
  ]
}

After creating the user, open it and generate an Access key

⚠️ Common Mistake: Using your AWS root account credentials in .env.local. Always create a scoped IAM user — if those keys ever leak, the blast radius is one bucket, not your entire AWS account.

Step 3: Configure CORS on the Bucket

Two of the three patterns in this guide (presigned URLs and multipart) have the browser talk directly to S3. By default, S3 blocks cross-origin requests from your site, so you need to explicitly allow it.

In your bucket → Permissions → Cross-origin resource sharing (CORS):

// s3-cors-config.json
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["PUT", "POST", "GET"],
    "AllowedOrigins": ["http://localhost:3000", "https://yourdomain.com"],
    "ExposeHeaders": ["ETag"]
  }
]

Why ExposeHeaders: ["ETag"] matters: the multipart pattern later needs to read the ETag header back from S3 after each chunk uploads. Without exposing it, your browser can see the response succeeded but can't read the header it needs.

💡 Tip: Consider enabling S3 Versioning from Properties Tab if users may overwrite files. It provides recovery from accidental deletes or replacements.

Step 4: Install Dependencies

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

@aws-sdk/client-s3 — the official AWS SDK v3 client for talking to S3
@aws-sdk/s3-request-presigner — generates temporary, signed upload URLs

Step 5: Environment Variables

# .env.local
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
S3_BUCKET_NAME=devstacked-uploads-demo

⚠️ Common Mistake: Never prefix these with NEXT_PUBLIC_. That would ship your AWS secret key to every visitor's browser. These stay server-only, always.

Step 6: Create a Reusable S3 Client

// lib/s3-client.ts
import { S3Client } from "@aws-sdk/client-s3";

export const s3Client = new S3Client({
  region: process.env.AWS_REGION!,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

Every pattern below imports this single client instead of creating a new one per request.

Pattern 1: Server-Side Proxying

How it works: the browser sends the file to your Next.js server, and your server forwards it to S3. Your server sits in the middle of every byte.

Browser → Next.js Route Handler → S3

This is the simplest pattern to reason about and the easiest to add validation, virus scanning, or image processing to — because your server actually sees the file. The tradeoff is exactly what we covered above: your server pays the time and bandwidth cost of the transfer, so this pattern is best kept for small files only (a few MB at most).

Step 1: Create the Upload Route Handler

// app/api/upload/route.ts
import { NextRequest, NextResponse } from "next/server";
import { PutObjectCommand } from "@aws-sdk/client-s3";
import { s3Client } from "@/lib/s3-client";
import { randomUUID } from "crypto";

const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp"];

export async function POST(request: NextRequest) {
  try {
    const formData = await request.formData();
    const file = formData.get("file") as File | null;

    if (!file) {
      return NextResponse.json({ error: "No file provided" }, { status: 400 });
    }

    if (!ALLOWED_TYPES.includes(file.type)) {
      return NextResponse.json({ error: "Unsupported file type" }, { status: 400 });
    }

    if (file.size > MAX_FILE_SIZE) {
      return NextResponse.json({ error: "File too large" }, { status: 400 });
    }

    const buffer = Buffer.from(await file.arrayBuffer());
    const key = `avatars/${randomUUID()}-${file.name}`;

    await s3Client.send(
      new PutObjectCommand({
        Bucket: process.env.S3_BUCKET_NAME!,
        Key: key,
        Body: buffer,
        ContentType: file.type,
      })
    );

    return NextResponse.json({ key }, { status: 200 });
  } catch (error) {
    console.error("Upload error:", error);
    return NextResponse.json({ error: "Upload failed" }, { status: 500 });
  }
}

What's happening here:

request.formData() reads the incoming multipart form data — this is how browsers send files
We validate file.type and file.size before touching S3, so bad requests fail fast and cheap
file.arrayBuffer() converts the browser File object into a Buffer that the AWS SDK can send
The S3 object Key (its path inside the bucket) includes a random UUID so two people uploading photo.jpg never overwrite each other

⚠️ Common Mistake: Trusting file.type alone for security. It's sent by the browser and can be spoofed. For anything sensitive, also validate the actual file signature (magic bytes) server-side, or run the file through a scanning service before it's considered "safe."

Step 2: Build the Upload Form

// components/proxy-upload-form.tsx
"use client";

import { useState } from "react";

export function ProxyUploadForm() {
  const [uploading, setUploading] = useState(false);
  const [message, setMessage] = useState("");

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    const fileInput = form.elements.namedItem("file") as HTMLInputElement;
    const file = fileInput.files?.[0];

    if (!file) return;

    setUploading(true);
    setMessage("");

    const formData = new FormData();
    formData.append("file", file);

    const res = await fetch("/api/upload", {
      method: "POST",
      body: formData,
    });

    const data = await res.json();
    setUploading(false);
    setMessage(res.ok ? `Uploaded: ${data.key}` : data.error);
  };

  return (
    <form onSubmit={handleSubmit} className="flex flex-col gap-3 max-w-sm">
      <input type="file" name="file" accept="image/*" required />
      <button
        type="submit"
        disabled={uploading}
        className="rounded-lg bg-primary px-4 py-2 text-white disabled:opacity-50"
      >
        {uploading ? "Uploading..." : "Upload"}
      </button>
      {message && <p className="text-sm text-muted-foreground">{message}</p>}
    </form>
  );
}

Nothing exotic here — a standard FormData submission to our route handler. This pattern is genuinely the easiest to get right, which is exactly why it's the wrong choice once files get bigger.

Pattern 2: Direct-to-S3 Presigned URLs

How it works: your server never touches the file. Instead, it asks S3 for a presigned URL — a temporary, signed link that grants permission to upload one specific file, to one specific location, for a short window of time. The browser then uploads directly to S3 using that URL.

Browser → Next.js (ask for permission) → gets presigned URL
Browser → S3 directly (actual file upload)

Think of a presigned URL like a guest pass: your server is the front desk that checks you're allowed in, then hands you a pass that only works for one door, for the next few minutes. You still never got a master key to the building.

This is the pattern you want for anything user-facing that could be more than a few MB — profile videos, portfolio images, document uploads. Your server's job shrinks down to a single, fast decision: "yes, generate a URL" or "no."

Step 1: Generate the Presigned URL

// app/api/presigned-url/route.ts
import { NextRequest, NextResponse } from "next/server";
import { PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { s3Client } from "@/lib/s3-client";
import { randomUUID } from "crypto";

const ALLOWED_TYPES = ["image/jpeg", "image/png", "video/mp4"];
const URL_EXPIRY_SECONDS = 60; // presigned URL is valid for 60 seconds

export async function POST(request: NextRequest) {
  try {
    const { fileName, fileType } = await request.json();

    if (!fileName || !fileType) {
      return NextResponse.json({ error: "Missing fileName or fileType" }, { status: 400 });
    }

    if (!ALLOWED_TYPES.includes(fileType)) {
      return NextResponse.json({ error: "Unsupported file type" }, { status: 400 });
    }

    const key = `uploads/${randomUUID()}-${fileName}`;

    const command = new PutObjectCommand({
      Bucket: process.env.S3_BUCKET_NAME!,
      Key: key,
      ContentType: fileType,
    });

    const uploadUrl = await getSignedUrl(s3Client, command, {
      expiresIn: URL_EXPIRY_SECONDS,
    });

    return NextResponse.json({ uploadUrl, key });
  } catch (error) {
    console.error("Presign error:", error);
    return NextResponse.json({ error: "Could not generate upload URL" }, { status: 500 });
  }
}

What's happening here:

We never receive the actual file — just its fileName and fileType, which is why this endpoint responds instantly no matter how big the file will be
getSignedUrl() doesn't make a network call to AWS — it cryptographically signs the request locally using your IAM credentials, so it's fast
expiresIn: 60 means this exact URL stops working after 60 seconds — plenty of time for the browser to start the upload, but not so long that a leaked URL stays exploitable

💡 Tip: Still validate fileType here even though you're not seeing the actual bytes. It's your only real gate at this stage — S3 will happily accept whatever ContentType the presigned request specifies.

Step 2: Upload Directly From the Browser

// components/presigned-upload-form.tsx
"use client";

import { useState } from "react";

export function PresignedUploadForm() {
  const [progress, setProgress] = useState(0);
  const [status, setStatus] = useState<"idle" | "uploading" | "done" | "error">("idle");

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    const fileInput = form.elements.namedItem("file") as HTMLInputElement;
    const file = fileInput.files?.[0];
    if (!file) return;

    setStatus("uploading");
    setProgress(0);

    // Step 1: ask our server for a presigned URL
    const presignRes = await fetch("/api/presigned-url", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ fileName: file.name, fileType: file.type }),
    });

    if (!presignRes.ok) {
      setStatus("error");
      return;
    }

    const { uploadUrl } = await presignRes.json();

    // Step 2: upload the actual file straight to S3, tracking progress
    await new Promise<void>((resolve, reject) => {
      const xhr = new XMLHttpRequest();
      xhr.open("PUT", uploadUrl);
      xhr.setRequestHeader("Content-Type", file.type);

      xhr.upload.onprogress = (event) => {
        if (event.lengthComputable) {
          setProgress(Math.round((event.loaded / event.total) * 100));
        }
      };

      xhr.onload = () => (xhr.status === 200 ? resolve() : reject());
      xhr.onerror = () => reject();
      xhr.send(file);
    })
      .then(() => setStatus("done"))
      .catch(() => setStatus("error"));
  };

  return (
    <form onSubmit={handleSubmit} className="flex flex-col gap-3 max-w-sm">
      <input type="file" name="file" accept="image/*,video/mp4" required />
      <button
        type="submit"
        disabled={status === "uploading"}
        className="rounded-lg bg-primary px-4 py-2 text-white disabled:opacity-50"
      >
        {status === "uploading" ? `Uploading... ${progress}%` : "Upload"}
      </button>
      {status === "done" && <p className="text-sm text-green-600">Upload complete!</p>}
      {status === "error" && <p className="text-sm text-destructive">Upload failed.</p>}
    </form>
  );
}

Why XMLHttpRequest instead of fetch? This is a genuinely common question. The fetch API still doesn't support upload progress tracking in a standard way — xhr.upload.onprogress does. For a file that could take a while, showing real progress is worth the slightly older API.

⚠️ Common Mistake: Forgetting to set the same Content-Type header on the PUT request that you signed the URL with. S3 checks that they match — a mismatch fails with a signature error that has nothing to do with your actual credentials, which makes it a confusing bug to track down.

Pattern 3: Multipart Uploads for Large Files

How it works: instead of uploading one large file as a single request, you split it into chunks (S3 calls these "parts"), upload each part with its own presigned URL, and then tell S3 to stitch them back together.

Browser → Next.js: "start a multipart upload"
Browser → S3: upload part 1, part 2, part 3... (each with its own presigned URL)
Browser → Next.js: "complete the upload" (with the list of parts)

This solves two real problems that plain presigned URLs don't:

Reliability — if part 4 of 10 fails on a flaky connection, you only retry part 4, not the entire 500MB file
Parallelism — multiple parts can upload at the same time instead of one after another

AWS requires every part except the last to be at least 5MB. This pattern is overkill for a 2MB avatar — it's built for videos, archives, and anything in the tens-to-hundreds-of-MB range.

Step 1: Start the Multipart Upload

// app/api/multipart/start/route.ts
import { NextRequest, NextResponse } from "next/server";
import { CreateMultipartUploadCommand } from "@aws-sdk/client-s3";
import { s3Client } from "@/lib/s3-client";
import { randomUUID } from "crypto";

export async function POST(request: NextRequest) {
  const { fileName, fileType } = await request.json();

  const key = `large-uploads/${randomUUID()}-${fileName}`;

  const { UploadId } = await s3Client.send(
    new CreateMultipartUploadCommand({
      Bucket: process.env.S3_BUCKET_NAME!,
      Key: key,
      ContentType: fileType,
    })
  );

  return NextResponse.json({ uploadId: UploadId, key });
}

This tells S3 "expect a multipart upload for this key" and gets back an UploadId — a token that ties every part together as belonging to the same file.

Step 2: Get a Presigned URL for Each Part

// app/api/multipart/presign-part/route.ts
import { NextRequest, NextResponse } from "next/server";
import { UploadPartCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { s3Client } from "@/lib/s3-client";

export async function POST(request: NextRequest) {
  const { key, uploadId, partNumber } = await request.json();

  const command = new UploadPartCommand({
    Bucket: process.env.S3_BUCKET_NAME!,
    Key: key,
    UploadId: uploadId,
    PartNumber: partNumber,
  });

  const url = await getSignedUrl(s3Client, command, { expiresIn: 300 });

  return NextResponse.json({ url });
}

Each part needs its own presigned URL, tagged with a PartNumber (1, 2, 3...) — this is how S3 knows the order to reassemble them in later.

Step 3: Complete the Multipart Upload

// app/api/multipart/complete/route.ts
import { NextRequest, NextResponse } from "next/server";
import { CompleteMultipartUploadCommand } from "@aws-sdk/client-s3";
import { s3Client } from "@/lib/s3-client";

export async function POST(request: NextRequest) {
  const { key, uploadId, parts } = await request.json();
  // parts: { PartNumber: number; ETag: string }[]

  await s3Client.send(
    new CompleteMultipartUploadCommand({
      Bucket: process.env.S3_BUCKET_NAME!,
      Key: key,
      UploadId: uploadId,
      MultipartUpload: { Parts: parts },
    })
  );

  return NextResponse.json({ success: true, key });
}

Why does every part need an ETag? Each time S3 accepts a part, it returns an ETag in the response headers — essentially a fingerprint confirming that part uploaded correctly and intact. When you call "complete," S3 cross-checks every ETag you send against what it actually received before stitching the file together. This is exactly why we exposed the ETag header in the CORS config back in setup.

⚠️ Common Mistake: Forgetting to add a cleanup step for abandoned multipart uploads (user closes the tab mid-upload). S3 keeps incomplete parts around and bills you for that storage. Set up an S3 Lifecycle rule to auto-abort incomplete uploads after a day or two.

Step 4: Orchestrate It All From the Browser

// components/multipart-upload-form.tsx
"use client";

import { useState } from "react";

const CHUNK_SIZE = 6 * 1024 * 1024; // 6MB per part (must be 5MB+)
// S3 requires every part except the last to be at least 5MB. Choosing 6MB provides a small buffer while keeping memory usage reasonable.

export function MultipartUploadForm() {
  const [progress, setProgress] = useState(0);
  const [status, setStatus] = useState<"idle" | "uploading" | "done" | "error">("idle");

  const uploadPart = async (
    url: string,
    chunk: Blob
  ): Promise<string> => {
    const res = await fetch(url, { method: "PUT", body: chunk });
    const etag = res.headers.get("ETag");
    if (!etag) throw new Error("Missing ETag from S3 response");
    return etag;
  };

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    const fileInput = form.elements.namedItem("file") as HTMLInputElement;
    const file = fileInput.files?.[0];
    if (!file) return;

    setStatus("uploading");
    setProgress(0);

    try {
      // Step 1: start the multipart upload
      const startRes = await fetch("/api/multipart/start", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ fileName: file.name, fileType: file.type }),
      });
      const { uploadId, key } = await startRes.json();

      // Step 2: split the file into chunks and upload each one
      const totalParts = Math.ceil(file.size / CHUNK_SIZE);
      const completedParts: { PartNumber: number; ETag: string }[] = [];

      for (let partNumber = 1; partNumber <= totalParts; partNumber++) {
        const start = (partNumber - 1) * CHUNK_SIZE;
        const chunk = file.slice(start, start + CHUNK_SIZE);

        const presignRes = await fetch("/api/multipart/presign-part", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ key, uploadId, partNumber }),
        });
        const { url } = await presignRes.json();

        const etag = await uploadPart(url, chunk);
        completedParts.push({ PartNumber: partNumber, ETag: etag });

        setProgress(Math.round((partNumber / totalParts) * 100));
      }

      // Step 3: tell S3 to assemble the parts into the final file
      await fetch("/api/multipart/complete", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ key, uploadId, parts: completedParts }),
      });

      setStatus("done");
    } catch (error) {
      console.error("Multipart upload failed:", error);
      setStatus("error");
    }
  };

  return (
    <form onSubmit={handleSubmit} className="flex flex-col gap-3 max-w-sm">
      <input type="file" name="file" required />
      <button
        type="submit"
        disabled={status === "uploading"}
        className="rounded-lg bg-primary px-4 py-2 text-white disabled:opacity-50"
      >
        {status === "uploading" ? `Uploading... ${progress}%` : "Upload Large File"}
      </button>
      {status === "done" && <p className="text-sm text-green-600">Upload complete!</p>}
      {status === "error" && <p className="text-sm text-destructive">Upload failed.</p>}
    </form>
  );
}

Walking through the flow: we start the upload and get back an uploadId, then loop through the file in 6MB slices using file.slice() — this is a native browser API, no library needed. For each slice, we request a fresh presigned URL, PUT the chunk directly to S3, and hold onto the ETag we get back. Once every part is uploaded, we send the full list of { PartNumber, ETag } pairs to the "complete" endpoint, and S3 assembles them into one file.

💡 Tip: The loop above uploads parts one at a time for clarity. In production, you'd typically run several uploadPart calls concurrently (e.g. 3–4 at once with Promise.all) to meaningfully speed up large uploads — just be sure to still track and report progress per part.

Which Pattern Should You Actually Use?

Situation	Pattern
Small files (avatars, PDFs under ~5MB)	Server-side proxying
You need to validate/process the file server-side before storing it	Server-side proxying
User-facing images or short videos, a few MB to ~50MB	Direct-to-S3 presigned URL
You want upload progress without server load	Direct-to-S3 presigned URL
Large files — videos, archives, datasets (50MB+)	Multipart upload
Uploads over unreliable connections that need retry-per-chunk	Multipart upload

A common real-world setup actually combines these: use a presigned URL (single or multipart, depending on size) to get the file into S3 quickly, then have S3 trigger a Lambda or your own webhook afterward to run any validation, resizing, or processing you'd otherwise have done during a server-side proxy.

Frequently Asked Questions

Do I need to use the AWS SDK, or can I just use fetch with S3's REST API directly?

You technically can call S3's REST API directly, but you'd be manually implementing AWS's request-signing algorithm (SigV4) yourself — the SDK handles that correctly and is the standard approach. Stick with @aws-sdk/client-s3 unless you have a very specific reason not to.

Is it safe to expose the S3 object key to the browser?

Yes — the key is just a file path, not a credential. What actually grants access is the signed portion of the presigned URL, which expires and is scoped to that one action. Just don't put sensitive information (like a user's email) directly in the key name if the bucket could ever become browsable.

Can I use this with the Pages Router instead of App Router?

The S3 SDK logic (creating the client, generating presigned URLs) works identically. You'd just swap the Route Handlers for pages/api/*.ts files using req/res instead of NextRequest/NextResponse.

What happens if a presigned URL expires mid-upload?

For the single presigned URL pattern, a slow upload could in theory outlive a very short expiry — that's why the expiry is a balance: long enough to comfortably start and finish, short enough to limit exposure if leaked. For multipart uploads, each part gets its own fresh URL, so this is naturally less of a concern for large files.

Do I need CloudFront in front of my bucket?

Not for uploads — CloudFront is about serving files back out fast, which is a separate concern from getting files in. If you're also displaying these uploaded files to users at scale, adding a CloudFront distribution in front of the bucket is a common next step, but it's optional for the upload flow itself. See my guide on displaying S3 images for the full breakdown of the public, presigned, and CloudFront display patterns.

Should I use Server Actions for uploads?

Server Actions work well for small files, but they still route the file through your server. The same trade-offs apply: body size limits, execution time, and bandwidth costs. For larger uploads, presigned URLs remain the recommended approach.

Wrapping Up

You now have three working, production-grade upload patterns for S3 in Next.js 16 — server-side proxying for small files you need to inspect, presigned URLs for everyday user uploads, and multipart uploads for the big stuff that needs to survive a bad connection. The pattern you reach for isn't really an S3 question — it's a question of how much of that file actually needs to pass through your server, and now you've got the code to implement whichever answer fits.

From here, the natural next step is displaying these uploaded files back to your users — covering public URLs, presigned GET links, and CloudFront delivery.

📦 Source Code: View on GitHub

Continue Learning

How to Display Images from S3 in Next.js 16 (2026 Guide) — now that your files are in S3, here's how to show them back to users safely
How to Setup Resend Email in Next.js 16 (2026 Complete Beginner Guide)
SaaS Starter Architecture with Next.js 2026
Next.js Rendering Strategies Explained: SSR, SSG, CSR, ISR & Cache Components (2026)

How to Display Images from S3 in Next.js 16 (2026 Guide)

Syed Muhammad Ali — Tue, 07 Jul 2026 19:00:00 +0000

Getting a file into S3 is only half the job. Sooner or later you need to actually show that image back to the user — on a profile page, in a gallery, inside a product card — and that's where a second wave of questions shows up. Do you just paste the S3 URL into an <img> tag? Does next/image even work with S3? What if the file is private and shouldn't be reachable by just anyone with the link?

If you followed our guide on uploading files to S3 with Next.js 16, you already have files living in one of three ways — proxied through your server, uploaded directly via a presigned URL, or pushed up in multipart chunks. The good news: how you display an image doesn't depend on how it was uploaded. It depends on one thing only — is the object public or private?

In this guide, you'll learn all three real-world patterns for displaying S3 images in Next.js 16:

Public bucket URLs — the simplest option, for non-sensitive assets
Presigned GET URLs — for private files that only the right user should see
CloudFront CDN delivery — for performance and scale, with both public and signed variants

By the end, you'll know exactly which pattern fits your use case and have working code for each.

Why This Is Tricky

It's tempting to think "S3 has a URL, I'll just use that." Sometimes that's genuinely fine. But most real apps hit one of these problems fast:

Not everything should be public. A user's private document or someone else's uploaded receipt shouldn't be reachable by anyone who guesses or copies the URL.
next/image doesn't know about S3 by default. Next.js's image optimizer blocks external domains until you explicitly allow them — skip this step and your images silently fail to load.
Raw S3 isn't a CDN. Every request hits the bucket directly, in one region, with no edge caching — fine for a side project, not great once you have real traffic.

So the real question for every image you display is: "Who is allowed to see this, and does it need to be fast at scale?" That answer picks your pattern.

💡 Tip: If you're unsure whether something should be public, default to private. It's much easier to make a private file public later than to discover a "public" file leaked something sensitive.

Prerequisites & Setup

This guide continues directly from our S3 upload guide and assumes:

Next.js 16 with the App Router
TypeScript in strict mode
Tailwind CSS for the UI examples
The same S3 bucket and s3Client from the upload guide's lib/s3-client.ts

If you haven't set up the S3 client yet, go set that up first — every pattern below reuses it.

Allow S3 (and CloudFront) in next.config

next/image refuses to optimize images from a domain it doesn't recognize — this is a security default, not a bug. Add your bucket's hostname to remotePatterns:

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

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "devstacked-uploads-demo.s3.us-east-1.amazonaws.com",
      },
      {
        protocol: "https",
        hostname: "*.cloudfront.net", // for Pattern 3 later in this guide
      },
    ],
  },
};

export default nextConfig;

⚠️ Common Mistake: Forgetting this step and assuming next/image is broken. The error Next.js throws ("hostname is not configured") is exactly this — it's not a bug, it's the optimizer refusing to fetch from an unlisted domain.

💡 Tip: If you're serving stable public URLs (Pattern 1 or the public side of Pattern 3), also tune minimumCacheTTL:
images: {
  minimumCacheTTL: 60 * 60 * 24 * 30, // cache optimized output for 30 days
  remotePatterns: [/* ... */],
},
By default, Next.js only caches an optimized image for 4 hours before re-checking the source. For images that never change once uploaded (like avatars or product photos with unique keys), a much longer TTL avoids repeated, unnecessary re-optimization of the same file.

Pattern 1: Public Bucket URLs

How it works: the object is publicly readable, so its S3 URL works for anyone, forever — no signing, no expiry, no server involvement at all.

Browser → S3 object URL directly (no server request needed)

This is the right call for genuinely non-sensitive assets: blog cover images, public product photos, avatars a user chose to make visible. It's also the fastest pattern to build, since there's no backend logic involved in displaying the image at all.

Step 1: Allow Public Reads on Specific Objects

Rather than making the whole bucket public (don't do that), scope a bucket policy to just the folder holding public assets:

// s3-public-read-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadForPublicFolder",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::devstacked-uploads-demo/public/*"
    }
  ]
}

What's happening here: this policy only opens read access to objects under the public/ prefix — everything else in the bucket (like uploads/ or large-uploads/ from the upload guide) stays private by default.

⚠️ Important: If your bucket still has Block all public access fully enabled (from the upload guide's setup), AWS will reject this policy outright with an "access denied" error, even though the policy itself is valid. Go to your bucket → Permissions → Block public access and uncheck the two bucket policy Block Public Access settings while leaving the ACL-related settings enabled. This allows a scoped public bucket policy without relying on public ACLs.

⚠️ Common Mistake: Applying a public-read policy to the entire bucket instead of a scoped prefix. If your upload code ever writes a sensitive file without thinking to change the key, it becomes silently public the moment it lands.

Step 2: Store the Public URL Format

// lib/s3-urls.ts
const BUCKET_NAME = process.env.S3_BUCKET_NAME!;
const REGION = process.env.AWS_REGION!;

export function getPublicUrl(key: string): string {
  // encodeURIComponent handles spaces and special characters in the key —
  // a raw key like "public/my photo.jpg" produces an invalid URL without it
  const encodedKey = key.split("/").map(encodeURIComponent).join("/");
  return `https://${BUCKET_NAME}.s3.${REGION}.amazonaws.com/${encodedKey}`;
}

Since public URLs never expire and never need signing, you can build this string anywhere — no API call needed, not even to your own server.

⚠️ Common Mistake: Encoding the whole key with a single encodeURIComponent(key) call. That also escapes the / characters in the path, turning public/avatars/photo.jpg into a single garbled segment instead of a valid nested path. Encode each path segment individually, as shown above.

Step 3: Render It with next/image

// components/public-avatar.tsx
import Image from "next/image";
import { getPublicUrl } from "@/lib/s3-urls";

interface Props {
  objectKey: string; // e.g. "public/avatars/uuid-photo.jpg"
  alt: string;
}

export function PublicAvatar({ objectKey, alt }: Props) {
  return (
    <Image
      src={getPublicUrl(objectKey)}
      alt={alt}
      width={96}
      height={96}
      className="rounded-full object-cover"
    />
  );
}

Because we added the S3 hostname to remotePatterns earlier, Next.js is happy to optimize this image — resizing, format conversion (like WebP), and lazy loading all work exactly like they would with a local image.

Pattern 2: Presigned GET URLs for Private Files

How it works: the object stays fully private in S3. When a user is allowed to view it, your server generates a short-lived, signed URL — just like the presigned upload URLs from the upload guide, but for reading instead of writing.

Browser → Next.js (ask "can I see this file?") → gets presigned GET URL
Browser → S3 directly, using that URL, before it expires

This is the mirror image of the presigned upload pattern: same idea, opposite direction. Use it for anything user-specific — private documents, someone's uploaded ID photo, a paid course's video thumbnail.

Step 1: Generate the Presigned GET URL

// app/api/image-url/route.ts
import { NextRequest, NextResponse } from "next/server";
import { GetObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
import { s3Client } from "@/lib/s3-client";
import { auth } from "@/lib/auth"; // your auth solution of choice

const URL_EXPIRY_SECONDS = 300; // 5 minutes

export async function GET(request: NextRequest) {
  const key = request.nextUrl.searchParams.get("key");
  const session = await auth();

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

  if (!key || !key.startsWith(`private/${session.userId}/`)) {
    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
  }

  const command = new GetObjectCommand({
    Bucket: process.env.S3_BUCKET_NAME!,
    Key: key,
  });

  const url = await getSignedUrl(s3Client, command, {
    expiresIn: URL_EXPIRY_SECONDS,
  });

  return NextResponse.json({ url });
}

What's happening here:

We check the user is authenticated before doing anything else — a presigned URL is only as safe as the check that generates it
The key check (key.startsWith('private/${session.userId}/')) makes sure a user can only ever get a signed URL for their own files, not someone else's, even if they know another user's exact key
expiresIn: 300 means the link works for 5 minutes — long enough to load the image, short enough that a copied link goes stale quickly

⚠️ Common Mistake: Generating a presigned GET URL without checking who's asking. It's easy to think "it expires, so it's safe" — but a 5-minute window is still plenty of time for a leaked link to be misused if you skip the ownership check.

Step 2: Fetch and Display It Client-Side

// components/private-image.tsx
"use client";

import { useEffect, useState } from "react";
import Image from "next/image";

interface Props {
  objectKey: string;
  alt: string;
}

export function PrivateImage({ objectKey, alt }: Props) {
  const [url, setUrl] = useState<string | null>(null);

  useEffect(() => {
    let cancelled = false;

    fetch(`/api/image-url?key=${encodeURIComponent(objectKey)}`)
      .then((res) => res.json())
      .then((data) => {
        if (!cancelled) setUrl(data.url ?? null);
      });

    return () => {
      cancelled = true;
    };
  }, [objectKey]);

  if (!url) {
    return <div className="h-24 w-24 rounded-lg bg-muted animate-pulse" />;
  }

  return (
    <Image
      src={url}
      alt={alt}
      width={96}
      height={96}
      unoptimized // presigned URLs change every load, so caching them via the optimizer adds little value
      className="rounded-lg object-cover"
    />
  );
}

Why unoptimized? Next.js's image optimizer caches the optimized result by URL. Since a presigned URL is different every single time it's generated, the optimizer would just be doing wasted work re-processing an image that's already the right size coming out of S3. Skipping optimization here is the correct call, not a shortcut.

This flag only bypasses Next.js's own optimization pipeline — it doesn't disable the browser's normal HTTP caching. The browser can still cache the actual image bytes according to whatever Cache-Control header S3 returns on the object itself. Many developers assume unoptimized means "never cached at all," which isn't true — it just means Next.js won't resize, re-encode, or store its own separate optimized copy of this particular image.

💡 Tip: For a server component instead of a client component, you can generate the presigned URL directly during the render on the server — no useEffect, no loading flicker, no extra round trip. Reach for the client-side version above only when the key isn't known until after the page has already loaded.

Pattern 3: CloudFront CDN Delivery

How it works: instead of the browser talking to S3 directly, it talks to a CloudFront distribution — a CDN that sits in front of your bucket, caches responses at edge locations close to your users, and can serve either public or signed content.

Browser → CloudFront (edge location near the user) → S3 (only on a cache miss)

Think of it like the difference between calling a single warehouse for every order versus having regional distribution centers — most requests get served from somewhere nearby instead of the original source every time.

This pattern matters once you have real traffic: it cuts latency, reduces direct load (and cost) on your S3 bucket, and gives you one clean domain to serve images from instead of raw S3 hostnames.

Step 1: Create a CloudFront Distribution

This is the part most tutorials gloss over, so let's walk through it fully — this guide is meant to get you a working setup, not just a conceptual overview.

a) Create the distribution

In the AWS Console under CloudFront → Distributions → Create distribution:

Under Origin domain, click into the field and select your S3 bucket from the dropdown (it appears automatically once you start typing the bucket name)
Leave Origin path empty unless you want CloudFront to only serve a subfolder of your bucket
Under Viewer protocol policy, choose Redirect HTTP to HTTPS
Leave the rest of the defaults for now and click Create distribution

Creation takes a few minutes to fully deploy — CloudFront needs to propagate your distribution to edge locations worldwide before it's live everywhere.

b) Attach Origin Access Control (for private objects)

If your bucket (or the folder you're serving) is private, you need CloudFront to be the only thing allowed to read from it directly:

Open your distribution → go to the Origins tab → select your origin → click Edit
Under Origin access control settings, choose Origin access control settings (recommended)
Click Create control setting, give it a name, and leave "Sign requests" as the default
Save — CloudFront will show a banner warning that the bucket policy still needs updating. That's expected; that's the next step.

c) Update the bucket policy to allow CloudFront

AWS actually generates the exact policy JSON for you at the end of step (b) — look for a "Copy policy" button in that same banner. It looks like this:

// s3-cloudfront-oac-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCloudFrontServicePrincipal",
      "Effect": "Allow",
      "Principal": { "Service": "cloudfront.amazonaws.com" },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::devstacked-uploads-demo/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::123456789012:distribution/EXAMPLE_ID"
        }
      }
    }
  ]
}

Paste this into your bucket → Permissions → Bucket policy. If you also have the public-read policy from Pattern 1, both statements can coexist in the same policy's Statement array — one scopes access to CloudFront's service principal, the other to Principal: "*" under the public/ prefix.

⚠️ Common Mistake: Copying an OAC policy example from an older tutorial that references the deprecated Origin Access Identity (OAI) instead of OAC. AWS now recommends OAC for all new distributions — OAI still works but lacks OAC's support for all S3 request types and encryption options.

d) Get your CloudFront domain

Once the distribution's status shows Enabled (back on the distributions list), copy the value under Domain name — it looks like d111111abcdef8.cloudfront.net. That's the CLOUDFRONT_DOMAIN value you'll use in the code below. If you own a custom domain, you can also attach it under Alternate domain names (CNAMEs) with a matching ACM certificate, but the default .cloudfront.net domain works fine to get started.

⚠️ Common Mistake: Setting up CloudFront in front of a bucket but forgetting to update the bucket policy to allow the CloudFront OAC principal. Without it, CloudFront gets a 403 from S3 on every request, which looks like a CloudFront bug but is actually a permissions gap between the two services.

Step 2: Serve Public Assets Through CloudFront

For public assets, this is a one-line change from Pattern 1 — swap the S3 hostname for your CloudFront domain:

// lib/s3-urls.ts
const CLOUDFRONT_DOMAIN = process.env.CLOUDFRONT_DOMAIN!; // e.g. "d111111abcdef8.cloudfront.net"

export function getPublicUrl(key: string): string {
  return `https://${CLOUDFRONT_DOMAIN}/${key}`;
}

Nothing else about Pattern 1's code changes — same next/image component, same remotePatterns entry (already added in setup), just a faster, cached path to the same file.

Step 3: Serve Private Assets with Signed CloudFront URLs

For private files behind CloudFront, you sign the CloudFront URL itself instead of the S3 URL. This needs a CloudFront key pair rather than your IAM credentials:

// lib/cloudfront-signer.ts
import { getSignedUrl } from "@aws-sdk/cloudfront-signer";

const CLOUDFRONT_DOMAIN = process.env.CLOUDFRONT_DOMAIN!;
const PRIVATE_KEY = process.env.CLOUDFRONT_PRIVATE_KEY!;
const KEY_PAIR_ID = process.env.CLOUDFRONT_KEY_PAIR_ID!;

export function getSignedCloudFrontUrl(key: string): string {
  return getSignedUrl({
    url: `https://${CLOUDFRONT_DOMAIN}/${key}`,
    keyPairId: KEY_PAIR_ID,
    privateKey: PRIVATE_KEY,
    dateLessThan: new Date(Date.now() + 5 * 60 * 1000).toISOString(), // 5 minutes
  });
}

Install the extra package this needs:

npm install @aws-sdk/cloudfront-signer

What's happening here: getSignedUrl from the CloudFront signer package works conceptually the same as the S3 presigner from Pattern 2 — it appends signed query parameters that CloudFront checks before serving the file — but it's signed with a dedicated CloudFront key pair, not your regular IAM credentials.

Where to create that key pair:

In the AWS Console, go to CloudFront → Key management → Public keys → Create public key
This requires an RSA key pair. Generate one locally first:

   openssl genrsa -out private_key.pem 2048
   openssl rsa -pubout -in private_key.pem -out public_key.pem

Paste the contents of public_key.pem into the Create public key form and save
Go to Key management → Key groups → Create key group, and add the public key you just created to it
Back in your distribution's Behaviors tab, edit the relevant behavior and set Restrict viewer access to Yes, then select your key group under Trusted key groups
Note the Key ID shown after creating the public key — that's your CLOUDFRONT_KEY_PAIR_ID. The contents of private_key.pem (never the public key) go into CLOUDFRONT_PRIVATE_KEY

⚠️ Common Mistake: Adding the public key to CloudFront but forgetting step 5 — setting Restrict viewer access on the actual behavior. Without that, CloudFront still serves the file to anyone, signed URL or not, because nothing told it signing was required in the first place.

You'd call this the same way as Pattern 2's route handler — check the requesting user owns the file, then return the signed CloudFront URL instead of a signed S3 URL.

💡 Tip: If most of your private files belong to logged-in users viewing many images per page (a dashboard, a gallery), look into signed cookies instead of signed URLs. One signed cookie can authorize access to many files at once, instead of generating and re-fetching a fresh signed URL per image.

Which Pattern Should You Actually Use?

	Public Bucket URLs	Presigned GET URLs	CloudFront CDN
Setup complexity	Low — one bucket policy	Medium — auth check + route handler	Higher — distribution, OAC, key pairs
Latency	Depends on bucket region	Depends on bucket region	Low — served from nearby edge locations
Caching	Browser cache only	Effectively none (URL changes each time)	Edge-cached, huge win at scale
Access control	None — anyone with the URL	Per-request, ownership-checked	Optional — public or signed
Best for	Non-sensitive, low-to-medium traffic assets	Private, user-specific files	Any file type at real scale

Situation	Pattern
Blog covers, public product photos, anything anyone can see	Public bucket URLs
Small app, low traffic, simplicity matters more than speed	Public bucket URLs
Private user documents, receipts, anything tied to one account	Presigned GET URLs
You need an ownership check before showing the file	Presigned GET URLs
Public images at real scale — you want edge caching and lower latency	CloudFront (public)
Private files at scale, or many private images per page	CloudFront (signed URLs or cookies)

A common real-world setup uses all three at once: public marketing assets served through CloudFront for speed, private user uploads gated by presigned URLs (or signed CloudFront URLs once traffic grows), all coming from the same bucket you set up in the upload guide.

Frequently Asked Questions

Can I just use a plain `<img>` tag instead of next/image?

Yes, especially for presigned URLs that change on every load, where next/image's optimization caching adds little value anyway. next/image is worth it for public, stable URLs where resizing and format conversion (WebP/AVIF) genuinely save bandwidth.

Do I need CloudFront if I'm only using presigned URLs?

Not necessarily. Presigned URLs work fine served directly from S3. CloudFront becomes worth the setup once you care about latency at scale or want to reduce direct requests hitting your bucket — it's a performance and cost optimization, not a requirement for private files to work.

Why does my S3 image 403 even though I set a bucket policy?

Usually one of two things: the object key in your policy's Resource doesn't actually match where the file lives, or — if you're using CloudFront with Origin Access Control — the bucket policy hasn't been updated to allow the CloudFront principal specifically, separate from any public-read policy.

Should I store the S3 key or the full URL in my database?

Store the key (e.g. public/avatars/uuid.jpg), not the full URL. Keys never change even if you switch from raw S3 URLs to CloudFront later, rename your bucket, or move regions — you'd just update the URL-building function, not every database row.

Can I resize images on the fly instead of storing multiple sizes?

Yes — a common pattern is a CloudFront distribution with a Lambda@Edge or CloudFront Function that resizes images based on query parameters the first time they're requested, then caches the result. That's a bigger setup than this guide covers, but it's the natural next step once next/image's built-in optimization isn't enough for your use case.

Why does my image download instead of render in the browser?

This happens when the object's Content-Disposition header is set to attachment instead of inline — usually because it was uploaded with that metadata set explicitly, or a client library defaulted to it. Fix it by setting the header correctly at upload time:

new PutObjectCommand({
  Bucket: process.env.S3_BUCKET_NAME!,
  Key: key,
  Body: buffer,
  ContentType: file.type,
  ContentDisposition: "inline", // ensures browsers render it instead of downloading it
})

If files are already uploaded with the wrong header, you can fix them without re-uploading by copying the object onto itself with CopyObjectCommand and the corrected ContentDisposition and MetadataDirective: "REPLACE".

Wrapping Up

You now have three complete patterns for displaying S3 images in Next.js 16 — plain public URLs for anything non-sensitive, presigned GET URLs for anything private and user-specific, and CloudFront for when performance and scale start to matter. Paired with the upload guide, you've got the full loop covered: getting files into S3 the right way, and getting them back out safely and fast.

From here, natural next steps include adding on-the-fly image resizing at the CDN layer, setting up signed cookies for pages with many private images, or wiring up automatic thumbnail generation with S3 Event Notifications when a file finishes uploading.

📦 Source Code: View on GitHub

DEV Community: Syed Muhammad Ali

How to Send Newsletters & Bulk Emails with Resend in Next.js 16

Why emails.send() Stops Working for Newsletters

Which Resend Feature Should You Actually Use?

The New Model in One Minute

Prerequisites

Step 1: Stop Storing Subscribers Only in Your CMS

Handling Duplicate Contacts

Step 2: Send the Newsletter with the Broadcast API

Scheduling Broadcasts

Step 3: Bulk Sending Different Content Per Recipient

Step 4: Preventing Timeouts on Larger Sends

Option A: Run the send after the response, with after()

Option B: Offload to a real queue for very large lists

Broadcast vs. Batch vs. Queue: Quick Comparison

Step 5: Avoid Duplicate Sends on Retry

Step 6: Track Bounces and Complaints with Webhooks

A Quick Pre-Send Checklist

Frequently Asked Questions

Do I still need resend.emails.send() for anything?

What happened to Audiences?

How many subscribers can a Broadcast actually handle?

What's the real difference between Batch and Broadcast?

Will my subscribers get duplicate emails if something fails halfway through?

Do I need a database of my own if I'm using Resend Contacts?

What happens if someone subscribes twice?

Can I schedule a newsletter to go out tomorrow morning?

Why are some endpoints Server Actions and others Route Handlers?

Should I use Broadcast or Batch for newsletters?

Wrapping Up

Continue Learning

Route Handlers Explained in Next.js 16 (Beginner's Guide)

What Are Route Handlers, Exactly?

Why This Is Tricky (For Beginners)

Route Handlers vs. Pages Router API Routes

Route Handlers vs. Server Actions

Prerequisites

Step 1: The route.ts File Convention

Step 2: Supported HTTP Methods

Response vs. NextResponse, Request vs. NextRequest

Step 3: Reading Data From the Request

Step 4: Dynamic Route Segments

Step 5: Caching Behavior

If You're Using Cache Components ("use cache")

A Quick Word on the Edge Runtime

Step 6: Handling Webhooks (Raw Body Access)

Step 7: Adding CORS Support

Route Resolution Rules to Know

Frequently Asked Questions

Can I use Route Handlers with the Pages Router?

Do I need Route Handlers if I'm already using Server Actions?

Why isn't my GET Route Handler getting cached?

Can I return something other than JSON?

How do I protect a Route Handler so only logged-in users can call it?

Wrapping Up

Image Optimization in Next.js 16: The Complete 2026 Guide

<img> vs next/image at a Glance

Why Image Optimization Is Tricky

Prerequisites

Step 1: Replace <img> with next/image

Step 2: Local vs. Static Imports

Step 3: Configure Remote Images with remotePatterns

Step 4: Responsive Images with sizes

Step 5: fill for Unknown Dimensions

Step 6: Choose the Right Loading Strategy

Step 7: Controlling Quality — qualities Is Now Required Config

Step 8: Choosing Output Formats — AVIF vs. WebP

Step 9: Blur Placeholders for a Smoother Load

Step 10: SVGs and Skipping Optimization

Step 11: Preserving SEO Rankings with overrideSrc

Step 12: Custom Markup with getImageProps()

Advanced Configuration

Custom Image Loaders (Skipping Next's Built-In Optimizer)

Caching Behavior with minimumCacheTTL

Self-Hosting Behind a Proxy or CDN

Real-World Example: A Blog Post Page

Image Optimization Checklist

Frequently Asked Questions

Do I still need to use the priority prop?

Should I use preload for my hero/LCP image?

Why `emails.send()` Stops Working for Newsletters

Option A: Run the send after the response, with `after()`

Do I still need `resend.emails.send()` for anything?

Step 1: The `route.ts` File Convention

If You're Using Cache Components (`"use cache"`)

`<img>` vs `next/image` at a Glance

Step 1: Replace `<img>` with `next/image`

Step 3: Configure Remote Images with `remotePatterns`

Step 4: Responsive Images with `sizes`

Step 5: `fill` for Unknown Dimensions

Step 7: Controlling Quality — `qualities` Is Now Required Config

Step 11: Preserving SEO Rankings with `overrideSrc`

Step 12: Custom Markup with `getImageProps()`

Caching Behavior with `minimumCacheTTL`

Do I still need to use the `priority` prop?

Should I use `preload` for my hero/LCP image?

How do I keep my image SEO rankings when migrating from `<img>` to `next/image`?

Why is my `quality` prop being ignored?

Can I use `next/image` with images from an external CMS?

What's the difference between `width`/`height` and the actual rendered size?

Where Does `STRIPE_WEBHOOK_SECRET` Come From?

What's the difference between `payment_intent.succeeded` and the client-side success redirect?

Add a `robots.txt`

Add a `sitemap.xml`