In this tutorial, I'll walk you through exactly how I built it, from the backend serverless function that talks to Google's Gemini API, to the React chat widget that displays the AI's response as it's being generated.

By the end of this tutorial, you'll understand:

1. How to set up a Vercel Serverless function that calls Gemini and streams its response back to the browser in small text chunks.

2. Why that approach makes a chatbot feel faster and more responsive than waiting for the entire reply to come back at once.

3. How to build a React component that reads that streaming response and updates the chat window in real time as new text arrives.

We'll also test the endpoint with curl before wiring up the UI, and we'll cover how to actually deploy the whole thing to Vercel.

All of this revolves around a technique called plain-text chunk streaming. Rather than waiting for the AI to generate its entire response and then sending it all back to the browser at once, the serverless function streams the response as a series of small text chunks, writing each one to the browser as soon as it's ready.

This is what gives the chatbot that responsive, "typing" feel you've probably seen in modern AI chat interfaces, instead of a long pause followed by the full answer appearing all at once.

What We'll Cover:

• 🧩 Architecture Overview

• ✅ Prerequisites

• 📜 API Contract

• ⚙️ Backend (the Vercel Serverless Function)

• 🧪 Testing the Endpoint Before Wiring Up the UI

• 🎨 Frontend: Reading the Response Stream

• 🚀 Deploying

• ⚠️ A Note on CORS for Embedded Widgets

• 🎉 Conclusion

🧩 Architecture Overview

The application is built from two main pieces. The UI component is a React chat widget, where the user types a message and the AI's response gets rendered back to them as it streams in. The backend is a Vercel serverless function (for example, api/chat) that validates the incoming request, calls Gemini, and streams the output back to the browser.

You can read more about Vercel's serverless functions in their official documentation.

Here's how the whole flow works, from start to finish: the browser sends a request to the Vercel function, the Vercel function calls the Gemini API, and Gemini's response is streamed back to the browser chunk by chunk.

In practice, this means the backend sends the response to the frontend in small pieces as they become available, rather than making the user wait for the entire response to be generated before they see anything at all.

✅ Prerequisites

Before you get started, make sure you have the following in place:

• Node.js installed locally (Node 18 or later)

• A Gemini API key 🔑 from Google AI Studio

• A Vercel account and the Vercel CLI

• The @google/genai package installed in your function's project, which you can add by running npm install @google/genai

You'll also want to store your key in an environment variable called process.env.GOOGLE_API_KEY for local development, and add that same variable in your Vercel project's dashboard (under Settings and then Environment Variables) before deploying, so the API key gets picked up correctly once the application is hosted.

📜 API Contract

Before diving into the code, it's worth taking a moment to understand the "contract" between the frontend and backend – in other words, what the frontend is expected to send, and what the backend expects to receive in return.

When a user sends a message in the chat widget, the frontend makes a POST request to /api/chat with a JSON body containing two things: the message the user just typed, and the résumé data that's already loaded into the app (since this particular chatbot is acting as a résumé coach). The backend then uses both pieces of information together to generate a response that's actually relevant to that user's résumé, rather than a generic reply.

Request:

POST /api/chat
{
  "message": "How can I improve my resume summary?",
  "resume": { "name": "...", "experience": [...], "skills": [...] }
}

⚙️ Backend (the Vercel Serverless Function)

This is the heart of the application: a single Vercel serverless function that receives the chat request, validates it, passes it along to Gemini, and streams the AI's response back to the browser as it's generated.

Below is the full handler, and I'll walk through what each part of it is doing once you've had a look at the whole thing.

const { GoogleGenAI } = require("@google/genai");
const ai = new GoogleGenAI({
    apiKey: process.env.GOOGLE_API_KEY,  // GOOGLE_API_KEY can be configured in Vercel
});
const MAX_TEXT_LENGTH = 2000;
const MAX_ARRAY_LENGTH = 50;

function sanitizeString(input = "") {
    // sanitize your input string here
}

function sanitizeObject(obj = {}) {
    // sanitize your resume object
}

const allowCors = fn => async (req, res) => {

    res.setHeader('Access-Control-Allow-Origin', '<<your web app url goes here>>');
    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');

    // ✅ Handle preflight request
    if (req.method === 'OPTIONS') {
        return res.status(200).end();
    }
    // another option
    res.setHeader('Access-Control-Allow-Methods', 'GET, HEAD, OPTIONS, POST, PUT, DELETE')
    res.setHeader(
        'Access-Control-Allow-Headers',
        'X-CSRF-Token, X-Requested-With, Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Api-Version'
    )
    if (req.method === 'OPTIONS') {
        res.status(200).end()
        return
    }
    return await fn(req, res)
};

const handler = async (req, res) => {

    if (req.url === '/api/chat' && req.method === 'POST') {

        const { message, resume } = req.body || {};

        const safeMessage = sanitizeString(message);
        const safeResume = sanitizeObject(resume);

        if (!safeMessage) {
            return res.status(400).json({ error: "Invalid message" });
        }

        if (!safeMessage || !safeResume) {
            return res.status(400).json({ error: 'Missing message or resume data' });
        }

        try {
            const stream = await ai.models.generateContentStream({
                model: "<<GEMINI MODEL GOES HERE>>",
                contents: `
            You are a professional Resume Coach AI.

            - Always respond clearly, politely, and professionally.
            - <<Add descriptive instruction for the prompt based on your requirement>>
            - Resume data:
${JSON.stringify(safeResume, null, 2)}

User question:
${safeMessage}
`,
            });
            res.setHeader("Content-Type", "text/plain; charset=utf-8");
            res.setHeader("Cache-Control", "no-cache");

            for await (const chunk of stream) {
                const text = chunk.text;
                if (text) {
                    res.write(text);
                }
            }

            res.end();
        } catch (error) {
            console.error('Gemini Error:', error);
            res.status(500).json({ error: 'AI request failed' });
        }
    }

    // I have added a health check for testing the handler
    if (req.url === '/api/chat?type=healthcheck' && req.method === 'GET') {
        res.status(200).json({ message: 'Hello from the chat endpoint!' });
    }
}

module.exports = allowCors(handler)

Now let's break that down piece by piece:

• Setting up the Gemini client: At the top of the file, we create a GoogleGenAI client using the API key stored in the GOOGLE_API_KEY environment variable. This client is what we'll use to actually talk to Gemini throughout the rest of the function.

• Sanitizing the input: Before we do anything with the incoming request, we run the message and résumé through sanitizeString and sanitizeObject. These functions strip out anything unexpected or oversized, so we're never passing untrusted user input straight through to the AI without a check first.

• Handling CORS: The allowCors wrapper function sits around our handler and takes care of Cross-Origin Resource Sharing. Since the chat widget might be embedded on a different domain than the Vercel function itself, we need to explicitly allow requests from that domain and handle the OPTIONS preflight request that browsers automatically send before the real POST request goes through.

• Validating the request: Inside the handler itself, we check that both message and resume made it through sanitization successfully. If either one is missing or invalid, we return a 400 error right away instead of wasting a call to Gemini on a request we already know is bad.

• Calling Gemini and streaming the response: This is the key part of the whole tutorial. Instead of calling a regular "generate content" method and waiting for the full response to come back, we call generateContentStream, which returns an async iterable. We loop over that stream with a for await...of loop, and every time a new chunk of text comes in, we immediately write it to the response with res.write(text). This is exactly what lets the browser start receiving text before Gemini has even finished generating the full answer.

• Error handling and the health check: If anything goes wrong while talking to Gemini, we catch the error, log it, and return a 500 response so the frontend knows something failed. There's also a simple GET health check endpoint you can hit to confirm the function is up and running before you start testing the actual chat flow.

🧪 Testing the Endpoint Before Wiring Up the UI

Before you start building out the frontend, it's a good idea to confirm that the serverless function is actually streaming chunks the way you expect. You can do that with a simple curl request.

curl -N -X POST "https://YOUR_APP.vercel.app/api/chat?type=chat" \
  -H "Content-Type: application/json" \
  -d '{"message":"Give me 3 resume summary tips","resume":{"name":"Test"}}'

The -N flag disables curl's output buffering, so you'll see the text appear incrementally in your terminal rather than all at once. That's your confirmation that the streaming is working end to end, before you've written a single line of frontend code.

🎨 Frontend: Reading the Response Stream

Here's a screenshot of the chat widget UI I built in React:

We won't walk through building that UI from scratch here. The layout, styling, and message list are really up to you and your own design preferences.

What we will cover is the function that actually powers it: the code behind the send button, which takes what the user typed, sends it off to our serverless function, and reads back the streaming response so the widget can display the AI's reply as it arrives, piece by piece, the way you see it happening in the screenshot above.

Before jumping into that function, here's the shell it lives inside, so you can see where it fits in the component:

function ChatWidget({ resume }) {
  const [messages, setMessages] = useState([]);
  const [input, setInput] = useState("");
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  async function sendMessage() {
    // ...actual function is added below
  }

  return (
    <div className="chat-widget">
      {/* message list, input box, and a send button that calls sendMessage() */}
    </div>
  );
}

That's the shell the function lives in: state for the message list, the input box, a loading flag, and an error slot. sendMessage is what fires when the send button is clicked.

Here's the full function, sendMessage, which runs whenever the user types a prompt and clicks send. This is the piece of code that connects the UI shown above to the backend we just built.

async function sendMessage() {
    const messageText = input.trim();
    if (!messageText || loading) return;

    const userMessage = { role: "user", text: messageText };
    setMessages((message) => [...message, userMessage]);
    setInput("");
    setLoading(true);
    setError(null);

    try {
      const res = await fetch("<<YOUR VERCEL SERVERLESS FUNCTION URL GOES HERE>>/api/chat", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ message: messageText, resume })
      });

      if (!res.ok) {
        throw new Error(`Failed to get response: ${res.status}`);
      }

      const reader = res.body.getReader();
      const decoder = new TextDecoder();

      let fullText = "";
      setMessages((message) => [...message, { role: "assistant", text: "" }]);

      while (true) {
        const { value, done } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        fullText += chunk;

        setMessages((message) => {
          const updated = [...message];
          updated[updated.length - 1] = { role: "assistant", text: fullText };
          return updated;
        });
      }

    } catch (err) {
      setError("Failed to send message. Please try again.");
      setMessages((m) => [...m, {
        role: "assistant",
        text: "Sorry, I encountered an error. Please try again later."
      }]);
    } finally {
      setLoading(false);
    }
  }

Here's what's happening step by step:

First, when the user clicks send, we grab their typed message and immediately add it to the messages array so it shows up in the chat right away.

Then we send a POST request to our /api/chat endpoint with the message and the résumé data. Once we get a response back, we call res.body.getReader() to get a ReadableStreamDefaultReader on the response body, and we use a TextDecoder to convert each raw chunk of bytes into readable text.

From there, we loop, reading one chunk at a time and appending it to a growing fullText string, and on every iteration we update the last message in the chat with that text.

That loop is exactly what creates the "typing" effect you see in the screenshot above: the assistant's message in the chat widget visibly grows word by word as new chunks arrive, instead of popping in all at once. This pattern is a bit different from the typical fetch().then(res => res.json()) call you're probably used to, so it's worth pausing on if you haven't streamed a fetch response before.

🚀 Deploying

Once you've confirmed that the function and UI both work locally, deploying comes down to three steps:

1. Set your environment variable in Vercel. In your project's dashboard, go to Settings and then Environment Variables and add GOOGLE_API_KEY with the same value you used locally.

2. Update your CORS origin and fetch URL. In the backend, point allowCors's Access-Control-Allow-Origin header at your real deployed domain. In the frontend, point the fetch call at that same deployed function URL instead of localhost.

3. Deploy, using whichever of the two options below fits your workflow.

Option A: Deploy from the CLI

npm install -g vercel   # if you haven't already
vercel login
vercel --prod

vercel login authenticates your machine, and vercel --prod builds and ships straight to production from your project directory. This is a good fit for one-off deploys, or when you want full control over exactly when a deploy happens.

Option B: Deploy via GitHub integration

1. Push your project to a GitHub repository (if it isn't already).

2. In the Vercel dashboard, click Add New and then Project, then select your repository.

3. Vercel auto-detects your framework settings. Confirm them and click Deploy.

4. From then on, every push to your main branch triggers an automatic redeploy.

I've always preferred this option and it has been more convenient if you're actively iterating on the project, since you never have to remember to run a deploy command yourself.

Once the deploy finishes, Vercel will give you a live URL for your app. Test it with the same curl command from earlier, swapping in your production URL, to confirm that streaming is working correctly in production before you consider yourself done.

⚠️ A Note on CORS for Embedded Widgets

If you're planning to embed this chat widget on a website that lives on a different domain than your Vercel app (for example, embedding it as a widget on a marketing site while the function itself is deployed elsewhere), you'll run into CORS restrictions by default. Browsers block requests to a different origin unless the server explicitly allows them.

To handle this correctly, your serverless function needs to respond to the OPTIONS preflight request that the browser automatically sends before the real POST request, and it needs to set the Access-Control-Allow-Origin header to match the domain your widget is actually running on. That's exactly what the allowCors wrapper in the backend code above is doing for you.

🎉 Conclusion

Plain-text chunk streaming is what makes a chatbot feel responsive on Vercel. Because the user sees the response appear gradually, they aren't stuck waiting for the entire answer to be generated before anything shows up on screen.

If you'd like to keep building on this, here are a few natural next steps to consider: adding rate limiting to prevent abuse of the endpoint, adding conversation persistence with something like KV, Redis, or Postgres so chat history isn't lost on refresh, and adding a stop button to the widget so users can cancel a response that's already in the middle of generating.

If you build something with this approach, I'd love to hear about it! What are you planning to build with Gemini and Vercel?

Hope you have a blessed week! 😇

Recently, I faced an issue where Vercel was giving me a warning that I was almost reaching my free tier limit on "Image Optimization - Transformation". After a few trials and errors, I managed to fix that so that it doesn't exceed my free tier unnecessarily.

In this article, I'll explain what the issues were, how I pinpointed the exact cause, and what options I had for resolving them. I'll also walk you through the approach I ultimately chose and how I managed to fix the problem.

So What Was the Problem?

My current website is running on version 5 (Year 2026), which uses a CDN from Cloudflare R2 Object Storage. It also has massive SEO optimization for both web search and AI search.

You can check out the website directly here: fahimbinamin.com. I'm not sure which version you'll be able to see in the domain when you're visiting the website, but it'll always be the latest version.

As version 5 of my website is a multi-page website, I tried to include everything about me under one platform. I have a lot of writing published in multiple places, and I wanted to add all of the articles under the same platform. But I also wanted to make sure that their canonical URLs worked well. This would help the AI crawler/bot understand the original published URL/source. So I incorporated this feature in the 5th version of my website.

This website uses Next.js and Next's image optimization protocol properly. Currently, the codebase is closed source and you won't be able to access it anywhere. But I've shared a screenshot so that you can have a glimpse of how it looks now.

Anyway, to save money, I like to utilize free resources as effectively as possible. For the CDN, I'm using Cloudflare with R2 object storage. All the media you see on my website (images, PDFs, and so on) comes from Cloudflare R2 object storage. It's running via Vercel.

Everything was going smoothly until yesterday, when I noticed an email from Vercel stating that I was approaching my free tier limit for image optimization.

I opened the usage panel expecting to see my own project images: profile photos, project screenshots, and gallery frames. Instead, almost every source image listed was hosted on freecodecamp.org.

This was confusing for a few seconds because I don't host my images on freeCodeCamp. Then I remembered that I actually link to them!

Table of Contents

I've organized the entire article with sections that can help you jump around if you want or need to read any specific section separately.

• Where These Images Actually Come From

• Confirming the Scope

• Two Ways to Fix This Issue

• Which Solution I Chose

• Doing the Migration

• Why This Is the Better Fix Long-Term

• What I Will Do Differently Next Time

• Conclusion

Where These Images Actually Come From

I have cross-posted a lot of my writing to freeCodeCamp over the years. When I backfilled my articles into this site's blog archive, I kept the article bodies intact, including the <img> tags pointing at freeCodeCamp's and Hashnode's CDNs (as those were the places where the screenshots had always lived).

The blog renderer wraps every inline image in a BlogImage component:

import Image from "next/image";
 
export default function BlogImage({ src, alt, caption }) {
  return (
    <figure>
      <Image src={src} alt={alt} fill sizes="(max-width: 768px) 100vw, 768px" />
      <figcaption>{caption}</figcaption>
    </figure>
  );
}

next/image actually doesn't care whether the src points at your own domain or someone else's. As long as the host is listed in images.remotePatterns in next.config.ts, Next.js will run it through Vercel's Image Optimization pipeline in this step, including fetching the original, resizing it for every breakpoint, re-encoding to AVIF/WebP, and caching the result.

I had added cdn-media-0.freecodecamp.org, www.freecodecamp.org, and cdn.hashnode.com to that allowlist months ago in two separate commits. I did that specifically so those backfilled images would render instead of breaking.

That actually worked for me in this case. But it also meant that every one of those images (and every responsive size Next.js generated from each one) counted against my Vercel account's free-tier Image Optimization quota. I don't want my quota to be spent carelessly, since it resets monthly and I don't control how many times a crawler or a page load re-triggers a size variant.

Confirming the Scope

Before fixing anything, I wanted real numbers instead of a guess. I grepped every post in content/posts/*.mdx for src="..." attributes pointing at the three external hosts:

src="(https://(?:cdn-media-0\.freecodecamp\.org|www\.freecodecamp\.org|cdn\.hashnode\.com)[^"]*)"

That turned up 691 image references across 33 posts: old screenshots from tutorials going back to 2021, everything from disk-partitioning walkthroughs to CUDA setup guides. All of it was being optimized on someone else's dime (mine) instead of being cached once and served flat. That's what was causing the issue earlier.

When I was looking for solutions, I found two ways that could instantly help me fix the issue quickly.

Two Ways to Fix This Issue

Option 1: Stop optimizing them. Pass unoptimized to next/image for any source that isn't my own CDN. Vercel stops touching those requests entirely.

In that case, the browser fetches the image straight from freeCodeCamp, and there's no resizing or AVIF conversion, and zero quota impact. This means that it will be just a small diff that can be done in minutes.

Option 2: Own the images. Download all 691, re-host them on the Cloudflare R2 bucket I already use for every other image on the site, rewrite the src attributes to point at cdn.fahimbinamin.com, and drop the three external hosts from remotePatterns entirely.

Which Solution I Chose

Option 1 was tempting for how little needed to be touched. But it meant permanently giving up responsive sizing and modern formats for a third of my blog archive, and it left the site depending on freeCodeCamp's CDN staying up and those specific URLs never changing.

Option 2 costs more up front but matches how every other image on the site already works. It also keeps the optimization benefit and removes the external dependency completely. So I went with Option 2.

Doing the Migration

Step 1: Download Everything

I wrote a small Node script that walked every post, matched the same three-host regex, and pulled down each unique URL:

const HOST_RE =
  /src="(https:\/\/(?:cdn-media-0\.freecodecamp\.org|www\.freecodecamp\.org|cdn\.hashnode\.com)[^"]*)"/g;
 
// ...for each match, download to downloaded-images/<slug>/<filename>
// and record oldUrl -> "images/writing/<slug>/<filename>" in url-map.json

Files were organized by post slug specifically to avoid collisions, since a lot of these screenshots share generic names like 2022-01-20_18-50.png across completely different tutorials. Lastly, it was a total of 691 downloads with 0 failures, about 105 MB in total.

Step 2: Upload to R2

I restructured the download folder to mirror the target key prefix (images/writing/<slug>/...) and uploaded it to the bucket using CS Browser. R2 exposes an S3-compatible API and a GUI client handles hundreds of nested files more reliably than dragging a folder through the dashboard.

Step 3: Verify Before Touching content

Before rewriting anything, I spot-checked a couple of the newly uploaded URLs:

curl -s -o /dev/null -w "%{http_code}\n" \
  "https://cdn.fahimbinamin.com/images/writing/automount-a-storage-partition-on-startup-in-linux/HDD-Partition.png"
# 200

Step 4: Rewrite the MDX

A second script read url-map.json and replaced every matching src="..." in content/posts/*.mdx with the equivalent cdn.fahimbinamin.com URL:

content = content.replace(HOST_RE, (match, url) => {
  const entry = urlMap[url];
  if (!entry) return match; // left untouched, logged for review
  return `src="${CDN_BASE}/${entry.cdnPath}"`;
});

After the testing, I found out that a total of 33 files changed, 692 replacements (one image was referenced twice in the same post), and 0 were left unmapped.

Step 5: Clean Up the Config

With no more <Image> references to the external hosts, I removed all three from images.remotePatterns in next.config.ts:

// Removed, no longer needed
{ protocol: "https", hostname: "cdn.hashnode.com", pathname: "/**" },
{ protocol: "https", hostname: "cdn-media-0.freecodecamp.org", pathname: "/**" },
{ protocol: "https", hostname: "www.freecodecamp.org", pathname: "/**" },

I ran a full production build afterward. All 43+ blog posts pre-rendered clean, lint passed, and nothing was broken.

Why This Is the Better Fix Long-Term

The quota problem was really a symptom of a smaller mistake: treating a third-party CDN as if it were infrastructure that I controlled. It rendered fine for months, right up until usage crossed a threshold I wasn't watching closely enough.

unoptimized would have made the warning go away without addressing the issue. But I would have kept depending on freeCodeCamp's URLs staying valid indefinitely, with no optimization to show for it either.

Self-hosting means that every image on this site now goes through the same pipeline, and uses the cache rules and CDN, regardless of where the content originally lived. I didn't want anything that could silently break because someone else changed a URL structure.

What I Will Do Differently Next Time

The two remotePatterns entries for freeCodeCamp and Hashnode were each added months apart, each time because a backfilled post's images were broken and adding the host was the fastest fix.

I never asked myself before, "should this actually be hosted here, or should it live on my own CDN from day one?" That question is cheap to ask before backfilling content and expensive to answer after 691 images and 33 posts are already live pointing outward.

I've written that rule down now, so future backfills download and re-host before a single <img> tag ever points off-domain.

Conclusion

Thank you so much for reading all the way through. I hope that this article will help you if you face the same issue in the future.

To get more content like this, you can follow me on LinkedIn and X. You can also check my website and follow me on GitHub if you're into open source and development. If you like to watch programming and technology-related videos, then you can subscribe to my YouTube channel as well.

We just posted a course on the freeCodeCamp.org YouTube channel that will teach you to use the Vercel AI SDK to create and ship a customer support agent that makes autonomous decisions to either answer questions based on your support docs or search the web in real time.

In this course, you’ll ship a customer support agent that:

• Embeds support docs into a Supabase vector store.

• Uses retrieval and web search as tools, selected on-the-fly based on the user’s question.

• Classifies intents with structured outputs (via generateObject + Zod).

• Answers questions with grounded, trustworthy responses—pulling from your docs when relevant or searching the web in real time when needed

The course covers these topics.

• Explain RAG & embeddings and decide when to use each of them.

• Set up Supabase as a vector store: create tables, embed documents, and handle chunking/text splitting for large files.

• Implement retrieval with Supabase RPC so your agent can fetch the right context for any question.

• Use Vercel AI SDK basics: embeddings and generateText for fast, reliable model calls.

• Produce structured outputs with generateObject and Zod to validate and route intents.

• Call tools with the AI SDK—define schemas, wire execution, and keep everything type-safe.

• Treat retrieval and web search as tools, and compose them into a single agent decision flow.

• Use the OpenAI web search tool to pull fresh, real-time information when your docs aren’t enough.

• Combine it all into a support agent that chooses the best strategy (retrieve, search, or answer directly) and explains its answers.

Watch the full course on the freeCodeCamp.org YouTube channel (2-hour watch).