But there’s a quiet shift happening inside the browser environment that a lot of engineers are completely missing out on.

The modern browser isn’t just a glorified engine for rendering HTML and CSS anymore. It’s turning into a full-blown runtime for local intelligence. We’ve reached a point where you can ship raw machine learning models straight to a user's device and run inference completely client-side. No server trips, no API keys to protect, and once those initial assets load, zero dependency on an internet connection.

This is the reality of Web AI. If you're building for the web today, understanding this paradigm shift is easily one of the most valuable skills you can add to your stack.

In this guide, we’re going to pull back the curtain on how Web AI actually operates under the hood, break down the browser technology stack making it possible, and build a real, working image classifier using Teachable Machine and TensorFlow.js. Along the way, we’ll also set up a live benchmark so you can watch exactly how WebGL and WebGPU stack up against each other in real-time execution speeds.

Prerequisites

To follow along with this tutorial, you should have:

• A working knowledge of JavaScript

• Basic familiarity with HTML and how the browser works

• Google Chrome installed (required for WebGPU support and Chrome's built-in AI APIs)

• A code editor like VS Code with the Live Server extension installed (recommended for running the demo locally)

No prior machine learning experience is required.

Table of Contents

• What is Web AI?

• Browser AI vs Cloud AI

• The Technology Stack

• How to Build AI in the Browser

• Chrome's Built-in AI APIs

• Where Web AI Is Headed

• What You Learned

• Resources

What is Web AI?

Instead of sending data off to a distant cloud server, Web AI lets you run machine learning models directly on the user’s device inside their browser. It uses standard web tech like JavaScript, WebAssembly, and WebGPU to handle all the heavy lifting right then and there.

The simplest definition: intelligence that runs in the browser, without sending your data anywhere.

Most of us already interact with on-device AI every day without realizing it. Think about unlocking an iPhone. The second you lift it, Face ID maps out roughly 30,000 infrared points, feeds that data through a neural network living on Apple's local silicon, matches it against an encrypted embedding, and opens the phone. The whole process takes milliseconds and happens entirely offline.

Browser-based AI works on that exact same core architecture. The only real difference is that we're building on top of shared web standards rather than native hardware APIs. When you spin up a face-tracking model using TensorFlow.js or MediaPipe in Chrome, you're running that exact same pipeline:

Camera input → Local ML model → Local decision

No round trip. No server. The browser is your Neural Engine.

Browser AI vs Cloud AI

There’s no right or wrong answer here. It just depends on what you’re trying to build. Both approaches have their pros and cons, so it’s just a matter of picking the tool that fits your specific use case.

Use browser AI when:

• You need split-second speed for things like tracking gestures or detecting objects live on a webcam

• The app has to work offline (whether it's a PWA or just needs to survive spotty internet)

• Privacy is a hard requirement to keep sensitive data like medical inputs, biometrics, or financial information strictly local

• You want to reduce or eliminate API costs on high-frequency, lightweight predictions

Use cloud AI when:

• You need large models like GPT-4, Gemini Pro, or Stable Diffusion

• You need centralized model updates, A/B testing, or user analytics

• You require serious GPU or TPU compute power

Most production systems actually use a mix of both. Take Google Photos: it handles face detection right on your device so it’s fast and private, but leaves the heavier categorization work for the cloud. Or think of a modern web app that might use TensorFlow.js locally to classify images instantly, but calls the Gemini API when it needs deeper language processing.

This hybrid setup, keeping lightweight intelligence at the edge and heavy compute in the cloud, is usually the sweet spot for most apps.

The Technology Stack

Browser AI isn’t just a single tool – it’s a stacked layer of technologies. Knowing how these layers fit together makes it a lot easier to choose your setup and navigate the trade-offs.

Tensors

Before jumping into any ML framework, you need to understand tensors. Not deeply, just enough of a handle on them so you don't get blindsided by tensor shape errors, because they will happen and they can be tricky to debug.

Think of a tensor as a multi-dimensional grid of numbers. Whether your model is processing images, audio, or text, everything gets converted into this format first. Models only speak numbers, and tensors are the containers that hold them.

A single number       → 0D tensor (scalar):  42
A list of numbers     → 1D tensor (vector):  [0.2, 0.8, 0.5]
A table of numbers    → 2D tensor (matrix):  [[1,2,3],[4,5,6]]
An image              → 3D tensor:           shape [224, 224, 3]
A batch of images     → 4D tensor:           shape [32, 224, 224, 3]

Models accept inputs in specific shapes. If your tensor shape doesn't match the model's expected input, your code breaks. That's why understanding dimensions is practical, not just theoretical.

TensorFlow is literally named after this concept. Tensor + Flow = tensors flowing through neural networks.

Here's how you create tensors in TensorFlow.js:

// 1D tensor — a list of values
const scores = tf.tensor([0.1, 0.7, 0.2]);

// 3D tensor — a single image (height x width x RGB channels)
const image = tf.tensor([
  [[255, 0, 0], [0, 255, 0]],
  [[0, 0, 255], [255, 255, 0]]
]);

// 4D tensor — a batch of 32 images
const batch = tf.zeros([32, 224, 224, 3]);

TensorFlow.js

TensorFlow.js is Google's JavaScript version of TensorFlow. It lets you run pre-trained models right in the browser and, if you really want to, train new ones completely client-side.

The most important concept in TensorFlow.js is the backend, the hardware your model actually runs on. You can switch between backends depending on what the user's device supports, and it makes a significant difference to performance.

await tf.setBackend('webgpu');  // fastest — true GPU compute
await tf.setBackend('webgl');   // very fast — GPU via graphics shaders
await tf.setBackend('wasm');    // fast — near-native CPU speed
await tf.setBackend('cpu');     // slowest — plain JavaScript on CPU

await tf.ready();
console.log('Running on:', tf.getBackend());

In practice, you want to try the fastest available backend and fall back gracefully if a user's browser doesn't support it:

const backends = ['webgpu', 'webgl', 'wasm', 'cpu'];

for (const backend of backends) {
  try {
    await tf.setBackend(backend);
    await tf.ready();
    console.log('Using backend:', backend);
    break;
  } catch {
    continue;
  }
}

WebAssembly

WebAssembly (WASM) basically lets code written in C++ or Rust run inside the browser at near-native speeds. When it comes to AI, this is a big deal because heavy math operations like tensor calculations, data preprocessing, and running compressed models happen way faster in WASM than they ever could in standard JavaScript.

Under the hood, TensorFlow.js's WASM backend is using a compiled C++ runtime. If you're running compressed models on a device's CPU, switching to the WASM backend can make your app anywhere from 2 to 10 times faster than just sticking with regular JavaScript.

await tf.setBackend('wasm');
await tf.ready();

WebGL and WebGPU

This is where browser AI performance gets interesting.

WebGL was originally built for 3D graphics. But developers discovered that the parallel computation that GPUs use for rendering is exactly the kind of parallel computation neural networks need.

TensorFlow.js's WebGL backend encodes tensor operations as graphics shader programs and runs them on the GPU. It works well, but it's a workaround, as WebGL was never designed for this kind of work.

WebGPU is what was actually designed for the job. It launched in Chrome back in April 2023 after six years of collaboration between Apple, Google, Mozilla, Intel, and Microsoft.

Instead of just handling graphics, it's a modern API built from the ground up for general-purpose computing. When it comes to running AI models, it can be 2 to 3 times faster than WebGL, which means you can actually run significantly larger models right in the browser.

Here's how to check for WebGPU support and use it:

if ('gpu' in navigator) {
  console.log('WebGPU is supported');
  await tf.setBackend('webgpu');
} else {
  console.warn('WebGPU not available, falling back to WebGL');
  await tf.setBackend('webgl');
}

await tf.ready();

To enable WebGPU in Chrome for development, go to:

chrome://flags/#enable-unsafe-webgpu → Enable → Restart Chrome

The performance progression across backends looks like this:

MediaPipe

MediaPipe is Google's framework for real-time perception tasks like hand tracking, face mesh detection, pose estimation, and object detection. Think of it as plug-and-play AI for anything that involves a camera.

You don't build these models yourself – you just import them and use them. MediaPipe is what actually powers the background blur in Google Meet and the visual filters in YouTube. Under the hood, it runs on TensorFlow.js and WebAssembly to keep everything moving fast.

You can try all MediaPipe models interactively before writing any code at MediaPipe Studio.

How to Build AI in the Browser

Step 1: Train a Model with Teachable Machine

Teachable Machine is Google's no-code tool for building models. It lets you create custom images, audio, or pose classifiers right from your webcam without needing any machine learning experience. Once you're done, you can export them as TensorFlow.js models that are completely ready to drop straight into your app.

Here's how to get started:

1. Go to teachablemachine.withgoogle.com

2. Choose Image Project, standard image model.

3. Create two or more classes. "Thumbs Up" and "Thumbs Down" is a simple starting point

4. Record examples for each class using your webcam

5. Click Train Model — training happens entirely in your browser

6. Click Export Model and choose TensorFlow.js

When you export, you get three files:

• model.json: The model architecture: layers, input/output shapes, and paths to the weights

• weights.bin: The trained weights stored as binary data

• metadata.json: Class labels, input size, and inference configuration

A note on training data quality

Teachable Machine relies on supervised learning. You give the model labeled examples, and it figures out the underlying patterns. When you're gathering your data, two things matter way more than the sheer number of pictures you take:

• Balance: If one class has significantly more examples than another, the model will be biased toward it. Keep the data roughly equal across classes.

  Variety: Fifty photos from different angles, distances, and lighting conditions will easily outperform two hundred near-identical shots from the same spot. The model needs to understand the concept of a "thumbs up", not memorise one specific photo of your specific thumb.

Keep in mind that the actual machine learning model is usually just a tiny fraction of your overall codebase. The vast majority of what you write is going to be standard JavaScript. At the end of the day, it's just another asset in your stack.

Step 2: Setting up and Writing the Code

Now that you have your model files, set up your project structure like this and create an index.html file:

your-project/
├── index.html
├── model.json
├── weights.bin
└── metadata.json

The model.json, weights.bin, and metadata.json files all go in the same folder as your index.html. The demo loads them from the same directory using const URL = "./".

To run it locally, open the folder in VS Code or your preferred IDE and use the Live Server extension. Just right-click index.html and select Open with Live Server. Opening the file directly in the browser without a server will cause CORS errors when loading the model files.

Step 3: Load the Model and Run Predictions

Paste the following in your index.html file. This demo loads your Teachable Machine model, starts your webcam, and runs continuous predictions in a loop:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Teachable Machine - Webcam + Backend Switch Demo</title>
    <style>
        body {
            font-family: Arial;
            text-align: center;
            margin: 20px;
        }

        #webcam-container {
            margin-top: 20px;
        }

        #label-container {
            margin-top: 10px;
            font-size: 18px;
            font-weight: bold;
        }

        button.backend-btn {
            margin: 5px;
            padding: 8px 16px;
            font-size: 16px;
            cursor: pointer;
        }

        #status {
            margin-top: 10px;
            font-weight: bold;
            color: #0078ff;
        }

        table {
            margin: 20px auto;
            border-collapse: collapse;
            width: 80%;
            max-width: 600px;
        }

        th,
        td {
            border: 1px solid #ccc;
            padding: 10px;
        }

        th {
            background: #0078ff;
            color: white;
        }
    </style>
</head>

<body>
    <h2>AI in the web Demo</h2>

    <div>
        <button class="backend-btn" onclick="switchBackend('cpu')">CPU</button>
        <button class="backend-btn" onclick="switchBackend('webgl')">WebGL</button>
        <button class="backend-btn" onclick="switchBackend('webgpu')">WebGPU</button>
    </div>

    <p id="status">Click a backend to start</p>

    <table>
        <thead>
            <tr>
                <th>Backend</th>
                <th>Load Time (s)</th>
                <th>Inference Time (ms)</th>
                <th>Status</th>
            </tr>
        </thead>
        <tbody id="results"></tbody>
    </table>

    <div id="webcam-container"></div>
    <div id="label-container"></div>

    <script src="https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@latest/dist/tf.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@tensorflow/tfjs-backend-webgpu"></script>
    <script
        src="https://cdn.jsdelivr.net/npm/@teachablemachine/image@latest/dist/teachablemachine-image.min.js"></script>

    <script>
        const URL = "./";
        const resultsTable = document.getElementById("results");
        const statusEl = document.getElementById("status");
        const backends = ["cpu", "webgl", "webgpu"];

        let model, webcam, maxPredictions;
        const backendResults = {};

        // Initialize webcam
        async function initWebcam() {
            if (!webcam) {
                webcam = new tmImage.Webcam(200, 200, true);
                await webcam.setup();
                await webcam.play();
                document.getElementById("webcam-container").appendChild(webcam.canvas);

                const labelContainer = document.getElementById("label-container");
                labelContainer.innerHTML = "";
                for (let i = 0; i < 2; i++) labelContainer.appendChild(document.createElement("div"));
            }
        }

        async function switchBackend(backend) {
            statusEl.innerText = `Switching to ${backend.toUpperCase()}...`;

            await initWebcam();

            try {
                const startLoad = performance.now();
                await tf.setBackend(backend);
                await tf.ready();
                model = await tmImage.load(URL + "model.json", URL + "metadata.json");
                maxPredictions = model.getTotalClasses();
                const endLoad = performance.now();
                const loadTime = ((endLoad - startLoad) / 1000).toFixed(2);

                // Single inference to measure time
                const startInference = performance.now();
                await model.predict(webcam.canvas);
                const endInference = performance.now();
                const inferenceTime = (endInference - startInference).toFixed(1);

                // Store results
                backendResults[backend] = { loadTime, inferenceTime };

                updateTable();

                statusEl.innerText = `${backend.toUpperCase()} ready`;
            } catch (err) {
                console.error(`${backend} not supported:`, err);
                statusEl.innerText = `${backend.toUpperCase()} not supported`;
            }
        }


        function updateTable() {
            resultsTable.innerHTML = "";
            for (let backend of backends) {
                const row = document.createElement("tr");
                const backendCell = document.createElement("td");
                const loadCell = document.createElement("td");
                const inferenceCell = document.createElement("td");
                const statusCell = document.createElement("td");

                backendCell.textContent = backend.toUpperCase();

                if (backendResults[backend]) {
                    loadCell.textContent = backendResults[backend].loadTime;
                    inferenceCell.textContent = backendResults[backend].inferenceTime;
                    statusCell.textContent = "✓";
                } else {
                    loadCell.textContent = "-";
                    inferenceCell.textContent = "-";
                    statusCell.textContent = "-";
                }

                row.appendChild(backendCell);
                row.appendChild(loadCell);
                row.appendChild(inferenceCell);
                row.appendChild(statusCell);
                resultsTable.appendChild(row);
            }
        }

        // Continuous prediction loop
        async function loop() {
            if (webcam && model) {
                webcam.update();
                const prediction = await model.predict(webcam.canvas);
                const labelContainer = document.getElementById("label-container");
                labelContainer.innerHTML = "";
                for (let i = 0; i < maxPredictions; i++) {
                    const p = document.createElement("div");
                    p.textContent = `\({prediction[i].className}: \){(prediction[i].probability * 100).toFixed(1)}%`;
                    labelContainer.appendChild(p);
                }
            }
            requestAnimationFrame(loop);
        }

        loop();
    </script>
</body>

</html>

A few things worth understanding about what this code is doing:

The switchBackend function does more than just swap the backend. Each time you click a backend button, it records how long the model takes to load on that backend and how long a single inference takes. Those numbers go straight into the comparison table so you can see the difference without having to look at console logs.

The loop function runs continuously using requestAnimationFrame. Every frame, it grabs the current webcam image, passes it to the model, and updates the prediction labels on screen. This is what makes the detection feel real-time.

Notice that initWebcam only runs once. It checks if webcam already exists before setting up. Switching backends reloads the model but keeps the same webcam stream running.

Open Chrome DevTools and go to the Network tab while the demo runs. After the model files finish loading, you'll see zero outbound requests. Every prediction is happening entirely in the browser.

Step 4: Switch Backends and Compare Performance

Once the demo is running, click each backend button one at a time: CPU, then WebGL, then WebGPU. The table updates after each switch and shows you the load time in seconds and inference time in milliseconds for each backend side by side.

Here's what you should expect to see:

• CPU will be the slowest with everything running in plain JavaScript

• WebGL will be noticeably faster as the GPU is now handling the tensor operations

• WebGPU will be the fastest with true GPU compute and less overhead than WebGL. The exact numbers depend on your machine, but the gap between CPU and WebGPU is usually significant enough to see immediately in the table.

Note: WebGPU requires Chrome with the flag enabled. If the WebGPU button shows "not supported", go to chrome://flags/#enable-unsafe-webgpu, enable it, and restart Chrome.

Chrome's Built-in AI APIs

Beyond loading your own models, Chrome is rolling out native AI capabilities that you can hook into directly through browser APIs. This means no managing bulky model files, no importing TensorFlow.js, and zero manual setup.

The powerhouse here is Gemini Nano, a lightweight version of Google's Gemini model built to run completely on-device inside Chrome. It handles tasks like smart replies and page summarization right in the browser without ever making a cloud call.

If you want to build with it, you can tap into these experimental APIs that Chrome exposes to developers:

chrome://flags → search "Prompt API for Gemini Nano" → Enable → Restart Chrome

These are still experimental and behind flags. But they show clearly where the platform is heading.

For the full prerequisites and setup guide for Chrome's built-in AI, see the official Chrome AI getting started documentation.

Where Web AI Is Headed

The browser is evolving into something that doesn't really have a clean name yet. It's no longer just a document viewer, and it's not quite a native app runtime either. Instead, it's becoming an intelligent edge node – a piece of infrastructure that can perceive, process, and act all on its own, without constantly phoning home for permission.

A few massive shifts are already well underway:

• Native AI built directly into the platform: AI capabilities are turning into standard browser APIs. Because they're cached and shared across the entire ecosystem, you won't have to re-download massive models for every single domain you visit.

  Browsers designed with AI as their core foundation are already popping up. OpenAI's Atlas browser is a perfect early signal of this trend. Every year, the idea of the browser acting as an intelligent agent platform rather than a simple content renderer gets more concrete.

• The developer shift: For developers, the immediate future is clear: a significant chunk of AI features that currently live on expensive servers will migrate straight to the client side. It won't be everything, but the lightweight, high-frequency, and privacy-sensitive tasks will absolutely make the jump.

WebGPU isn't just a flashy demo technology, and browser inference is definitely not a toy. These are serious production tools, and they're only getting more capable as AI models shrink and user hardware gets more powerful.

If you're currently building an interactive, AI-powered feature, it's well worth pausing to ask yourself: does this actually need a server?

Sometimes the answer is still yes. But more and more often, the answer is a definitive no.

What You Learned

In this tutorial, we covered:

• What Web AI is and how it differs from cloud-based AI

• When to use browser AI versus cloud AI and how a hybrid approach works

• The technology stack behind browser AI: tensors, TensorFlow.js, WebAssembly, WebGL, WebGPU, and MediaPipe

• How to train a custom model with Teachable Machine and export it for the browser

• How to load that model, run it against live webcam input, and manage GPU memory correctly

• How to benchmark WebGL vs WebGPU inference times to measure real performance differences

• How to access Chrome's built-in AI APIs including Gemini Nano

If you found this useful or want to connect, you can find me on Twitter/X or LinkedIn.

Resources

• TensorFlow.js Documentation

• Teachable Machine

• MediaPipe Studio

• WebGPU in Chrome

• Chrome Built-in AI — Getting Started

• Chrome AI Translator API

• Google Web AI Demos on GitHub

• Hugging Face Transformers.js

• WebLLM — Run LLMs in the Browser

• Chrome AI Features — Google Blog

Maybe you were asked to complete twenty fields in one go. You carefully filled everything out, hit Submit — and only then were you told that your password didn't meet some hidden, unspoken requirement. A requirement that was never communicated upfront.

Instead of helpful guidance, you were met with a vague message: “Invalid input." Invalid how, you wonder?

Required fields weren’t marked. There was no real‑time validation. No helpful red outline showing which field was wrong. Just a generic prompt telling you to “go back and correct missing information,” as if you’re supposed to magically know what the system wants.

So you scroll.

You search.

You guess.

And you're now getting frustrated.

The reason you're frustrated is simple: no one enjoys repeating a task they thought they had already completed — especially when the mistakes could've been prevented with clear guidance along the way.

You manage to fill in the form and you tap the Submit button.

Nothing happens.

No loading spinner.

No subtle animation.

No confirmation message.

No success screen.

Just silence. For a brief moment, you’re left wondering: Did it go through? So you tap again. And maybe… one more time.

At this point, you become fed up and you either postpone the signup process to when you have the time, or you may not ever return.

Even if you haven’t experienced this exact scenario, you’ve almost certainly felt the same kind of friction: that moment when a digital interface makes you pause, hesitate, or wonder what you’re supposed to do next.

These frustrations often arise because frontend developers either overlook or are unaware of the essential design principles and theories that underpin a smooth, intuitive user experience.

As a frontend developer, your interface should minimise cognitive load, provide immediate clarity, and guide users effortlessly through every task.

In this handbook, I'll introduce the academic theories that should inform and elevate your frontend decisions.

Table of Contents

• 1.0 Fitts’s Law:

  • 1.1 Use padding wisely

  • 1.2 Use infinite targets

  • Design Takeaway from Fitts Law:

• 2.0 Hick's Law:

  • Design Takeaway from Hick's Law

• 3.0 Gestalt Principles:

  • Key Gestalt Principles:

  • 3.1 Proximity

  • 3.2 Similarity

  • 3.3 Continuity

  • 3.4 Closure

  • 3.5 Figure/Ground

  • 3.6 Common Fate

  • 3.7 Focal Point

  • Design Takeaways from the Gestalt Principles

• 4.0 Von Restorff Effect (The Isolation Effect):

  • Design takeway from Von Restorff

• 5.0 Jakob’s Law

  • Design Takeaway from Jakob's Law

• 6.0 Miller’s Law

  • Design Takeaway from Miller's Law

• 7.0 The Goal-Gradient Hypothesis

  • Design Takeaway from Goal-Gradient Hypothesis

• 8.0 Zeigarnik Effect

  • Design Takeaway from Zeigarnik Effect

• 9.0 Tesla’s Law:

  • Design Takeaway from Tesla's Law

• 10.0 Peak End Rule:

  • Design takeaway from Peak End Rule

• 11.0 Postel’s Law:

  • Design Takeaway from Postel's Law

• 12.0 Doherty Threshold:

  • Design Takeaways from Doherty Threshold

• 13.0 Serial Position Effect (Primacy and Recency):

  • Design Takeaways Serial Position Effect

• 14.0 Occam’s Razor:

  • Design Takeaway from Occam's Razor

• 15.0 Parkinson's Law

  • Design Takeaway for Parkinson's law

• Conclusion

• References

You might wonder what academic theories have to do with frontend development.

The answer is simple. Academic theories aren't abstract ideas. There are the result of rigorous scientific investigation — controlled experiments, validated models, and decades of research into how humans think, learn, perceive, and interact with information.

Because these theories are grounded in evidence rather than opinion, they offer reliable guidance for building interfaces that align with how the human brain actually processes information.

Applying them to frontend development means you're not designing by guesswork or personal preference. Instead, you're applying tested, scientific insights to create clearer, faster, more humane user experiences.

In other words, when you build with academic theory in mind, your frontend becomes more than just visually appealing — it becomes cognitively efficient, behaviourally aligned, and measurably easier for users to navigate.

You can use the following laws and principles to guide your development work. Let’s start by looking at Fitt’s law.

1.0 Fitts’s Law:

Fitts’s law is the brainchild of Paul Fitts. He was among the early psychologists who recognised that many human errors result from flawed design rather than simple human weakness.

During World War II, he studied airplane cockpit layouts and concluded that numerous incidents attributed to pilot error were actually caused by poor design decisions (Hall, 2023; Budiu, 2022).

Here's the formula:

$$T = a + b \cdot \log_2\left(1 + \frac{D}{W}\right)$$

T = Movement Time

D = Distance to the target

W = Width (size) of the target

a, b = Empirically determined constants

Based on his findings, Fitts postulated that the time required to acquire/reach a target is determined by the distance to the target and the size of the target.

Fig 1.0: Illustration of Fitts Law.

From the above, between Target B and Target C, it will be faster to interact with Target C than Target B simply because of the distance (Target B is farther away). Interestingly, though Target A and Target C are at the same distance, Target C will still be faster to interact with and less error-prone because of its larger size.

In simple terms, Fitt’s Law tells us that the time required to move to a target depends on two main factors: the distance to the target and the size of the target. The farther away an element is, the longer it takes to reach. The smaller it is, the more precision it demands, which increases the interaction time and the likelihood of errors.

Conversely, closer and larger targets reduce cognitive load, motor effort, and frustration.

In a nutshell, Fitts’s main message to developers is to reduce the distance users must travel on the screen and to make important buttons large and visually dominant.

Fig 1.1: Showing Call-to-Action buttons are the largest and most visually prominent elements on each screen.

From the image above, you can see that the Call-to-Action buttons on each of the screens are the most visually dominant button and largest in size. They're also placed within the natural region. This makes them faster/easier to interact with.

You should also place your Call-to-Action button within the natural zone. This is a zone on a mobile phone where it's easy to reach with the thumb (as most people use their thumbs to select things on a phone screen). Here's a diagram showing the "natural zone" on a typical smartphone. It's much faster for a user to interact within the "natural zone" than the "hard zone" (see figure).

Fig 1.2: Showing three different zones for buttons placement (natural, stretching and hard region)

1.1 Use Padding Wisely

Fitts' law can be applied to your development by increasing padding wisely. You can also use padding to increase the interactive area. By doing this, you're increasing the size of the targets.

This is important, because imagine a menu that disappears the moment your cursor drifts a few inches away. You’re weren't trying to close it — you simply moved slightly, and suddenly the entire menu collapses. That tiny slip forces you to start the interaction all over again. It’s a small mistake, but it creates a disproportionately frustrating experience.

This happens because the interactive area is too narrow.

That’s why effective padding — or more broadly, generous interactive zones — is essential. By increasing the clickable or hoverable area around a menu, you are increasing the size of the targets, which makes the interaction more stable, more forgiving, and far less cognitively demanding.

This ensures users can move naturally without fear of accidentally “falling off” the target.

1.2 Use Infinite Targets

Another fundamental principle that emerges from Fitt’s Law is the idea of infinite targets. When an interface element is placed at the very edge or corner of a screen, it becomes effectively “infinite” because the cursor can't move beyond the screen boundary. The edge acts as a physical barrier, allowing the user to fling the mouse in that direction without precision or careful aiming.

As a result, corners and edges become the fastest, easiest, and most reliable places for users to access important controls.

This is why operating systems such as Apple’s macOS and Microsoft Windows position their most essential menus and buttons at these locations. The macOS Apple Menu sits in the top‑left corner, Windows historically placed the Start button in the bottom‑left corner, and both systems anchor taskbars, docks, and notification areas along screen edges.

These placements reduce cognitive load, minimise motor effort, and increase interaction speed because users do not need to slow down or correct their cursor movement. The screen itself “catches” the pointer.

In essence, infinite targets transform small interface elements into large, easy‑to‑hit zones simply by leveraging the geometry of the screen.

What this means for you: place your most important and frequently used actions where users can reach them with the least effort. Screen edges and corners act as natural stopping points, meaning users can't overshoot them.

Design Takeaways from Fitts Law:

Place Primary Actions Where the Task Ends:
Placing a submit button at the top‑right forces users to travel all the way back after completing a long form. This increases interaction cost and breaks flow. The best place for a submit button is at the bottom of the form — exactly where the user finishes the task. This aligns with natural reading and interaction patterns.

Keep Related Actions Physically Close:
Separating “Add to Cart” and “Check Out” across opposite sides of the screen forces unnecessary thumb movement. Group related actions to reduce effort and speed up decisions.

Make Primary Targets Large and Visually Dominant:
Your main CTAs (“Subscribe Now,” “Pay Now,” “Create Account,” “Sign Up”) should be the most recognisable elements on the screen. Large, high‑contrast targets reduce errors and improve speed.

Place High‑Value Actions at Screen Edges and Corners:
Edges and corners act as “infinite targets” because the cursor can’t overshoot them. This makes them the fastest, easiest, and most reliable places for critical controls.

A tiny icon in the middle of the screen is hard to hit. The same icon placed at an edge becomes effectively huge because the boundary “catches” the pointer. Also, actions like navigation, primary CTAs, or global controls should live where users can reach them with minimal effort. Avoid burying important actions in the centre of the screen.

Increase Target Size With Generous Padding:
Small interactive zones force users to aim with pixel‑level precision. Adding padding expands the clickable or hoverable area, making interactions easier, faster, and more forgiving.

Prevent Accidental “Fall‑Off” With Larger Hit Areas:
Menus that collapse the moment the cursor drifts slightly create frustration. A wider interactive zone keeps the menu open during natural mouse movement, reducing accidental resets.

Users don’t move perfectly. Interfaces should accommodate slight slips without punishing them. Larger targets reduce cognitive load and eliminate unnecessary frustration. so by increasing the effective size of buttons, menus, and controls, you create interactions that feel stable and predictable, and users can move confidently without fear of losing their place.

To Sum Up: The farther away an element is, the longer it takes to reach. The smaller it is, the more precision it demands, which increases the interaction time and the likelihood of errors. Conversely, closer and larger targets reduce cognitive load, motor effort, and frustration.

2.0 Hick's Law:

Hick’s Law is a psychological principle that describes the relationship between the number of choices presented to a user and the time it takes them to make a decision. It was formulated by William Edmund Hick in 1952 (Yablonski, 2022; Proctor & Scheider, 2018).

The law states that as the number of options increases, the decision time increases logarithmically. In simple terms, more choices slow users down, while fewer choices speed up decision-making.

$$T = a + b \cdot \log_2(n + 1)$$

Where:

T = time to make a decision,

n = number of choices,

b= a constant that depends on the task and the individual

Figure 2.0 illustrates the relationship between user experience, reaction time, and the number of actions.

This is how users feel, for example, when they encounter a form that asks for too much information upfront. The longer the form gets, the more frustrated they become.

Examples of this are overloading menus with too many items, presenting long, unorganised forms, giving too many calls-to-action on one screen, and building nested menus with excessive depth.

All of these create friction and can lead to cognitive overload.

Design Takeaway from Hick's Law

Avoid Overloading Users With Too Many Actions:
Too many buttons, menu items, or choices at once increases cognitive load and slows decision‑making. Users freeze when everything competes for attention.

Keep Navigation Clean and Focused:
Cluttered menus hurt both usability and SEO. Search engines struggle to track overly complex navigation structures, and users struggle to find what matters.

Use Progressive Disclosure to Reduce Complexity:
Hide advanced or rarely used options under “More” or expandable sections. Reveal complexity only when the user needs it.

Break Complex Tasks Into Smaller, Manageable Steps:
Progressive disclosure works beautifully for multi‑step forms and decision flows. Smaller steps reduce overwhelm and improve completion rates.

Group Related Options Into Logical Categories:
Organising actions into meaningful clusters helps users process information faster. For example, placing “Edit” and “Delete” together leverages natural mental grouping.

Video 2.0: Video description of Progressive Disclosure.

From the video above, instead of showing all the menu details at once, it is better to hide them initially. As you can see, the additional information only appears when the arrow down button is pressed. This approach prevents overwhelming the user and keeps the interface clean and focused.

You should also reduce decision anxiety, as too many choices create doubt and friction (as they say, the more you ask from a user, the less you get).

Beyond this, try to use recommended labels, show brief descriptions, provide visual previews, and use comparison tables wisely to show comparison between products especially when they have many characteristics. An example of a comparison table is shown below:

Figure 2.1: A comparison table being used to simplify complex information.

Also, rather than showing advanced configuration options by default, display only the most commonly used settings. Advanced options can be hidden under an expandable section like “Advanced” or “More Settings. This makes your interface less cluttered and more visually organized.

And speaking of visual organization, this is the perfect moment to introduce Gestalt principles — the psychological rules that explain how users naturally group and interpret what they see.

To Sum Up: As the number of options increases, the decision time increases logarithmically.

3.0 Gestalt Principles:

In the 1920s, a group of German psychologists – Max Wertheimer, Kurt Koffka, and Wolfgang Köhlern – introduced what are now known as the Gestalt Principles. Their work sought to understand how humans perceive and interpret visual information (Bustamante, 2023).

The word “Gestalt” is German for “unified whole,” reflecting the core idea behind the theory: people naturally perceive objects as organised patterns and complete forms rather than as separate, disconnected parts.

These principles explain how the human mind structures visual elements to make sense of the world. Over time, they have become highly influential in fields such as design, user experience (UX), psychology, and data visualization, where understanding perception is critical.

Key Gestalt Principles:

3.1 Proximity

Elements that are placed close to each other are perceived as a group, while those spaced far apart are seen as separate. This is why labels are placed directly next to their corresponding input fields.

For example: In a blog feed, the "Title," "Author," and "Date" should have small margins between them (8px), while the space between one blog post card and the next should be much larger (40px). This tells the user's brain: "These three text strings belong to this specific post."

Fig 3:0 Illustration of proximity (Gestalt Principle)

From the fig above, the spacing within the blog feed plays a powerful role in how effortlessly users interpret what they see. When elements sit close together, the brain instinctively treats them as belonging to the same unit. This is why placing the author credit just 8px beneath the title creates an immediate mental link. The viewer doesn’t need to pause or decode who wrote which article; proximity does the cognitive work automatically, forming a tight, intuitive grouping.

Equally important is the generous 40px gap between individual cards. This larger spacing introduces “visual breathing room.” Without it, a feed can quickly collapse into a dense wall of text, overwhelming the user and discouraging exploration. The wider margin establishes a clear boundary—a natural stop-and-start rhythm—that makes each card feel distinct and the entire layout more scannable.

Finally, subtle spacing differences can guide behaviour, not just perception. The slightly larger 12px margin above the read‑more link separates it from the passive information above it. This spacing cues the user that the link represents an action rather than another piece of descriptive text. It’s a small adjustment, but it shifts the element’s role from informational to interactive, helping users understand what they can do next.

Together, these spacing decisions transform a simple list of posts into a structured, intuitive, and behaviourally clear interface—one where the user never has to think about the layout, because the layout is already thinking for them.

Proximity controls meaning: move elements closer to show connection, separate them to show difference.

3.2 Similarity

We naturally group elements that share similar visual characteristics, such as color, shape, size, or orientation.

For example, even if buttons are spread across a page, if they're all the same shade of blue, the user understands they perform similar functions.

If your primary "Submit" button is blue with rounded corners, every other primary action on your site should look exactly the same. If you suddenly use a square red button for a primary action, the user will be confused because the "similarity" is broken.

Fig 3:1 : illustration of similarity (Gestalt principle)

As you can see from above, the layout clearly demonstrates how the Gestalt Principle of Similarity works by showing two different visual situations: one where everything matches, and one where a single element breaks the pattern.

All three product cards share the same visual characteristics:

• Same card shape

• Same border and shadow

• Same image size and placement

• Same blue “Add to Cart” button

• Same font style and spacing

Because these elements look alike, your brain automatically groups them as one category — “products that belong together.”
You don’t have to think about it; the similarity creates instant visual unity.

This is the Gestalt Principle of Similarity in action.

In the second row, everything is still similar except one button:

• The middle product’s button is orange, not blue

• It has square corners, not rounded

• The text is italic, not regular

• The label changes to “Quick Buy”

Because this button breaks the shared pattern, your brain immediately notices it and treats it as different or special.

Developers can use broken similarity to intentionally highlight featured items, promotions, or urgent actions.

When similarity is broken, the different element stands out and draws attention.

3.3 Continuity

The human eye prefers to follow a continuous path or curve rather than jagged or broken lines. We perceive items aligned on a line or curve as being related. This is often used in navigation menus or horizontal carousels to guide the user's gaze.

For example, you might have a horizontal carousel where the last visible card is slightly "cut off" at the edge of the screen. This visual break creates a path that encourages the user to keep scrolling as their eyes follow the line of cards.

Fig 3:2: illustration of continuity (Gestalt principle)

As you can see, all four form fields — First Name, Last Name, Email Address, and Phone Number — are perfectly aligned along one continuous horizontal path. Because the human eye naturally prefers to follow an unbroken line, your gaze moves smoothly from left to right across the fields without effort.

The final field is slightly cut off at the edge, which creates a subtle visual cue that the line continues beyond the visible area. This encourages the user to keep scrolling or swiping, because their eyes are already following the direction of the form.
when elements are arranged along a straight path, curve, or flow, the brain automatically treats them as connected and expects the pattern to continue.

Another example is Instagram Stories, which are arranged in a smooth horizontal line at the top of the app. Instagram reinforces this by slightly revealing the next story circle at the edge of the screen. That tiny “peek” acts as a continuation cue — your eyes expect the line to keep going, so your finger follows.

Fig 3:3: illustration of continuity (Gestalt principle)

As you can see from above, all the circular story icons are arranged in a straight horizontal line, and your visual system instinctively follows that line from left to right without effort.

The slight visibility of the next story at the edge of the screen strengthens this effect, signaling that the sequence continues beyond what's currently shown. Also, because the icons share the same size, spacing, and shape, there are no visual interruptions, allowing your eyes to glide across them in one continuous motion.

This seamless flow is exactly what continuity describes: the tendency of the human eye to follow the direction of a line or pattern, assuming it continues even when part of it is out of view.

Continuity is the tendency of the human eye to follow the direction of a line or pattern, assuming it continues even when part of it is out of view.

3.4 Closure

Closure refers to the mind’s ability to perceive a complete, unified form even when parts of that form are missing. Rather than requiring every boundary, line, or shape to be explicitly drawn, the brain instinctively fills in the gaps. When used intentionally, closure allows interfaces to feel cleaner, more elegant, and more cognitively efficient.

When we look at a complex arrangement of visual elements, we tend to look for a single, recognisable pattern. If an image is missing parts, our brains fill in the gaps to "close" the shape.

One of the most celebrated examples of closure in visual identity design is the panda symbol used by the World Wide Fund for Nature (WWF). This logo demonstrates how strategic omission can produce a memorable, emotionally resonant, and universally recognisable mark.

At first glance, the panda illustration appears simple, composed of a few bold black shapes arranged against a white background.

Yet a closer look reveals that the panda is not fully drawn. There are no outlines defining the body, no complete contours around the head, and no explicit boundaries separating limbs from background. Instead, the designer uses a series of carefully placed shapes (ears, eye patches, nose, and partial limbs) to imply the rest of the animal. The viewer’s mind fills in the missing information, completing the silhouette effortlessly.

This is closure at its most effective: the brain constructs a whole from fragments, creating a sense of completeness without visual overload.

Fig 3:4: illustration of closure (Gestalt principle)

For example, a "hamburger menu" (three lines) isn't a literal drawer, but our brains "close" the shape to understand it represents a menu.

Fig 3:5: illustration of closure (Gestalt principle)

An example of closure in practice can be seen in step indicators commonly used in checkout flows. These components often rely on partial shapes, implied boundaries, and incomplete outlines to guide the user through a sequence of actions.

For instance, upcoming steps may be represented by dashed circles. Although the circles aren't fully drawn, the viewer immediately recognises them as complete shapes. The brain resolves the missing segments, allowing the interface to communicate progression without heavy borders or fully rendered icons. This subtle use of closure reduces visual clutter while preserving clarity.

Closure refers to the mind’s ability to perceive a complete, unified form even when parts of that form are missing.

3.5 Figure/Ground

This principle describes the mind's tendency to separate an object (the figure) from its surrounding area (the ground or background). In web design, using a "modal" or "pop-up" relies on this: by blurring the background, you force the user to see the pop-up as the focal figure.

When a user clicks "Login" on a modal/lightbox, the background site often dims (the "Ground") while the login box stays bright and centered (the "Figure"). This immediate depth change tells the user exactly where their attention belongs.

Video 3.5.0 Video description of Figure/Ground (Gestalt Principle)

From the video above, you can see that when the Quick View button is clicked, the selected figure stands out while the background darkens. This contrast guides the user’s attention and helps them focus on the figure. Developers can use this technique to direct users’ attention to what matters most or to what they want users to notice.

This principle describes the mind's tendency to separate an object (the figure) from its surrounding area (the ground or background).

3.6 Common Fate

Elements that move in the same direction are perceived as more related than elements that are stationary or move in different directions. Think of a dropdown menu: when all sub-items slide down together, they are clearly part of the same "unit."

For example, when you click a FAQ header and five sub-items slide down at the exact same speed and direction, the "Common Fate" tells the user that all those items belong to that specific category. If they flew in from different directions, the relationship would be lost.

Video 3.6.1 Video description of common fate (Gestalt Principle)

Video 3.6.2 Video description of common fate (Gestalt Principle)

From the video shown above, the e‑commerce animation example demonstrates these principles clearly by using two distinct motion patterns: a group of regular products that move upward together, and a pair of special‑category items that enter dramatically from the left. Through these contrasting movements, the interface communicates category differences without relying on text labels or explicit instructions.

Therefore, developers can use this motion‑based differentiation as a design strategy to guide users’ perception—allowing the interface to signal hierarchy, category structure, and product importance purely through animated behaviour rather than through static visual labels.

Elements that move in the same direction are perceived as more related than elements that are stationary or move in different directions.

3.7 Focal Point

Whatever stands out visually will capture and hold the viewer’s attention first. This is essentially the principle of emphasis. A bright "Sign Up" button in a sea of gray text acts as the focal point, directing the user's primary action.

For example, an alert banner or a pricing table should stand out from its surroundings. Beyond this, in a three-tier pricing table (Basic, Pro, Enterprise), the "Pro" column is often slightly larger or a different color. This creates a focal point that draws the eye to the "recommended" option immediately.

Fig 3:7: illustration of closure (Gestalt principle)

In visual interface design, the Gestalt principle of Focal Point plays a crucial role in directing user attention toward the most important element on a screen.

A focal point is created when one element breaks the established pattern of surrounding elements, making it stand out immediately.

In e‑commerce interfaces, this principle is often applied to highlight primary actions such as purchasing, subscribing, or upgrading. The “Buy Now” button provides a clear and practical example of how focal points function within a layout.

From the example above, the first two buttons share the same visual characteristics: neutral colours, and regular weight text. This repetition establishes a visual pattern that the user quickly becomes familiar with.

But the “Buy Now” button intentionally disrupts this pattern. It uses a bright colour, which contrasts sharply with the muted tones of the other buttons. This colour difference alone is enough to draw the eye, as humans are naturally sensitive to changes in hue and saturation within a uniform environment.

The Focal Point may sound like it's similar to the principle of Similarity, but the two operate in completely opposite ways within perceptual psychology.

Similarity explains how the mind naturally groups elements that share visual characteristics – such as colour, shape, or size – into coherent units. Once this grouping is established, the interface gains structure and predictability.

Focal Point, on the other hand, works by intentionally breaking that structure. Instead of reinforcing uniformity, it introduces a deliberate contrast – through colour, scale, brightness, or motion – to draw the viewer’s attention to one specific element.

In other words, Similarity creates the background pattern, while Focal Point identifies the one element that must stand out against that pattern.

Whatever stands out visually will capture and hold the viewer’s attention first.

Design Takeaways from the Gestalt Principles

Use Spacing as Your Primary Grouping Tool:
Elements that belong together should sit closer to each other than to anything else. Spacing communicates structure faster than borders or boxes. Use tight internal spacing (6–12px) for related items and wide external spacing (24–48px) to separate groups.

Build a Strict, Consistent Visual System — and Stick to It:
Define clear rules for button types, text styles, icon sizes, and alignment patterns. Consistent left‑aligned text blocks, predictable carousel lines, and stable flow patterns reduce cognitive load and make interfaces feel trustworthy.

Guide the Brain With Spacing, Alignment, Consistency, Contrast, and Motion:
The human brain is always trying to group, follow, and prioritise what it sees. Your job is to guide that instinct through intentional layout decisions, not fight against it.

4.0 Von Restorff Effect (The Isolation Effect):

This is the brainchild of Hedwig von Restorff, posited in 1933. In principle it states: An item that stands out is more noticable and more likely to be remembered than other items (Hunt, 1995).

So unique or visually distinct elements grab attention and are more memorable – in other words, distinctiveness dictates memory. When a user interacts with an interface, their brain naturally seeks patterns to minimize cognitive effort.

While consistency is generally a virtue in design, a perfectly uniform layout can lead to "banner blindness" or habituation, where the user stops noticing details.

By strategically breaking a pattern through changes in color, size, shape, or spacing, the developer can "isolate" an element, triggering a biological response that flags the item as high-priority.

Note that although the Focal Point principle may initially seem similar to the Von Restorff Effect, they describe two different psychological processes.

Focal Point is a Gestalt visual principle that explains how one element becomes the centre of attention within a composition because it carries the strongest visual contrast – through size, colour, brightness, position, or motion. Its purpose is to guide the viewer’s eye toward the most important element in the layout.

The Von Restorff Effect comes from cognitive psychology, not Gestalt theory. It states that an item that is noticeably different from a group of similar items is not only more attention‑grabbing but also more memorable.

So Focal Point is about where the eye goes first, while the Von Restorff Effect is about what the brain remembers later.

Design takeaways from Von Restorff

Use Isolation to Make CTAs Impossible to Miss:
On a page filled with neutral text and standard links, a single high‑contrast button (like a bold “Primary Blue” or “Emergency Red”) instantly becomes the standout element. This leverages the Von Restorff Effect to pull the user’s eye toward the most important action.

Create a Visual “Hitch” in the Scan Path:
A distinct CTA interrupts the user’s natural left‑to‑right, top‑to‑bottom scanning rhythm. This makes actions like “Buy Now” or “Sign Up” the first thing they notice and the last thing they forget.

Make Critical Actions Visually Distinct:
Because users naturally notice the one element that breaks a pattern, your most important actions should use deliberate contrast — color, size, shape, weight, or motion. Isolate key information instead of letting it blend into surrounding UI noise.

Avoid Over‑Differentiation — or Nothing Stands Out: If every button is loud, animated, or uniquely styled, the interface becomes chaotic. The Von Restorff Effect only works when there is a clear, stable pattern — and you break it once, intentionally.

To Sum Up: An item that stands out is more noticable and more likely to be remembered than other items.

5.0 Jakob’s Law

Jakob’s Law states that users spend most of their time on other sites, so they expect your interface to behave like the ones they already know.

Familiar patterns — hamburger menus, top navigation, search icons, and clickable top‑left logos — reduce cognitive load because users don’t have to interpret anything new.

But while Jakob’s Law is foundational to UX, I think it can also unintentionally suppress innovation.

When developers over‑prioritise familiarity, they fall into a standardisation trap: endlessly optimising conventional patterns instead of exploring fundamentally better ones.

The Pie Menu is a perfect illustration of this. According to Fitts’s Law, the time required to reach a target depends on its distance and size. Linear menus place the last item much farther from the cursor than the first, creating uneven interaction costs.

Radial menus position every option at an equal distance from the centre, and their wedge‑shaped targets effectively grow larger as the pointer moves outward.

Mathematically, pie/radial menu are faster to interact with and more efficient — yet they remain rare in mainstream web design because they violate users’ expectations. In other words, Jakob’s Law keeps us locked into a familiar but suboptimal pattern simply because “that’s how it’s always been done.”

But the challenge is not choosing between familiarity and innovation, but balancing them.

This is where the Aesthetic–Usability Effect becomes powerful. Research shows that users perceive attractive interfaces as easier to use, and they are more forgiving of minor usability friction when the design is visually pleasing.

A beautifully crafted Pie Menu, for example, can encourage users to invest the small amount of learning required to use it. By applying aesthetic delight strategically, developers can introduce innovative patterns without overwhelming users.

The principle that emerges is simple: Be conventional where it matters, and innovative where it delights.

Design Takeaway from Jakob's Law

Keep Trust‑Critical Elements Predictable:
Navigation, search, authentication, and other high‑stakes interactions must follow established conventions. Users rely on these patterns for speed, confidence, and safety — this is where Jakob’s Law should be respected without exception.

Experiment Only in Low‑Risk, High‑Creativity Areas:
In creative or productivity‑focused zones — like editing tools in a photo app — you can safely introduce new interaction models such as radial menus, gesture wheels, or context‑aware tool selectors. These areas invite exploration and benefit from efficiency‑driven innovation.

To Sum Up: Be conventional where it matters, and innovative where it delights.

6.0 Miller’s Law

Miller’s Law originates from George A. Miller’s classic paper “The Magical Number Seven, Plus or Minus Two.” It states that the average person can hold only about 7 (±2) chunks of information in working memory at any given moment (Miller, 1956).

Crucially, Miller emphasised that the brain doesn’t store isolated items — it groups them into meaningful units called chunks. Because working memory is so limited, developers must structure information in ways that respect this cognitive boundary.

This principle has direct implications for interface design. Long, unbroken strings of information overwhelm users, whereas chunked formats are far easier to process.

For example, instead of displaying a phone number as 1234567890, formatting it as 123‑456‑7890 transforms ten digits into three manageable chunks. The same logic applies to navigation: aim for five to nine primary menu items, and if you need more, group them into categories. Users remember the category as a single chunk rather than each individual link.

Miller’s Law also explains why long forms are so intimidating. When a user sees 30 fields on one page, their brain interprets it as a single, massive task — far beyond the 7±2 limit.

A progressive stepper solves this by breaking the form into smaller stages of 5–7 fields each. This reduces cognitive load, creates a sense of progress, and significantly lowers abandonment rates.

The same principle applies to product listings or search results. Expecting users to compare 50 items at once is unrealistic. Instead, provide strong filtering tools so users can narrow the set to a manageable size — ideally within the range their working memory can meaningfully evaluate.

In essence, Miller’s Law reminds developers that humans don’t process information in bulk. They process it in structured, meaningful chunks.

Fig 6.0: Illustrating progressive stepper

In the example above, the interface uses both a progress bar and a stepper to guide the user through multiple stages of a task. After completing the first page and selecting “Continue,” the user moves to the next step, and the progress bar updates accordingly. This creates a clear sense of forward movement and accomplishment.

By breaking the process into smaller segments, the interface prevents cognitive overload. If all the information were presented on a single page, users might feel overwhelmed, unsure where to begin, or discouraged by the sheer volume of work.

A step‑by‑step flow transforms a large task into a sequence of manageable actions, increasing the likelihood of completion.

Design Takeaway from Miller's Law

Respect the 7±2 Working‑Memory Limit:
Users can only hold about seven chunks of information at once. Long, unbroken content overwhelms them, while chunked information is instantly easier to process.

Chunk Information Into Meaningful Units:
The brain doesn’t store isolated items — it groups them. Format data (like phone numbers), menus, and settings into clear, memorable chunks instead of long, flat lists.

Keep Navigation Within 5–9 Primary Items:
If you need more than nine options, group them into categories. Users remember the category as a single chunk, not each individual link.

Break Long Forms Into Smaller Steps:
A 30‑field form feels like one giant task. A progressive stepper with 5–7 fields per step keeps users below the cognitive overload threshold and dramatically reduces abandonment.

Reduce Comparison Load With Strong Filters:
Expecting users to compare 50 products at once is unrealistic. Provide filtering tools that shrink the decision set to something the working memory can actually handle.

Design for Chunked Thinking, Not Bulk Processing:
Humans don’t process information in bulk — they process structured, meaningful groups. Interfaces that respect this limitation feel lighter, faster, and more intuitive.

To Sum Up: A step‑by‑step flow transforms a large task into a sequence of manageable actions, increasing the likelihood of completion.

7.0 The Goal-Gradient Hypothesis

This is the perfect moment to introduce the Goal‑Gradient Hypothesis, originally proposed by behaviorist Clark Hull in 1932 (Yablonski, 2022). The hypothesis states that people become more motivated as they get closer to achieving a goal. In other words, users naturally accelerate their engagement when they sense they are nearing completion.

This principle is incredibly powerful in UX design, especially for progress tracking, gamification, and reward systems.

The takeaway is straightforward: Because users are more motivated near the finish line, progress indicators should be prominent and meaningful.

Percentages, progress bars, and step counters reinforce momentum. Micro‑achievements — such as badges, checkmarks, or subtle confetti — amplify motivation by celebrating small wins.

Tasks should be broken into measurable milestones so users can see themselves advancing.

This is why e‑learning platforms display messages like “You’ve completed 8 of 10 lessons — almost there!” and why fitness apps highlight progress with prompts such as “3 km done, 2 km to go.” These cues leverage the goal‑gradient effect to keep users engaged, energized, and eager to finish.

By combining progressive steppers with clear progress feedback, developers create interfaces that feel lighter, more encouraging, and far more motivating — ultimately improving completion rates and overall user satisfaction.

But what happens when a goal isn't completed? Why do we sometimes feel uncomfortable leaving things unfinished? That discomfort is explained by another psychological principle called the Zeigarnik Effect — the tendency for people to remember and feel tension about incomplete tasks. We will look at this next.

Design Takeaway from Goal-Gradient Hypothesis

Make Progress Visible to Boost Motivation:
According to the Goal‑Gradient Hypothesis, users naturally speed up as they sense they’re nearing completion. Prominent progress bars, percentages, and step counters tap into this instinct and keep momentum high.

Celebrate Micro‑Achievements to Reinforce Engagement:
Badges, checkmarks, subtle confetti, and “step completed” cues reward small wins. These micro‑rewards amplify motivation and make long tasks feel lighter and more achievable.

Break Tasks Into Measurable Milestones:
Users stay motivated when they can see themselves advancing. Divide complex flows into clear steps so progress feels tangible rather than overwhelming.

Use Progress Feedback to Drive Completion:
Messages like “8 of 10 lessons completed — almost there” or “3 km done, 2 km to go” leverage the goal‑gradient effect to energise users and pull them toward the finish line.

Combine Steppers With Clear Feedback for Maximum Impact:
Progressive steppers paired with strong visual feedback create interfaces that feel encouraging, structured, and motivating — dramatically improving completion rates.

Video 8.0 : Video illustrating goal gradient

To Sum Up: People become more motivated as they get closer to achieving a goal.

8.0 Zeigarnik Effect

The Zeigarnik Effect is a psychological principle stating that people remember unfinished or interrupted tasks better than completed ones (Cherry, 2024).

Memory begins with sensory input, which is processed into short-term memory. Unfinished tasks persist in our thoughts, leading to active recall. This ongoing engagement can turn them into long-term memories, enhancing recall until resolved. This increases engagement, encourages task completion, improves retention, and drives conversions.

So because people remember unfinished tasks better than completed ones (Zeigarnik Effect), developers use progress indicators to make users aware that something is incomplete and motivate them to finish it.

In your designs, you can break long forms into multi-step processes to encourage completion and display profile completion percentages (for example, 70% complete) to push users toward 100%.

This is the main reason why e-commerce platforms send abandoned cart reminders to bring users back to complete their purchases. It's also why apps use streak systems to encourage daily engagement and habit formation and learning platforms show course completion bars to motivate users to finish modules.

Design Takeaway from Zeigarnik Effect

Unfinished Tasks Stay Active in Memory — Use That to Drive Completion:
Because incomplete tasks linger in working memory (Zeigarnik Effect), users naturally keep thinking about what they haven’t finished. This tension boosts recall, engagement, and the likelihood of returning to complete the task.

Make Incompleteness Visible With Progress Indicators:
Progress bars, percentages, and step counters remind users that something is still unfinished. This gentle psychological pressure motivates them to continue until the task is complete.

Break Long Flows Into Multi‑Step Processes:
A massive form feels overwhelming, but a stepper with smaller chunks keeps users moving. Showing “70% complete” nudges them toward finishing the last stretch.

Use Reminders to Re‑activate Unfinished Intent:
Abandoned cart emails, streak reminders, and “continue your lesson” prompts work because the unfinished task is already active in the user’s mind. The reminder simply pulls them back into the loop.

Celebrate Completion to Close the Cognitive Loop:
Checkmarks, confirmations, and completion badges give users closure. This resolves the mental tension created by the unfinished task and reinforces positive behaviour.

To Sum Up: Unfinished tasks persist in our thoughts, leading to active recall.

9.0 Tesler’s Law:

This law was proposed by Lawrence Tesler. He was a computer scientist known for his work on human-computer interaction, and he contributed significantly to making software more user-friendly, including work on cut, copy, and paste functionality.

This law is otherwise known as the Law of Conservation of Complexity. The core Idea here is every process has a certain amount of “inherent complexity" that can't be removed. You can only decide who handles it: the user or the system.

Some examples of these inherent complexities might be:

• translating user actions into correct operations behind the scenes,

• handling unreliable or slow network connections,

• connecting with third-party APIs, services, or legacy systems,

• sorting large datasets quickly,

• performing complex search operations

• managing version changes and compatibility issues,

• managing state, interactions, and animations without confusing the user.

All of these can be inherently complex, but it's the job of the developer to deal with the complexity.

As a developer, you should always try as much as possible to push complexity to the system. For example, instead of making a user type their full address manually, use an Auto-complete API (Google’s Places and Map is best for this). The complexity of finding and validating the address still exists, but the software handles the work for them.

Here's a practical example: let’s say you're designing a student platform that requires users to enter their university name. A practical approach would be to store an array of all universities in the UK in your codebase (This is the hard part Tesla hinted at).

As the user types, they don't need to enter the full name, and their full university name is shown (relating to what they have typed). For instance, if they intend to type “University of Sheffield,” simply typing “Sheff” should prompt the system to display the full university name, which they can then select.

In Dart, you can use a package like fuzzysearch to implement this kind of intelligent matching.

The advantage of this approach is greater than it first appears. It improves data consistency because users often enter the same information in different ways. For example, some users might type “Uni of Sheff,” others “Sheffield University,” and others “Uni of Sheffield,” while all are referring to “University of Sheffield.”

This is how messy data is created, and it creates more work for data analysts. Little wonder that data analysts spend up to 70% of their time cleaning data.

If developers invested more time in structuring how data is collected to ensure consistency, there would be far less work downstream for analysts. This same logic should be applied in how we collect date, time, and other information.

So apart from people's names and email addresses, you should try to standardize the data your app collects as much as possible. Use date and time pickers, stepper controls, input masks, checkboxes, dropdown menu and radio buttons, toggle switches. and so on.

The essence of removing complexity from the user is not only about improving usability, but also about ensuring that the data collected is standardised, structured, and consistent.

Design Takeaway from Tesler's Law

Push Complexity to the System, Not the User:
Every process contains unavoidable complexity. Your job is to handle it behind the scenes so the user experiences the simplest possible interaction.

Automate Tasks Users Shouldn’t Have to Think About:
Use tools like autocomplete, fuzzy search, intelligent defaults, and validation APIs to remove manual effort. The complexity still exists — but the system absorbs it instead of the user.

Standardise Inputs to Prevent Messy Data:
Users enter the same information in wildly different ways. Use pickers, dropdowns, input masks, radio buttons, and toggles to enforce consistent, structured data collection.

Handle Inherent Technical Complexity Internally:
Network issues, API quirks, large dataset sorting, search optimisation, state management, and animation logic are all developer responsibilities. Users should never feel this complexity.

To Sum Up: Every process contains unavoidable complexity. Your job as a developer is to handle it behind the scenes so the user experiences the simplest possible interaction.

10.0 Peak End Rule:

In 1993, Daniel Kahneman, Barbara Fredrickson, Charles Schreiber, and Donald Redelmeier invited volunteers into a lab for what sounded like a simple experiment. The task was straightforward: place a hand into a container of painfully cold water (Kahneman et al., 1993)

In the first round, participants kept their hand in 14°C water for 60 seconds. It was uncomfortable, sharp, and unpleasant but after one minute, it was over.

In the second round, they again endured 60 seconds in 14°C water. But this time, they were asked to keep their hand in for an extra 30 seconds. The temperature was raised slightly to 15°C. Still cold. Still unpleasant. Just slightly less intense.

Objectively, the second experience was worse. It lasted 90 seconds instead of 60. More total pain. More suffering.

Later, the researchers asked a simple question:

If you had to repeat one of the trials, which would you choose?” Surprisingly, most participants chose the longer one.

Why would anyone choose more pain?

The researchers realised something profound: people don’t remember experiences by calculating total discomfort. Instead, the mind summarizes the experience using just two key moments — the most intense point (the peak) and the final moment (the end).

In both trials, the peak pain was the same: 14°C. But the longer trial ended slightly better, at 15°C. That small improvement at the end reshaped how the entire episode was remembered. The participants’ “experiencing self” suffered more during the longer trial. But their “remembering self” preferred it because it ended on a less painful note.

From this, the researchers introduced what became known as the Peak–End Rule: we judge experiences largely by their most intense moment and how they finish, not by how long they last.

Since people largely judge an experience by how it ends, developers should focus on designing satisfying confirmation screens and smooth exit interactions. You should concentrate less on making every single moment perfect and instead prioritise optimising the peak and final moments.

A negative ending can overshadow an otherwise good experience, so carefully avoid frustrating final steps such as unexpected fees or confusing confirmations.

Emotional intensity strongly shapes memory, which is why many apps incorporate celebration animations, rewards, or success messages at key moments to leave a lasting positive impression.

Design takeaway from Peak End Rule

People Judge Experiences by the Peak and the Ending — Not the Total Duration:
Users don’t remember every moment. They remember the most intense point and how the experience ends. A slightly better ending can completely reshape how the entire interaction is remembered.

Prioritise Strong, Positive Endings in Your UX Flows:
A smooth final step, a clear confirmation, or a satisfying success screen leaves a disproportionately strong impression. A bad ending can overshadow an otherwise great experience.

Design for Emotional Peaks at Key Moments:
Celebration animations, rewards, checkmarks, and success messages create memorable emotional spikes. These peaks anchor the experience in the user’s memory.

Don’t Try to Perfect Every Moment — Perfect the Right Moments:
Optimise the peak and the end of the journey. These two moments define how users recall the entire interaction.

Avoid Negative Surprises at the Finish Line:
Unexpected fees, confusing confirmations, or friction at the last step can ruin the memory of the whole process. Protect the ending carefully.

To Sum Up: We judge experiences largely by their most intense moment and how they finish, not by how long they last.

11.0 Postel’s Law:

Jon Postel’s famous principle – “Be conservative in what you send, be liberal in what you accept” –  is a philosophy of kindness in software design. At its core, the principle argues that systems should be generous with what they accept from users, yet disciplined and predictable in what they output.

When developers follow this approach, users feel supported and understood. When they don’t, users feel punished for being human.

A user’s input is rarely perfect. People type quickly, make mistakes, follow their own habits, or rely on formats familiar to them. A robust system embraces this reality. It accepts messy, human input and quietly transforms it into clean, standardized data.

Real people don't think in strict formats. They write dates the way they learned in school, type phone numbers the way they say them aloud, and enter names and addresses in whatever structure feels natural to them.

A rigid system will reject anything that doesn’t match its narrow expectations, but a robust system, by contrast, adapts to the user.

Consider dates. A brittle interface might demand MM/DD/YYYY and reject everything else. A more humane system accepts a wide range of formats — “1 May 2024,” “2024‑05‑01,” “05/01/24,” or “May 1st, 2024” — and quietly converts them into a standard internal representation. This is where the complex handling described by Tesla's Law comes into play (Shifting complexity to the system, rather than the user).

Phone numbers follow the same pattern. People might enter (555) 123 4567, 555‑123‑4567, 5551234567, or +1 555 123 4567. A fragile system throws errors. A robust one parses all of them using libraries like libphonenumber and moves on.

Addresses are equally varied. “221B Baker St,” “221‑B Baker Street,” and “221 Baker St., Apt B” all refer to the same place. A forgiving system normalizes these instead of rejecting them.

Even names can be surprisingly complex. Hyphens, apostrophes, multiple words, and titles are all part of real human identity. Rejecting “O’Connor,” “Jean‑Luc,” or “Dr. Sarah Lee” is not just technically incorrect — it's disrespectful to the user.

Search bars offer another clear example. A strict search bar demands perfect spelling and exact phrasing. A robust one handles typos (“restuarant”), partial words (“resta”), synonyms (“food places”), and natural language (“where can I eat nearby”). It meets the user where they are instead of forcing them to think like a machine.

Currency should be normalized to a clear format such as GBP 5.00, no matter whether the user typed “£5,” “5 pounds,” or “5 GBP.”

Even file uploads benefit from standardization: whether the user uploads .jpeg, .jpg, .JPG, or .JPEG, the system should store everything as .jpg.

Error messages follow the same principle. Vague feedback like “Invalid password” leaves users confused and frustrated.

A clear, conservative message — “Incorrect password. Please try again.” — respects the user’s time. And instead of hiding password requirements, the system should state them upfront: minimum eight characters, at least one uppercase letter, at least one number.

Predictability reduces friction.

Because users inevitably make mistakes or enter data in unexpected ways, developers should design input fields that are tolerant rather than brittle. This means accepting flexible formats, offering autocorrect or intelligent parsing, and using forgiving validation rules that interpret the user’s intent instead of rejecting their effort.

Clear instructions, tooltips, and visible requirements should appear before submission so users understand what the system expects without trial and error.

When errors do occur, the interface should handle them gently—never crashing, and never forcing the user to start over.

Even simple variations, such as phone numbers typed with spaces, dashes, or parentheses, should be accepted and normalized behind the scenes.

By embracing flexibility on the input side and clarity on the output side, developers create systems that feel humane, resilient, and respectful of the way real people actually behave.

Design Takeaway from Postel's Law

Accept Messy Human Input, Output Clean Structured Data:
Users type dates, names, phone numbers, and addresses in unpredictable ways. A humane system accepts this variability and quietly normalises it into a consistent internal format.

Rigid interfaces punish users for being human. Robust interfaces interpret intent — handling typos, partial matches, synonyms, and natural language without complaint.

Also accept variations in spacing, punctuation, casing, and structure. Let users type naturally — the system should handle the complexity, not them.

Be Flexible With Input, Be Strict With Output:
This is the heart of Postel’s Law. Let users express information naturally, but ensure your system stores and displays it in a predictable, standardised way.

Use Intelligent Parsing and Autocorrection to Reduce Errors:
Libraries like libphonenumber, fuzzy search, and natural‑language parsers allow systems to accept a wide range of formats while still producing clean, reliable data.

Normalise Everything Behind the Scenes:
Dates, phone numbers, currency, file extensions, and addresses should all be standardised internally. This prevents messy data and reduces downstream cleanup work.

Provide Clear, Predictable Feedback:
Error messages should be specific and helpful. Requirements should be visible upfront. Users should never be surprised, confused, or forced to start over.

Combine Postel’s Law With Tesler’s Law:
Shift complexity to the system. Intelligent handling of messy input reduces cognitive load, improves usability, and ensures consistent, high‑quality data.

To Sum Up: A rigid system will reject anything that doesn’t match its narrow expectations, but a robust system, by contrast, adapts to the user.

12.0 Doherty Threshold:

The Doherty Threshold is a principle in human–computer interaction which proposes that systems should respond quickly enough to keep users actively engaged (Mod 2024).

When response times stay below a certain limit, users remain focused and productive. But once performance already meets this optimal responsiveness level, making the system even faster or adding extra capability doesn't significantly enhance satisfaction or efficiency.

The idea was introduced by Walter J. Doherty in 1976 in his paper “A Comparison of Programming Systems and Doherty Threshold.” His research showed that maintaining rapid system feedback fast enough to sustain continuous interaction has a stronger impact on productivity than simply increasing system power or features beyond that point.

Doherty proposes that this shouldn't be greater than 400ms Rule: If the system responds within this window, the user feels in total control. If the response takes longer, the user's attention begins to wander, and their "train of thought" is broken.

The challenge, of course, is that not every operation can realistically complete within 400ms. Some tasks require heavy computation, large network calls, or complex rendering. This is where the concept of perceived performance becomes essential.

Even when the system can't finish the work quickly, it can feel fast by responding instantly at the UI level. Developers can achieve this illusion of speed through a combination of thoughtful design patterns and disciplined engineering practices.

On the technical side, performance begins with reducing unnecessary work. Keeping the number of HTML elements low helps the browser render faster. Rendering only the visible portion of long lists prevents the Document Oject Model (DOM) from becoming bloated. Splitting scripts and deferring non‑critical code ensures that essential interactions load first.

Using CSS transforms and opacity changes avoids expensive layout recalculations. Lazy‑loading images, videos, and scripts ensures that the interface becomes interactive long before all assets are downloaded.

These optimizations don’t just improve raw speed — they create the foundation for interfaces that feel responsive.

Design Takeaways from Doherty Threshold

Instant Feedback: When a user clicks a button, provide a visual change (like a button press animation or a spinner) immediately, even if the background task takes longer.

Skeleton Screens: Use placeholder blocks that mimic the layout of the page while data loads. This makes the app feel like it is responding instantly.

Progressive Loading: Load text and basic structures first, then "pop in" high-resolution images later.

Optimistic UI: When a user hits "Save," don't wait for the server. Update the UI instantly (Doherty) and handle the "messy" data formatting on the backend (Postel).

Live Inline Validation: Show a green checkmark or a helpful error message as the user types. This keeps them below the 400ms "thought-break" limit.

Debouncing: In search bars, start showing results after a few keystrokes so the user feels the app is "predicting" their needs.

To Sum Up: When response times stay below a certain limit, users remain focused and productive. But once performance already meets this optimal responsiveness level, making the system even faster or adding extra capability doesn't significantly enhance satisfaction or efficiency.

13.0 Serial Position Effect (Primacy and Recency):

Murdock’s study investigated how the position of a word in a list affects recall, known as the serial position effect. He presented 103 psychology students with lists of 10 to 40 words, one at a time, at either 1 or 2 seconds per word (McLeod, 2025).

Participants were divided into six groups, each experiencing a different combination of list length and presentation rate, and were asked to recall as many words as possible in any order.

The results showed that participants were most likely to remember words at the beginning of the list (primacy effect) and at the end of the list (recency effect), while words in the middle were recalled less often. The recency effect persisted even in longer lists, and the middle section of the recall curve formed a flat asymptote.

Murdock explained this using the multi-store model of memory: early words were rehearsed and transferred to long-term memory, last words remained in short-term memory, and middle words were neither sufficiently rehearsed nor retained, leading to poorer recall.

The experiment demonstrated that memory performance varies systematically with the position of information in a sequence.

This is the reason why the most important information or actions should never be buried in the middle.

As a developer, you should put your most critical navigation links (like "Home" or "Dashboard") at the far left or the top of a list. In a pricing table, put the most popular or recommended plan on the Place "Final Actions" (like "Log Out," "Cart," or "Support") at the end of a menu or the far right of a navigation bar.

In a long onboarding flow, put the most exciting benefit of the app on the very last slide so the user enters the app feeling motivated.

Avoid placing highly important buttons in the middle of a row. If you have a row of 7 buttons, the user is statistically likely to overlook the 4th one.

Design Takeaways Serial Position Effect

Place Critical Items at the Beginning or End — Never the Middle:
Users reliably remember the first and last items in any sequence (primacy and recency). Anything placed in the middle is statistically more likely to be forgotten or ignored. Also, actions such as “Log Out,” “Cart,” “Support,” or “Checkout” should sit at the far right or bottom — the natural recency position.

Put Essential Navigation Links at the Far Left or Top:
Links like “Home,” “Dashboard,” or “Overview” should appear at the start of a menu, where recall and recognition are strongest.

To Sum Up: The results showed that participants were most likely to remember words at the beginning of the list (primacy effect) and at the end of the list (recency effect), while words in the middle were recalled less often.

14.0 Occam’s Razor:

Although first articulated in the 14th century by the Franciscan friar William of Ockham, Occam’s Razor remains one of the most indispensable principles in a developer’s toolkit. In fact, skipping this law while discussing other theories and principles would be like skipping the glue that holds the entire framework together.

At its core, Occam’s Razor states that “among competing explanations, the simplest one is usually the best.”

For example, if two user interfaces achieve the same goal, the one with fewer visual elements is typically superior because it requires less processing power.

The fundamental takeaway for modern developers regarding Occam’s Razor is that complexity is a tax on the user’s cognitive resources.

In an era of information density, the developer's primary role is no longer to provide "more" features – rather, it's to curate the most direct path to a solution.

In practice, Occam’s Razor becomes a reminder to keep things as simple as possible. This “less is more” mindset shapes everything from navigation to forms.

A good rule for navigation is the Rule of Five: aim for three to five main menu items instead of a long, overwhelming list. This keeps choices clear and prevents users from freezing up when they see too many options.

The same idea applies to data entry. When you ask only for the information that truly matters, you respect the user’s time and reduce the chance of “form fatigue,” which is one of the biggest reasons people abandon sign‑ups or checkout flows.

Simplicity isn’t just elegant — it’s practical, humane, and far more effective.

Design Takeaway from Occam's Razor

Choose the Simplest Effective Solution:
When two designs achieve the same goal, the one with fewer elements is almost always better. Simplicity reduces cognitive load and speeds up user decision‑making.

Simplicity Is Not Just Aesthetic — It’s Humane:
Clear, minimal interfaces respect the user’s time, reduce friction, and make the product feel effortless. Simplicity is both a design strategy and an act of empathy.

To Sum Up: Simplicity isn’t just elegant — it’s practical, humane, and far more effective.

15.0 Parkinson's Law

Occam’s Razor teaches us to prefer the simplest solution that works. But why do we so often end up with complex systems in the first place? That tendency is explained by another principle: Parkinson’s Law.

Parkinson’s Law states that "work expands to fill the time available for its completion". In design, this means projects often become overly complex or take longer than necessary if given too much time, resulting in inefficient, over-designed, or cluttered interfaces.

In design, this manifests as Feature Creep. If you give yourself three months to build an app, you will spend three months adding "nice-to-have" animations, extra settings toggles, and niche edge cases that nobody asked for and in reality, what you have added isn’t that important.

You just succeeded in adding layers of complexity that might ends up violating some of the laws we spoke about. Occam’s Razor reminds us that the simplest solution is often the most effective.

By being aware of Parkinson’s Law and the tendency for work to expand, developers can manage their time intentionally and focus only on what truly matters.

Design Takeaway for Parkinson's law

Set Clear Constraints to Keep Designs Focused:
Intentional time limits and scope boundaries prevent over‑designing. Constraints force clarity, prioritisation, and simplicity.

Build Only What Truly Matters for the User:
Parkinson’s Law reminds you to resist the urge to fill time with unnecessary features. Focus on the core experience, not the edge cases nobody asked for.

Use Occam’s Razor to Counterbalance Parkinson’s Law:
As work expands, complexity grows. Occam’s Razor pulls you back to the simplest effective solution. Together, the two principles prevent bloated, over‑engineered products.

To Sum Up: Work expands to fill the time available for its completion

Conclusion

Human-centered design is deeply influenced by a set of psychological principles that explain how users perceive, process, and interact with digital systems.

Among these, Fitts’s Law establishes that the time required to acquire a target depends on its size and distance. In practice, this means that larger and closer elements are easier and faster to interact with.

To apply this in practice, developers should make primary call-to-action elements prominent, large, and easily reachable – especially in mobile interfaces where thumb accessibility is critical.

Closely related to decision-making is Hick’s Law, which states that the more choices a user is presented with, the longer it takes to make a decision. Excessive options can overwhelm users and lead to decision fatigue.

To address this, developers should simplify interfaces, minimise unnecessary options, and guide users through processes step-by-step rather than presenting everything at once.

Another important cognitive principle discussed is Miller’s Law, which suggests that the average person can hold approximately seven (plus or minus two) items in working memory at a time. This limitation highlights the need to present information in manageable chunks.

By breaking content into smaller groups and avoiding information overload, developers can improve comprehension and usability.

User expectations are strongly shaped by Jakob’s Law, which says that people spend most of their time on other websites and therefore expect similar patterns across digital products.

Instead of reinventing basic interactions, developers should follow familiar conventions such as placing the logo in the top‑left, the shopping cart in the top‑right, and keeping scrolling behaviour predictable.

But innovation is still possible where it truly adds value. As we discussed with the Aesthetic‑Usability Effect, users are far more tolerant of new or unusual design patterns when the interface is visually appealing and thoughtfully crafted.

The Gestalt Principles provided additional insight into how users visually organise information. The principle of proximity suggests that objects placed close together are perceived as related, so grouping related elements improves clarity. Similarity indicates that elements with consistent colours, shapes, or styles are seen as belonging together, reinforcing visual hierarchy and function. Closure explains that users can perceive incomplete shapes as complete, allowing for minimalistic designs where the brain fills in missing details. Continuity highlights that users naturally follow smooth visual paths, meaning layouts should guide the eye logically through alignment and structure.

We also looked at The Von Restorff Effect which emphasizes that elements which stand out are more likely to be remembered. By using contrast in colour, size, or design, important features such as buttons or alerts can capture user attention.

Managing complexity was addressed by Tesler’s Law, which asserts that every system has inherent complexity that cannot be eliminated but only managed.

Developers must therefore shift complexity away from the user by simplifying interfaces while handling intricate processes behind the scenes.

The Zeigarnik Effect reveals that people remember unfinished tasks better than completed ones, creating a sense of mental tension. This can be leveraged by incorporating progress indicators, checklists, and reminders that encourage users to complete tasks.

Similarly, the Peak-End Rule suggests that users judge an experience based on its most intense moment and its conclusion. Developers should create memorable highlights and ensure a smooth, satisfying ending to user journeys.

We also discussed the Goal-Gradient Effect, which explains that users become more motivated as they approach the completion of a task. By showing progress –such as indicating that a process is “80% complete” – and breaking tasks into stages, developers can encourage users to finish what they have started.

In terms of system interaction, Postel’s Law advises developers to be flexible in accepting user input while maintaining strict standards for output. This means allowing different input formats while ensuring consistent and reliable system responses.

Performance is equally important, as highlighted by the Doherty Threshold, which shows that productivity increases when system response times stay under 400 milliseconds. Fast systems keep users engaged and create a sense of ease.

This means that developers should focus on building interfaces that feel instant, even when real processing takes longer, by combining smart engineering practices with thoughtful design patterns that maintain the illusion of speed.

Memory and attention are further explained by the Serial Position Effect, where users tend to remember the first and last items in a sequence more than those in the middle. Developers should position key information or actions at the beginning or end of lists.

Simplicity is reinforced by Occam’s Razor, which argues that the simplest solution is often the most effective. Eliminating unnecessary features reduces friction and enhances usability, and we further discussed about Parkinson’s Law, which suggests that tasks expand to fill the time available, indicating the importance of setting constraints such as deadlines or timers to encourage timely action.

These principles collectively highlight the importance of simplicity, clarity, performance, and user psychology in design. By applying them thoughtfully, developers can create intuitive, efficient, and engaging user experiences that align with both human behaviour and user expectations.

References

Budiu, R. (2022). Fitts’s Law and Its Applications in UX. [online] Nielsen Norman Group. Available at: https://www.nngroup.com/articles/fitts-law/.

Bustamante, N. (2023). Gestalt Psychology? Definition, Principles, & Examples - Simply Psychology. [online] www.simplypsychology.org. Available at: https://www.simplypsychology.org/what-is-gestalt-psychology.html.

Cherry, K. (2024). The Zeigarnik Effect Is Why You Keep Thinking of Unfinished Work. [online] Verywell Mind. Available at: https://www.verywellmind.com/zeigarnik-effect-memory-overview-4175150.

DO, A.M., RUPERT, A.V. and WOLFORD, G. (2008). Evaluations of pleasurable experiences: The peak-end rule. Psychonomic Bulletin & Review, 15(1), pp.96–98. doi:https://doi.org/10.3758/pbr.15.1.96.

GUPTA, S., GUPTA, S., MAHENDRA, A. and GUPTA, S. (2006). Inverse Halo Nevus. Dermatologic Surgery, 32(6), pp.871–872. doi:https://doi.org/10.1097/00042728-200606000-00025.

‌Hall, D. (2023). Pilot Error, Chapanis and The Shape of Things to Come. [online] UX Magazine. Available at: https://uxmag.com/articles/pilot-error-chapanis-and-the-shape-of-things-to-come.

Hunt, R.R. (1995). The subtlety of distinctiveness: What von Restorff really did. Psychonomic Bulletin & Review, 2(1), pp.105–112. doi:https://doi.org/10.3758/bf03214414.

Kahneman, D., Fredrickson, B.L., Schreiber, C.A. and Redelmeier, D.A. (1993). When More Pain Is Preferred to Less: Adding a Better End. Psychological Science, 4(6), pp.401–405. doi:https://doi.org/10.1111/j.1467-9280.1993.tb00589.x.

Mod, D. (2024). Doherty Threshold: UX Law of Swift Interactions. [online] Articles on everything UX: Research, Testing & Design. Available at: https://blog.uxtweak.com/doherty-threshold/.

Miller, G.A. (1956). The magical number seven, plus or minus two: Some limits on our capacity for processing information. Psychological Review, [online] 101(2), pp.343–352. doi:https://doi.org/10.1037/0033-295x.101.2.343.

Proctor, R.W. and Schneider, D.W. (2018). Hick’s law for choice reaction time: A review. Quarterly Journal of Experimental Psychology, [online] 71(6), pp.1281–1299. doi:https://doi.org/10.1080/17470218.2017.1322622.

Yablonski, J. (2022). Hick’s Law. [online] Laws of UX. Available at: https://lawsofux.com/hicks-law/.

Yablonski, J. (2022). Goal-Gradient Effect. [online] Laws of UX. Available at: https://lawsofux.com/goal-gradient-effect/.

‌

‌

‌

But that's only the first 10% of a real payment system.

What happens after the customer pays? You need to record the purchase in your database, send a confirmation email, and grant product access (a GitHub repo invitation, an API key, a license file). You need to notify yourself as the admin. You need to handle refunds two weeks later and send recovery emails when someone abandons checkout.

This is the complete payment lifecycle, and it's where most SaaS applications break.

This article walks you through building the entire flow, from the "Buy" button to the "Welcome" email and everything in between. Every code example comes from a production application processing real payments. You'll see how to design the database schema, create Stripe products, build the checkout flow, process purchases reliably, handle refunds, recover abandoned carts, and send transactional emails.

Here is what you'll learn:

• How to design a database schema that tracks every stage of a purchase

• How to create Stripe products and prices programmatically

• How to build a checkout flow with success/cancel handling

• How to process webhooks securely with signature verification

• How to split post-payment processing into durable, independently retried steps

• How to handle full and partial refunds with automatic access revocation

• How to recover revenue from abandoned checkouts

• How to build transactional email templates with React Email and Resend

• How to test the entire flow locally with Stripe CLI and Inngest

Table of Contents

• Prerequisites

• How to Design the Payment Database Schema

• How to Create Stripe Products and Prices

• How to Build the Checkout Flow

• How to Handle Webhooks Securely

• How to Process Purchases with Durable Background Jobs

• How to Handle Refunds

• How to Recover Abandoned Checkouts

• How to Send Transactional Emails with React Email

• How to Test the Complete Flow Locally

• Conclusion

Prerequisites

To follow along, you should be familiar with:

• TypeScript and Node.js

• SQL databases (the examples use PostgreSQL)

• React (for email templates)

• Basic understanding of webhooks

You don't need prior experience with any of the specific libraries. This handbook explains each one as it appears.

What You Need Installed

Install these packages to run the code examples:

bun add stripe drizzle-orm @neondatabase/serverless inngest resend @react-email/components

You'll also need:

• A Stripe account (test mode is fine)

• A Neon PostgreSQL database (or any PostgreSQL instance)

• A Resend account for sending emails

• The Stripe CLI for local webhook testing

Environment Variables

Set up these environment variables in your .env file:

# Database
DATABASE_URL=postgresql://...

# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRO_PRICE_ID=price_...

# Email
RESEND_API_KEY=re_...
EMAIL_FROM="Your App <noreply@mail.yourapp.com>"
ADMIN_EMAIL=you@yourapp.com

# App
BETTER_AUTH_URL=http://localhost:3000

How to Design the Payment Database Schema

Before writing any Stripe code, you need a database schema that can track a purchase through every stage of its lifecycle: creation, completion, partial refund, and full refund.

A purchase starts as pending when the user clicks "Buy." After Stripe confirms payment, it transitions to completed. From there, it can move to refunded or partially_refunded. Pending purchases that are never completed expire after 24 hours (abandoned carts).

Here is the schema I use in production, defined with Drizzle ORM. The examples throughout this article grant access to a private GitHub repository because that's what this particular product sells.

Your "grant access" step will be different: upgrading a user to a Pro plan, provisioning API credits, unlocking course content, or activating a subscription. The schema fields and step logic change, but the durable execution pattern is the same.

// src/lib/db/schema.ts
import {
  boolean,
  integer,
  pgEnum,
  pgTable,
  text,
  timestamp,
  varchar,
} from "drizzle-orm/pg-core";

export const purchaseTierEnum = pgEnum("purchase_tier", ["pro"]);
export const purchaseStatusEnum = pgEnum("purchase_status", [
  "completed",
  "partially_refunded",
  "refunded",
]);

export const users = pgTable("users", {
  id: text("id").primaryKey(),
  email: varchar("email", { length: 255 }).notNull().unique(),
  emailVerified: boolean("email_verified").notNull().default(false),
  name: text("name"),
  image: text("image"),
  githubUsername: text("github_username"),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const purchases = pgTable("purchases", {
  id: text("id")
    .primaryKey()
    .$defaultFn(() => crypto.randomUUID()),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  stripeCheckoutSessionId: text("stripe_checkout_session_id")
    .notNull()
    .unique(),
  stripeCustomerId: text("stripe_customer_id"),
  stripePaymentIntentId: text("stripe_payment_intent_id"),
  tier: purchaseTierEnum("tier").notNull(),
  status: purchaseStatusEnum("status").notNull().default("completed"),
  githubAccessGranted: boolean("github_access_granted")
    .notNull()
    .default(false),
  githubInvitationId: text("github_invitation_id"),
  amount: integer("amount").notNull(),
  currency: text("currency").notNull().default("usd"),
  purchasedAt: timestamp("purchased_at").notNull().defaultNow(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export type Purchase = typeof purchases.$inferSelect;
export type NewPurchase = typeof purchases.$inferInsert;

Let me walk through the design decisions behind this schema.

Why Three Stripe ID Columns?

The purchases table stores three separate Stripe identifiers: stripeCheckoutSessionId, stripeCustomerId, and stripePaymentIntentId.

Each one serves a different purpose.

The checkout session ID is what you receive first. When a customer starts checkout, Stripe creates a session and gives you this ID. You use it to claim the purchase after the customer returns from Stripe's hosted checkout page.

The unique() constraint on this column is your idempotency guard. If someone tries to claim the same session twice, the database rejects the second insert.

The customer ID is Stripe's internal identifier for the buyer. You need this to look up the customer's payment history in Stripe's dashboard and to create future checkout sessions pre-filled with their billing info.

The payment intent ID is what Stripe sends in refund webhook events. When a charge.refunded event fires, it includes the payment intent ID but not the checkout session ID. Without storing this field, you would have no way to match a refund back to a purchase in your database.

Why Track Access State in Your Database

The githubAccessGranted and githubInvitationId fields might look unnecessary. You could check GitHub's API to see if a user has access. But querying an external API every time you need to check a user's access state is slow, rate-limited, and unreliable.

By tracking access state in your own database, you can answer "does this user have access?" with a single indexed query. You also know whether access was ever granted, which is critical for refund processing. If githubAccessGranted is false, you don't need to revoke anything on refund.

Why a Status Enum with Three Values?

The purchaseStatusEnum has three values: completed, partially_refunded, and refunded.

This matters for downstream logic. Your dashboard, analytics, support tools, and email sequences all need to know the exact state of a purchase. A partially refunded customer still has access, but a fully refunded customer doesn't.

If you only tracked "refunded" as a boolean, you would lose the distinction between partial and full refunds. That distinction affects whether you revoke product access.

How to Generate and Run Migrations

After defining your schema, generate a migration file and apply it to your database:

# Generate migration SQL from schema changes
bun run drizzle-kit generate

# Push schema directly (development only)
bun run drizzle-kit push

# Run migrations (production)
bun run drizzle-kit migrate

Drizzle Kit compares your TypeScript schema to the database and generates the SQL needed to bring them in sync. Review the generated migration file before running it in production. Schema changes are one of the few things you can't easily undo.

For development, drizzle-kit push is faster because it applies changes directly without creating migration files. For production, always use drizzle-kit generate followed by drizzle-kit migrate so you have a versioned record of every schema change.

How to Create Stripe Products and Prices

You can create products and prices through the Stripe dashboard, but managing them programmatically is better for reproducibility. Here's a seed script that creates everything you need:

// src/lib/payments/seed.ts
import { stripe } from "./index";

const PRODUCTS = [
  {
    name: "My SaaS Product",
    description: "Full access, one-time purchase",
    features: [
      "Full source code access",
      "Production-ready infrastructure",
      "Lifetime updates",
    ],
    metadata: { tier: "pro" },
    prices: [
      {
        lookupKey: "pro_one_time",
        unitAmount: 19900, // $199.00 in cents
        currency: "usd",
        nickname: "Pro One-Time",
      },
    ],
  },
];

async function main() {
  console.log("Seeding Stripe products and prices...\n");

  for (const config of PRODUCTS) {
    // Create or find product
    const products = await stripe.products.list({ active: true, limit: 100 });
    let product = products.data.find((p) => p.name === config.name);

    if (!product) {
      product = await stripe.products.create({
        name: config.name,
        description: config.description,
        marketing_features: config.features.map((f) => ({ name: f })),
        metadata: config.metadata,
      });
      console.log(`Created product "\({config.name}" (\){product.id})`);
    }

    // Create prices
    for (const priceConfig of config.prices) {
      const existing = await stripe.prices.list({
        lookup_keys: [priceConfig.lookupKey],
        active: true,
        limit: 1,
      });

      if (existing.data[0]) {
        console.log(`Price "${priceConfig.lookupKey}" already exists`);
        continue;
      }

      const price = await stripe.prices.create({
        product: product.id,
        unit_amount: priceConfig.unitAmount,
        currency: priceConfig.currency,
        nickname: priceConfig.nickname,
        lookup_key: priceConfig.lookupKey,
        transfer_lookup_key: true,
      });

      console.log(`Created price "\({priceConfig.lookupKey}" (\){price.id})`);
    }
  }

  console.log("\nDone! Add the price ID to your .env as STRIPE_PRO_PRICE_ID");
}

main().catch(console.error);

Run this with bun run src/lib/payments/seed.ts.

A few things worth noting.

• Use lookup_key instead of hardcoding price IDs: Price IDs are different between test and live mode. Lookup keys let you reference prices by name (pro_one_time) rather than by Stripe's generated ID (price_1P...).

  The transfer_lookup_key: true option ensures that if you create a new price with the same lookup key, it replaces the old one automatically.

• Prices are in cents: Stripe's API expects amounts in the smallest currency unit. For USD, that means 19900 represents $199.00.

  This is a common source of bugs. Always store amounts in cents in your database and convert to dollars only at the display layer.

• The seed script is idempotent: You can run it multiple times safely. It checks for existing products and prices before creating new ones.

How to Set Up the Stripe Client

The Stripe client uses lazy initialization so that importing it doesn't throw if the API key is missing at module load time. This matters in build environments where environment variables aren't set.

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

let stripeClient: Stripe | null = null;

function getStripe(): Stripe {
  if (!stripeClient) {
    const secretKey = process.env.STRIPE_SECRET_KEY;
    if (!secretKey) {
      throw new Error("STRIPE_SECRET_KEY is not set");
    }
    stripeClient = new Stripe(secretKey);
  }
  return stripeClient;
}

export const stripe = new Proxy({} as Stripe, {
  get(_, prop) {
    return Reflect.get(getStripe(), prop);
  },
});

The Proxy wrapper is the key pattern here. Code across your application imports stripe and calls methods like stripe.checkout.sessions.create(...). The proxy intercepts every property access and forwards it to the lazily initialized client.

This means the Stripe SDK only initializes when you actually use it, not when the module is imported.

How to Build the Checkout Flow

The checkout flow has three parts: creating the session, redirecting the customer, and handling the return.

How to Create a Checkout Session

Here's the function that creates a Stripe Checkout session for a one-time payment:

// src/lib/payments/index.ts
export async function createOneTimeCheckoutSession(params: {
  priceId: string;
  successUrl: string;
  cancelUrl: string;
  metadata: Record<string, string>;
  customerEmail?: string;
  couponId?: string;
}) {
  const client = getStripe();

  const session = await client.checkout.sessions.create({
    mode: "payment",
    line_items: [{ price: params.priceId, quantity: 1 }],
    success_url: params.successUrl,
    cancel_url: params.cancelUrl,
    metadata: params.metadata,
    ...(params.customerEmail && {
      customer_email: params.customerEmail,
    }),
    ...(params.couponId
      ? { discounts: [{ coupon: params.couponId }] }
      : { allow_promotion_codes: true }),
  });

  return session;
}

Three details matter here.

• The mode: "payment" setting tells Stripe this is a one-time charge, not a subscription. For subscriptions, you would use mode: "subscription". The mode affects which webhook events Stripe sends after payment.

• The metadata field is how you link the Stripe session back to your application. Pass your internal product tier, user ID, or any other data you need after payment. Stripe stores this metadata and includes it in webhook events and API responses.

• The allow_promotion_codes: true option shows a promo code field on the checkout page. If you have a specific coupon to apply (from a landing page URL parameter, for example), pass it via discounts instead. You can't use both at the same time.

How to Create the Checkout API Endpoint

Here's the API endpoint that creates a checkout session and returns the URL:

// src/server/api.ts
app.post("/api/payments/checkout", async ({ set }) => {
  const priceId = process.env.STRIPE_PRO_PRICE_ID;

  if (!priceId) {
    set.status = 500;
    return { error: "Price not configured" };
  }

  const baseUrl = process.env.BETTER_AUTH_URL ?? "http://localhost:3000";
  const tier = "pro";

  const checkoutSession = await createOneTimeCheckoutSession({
    priceId,
    successUrl: `${baseUrl}/dashboard?purchase=success&session_id={CHECKOUT_SESSION_ID}`,
    cancelUrl: `${baseUrl}/pricing`,
    metadata: { tier },
  });

  return { url: checkoutSession.url };
});

The {CHECKOUT_SESSION_ID} placeholder in the success URL is a Stripe template variable. Stripe replaces it with the actual session ID when redirecting the customer. This lets your frontend know which session just completed.

How to Claim the Purchase After Checkout

When the customer returns to your success URL, your frontend reads the session_id from the URL and sends it to a "claim" endpoint. This endpoint verifies the payment and creates the purchase record.

// src/server/api.ts
app.post(
  "/api/purchases/claim",
  async ({ body, request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const { sessionId } = body;

    // Check if this session was already claimed
    const existing = await db
      .select()
      .from(purchases)
      .where(eq(purchases.stripeCheckoutSessionId, sessionId))
      .limit(1);

    if (existing[0]) {
      return { success: true, alreadyClaimed: true, tier: existing[0].tier };
    }

    // Retrieve the Stripe checkout session to verify payment
    const stripeSession = await retrieveCheckoutSession(sessionId);

    if (stripeSession.payment_status !== "paid") {
      set.status = 400;
      return { error: "Payment not completed" };
    }

    const tier = (stripeSession.metadata?.tier ?? "pro") as PaymentTier;

    // Create purchase record
    await db.insert(purchases).values({
      userId: session.user.id,
      stripeCheckoutSessionId: sessionId,
      stripeCustomerId:
        typeof stripeSession.customer === "string"
          ? stripeSession.customer
          : stripeSession.customer?.id ?? null,
      stripePaymentIntentId:
        typeof stripeSession.payment_intent === "string"
          ? stripeSession.payment_intent
          : stripeSession.payment_intent?.id ?? null,
      tier,
      status: "completed",
      amount: stripeSession.amount_total ?? 0,
      currency: stripeSession.currency ?? "usd",
    });

    // Trigger background processing
    await inngest.send({
      name: "purchase/completed",
      data: {
        userId: session.user.id,
        tier,
        sessionId,
      },
    });

    return { success: true, tier };
  },
  {
    body: t.Object({
      sessionId: t.String(),
    }),
  }
);

This endpoint does four things, in order.

1. First, it checks if the session was already claimed. The unique() constraint on stripeCheckoutSessionId in the schema prevents duplicate records, but checking first lets you return a clean response without catching a database error.

2. Second, it verifies payment with Stripe. Never trust data from the client. The frontend passes the session ID, but you must call Stripe's API to confirm that payment_status is "paid".

3. Third, it creates the purchase record. Notice how it extracts the customer and payment_intent from the Stripe session. Both fields are returned as either strings or expanded objects depending on your Stripe API settings, so the ternary handles both cases.

4. Fourth, it sends a purchase/completed event to Inngest. This triggers the background processing flow that handles emails, access grants, analytics, and follow-up scheduling. The API endpoint doesn't do any of that work and returns { success: true } immediately.

This separation between recording the purchase and processing it is fundamental. The database insert is fast and reliable. The downstream processing (emails, API calls, analytics) is slow and unreliable.

By splitting them, you ensure the customer sees a success response instantly while the background work happens durably.

How to Handle Webhooks Securely

Your webhook endpoint is the entry point for Stripe events that happen outside your checkout flow: refunds, expired sessions, and disputes.

How to Verify Webhook Signatures

Every webhook from Stripe includes a signature header. You must verify this signature before processing the event. Without verification, anyone could send fake events to your webhook URL.

// src/lib/payments/index.ts
export async function constructWebhookEvent(
  payload: string | Buffer,
  signature: string
) {
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
  if (!webhookSecret) {
    throw new Error("STRIPE_WEBHOOK_SECRET is not set");
  }
  const client = getStripe();
  return client.webhooks.constructEventAsync(payload, signature, webhookSecret);
}

One critical detail: use constructEventAsync instead of constructEvent. The async version uses the Web Crypto API, which is compatible with modern runtimes like Bun and Cloudflare Workers. The synchronous version depends on Node.js's crypto module, which isn't available everywhere.

Another critical detail: pass the raw request body to signature verification. If your framework parses the body as JSON before you access it, the signature check fails. The signature is computed over the raw bytes of the request, not the parsed JSON.

How to Build the Webhook Endpoint

Here is the production webhook handler. Its only job is to validate the event and route it to the background job system.

// src/server/api.ts
app.post("/api/payments/webhook", async ({ request, set }) => {
  const body = await request.text();
  const sig = request.headers.get("stripe-signature");

  if (!sig) {
    set.status = 400;
    return { error: "Missing signature" };
  }

  try {
    const event = await constructWebhookEvent(body, sig);
    console.log(`[Webhook] Received ${event.type}`);

    if (event.type === "charge.refunded") {
      const charge = event.data.object as {
        id: string;
        payment_intent: string;
        amount: number;
        amount_refunded: number;
        currency: string;
      };
      await inngest.send({
        name: "stripe/charge.refunded",
        data: {
          chargeId: charge.id,
          paymentIntentId: charge.payment_intent,
          amountRefunded: charge.amount_refunded,
          originalAmount: charge.amount,
          currency: charge.currency,
        },
      });
    }

    if (event.type === "checkout.session.expired") {
      const session = event.data.object as {
        id: string;
        customer_email: string | null;
      };
      await inngest.send({
        name: "stripe/checkout.session.expired",
        data: {
          sessionId: session.id,
          customerEmail: session.customer_email,
        },
      });
    }

    return { received: true };
  } catch (error) {
    console.error("[Webhook] Stripe verification failed:", error);
    set.status = 400;
    return { error: "Webhook verification failed" };
  }
});

This is the "thin webhook handler" pattern. Notice what it does not do: it does not query the database, send emails, grant access, or call any external service. It validates the signature, extracts the fields it needs, and sends a typed event to Inngest.

The entire handler completes in milliseconds.

Why does this matter? Stripe expects your webhook to return a 2xx response within about 20 seconds. If your handler tries to do too much work (database queries, email sends, API calls), it risks timing out.

Stripe marks it as failed and retries the entire event. Now you have partial completion and duplicate processing.

The thin handler avoids this entirely. Validate, enqueue, return. All the real work happens asynchronously in durable background functions.

Why Extract Fields Before Enqueueing?

You might notice that the webhook handler extracts specific fields from the Stripe event before sending them to Inngest:

await inngest.send({
  name: "stripe/charge.refunded",
  data: {
    chargeId: charge.id,
    paymentIntentId: charge.payment_intent,
    amountRefunded: charge.amount_refunded,
    originalAmount: charge.amount,
    currency: charge.currency,
  },
});

Why not forward the entire Stripe event? Two reasons.

First, Stripe event objects are large and deeply nested. Your background function only needs five fields. Sending the entire object means your durable function stores a large payload at every checkpoint, and over thousands of runs, this adds up.

Second, extracting fields at the boundary creates a clean contract between your webhook handler and your background functions. If Stripe changes the shape of their event objects in a future API version, you only need to update the extraction logic in the webhook handler. Your background functions keep working because they depend on your own typed data shape, not Stripe's.

How to Set Up Webhooks in Production

For production, you configure webhooks in the Stripe Dashboard:

1. Go to Stripe Dashboard, then Developers, then Webhooks.

2. Add an endpoint pointing to your production URL: https://yourapp.com/api/payments/webhook.

3. Select the events you want to receive: charge.refunded and checkout.session.expired.

4. Copy the signing secret and add it to your production environment variables as STRIPE_WEBHOOK_SECRET.

The production signing secret is different from the one the Stripe CLI generates for local testing. Make sure your environment variables are set correctly for each environment.

Which Webhook Events to Listen For

For a complete payment flow, you need these webhook events configured in Stripe:

For subscription-based billing, you would also listen for customer.subscription.updated, customer.subscription.deleted, and invoice.payment_failed. This article covers one-time payments, so the examples focus on the two events above.

The checkout.session.completed event is notably absent. For one-time payments, you typically process the purchase in the "claim" endpoint (shown in the previous section) rather than in a webhook, because you need the authenticated user's session to link the purchase to their account.

How to Process Purchases with Durable Background Jobs

This is the heart of the payment flow. After the purchase record is created and the purchase/completed event is sent, a durable function takes over and runs the entire post-payment workflow.

Each step in this function is individually checkpointed. If step 5 fails, steps 1 through 4 don't re-run. Step 5 retries on its own, and once it succeeds, steps 6 through 9 continue.

This is what "durable execution" means. It's the difference between a payment system that works in development and one that works in production.

I use Inngest for this. It is an event-driven durable execution platform that provides step-level checkpointing out of the box. You define functions with step.run() blocks, and Inngest handles retry logic, state persistence, and observability.

The Inngest client setup is minimal:

// src/lib/jobs/client.ts
import { Inngest } from "inngest";

export const inngest = new Inngest({
  id: "my-app",
});

Register your functions with the Inngest serve handler so the dev server (and production) can discover them:

import { serve } from "inngest/bun";
import { inngest } from "@/lib/jobs/client";
import { stripeFunctions } from "@/lib/jobs/functions/stripe";

const inngestHandler = serve({
  client: inngest,
  functions: [...stripeFunctions],
});

// Mount on your API
app.all("/api/inngest", async (ctx) => {
  return inngestHandler(ctx.request);
});

Here's the complete purchase function:

// src/lib/jobs/functions/stripe.ts
import { eq } from "drizzle-orm";
import { createElement } from "react";

import { inngest } from "../client";
import { trackServerEvent } from "@/lib/analytics/server";
import { brand } from "@/lib/brand";
import { db, purchases, users } from "@/lib/db";
import {
  sendEmail,
  PurchaseConfirmationEmail,
  AdminPurchaseNotificationEmail,
  RepoAccessGrantedEmail,
} from "@/lib/email";
import { addCollaborator } from "@/lib/github";

export const handlePurchaseCompleted = inngest.createFunction(
  { id: "purchase-completed", triggers: [{ event: "purchase/completed" }] },
  async ({ event, step }) => {
    const { userId, tier, sessionId } = event.data as {
      userId: string;
      tier: string;
      sessionId: string;
    };

    // Step 1: Look up user and purchase details
    const { user, purchase } = await step.run(
      "lookup-user-and-purchase",
      async () => {
        const userResult = await db
          .select({
            id: users.id,
            email: users.email,
            name: users.name,
            githubUsername: users.githubUsername,
          })
          .from(users)
          .where(eq(users.id, userId))
          .limit(1);

        const foundUser = userResult[0];
        if (!foundUser) {
          throw new Error(`User not found: ${userId}`);
        }

        const purchaseResult = await db
          .select({
            amount: purchases.amount,
            currency: purchases.currency,
            stripePaymentIntentId: purchases.stripePaymentIntentId,
          })
          .from(purchases)
          .where(eq(purchases.stripeCheckoutSessionId, sessionId))
          .limit(1);

        const foundPurchase = purchaseResult[0];

        return {
          user: foundUser,
          purchase: foundPurchase ?? {
            amount: 0,
            currency: "usd",
            stripePaymentIntentId: null,
          },
        };
      }
    );

    // Step 2: Track purchase in analytics
    await step.run("track-purchase-to-posthog", async () => {
      try {
        await trackServerEvent(userId, "purchase_completed_server", {
          tier,
          amount_cents: purchase.amount,
          currency: purchase.currency,
          stripe_session_id: sessionId,
          stripe_payment_intent_id: purchase.stripePaymentIntentId,
        });
      } catch (error) {
        console.error(`Failed to track to PostHog:`, error);
      }
    });

    // Step 3: Send purchase confirmation to customer
    await step.run("send-purchase-confirmation", async () => {
      await sendEmail({
        to: user.email,
        subject: `Your ${brand.name} purchase is confirmed!`,
        template: createElement(PurchaseConfirmationEmail, {
          amount: purchase.amount,
          currency: purchase.currency,
          customerEmail: user.email,
        }),
      });
    });

    // Step 4: Send admin notification
    await step.run("send-admin-notification", async () => {
      const adminEmail = process.env.ADMIN_EMAIL;
      if (!adminEmail) return;

      await sendEmail({
        to: adminEmail,
        subject: `New template sale: ${user.email}`,
        template: createElement(AdminPurchaseNotificationEmail, {
          amount: purchase.amount,
          currency: purchase.currency,
          customerEmail: user.email,
          customerName: user.name,
          stripeSessionId: purchase.stripePaymentIntentId ?? sessionId,
        }),
      });
    });

    // Early return if user has no GitHub username
    if (!user.githubUsername) {
      return { success: true, userId, tier, githubAccessGranted: false };
    }

    // Step 5: Grant GitHub repository access
    const collaboratorResult = await step.run(
      "add-github-collaborator",
      async () => {
        return addCollaborator(user.githubUsername!);
      }
    );

    // Step 6: Track GitHub access granted
    await step.run("track-github-access", async () => {
      await trackServerEvent(userId, "github_access_granted", {
        tier,
        github_username: user.githubUsername,
        invitation_status: collaboratorResult.status,
      });
    });

    // Step 7: Update purchase record
    await step.run("update-purchase-record", async () => {
      await db
        .update(purchases)
        .set({
          githubAccessGranted: true,
          githubInvitationId: collaboratorResult.status,
          updatedAt: new Date(),
        })
        .where(eq(purchases.stripeCheckoutSessionId, sessionId));
    });

    // Step 8: Send repo access email
    await step.run("send-repo-access-email", async () => {
      const repoUrl = brand.social.github;
      await sendEmail({
        to: user.email,
        subject: `Your ${brand.name} repository access is ready!`,
        template: createElement(RepoAccessGrantedEmail, { repoUrl }),
      });
    });

    // Step 9: Schedule follow-up email sequence
    await step.run("schedule-follow-up", async () => {
      const purchaseRecord = await db
        .select({ id: purchases.id })
        .from(purchases)
        .where(eq(purchases.stripeCheckoutSessionId, sessionId))
        .limit(1);

      if (purchaseRecord[0]) {
        await inngest.send({
          name: "purchase/follow-up.scheduled",
          data: {
            userId,
            purchaseId: purchaseRecord[0].id,
            tier,
          },
        });
      }
    });

    return { success: true, userId, tier, githubAccessGranted: true };
  }
);

That's a lot of code. Let me break down why each step exists and why it must be separate.

Step 1: Look Up User and Purchase

const { user, purchase } = await step.run(
  "lookup-user-and-purchase",
  async () => {
    // Database queries for user and purchase records
    return { user: foundUser, purchase: foundPurchase };
  }
);

This step queries the database for the user and purchase details. Every subsequent step depends on these values (the user's email, the purchase amount, the user's GitHub username).

Because this is wrapped in step.run(), the return value is cached by Inngest. If a later step fails and the function retries, this step doesn't re-run. The cached values are replayed instead.

If the user doesn't exist in the database, this step throws an error that halts the entire function. There's no point continuing if the user can't be found.

Step 2: Track Analytics

await step.run("track-purchase-to-posthog", async () => {
  try {
    await trackServerEvent(userId, "purchase_completed_server", {
      tier,
      amount_cents: purchase.amount,
      currency: purchase.currency,
    });
  } catch (error) {
    console.error(`Failed to track to PostHog:`, error);
  }
});

Analytics tracking gets its own step because analytics services have their own failure modes. PostHog could be rate-limited or temporarily unreachable. If that happens, you don't want it to block the confirmation email.

Notice the try-catch. A tracking failure logs the error but doesn't halt the function. Analytics data is valuable but not critical to the purchase flow.

Steps 3 and 4: Email Notifications

The customer confirmation and admin notification are separate steps because they are independent operations. If Resend returns a 500 when sending the admin email, the customer should still get their confirmation.

// Step 3: Customer confirmation
await step.run("send-purchase-confirmation", async () => {
  await sendEmail({
    to: user.email,
    subject: `Your ${brand.name} purchase is confirmed!`,
    template: createElement(PurchaseConfirmationEmail, {
      amount: purchase.amount,
      currency: purchase.currency,
      customerEmail: user.email,
    }),
  });
});

// Step 4: Admin notification
await step.run("send-admin-notification", async () => {
  const adminEmail = process.env.ADMIN_EMAIL;
  if (!adminEmail) return;

  await sendEmail({
    to: adminEmail,
    subject: `New template sale: ${user.email}`,
    template: createElement(AdminPurchaseNotificationEmail, {
      // ... admin-specific fields
    }),
  });
});

The admin notification step includes a guard: if ADMIN_EMAIL isn't set, it returns early. This makes the function work in development environments where you haven't configured all environment variables.

Step 5: Grant Product Access

if (!user.githubUsername) {
  return { success: true, userId, tier, githubAccessGranted: false };
}

const collaboratorResult = await step.run(
  "add-github-collaborator",
  async () => {
    return addCollaborator(user.githubUsername!);
  }
);

This is the step most likely to fail. GitHub's API has rate limits, can time out, and the user's GitHub username might be invalid.

By making it its own step, a GitHub API failure doesn't re-trigger the confirmation email (step 3) or the admin notification (step 4). Those are already checkpointed.

Notice the early return before step 5. If the user has no GitHub username linked, the function returns after step 4. The remaining steps only run when there's a GitHub account to grant access to.

Steps 6-7: Track and Update

After granting GitHub access, the function tracks the event in analytics (step 6) and updates the purchase record in the database (step 7).

The database update is intentionally ordered after the GitHub API call. You only set githubAccessGranted: true after the invitation actually succeeded. If you updated the record first and the GitHub step failed, your database would say access was granted when it was not.

Step 8: Send Access Email

await step.run("send-repo-access-email", async () => {
  const repoUrl = brand.social.github;
  await sendEmail({
    to: user.email,
    subject: `Your ${brand.name} repository access is ready!`,
    template: createElement(RepoAccessGrantedEmail, { repoUrl }),
  });
});

This email only sends after the GitHub invitation is confirmed. The ordering is deliberate. You don't tell the customer "your access is ready" if the invitation hasn't been sent.

Step 9: Schedule Follow-Up Sequence

await step.run("schedule-follow-up", async () => {
  const purchaseRecord = await db
    .select({ id: purchases.id })
    .from(purchases)
    .where(eq(purchases.stripeCheckoutSessionId, sessionId))
    .limit(1);

  if (purchaseRecord[0]) {
    await inngest.send({
      name: "purchase/follow-up.scheduled",
      data: {
        userId,
        purchaseId: purchaseRecord[0].id,
        tier,
      },
    });
  }
});

The final step triggers a separate function that handles the follow-up email sequence: day 7 onboarding tips, day 14 feedback request, day 30 testimonial request. This is an event-driven chain: one function completes and triggers another.

The follow-up function uses step.sleep() to wait between emails without consuming compute resources:

export const handlePurchaseFollowUp = inngest.createFunction(
  {
    id: "purchase-follow-up",
    triggers: [{ event: "purchase/follow-up.scheduled" }],
    cancelOn: [
      {
        event: "purchase/follow-up.cancelled",
        match: "data.purchaseId",
      },
    ],
  },
  async ({ event, step }) => {
    await step.sleep("wait-7-days", "7d");
    await step.run("send-day-7-email", async () => {
      // Send onboarding tips
    });

    await step.sleep("wait-14-days", "7d");
    await step.run("send-day-14-email", async () => {
      // Send feedback request
    });
  }
);

The cancelOn option is worth noting. If the purchase is refunded, you send a purchase/follow-up.cancelled event, and the entire follow-up sequence stops. No stale emails to customers who refunded.

The Rule for Step Separation

Any operation that calls an external service or could fail independently should be its own step. A database query is a step because the database can be temporarily unreachable. An email send or API call is a step because those services can return errors or hit rate limits.

If two operations always succeed or fail together, they can share a step. But when in doubt, make it separate. The overhead is negligible, and the reliability gain is significant.

How to Handle Refunds

Refund processing is the most commonly overlooked part of a payment system. You need to handle two cases: full refunds (revoke access) and partial refunds (keep access, update status).

Here's the complete refund handler:

// src/lib/jobs/functions/stripe.ts
export const handleRefund = inngest.createFunction(
  { id: "refund-processed", triggers: [{ event: "stripe/charge.refunded" }] },
  async ({ event, step }) => {
    const data = event.data as {
      chargeId: string;
      paymentIntentId: string;
      amountRefunded: number;
      originalAmount: number;
      currency: string;
    };

    const chargeId = data.chargeId;
    const paymentIntentId = data.paymentIntentId;
    const currency = data.currency;
    const amountRefunded = data.amountRefunded;
    const originalAmount = data.originalAmount;
    const isFullRefund = amountRefunded >= originalAmount;

    // Step 1: Look up the purchase and user
    const { user, purchase } = await step.run(
      "lookup-purchase-by-payment-intent",
      async () => {
        const purchaseResult = await db
          .select({
            id: purchases.id,
            userId: purchases.userId,
            stripePaymentIntentId: purchases.stripePaymentIntentId,
            githubAccessGranted: purchases.githubAccessGranted,
          })
          .from(purchases)
          .where(eq(purchases.stripePaymentIntentId, paymentIntentId))
          .limit(1);

        const foundPurchase = purchaseResult[0];
        if (!foundPurchase) {
          return { user: null, purchase: null };
        }

        const userResult = await db
          .select({
            id: users.id,
            email: users.email,
            name: users.name,
            githubUsername: users.githubUsername,
          })
          .from(users)
          .where(eq(users.id, foundPurchase.userId))
          .limit(1);

        return { user: userResult[0] ?? null, purchase: foundPurchase };
      }
    );

    if (!purchase || !user) {
      return { success: false, reason: "no_matching_purchase" };
    }

    let accessRevoked = false;

    // Step 2: Revoke GitHub access (only for full refunds)
    if (isFullRefund && user.githubUsername && purchase.githubAccessGranted) {
      const revokeResult = await step.run(
        "revoke-github-access",
        async () => {
          return removeCollaborator(user.githubUsername!);
        }
      );
      accessRevoked = revokeResult.success;
    }

    // Step 3: Update purchase status
    await step.run("update-purchase-status", async () => {
      if (isFullRefund) {
        await db
          .update(purchases)
          .set({
            status: "refunded",
            githubAccessGranted: false,
            updatedAt: new Date(),
          })
          .where(eq(purchases.id, purchase.id));
      } else {
        await db
          .update(purchases)
          .set({
            status: "partially_refunded",
            updatedAt: new Date(),
          })
          .where(eq(purchases.id, purchase.id));
      }
    });

    // Step 4: Track refund in analytics
    await step.run("track-refund-event", async () => {
      try {
        await trackServerEvent(user.id, "refund_processed", {
          charge_id: chargeId,
          payment_intent_id: paymentIntentId,
          amount_cents: amountRefunded,
          original_amount_cents: originalAmount,
          currency,
          is_full_refund: isFullRefund,
          github_access_revoked: accessRevoked,
        });
      } catch (error) {
        console.error(`Failed to track to PostHog:`, error);
      }
    });

    // Step 5: Notify customer
    await step.run("send-customer-notification", async () => {
      if (isFullRefund) {
        await sendEmail({
          to: user.email,
          subject: `Your ${brand.name} refund has been processed`,
          template: createElement(AccessRevokedEmail, {
            customerEmail: user.email,
            refundAmount: amountRefunded,
            currency,
          }),
        });
      } else {
        await sendEmail({
          to: user.email,
          subject: `Your ${brand.name} partial refund has been processed`,
          template: createElement(PartialRefundEmail, {
            customerEmail: user.email,
            refundAmount: amountRefunded,
            originalAmount,
            currency,
          }),
        });
      }
    });

    // Step 6: Notify admin
    await step.run("send-admin-notification", async () => {
      const adminEmail = process.env.ADMIN_EMAIL;
      if (!adminEmail) return;

      await sendEmail({
        to: adminEmail,
        subject: `\({isFullRefund ? "Full" : "Partial"} refund processed: \){user.email}`,
        template: createElement(AdminRefundNotificationEmail, {
          customerEmail: user.email,
          customerName: user.name,
          githubUsername: user.githubUsername,
          refundAmount: amountRefunded,
          originalAmount,
          currency,
          stripeChargeId: chargeId,
          accessRevoked,
          isPartialRefund: !isFullRefund,
        }),
      });
    });

    return { success: true, accessRevoked, isFullRefund, userId: user.id };
  }
);

How Full Refunds Differ from Partial Refunds

The function distinguishes between the two with a simple comparison:

const isFullRefund = amountRefunded >= originalAmount;

For a full refund, three things happen:

1. GitHub access is revoked (the removeCollaborator call).

2. The purchase status is set to "refunded".

3. The customer receives an AccessRevokedEmail explaining that their access has been removed.

For a partial refund, the customer keeps access:

1. GitHub access is not revoked.

2. The purchase status is set to "partially_refunded".

3. The customer receives a PartialRefundEmail showing the refunded amount and the original amount.

This distinction matters for your database integrity. Downstream systems (your dashboard, analytics, support tools) need accurate status values. A partially_refunded purchase still represents an active customer.

How Conditional Steps Work

The "revoke GitHub access" step only runs when three conditions are all true: it's a full refund, the user has a GitHub username, and access was previously granted.

if (isFullRefund && user.githubUsername && purchase.githubAccessGranted) {
  const revokeResult = await step.run("revoke-github-access", async () => {
    return removeCollaborator(user.githubUsername!);
  });
  accessRevoked = revokeResult.success;
}

If any of those conditions is false, the step is skipped entirely. Inngest handles this cleanly. The function continues to step 3 (update purchase status) with accessRevoked still set to false.

How to Recover Abandoned Checkouts

When a customer starts checkout but doesn't complete it, Stripe eventually expires the session (after 24 hours by default). You can listen for this event and send a recovery email.

The key insight is that you don't want to send the email immediately. Give the customer an hour to come back on their own.

// src/lib/jobs/functions/stripe.ts
export const handleCheckoutExpired = inngest.createFunction(
  {
    id: "checkout-expired",
    triggers: [{ event: "stripe/checkout.session.expired" }],
  },
  async ({ event, step }) => {
    const { customerEmail, sessionId } = event.data as {
      customerEmail: string | null;
      sessionId: string;
    };

    if (!customerEmail) {
      return { success: false, reason: "no_email" };
    }

    // Wait 1 hour before sending recovery email
    await step.sleep("wait-before-recovery-email", "1h");

    // Send abandoned cart email
    await step.run("send-abandoned-cart-email", async () => {
      const baseUrl =
        process.env.BETTER_AUTH_URL ?? "https://your-app.com";
      const checkoutUrl = `${baseUrl}/pricing`;

      await sendEmail({
        to: customerEmail,
        subject: `Your ${brand.name} checkout is waiting`,
        template: createElement(AbandonedCartEmail, {
          customerEmail,
          checkoutUrl,
        }),
      });
    });

    // Track the recovery attempt
    await step.run("track-abandoned-cart", async () => {
      try {
        await trackServerEvent("anonymous", "abandoned_cart_email_sent", {
          customer_email: customerEmail,
          session_id: sessionId,
        });
      } catch (error) {
        console.error(`Failed to track to PostHog:`, error);
      }
    });

    return { success: true, customerEmail };
  }
);

The step.sleep("wait-before-recovery-email", "1h") line pauses the function for one hour without consuming compute resources. Inngest schedules the function to resume after the delay. No cron jobs, no Redis queues, no setTimeout that gets lost when your server restarts.

There is a guard at the top of the function. If the checkout session has no customer email (the customer closed the page before entering their email), the function returns early. You can't send a recovery email without an address.

You could extend this pattern with a second sleep and follow-up email three days later. You could also check if the customer has since completed a purchase (by querying the database in a step.run()) and skip the email if they have.

Why One Hour Is the Right Delay

Sending the recovery email immediately after checkout expiration feels aggressive. The customer might still be comparing options, waiting for payday, or just distracted. An immediate email says "we noticed you left," which feels surveillance-like.

Waiting 24 hours is too long. The customer has moved on. They have forgotten your product or found an alternative.

One hour is the sweet spot I found through testing. The customer's intent is still fresh, and the email feels helpful rather than pushy.

Your mileage may vary. The delay is configurable: change "1h" to "30m" or "3h" and redeploy.

Why This Is Better Than a Cron Job

Without durable execution, abandoned cart recovery typically works like this: a cron job runs every hour, queries the database for expired sessions that haven't been recovered yet, sends emails to each one, and marks them as recovered.

This approach has several problems. You need a recovered_at column to avoid sending duplicate emails. You need to handle the case where the cron job crashes halfway through the batch, and you need to tune the cron interval carefully.

The step.sleep() approach eliminates all of this. Each expired session gets its own function instance with its own timer. There's no batch processing, no database flag, and no duplicate risk.

How to Send Transactional Emails with React Email

Every email in the payment flow is a React component rendered to HTML and sent via Resend. This gives you type-safe templates with props, component reuse, and the ability to preview emails in your browser during development.

How to Set Up the Email Client

The email client wraps Resend with a simple sendEmail function:

// src/lib/email/index.ts
import { render } from "@react-email/components";
import type { ReactElement } from "react";
import { Resend } from "resend";

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

let resendClient: Resend | null = null;

function getResend(): Resend {
  if (!resendClient) {
    const apiKey = process.env.RESEND_API_KEY;
    if (!apiKey) {
      throw new Error("RESEND_API_KEY is not set");
    }
    resendClient = new Resend(apiKey);
  }
  return resendClient;
}

interface SendEmailOptions {
  to: string | string[];
  subject: string;
  template: ReactElement;
  from?: string;
  replyTo?: string;
}

export async function sendEmail({
  to,
  subject,
  template,
  from = process.env.EMAIL_FROM ?? brand.emails.from,
  replyTo,
}: SendEmailOptions) {
  const resend = getResend();
  const html = await render(template);

  return resend.emails.send({
    from,
    to,
    subject,
    html,
    replyTo,
  });
}

The render() function from @react-email/components converts a React element into an HTML string. This HTML is what Resend delivers to the customer's inbox.

The from address defaults to your brand's email configuration. You need a verified domain in Resend for this to work. During development, Resend's free tier lets you send to your own email address without domain verification.

How to Build a Purchase Confirmation Template

Here's the real purchase confirmation email template:

// src/lib/email/emails/purchase-confirmation.tsx
import {
  Body,
  Container,
  Head,
  Heading,
  Hr,
  Html,
  Link,
  Preview,
  Section,
  Text,
} from "@react-email/components";

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

interface PurchaseConfirmationEmailProps {
  amount: number;
  currency: string;
  customerEmail: string;
}

const colors = {
  primary: "#d97757",
  background: "#faf9f5",
  foreground: "#30302e",
  muted: "#6b6860",
  border: "#e5e4df",
  card: "#ffffff",
  success: "#16a34a",
  successLight: "#f0fdf4",
};

export default function PurchaseConfirmationEmail({
  amount,
  currency,
  customerEmail,
}: PurchaseConfirmationEmailProps) {
  const formattedAmount = new Intl.NumberFormat("en-US", {
    style: "currency",
    currency: currency.toUpperCase(),
  }).format(amount / 100);

  return (
    <Html>
      <Head />
      <Preview>Your {brand.name} purchase is confirmed!</Preview>
      <Body style={main}>
        <Container style={container}>
          <Section style={header}>
            <Text style={logoText}>{brand.name}</Text>
          </Section>

          <Hr style={divider} />

          <Section style={successBadge}>
            <Text style={successText}>Payment Successful</Text>
          </Section>

          <Heading style={h1}>Thank you for your purchase!</Heading>

          <Text style={text}>
            Your payment has been processed successfully. We are now setting
            up your GitHub repository access. You will receive another email
            shortly with your access link.
          </Text>

          <Section style={detailsBox}>
            <Text style={detailsTitle}>Order Details</Text>

            <Section style={detailRow}>
              <Text style={detailLabel}>Product</Text>
              <Text style={detailValue}>{brand.name}</Text>
            </Section>

            <Section style={detailRow}>
              <Text style={detailLabel}>Amount</Text>
              <Text style={detailValue}>{formattedAmount}</Text>
            </Section>

            <Section style={detailRow}>
              <Text style={detailLabel}>Email</Text>
              <Text style={detailValue}>{customerEmail}</Text>
            </Section>
          </Section>

          <Text style={text}>
            This is a one-time purchase. No recurring charges will be made.
          </Text>

          <Hr style={divider} />

          <Text style={footer}>
            Questions about your purchase? Reply to this email or reach
            out at{" "}
            <Link
              href={`mailto:${brand.emails.support}`}
              style={link}
            >
              {brand.emails.support}
            </Link>
          </Text>
        </Container>
      </Body>
    </Html>
  );
}

PurchaseConfirmationEmail.PreviewProps = {
  amount: 9900,
  currency: "usd",
  customerEmail: "customer@example.com",
} satisfies PurchaseConfirmationEmailProps;

A few things to note about this template.

• Currency formatting happens in the template: The amount prop is in cents (the same format stored in your database and returned by Stripe). The Intl.NumberFormat call converts it to a human-readable string like "$99.00" and keeps currency formatting logic in one place.

• The PreviewProps object is for development. React Email uses these props to render a preview in the browser. The satisfies keyword ensures the preview props match the component's interface.

• All styles are inline objects. Email clients strip <style> tags and ignore most CSS. Inline styles are the only reliable way to style emails across Gmail, Outlook, Apple Mail, and every other client.

How to Build a Repo Access Template

The repo access email is sent after the GitHub invitation succeeds:

// src/lib/email/emails/repo-access-granted.tsx
import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Hr,
  Html,
  Link,
  Preview,
  Section,
  Text,
} from "@react-email/components";

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

interface RepoAccessGrantedEmailProps {
  repoUrl: string;
}

export default function RepoAccessGrantedEmail({
  repoUrl,
}: RepoAccessGrantedEmailProps) {
  return (
    <Html>
      <Head />
      <Preview>Your {brand.name} repository access is ready!</Preview>
      <Body style={main}>
        <Container style={container}>
          <Section style={header}>
            <Text style={logoText}>{brand.name}</Text>
          </Section>

          <Hr style={divider} />

          <Heading style={h1}>You are in!</Heading>

          <Text style={text}>
            Your GitHub repository access has been granted. You now have
            full access to the {brand.name} codebase.
          </Text>

          <Section style={buttonContainer}>
            <Button style={button} href={repoUrl}>
              Open Repository
            </Button>
          </Section>

          <Section style={infoBox}>
            <Text style={infoTitle}>Quick Start</Text>
            <Text style={infoText}>
              <strong>1.</strong> Clone the repository to your machine
            </Text>
            <Text style={infoText}>
              <strong>2.</strong> Run{" "}
              <code style={codeStyle}>bun install</code> to install
              dependencies
            </Text>
            <Text style={infoText}>
              <strong>3.</strong> Follow the README for environment setup
            </Text>
            <Text style={infoText}>
              <strong>4.</strong> Run{" "}
              <code style={codeStyle}>bun dev</code> to start building
            </Text>
          </Section>

          <Hr style={divider} />

          <Text style={footer}>
            Need help? Reply to this email or reach out at{" "}
            <Link
              href={`mailto:${brand.emails.support}`}
              style={link}
            >
              {brand.emails.support}
            </Link>
          </Text>
        </Container>
      </Body>
    </Html>
  );
}

This template includes a <Button> component that links directly to the GitHub repository. The quick start section gives the customer immediate next steps so they aren't left wondering what to do after gaining access.

How to Build an Abandoned Cart Template

The abandoned cart email brings the customer back to your pricing page:

// src/lib/email/emails/abandoned-cart.tsx
import {
  Body,
  Button,
  Container,
  Head,
  Heading,
  Hr,
  Html,
  Preview,
  Section,
  Text,
} from "@react-email/components";

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

interface AbandonedCartEmailProps {
  customerEmail: string;
  checkoutUrl: string;
}

export default function AbandonedCartEmail({
  customerEmail,
  checkoutUrl,
}: AbandonedCartEmailProps) {
  return (
    <Html>
      <Head />
      <Preview>Your {brand.name} checkout is waiting for you</Preview>
      <Body style={main}>
        <Container style={container}>
          <Section style={header}>
            <Text style={logoText}>{brand.name}</Text>
          </Section>

          <Hr style={divider} />

          <Heading style={h1}>You left something behind</Heading>

          <Text style={text}>
            We noticed you started a checkout but did not complete your
            purchase. No worries. Your cart is still waiting for you.
          </Text>

          <Text style={text}>
            {brand.name} gives you everything you need to ship your
            startup this weekend: authentication, payments, email,
            background jobs, and more. All wired together and ready
            to go.
          </Text>

          <Section style={buttonContainer}>
            <Button style={button} href={checkoutUrl}>
              Complete Your Purchase
            </Button>
          </Section>

          <Text style={textSmall}>
            If you ran into any issues during checkout or have questions
            about {brand.name}, just reply to this email. I read every
            message personally.
          </Text>

          <Hr style={divider} />

          <Text style={footer}>
            This email was sent to {customerEmail} because you started
            a checkout on {brand.name}. If this was not you, you can
            safely ignore this email.
          </Text>
        </Container>
      </Body>
    </Html>
  );
}

The tone matters here. "You left something behind" is friendly, not pushy. The email explains the product's value briefly, includes a single clear call to action, and the footer explains why they received the email.

How Templates Integrate with Durable Steps

Every email template is invoked via createElement inside a step.run() block:

await step.run("send-purchase-confirmation", async () => {
  await sendEmail({
    to: user.email,
    subject: `Your ${brand.name} purchase is confirmed!`,
    template: createElement(PurchaseConfirmationEmail, {
      amount: purchase.amount,
      currency: purchase.currency,
      customerEmail: user.email,
    }),
  });
});

The createElement call creates a React element from the template component with the given props. The sendEmail function renders it to HTML via React Email's render() and sends it through Resend.

Because this is inside a step.run(), the email send is checkpointed. If Resend is down and the step fails, it retries on its own without re-running previous steps. The customer never gets a duplicate email.

How to Test the Complete Flow Locally

Testing the complete payment lifecycle locally requires three things running simultaneously: your application, the Stripe CLI forwarding webhook events, and the Inngest dev server processing background jobs.

Step 1: Start the Stripe CLI

Install the Stripe CLI and log in:

# macOS
brew install stripe/stripe-cli/stripe

# Authenticate
stripe login

Forward webhook events to your local server:

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

The CLI prints a webhook signing secret starting with whsec_. Copy this to your .env as STRIPE_WEBHOOK_SECRET.

Step 2: Start the Inngest Dev Server

The Inngest dev server gives you real-time visibility into every function execution, every step, and every retry:

npx inngest-cli@latest dev -u http://localhost:3000/api/inngest

Open http://localhost:8288 in your browser. This is the Inngest dashboard where you'll watch your durable functions execute step by step.

Step 3: Start Your Application

bun run dev

Your application should now be running on http://localhost:3000.

Step 4: Test the Purchase Flow

1. Go to your pricing page and click the checkout button.

2. Use Stripe's test card number 4242 4242 4242 4242 with any future expiration date and any CVC.

3. Complete the checkout. Stripe redirects you to your success URL.

4. Your frontend calls the /api/purchases/claim endpoint with the session ID.

5. Watch the Inngest dashboard. You should see the purchase-completed function trigger and each step execute in sequence.

In the Inngest dashboard, you will see:

• Step 1: "lookup-user-and-purchase" completes with the user and purchase data.

• Step 2: "track-purchase-to-posthog" completes (or logs a warning if PostHog isn't configured).

• Step 3: "send-purchase-confirmation" completes. Check your email.

• Step 4: "send-admin-notification" completes (if ADMIN_EMAIL is set).

• Steps 5-9: Run if the user has a GitHub username linked.

Step 5: Test a Refund

Trigger a refund through the Stripe CLI:

stripe trigger charge.refunded

Or go to the Stripe dashboard, find the test payment, and issue a refund manually. The Stripe CLI will forward the charge.refunded webhook to your local server.

In the Inngest dashboard, you'll see the refund-processed function trigger with its own set of steps: lookup, conditional access revocation, status update, analytics tracking, and email notifications.

Step 6: Test Abandoned Cart Recovery

Trigger a checkout expiration:

stripe trigger checkout.session.expired

The checkout-expired function will appear in the Inngest dashboard. You'll see the 1-hour sleep step. In the dev server, you can fast-forward through sleeps by clicking the "Skip" button in the dashboard. This lets you test the delayed email without actually waiting an hour.

How to Simulate Step Failures

To test the retry behavior, temporarily throw an error in one of your steps:

const collaboratorResult = await step.run(
  "add-github-collaborator",
  async () => {
    throw new Error("Simulated GitHub API failure");
  }
);

In the Inngest dashboard, you'll see:

• Steps 1 through 4 succeed and their results are cached.

• Step 5 fails and is retried with exponential backoff.

• Steps 6 through 9 remain pending.

Remove the thrown error, and on the next retry, step 5 succeeds. Steps 6 through 9 execute, while steps 1 through 4 aren't re-executed. This is the checkpointing behavior that makes durable execution reliable.

Conclusion

Building a complete SaaS payment flow is more than integrating Stripe Checkout. It's the entire lifecycle from "Buy" button to "Welcome" email, including the parts that happen when things go wrong.

Here's what you built in this tutorial:

• A database schema that tracks purchases through every state: completed, partially refunded, and fully refunded.

• A Stripe product and price seed script that creates your catalog programmatically.

• A checkout flow with session creation, payment verification, and idempotent purchase claiming.

• A thin webhook handler that validates signatures and routes events to background jobs.

• A 9-step durable purchase function where each step is independently checkpointed and retried.

• A refund handler that distinguishes between full and partial refunds, revoking access only when appropriate.

• An abandoned cart recovery flow that waits an hour before sending a friendly recovery email.

• Three transactional email templates built with React Email: purchase confirmation, repo access granted, and abandoned cart.

• A local testing setup with Stripe CLI, Inngest dev server, and step-by-step observability.

The most important pattern is the separation between receiving and processing. Your API endpoints and webhook handlers should be thin: validate, record, enqueue, return. All the complex multi-step work happens in durable background functions where failures are isolated and retried at the step level.

This pattern scales. Add a new step to the purchase flow, and it gets the same checkpointing and retry behavior. Add a new webhook event, and you route it to a new durable function.

Your requirements may differ. You might sell subscriptions instead of one-time purchases, or provision API keys instead of GitHub access. The specific steps change, but the architecture stays the same.

If you want to start with all of these patterns already wired together in a production-ready codebase, Eden Stack includes the complete payment flow described in this article, along with 30+ additional production-tested patterns for authentication, email, analytics, background jobs, and more.

Magnus Rødseth builds AI-native applications and is the creator of Eden Stack, a production-ready starter kit with 30+ Claude skills encoding production patterns for AI-native SaaS development.

If you understand how SEO landing pages actually work today, you’re not guessing. Instead, you're building assets that pull traffic and convert.

This guide walks you through how I researched, structured, built, and deployed a real SEO landing page tailored for affiliate marketers.

Table of Contents

• Prerequisites

• Keyword Research

  • Supporting Keywords

  • How Did I Get Those Keywords?

• What To Do After Keyword Research

  • Lock Your Page Intent (Critical)

  • Group Your Keywords (Clustering)

  • Analyze the SERP (Your Real Competitors)

• Create Your SEO Landing Page Blueprint

  • Above the Fold (Conversion Zone)

  • Main Content (Ranking and Conversion Zone)

  • Scalability Thinking

• How I Built the Project (Development Process)

• On-Page SEO Setup

  • Project Structure

  • SEO + Metadata Setup

  • Structured Data (Schema Markup)

  • Hero Section (Above-the-Fold SEO)

  • Value Section (Keyword Reinforcement)

  • Benefits Grid (Scannable SEO Content)

  • Product Section (Conversion + Affiliate SEO)

  • Comparison Table (High-Intent SEO Content)

  • Review Section

  • FAQ Section (Search Expansion)

  • CTA Section (Conversion Signal)

  • Footer

  • JavaScript UX Enhancements

• Deployment (Using Netlify)

  • Why Netlify?

  • Step 1 — Push Your Project to GitHub

  • Enable HTTPS

  • Publish and Index

  • Post-Publish (This Is Where Ranking Happens)

  • Turn This Into a System (Advanced Move)

  • Simple Reality Check

  • Final Result

Prerequisites

Before following this guide, you should have:

• Basic understanding of how websites work (HTML, CSS and JavaScript basics is helpful)

• A GitHub account (for deployment)

• A Netlify account (free)

• Basic understanding of SEO (keywords, search intent)

• A niche or product idea to build your landing page around

Optional but helpful:

• Familiarity with tools like Google Keyword Planner, Ahrefs, or Semrush

Keyword Research

First, get your primary keyword. The primary keyword for the purpose of this article is "eco-friendly running shoes".

Supporting Keywords:

• eco friendly running shoes for men

• sustainable running shoes brands

• biodegradable running shoes

• vegan running shoes

• best recycled material sneakers

• eco running shoes review

• affordable eco-friendly sneakers

• lightweight sustainable running shoes

How Did I Get Those Keywords?

Well, by using tool-based research. I simulated the process with Google Keyword Planner. There are also other tools like Semrush and Ahrefs you can use for this purpose.

Process

• Entered: best eco-friendly running shoes

• Filtered for:

  • Buyer intent (words like “best”, “buy”, “review”)

  • Medium/low competition

  • Long-tail phrases

SERP Intent Research

Next, I opened my browser and searched: best eco-friendly running shoes

Then I analyzed:

• Are results blog posts or product pages?

• Do they compare products?

• Are there buying guides?

I found a variety of list-style articles (listicles), product comparisons pages, affiliate-style landing pages, and strong CTAs like "Buy now” or “Check price”.

This tells us users want curated recommendations plus a clear path to purchase.

Keyword Selection Logic

I picked the primary keyword because:

• It shows clear buying intent

• It’s long-tail (easier to rank)

• It matches a conversion-focused landing page

What To Do After Keyword Research

Once you have your keywords, don’t jump into writing yet. Do this:

Lock Your Page Intent (Critical)

Before writing anything, decide your page goal: Is it to sell or educate?

The four types of search intent are commercial, transactional, informational, and navigational.

For this keyword – best eco-friendly running shoes – the primary Intent is transactional (buying) while the secondary intent is informational.

So your page needs to help users choose the right product and guide them toward making a purchase.

If your intent is unclear, your page will struggle to rank.

Group Your Keywords (Clustering)

Instead of treating keywords separately, organize them into groups.

Let's look at an example:

Primary Keyword

• best eco-friendly running shoes

Cluster 1 – Buyer Intent

• eco friendly running shoes for men

• best sustainable running shoes

• affordable eco-friendly sneakers

Cluster 2 – Informational

• what are eco-friendly running shoes

• benefits of sustainable shoes

• how eco shoes are made

This matters because Google ranks pages based on topics, not just individual keywords.

Analyze the SERP (Your Real Competitors)

Search your keyword again and study the top 3 – 5 results.

Look at page structure, content length, and the sections included.

You should also check for patterns:

• Do they list multiple products?

• Do they include comparison tables?

• Are there FAQs?

• Do they use images or videos?

Your goal is not to copy but to build something better structured and more useful.

Create Your SEO Landing Page Blueprint

Now turn your research into a clear structure.

Your page should look like this:

Above the Fold (Conversion Zone)

This is what users see first.

• H1: Best Eco-Friendly Running Shoes

• Short sub-headline (value-focused)

• Strong CTA (for example, Shop Now, View Top Picks)

Main Content (Ranking and Conversion Zone)

This is where SEO and conversions happen together.

You should include:

1. Top Products Section: List at least 5 recommended shoes

2. Benefits of Eco-Friendly Shoes: Educate users briefly

3. Comparison Table: Help users quickly decide

4. Product Reviews / Social Proof: Build trust

5. FAQ Section: Answer common questions and capture extra search traffic.

Scalability Thinking

If your goal is to build multiple SEO pages, you need a system — not random pages. I designed this landing page to be scalable.

In practice, scalability means a few different things.

First, you'll need to have a reusable layout. Instead of designing every page from scratch, create one high-converting template (headline, product list, comparison table, FAQs). Then reuse it across different keywords.

Second, you'll need to understand content swapping. This means you only change the keyword, product list, images, and supporting content.

For example:

• Page 1: Best eco-friendly running shoes

• Page 2: Best vegan running shoes

• Page 3: Best sustainable gym wear

You'll also want to make sure your site has a consistent structure as this results in faster ranking. Google understands your site better when pages follow a clear pattern.

You should also understand the advantages of internal linking. When you connect these pages together, you build topical authority, which improves rankings across all pages.

The goal is simple: build once, scale many times.

How I Built the Project (Development Process)

This sample landing page is designed for affiliate marketers.

Note that the brand names, values, images, and prices used on this page are fictitious and are for demonstration purposes only.

To build this page, I used HTML, CSS, and JavaScript.

My focus areas were:

• That it had a clean and structured layout

• That is was fast loading and scored well on performance

• That it had a mobile-friendly design

On-Page SEO Setup

Here’s a real example of how I built this SEO landing page:

Project Structure

ECO-PREMIUM/
├── index.html
├── styles.css
├── script.js
├── README.md
└── assets/
    └── shoes/
        ├── allbirds.jpg
        ├── reebok.jpg
        ├── brooks.jpg
        ├── veja.jpg
        ├── adidas.jpg
        ├── nike.jpg
        ├── hero-bg.jpg

SEO + Metadata Setup

This is where SEO starts. Before design, I made sure Google understands the page instantly.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">

<title>Best Eco-Friendly Running Shoes (2026 Guide)</title>

<meta name="description" content="Discover the best eco-friendly running shoes for men and women. Compare sustainable running shoes brands, reviews, and find affordable eco sneakers.">

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css">

<link rel="stylesheet" href="styles.css">

<link rel="preload" as="image" href="assets/shoes/allbirds.jpg">

Why This Matters (SEO Strategy)

• The viewport tag makes sure the page looks good on mobile, which is important for rankings.

• The title combines the main keyword with a year like “2026” to keep it fresh and relevant in search.

• The meta description briefly explains what users will get and encourages clicks.

• The Font Awesome stylesheet adds scalable icons for better UI and trust signals.

• The styles.css file controls the site’s design, ensuring a clean, responsive layout that supports user experience and engagement.

• And preloading key images helps the page load faster, improving performance and SEO.

Structured Data (Schema Markup)

<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What are eco-friendly running shoes?",
"acceptedAnswer": {"@type": "Answer","text": "They are shoes made from sustainable materials."}
}
]
}
</script>

Why This Matters

• It enables rich snippets in Google, improves click-through rates, and strengthens topical authority.

Hero Section (Above-the-Fold SEO)

This is the most important section for both users and search engines.

<header class="hero">
  <div class="hero-overlay"></div>

  <div class="hero-content">
    <h1>Best Eco-Friendly Running Shoes</h1>
    <p>High-performance. Sustainable. Built for runners who care.</p>
    <a href="#products" class="btn">Explore Top Picks</a>
  </div>
</header>

The styling:

.hero {
  background:url('assets/shoes/hero-bg.jpg') center/cover no-repeat;
  min-height:90vh;
  display:flex;
  justify-content:center;
  align-items:center;
  text-align:center;
}

.hero-overlay {
  position:absolute;
  inset:0;
  background:rgba(0,0,0,0.6);
}

The UI view:

Why This Matters

• The H1 targets the primary keyword, while strong visual engagement helps reduce bounce rate, and a clear CTA improves user interaction signals.

Value Section (Keyword Reinforcement)

This section strengthens semantic SEO relevance.

<section class="value">
  <h2>Premium Sustainable Running Experience</h2>
  <p>
    Discover eco friendly running shoes for men and women designed with recycled materials.
  </p>
</section>

section {
  padding:80px 20px;
  max-width:1100px;
  margin:auto;
}

Why This Matters

• It supports keyword variations, improves topical depth, and helps Google better understand search intent.

Benefits Grid (Scannable SEO Content)

Google favors structured, easy-to-scan content.

<section class="benefits">
  <h2>Why Choose Eco Running Shoes</h2>
  <div class="grid">
    <div>Sustainable materials</div>
    <div>Lower carbon footprint</div>
    <div>Lightweight design</div>
  </div>
</section>

The styling:

.grid {
  display:grid;
  grid-template-columns:repeat(auto-fit,minmax(200px,1fr));
  gap:20px;
}

The UI view:

Why This Matters

• It supports keyword variations, improves topical depth, and helps Google better understand search intent.

Product Section (Conversion + Affiliate SEO)

This is where traffic turns into revenue.

<!-- PRODUCTS -->
<section id="products" class="products">
  <h2>Top Picks</h2>

  <div class="cards">

    <div class="card">
      <img src="assets/shoes/allbirds.jpg" alt="Allbirds Tree     Dasher eco-friendly running shoes made from sustainable materials" loading="lazy">
      <h3>Allbirds Tree Dasher</h3>
      <p>Lightweight sustainable running shoes.</p>
      <a href="https://example.com/allbirds-affiliate" target="_blank" class="btn">Check Price</a>
    </div>
 </div>
</section>

The styling:

.cards {
  display:grid;
  grid-template-columns:repeat(3,1fr);
  gap:30px;
}

.card {
  background:#111;
  padding:20px;
  border-radius:20px;
}

Why This Matters

• Lazy loading improves performance, a well-structured product layout drives affiliate conversions, and animations enhance user engagement.

The UI view:

Avoid this common mistake for image alt text:

alt="eco shoes eco friendly running shoes best eco shoes cheap eco shoes"

That hurts SEO more than it helps.

This is bad because:

• It’s keyword stuffing (Google may treat this as spam)

• It provides no real description of the image

• It creates a poor experience for screen readers (accessibility issue)

What Google prefers:

Alt text should describe the image naturally while including the keyword where relevant.

Pro Tip (for your whole site)

Use this formula for every product image alt text:

[Product Name] + [Main Feature] + [Keyword]

Example:

• “Nike Air Zoom eco-friendly running shoes with recycled materials”

This improves: SEO relevance, Accessibility, and User experience

Comparison Table (High-Intent SEO Content)

This targets buyers ready to decide.

<section class="comparison">
  <h2>Comparison Table</h2>
  <table>
    <tr>
      <th>Brand</th><th>Weight</th><th>Material</th>                   <th>Durability</th>
      <th>Comfort</th><th>Eco Score</th><th>Price</th><th>Best For</th>
    </tr>
    <tr>
      <td>Allbirds</td><td>Light</td><td>Eucalyptus, fibre, sugarcane</td><td>High</td>
      <td>Very Good</td><td>8/10</td><td>$125</td><td>Daily runs</td>
    </tr>
</table>
</section>

Why This Matters

• It captures comparison keywords, improves time on page, and increases visibility for "product vs product" searches.

The UI view:

Review Section

<section class="reviews">
  <h2>Trusted by Runners</h2>
  <p>⭐⭐⭐⭐⭐ "Right place to buy the best eco-friendly sneakers"</p>
  <p>⭐⭐⭐⭐⭐ "Brands they sell are lightweight and durable"</p>
  <p>⭐⭐⭐⭐ "My order arrived on time, I like their timing!"</p>
</section>

Why this matters

• It builds trust and makes people more likely to click and buy. It also helps SEO by adding real user language and improving engagement.

FAQ Section (Search Expansion)

<section class="faq">
  <h2>FAQs</h2>

  <details>
    <summary>What are eco-friendly running shoes?</summary>
    <p>Eco-friendly running shoes are made using sustainable or recycled materials like organic cotton, eucalyptus fiber, and recycled plastics to reduce environmental impact.</p>
  </details>
</section>

The UI view:

Why this matters

• It targets long-tail keywords, supports featured snippets, and reinforces schema relevance.

CTA Section (Conversion Signal)

<section class="cta">
  <h2>Start Running Sustainably</h2>
  <a href="#products" class="btn">Shop Now</a>
</section>

Why This Matters

• It encourages user action, improves engagement metrics, and signals to Google that the content is useful and valuable.

Footer

<!-- FOOTER -->
<footer class="footer">

  <div class="footer-top">

    <div class="footer-brand">
      <img src="assets/logo.png" alt="Logo" class="logo">
      <p>Trusted eco-friendly product reviews.</p>
    </div>
  <div class="footer-bottom">
    <p>© 2026 Eco Running Guide</p>
  </div>

</footer>

The UI view:

Why This Matters

• The footer builds trust, provides important legal and navigation links, and supports SEO by reinforcing site credibility.

JavaScript UX Enhancements

<html>
.
.
.
<body>
.
.
.
<script src="script.js"></script>
</body>
</html>

JavaScript code snippet:

// Smooth scroll
document.querySelectorAll('a[href^="#"]').forEach(anchor=>{
  anchor.addEventListener("click",function(e){
    e.preventDefault();
    document.querySelector(this.getAttribute("href"))
    .scrollIntoView({behavior:"smooth"});
  });
});

// Fade-in cards
const cards = document.querySelectorAll('.card');
cards.forEach(card=>{
  card.style.opacity = 0;
  card.style.transform = "translateY(20px)";
});

window.addEventListener('scroll', ()=>{
  cards.forEach(card=>{
    const rect = card.getBoundingClientRect();
    if(rect.top < window.innerHeight - 50){
      card.style.opacity = 1;
      card.style.transform = "translateY(0)";
      card.style.transition = "0.5s";
    }
  });
});

Why This Matters

• The script link ensures interactive features (like smooth scrolling and animations) load properly, improving user experience and engagement.

Note that the above code snippets are part of the main code file. You can copy or clone the project code files from this repository.

Deployment (Using Netlify)

Why Netlify?

Netlify is one of the easiest and fastest ways to deploy modern websites. It’s widely used by developers because it has:

• Free hosting for small to medium projects

• Automatic deployment from GitHub (no manual uploads)

• A fast global CDN (your site loads quickly anywhere)

• Built-in HTTPS (SSL security included)

• Simple custom domain setup

• It's perfect for static sites (HTML, CSS, JS landing pages)

In simple terms, Netlify removes the stress of server setup and lets you focus on building and improving your site.

Step 1 — Push Your Project to GitHub

Before anything, make sure your landing page project is already uploaded to GitHub.

Connect to Netlify

1. Go to Netlify and sign up or log in.

2. Click “Add new site”

3. Select “Import an existing project”

4. Choose GitHub

5. Authorize Netlify to access your repositories

Select Your Repository

Then find your project repo (for example,seo-landing-landing) and click on it. Netlify will automatically detect it as a static site.

Deploy the Site

Now click “Deploy site”. Netlify will build and host your project. After a few seconds, you’ll get a live URL.

Example:

https://ecorunningshoes.netlify.app/

Adding a Custom Domain

To make your site look professional (instead of using netlify.app), you can connect your own domain like:

www.yourdomain.com

Steps:

1. Go to your Netlify dashboard

2. Open your deployed site

3. Click “Domain settings”

4. Select “Add custom domain”

5. Enter your domain name (e.g. ecorunshoes.com)

6. Click "verify"

Configure DNS (Important)

After adding your domain, go to your domain provider (for example, Namecheap, GoDaddy) and update the DNS records as Netlify instructs:

• Add CNAME record pointing to Netlify

• Or use Netlify DNS (recommended) for easier setup

Enable HTTPS

Once the domain is connected, Netlify automatically issues a free SSL certificate. Your site becomes secure:

https://yourdomain.com

Publish and Index

After deployment, make sure to submit the URL to Google Search Console and request indexing.

Post-Publish (This Is Where Ranking Happens)

Most pages don’t rank because people stop at publishing.

There are a few more things you should do before you're done:

Build backlinks

• Add guest posts

• Blog mentions

• Directories

Update content

• Add new products

• Improve sections

• Refresh FAQs

Turn This Into a System (Advanced Move)

Don’t just build ONE page. Build a cluster system:

The main page will focus on "best eco-friendly running shoes".

The Supporting pages:

• best vegan running shoes

• eco-friendly gym wear

• sustainable shoe brands

Link them together so authority increases and rankings grow faster.

Simple Reality Check

Keyword research is only 20% of SEO.

The other 80% is:

• Structure

• Intent matching

• Content depth

• Authority (backlinks)

When these work together, your page doesn’t just rank — it sells.

Final Result

You now have a live SEO landing page that's hosted for free on Netlify and automatically updated from GitHub, as well as a professional custom domain (optional but recommended).

A high-ranking SEO landing page works best when strategy, structure, and intent are properly aligned. Good keyword research, SERP analysis, and a clear page layout all contribute to both visibility and conversions.

When combined with solid on-page SEO and proper deployment, your landing page becomes a reliable asset that can attract traffic and deliver results over time. Success in SEO also depends on consistent updates and ongoing optimization after publishing.

If you’ve ever tried to upload a PDF and hit a file size limit, you’ve already seen why compression matters.

Most tools solve this by uploading your file to a server. That works, but it’s not always ideal, especially when dealing with private or sensitive documents.

The good news is that modern browsers are powerful enough to handle basic PDF compression locally.

In this tutorial, you’ll learn how to build a browser-based PDF compression tool using JavaScript, where everything runs directly in the browser.

Table of Contents

1. How PDF Compression Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading the PDF File

6. Understanding Compression Strategy

7. Compressing the PDF

8. Generating and Downloading the File

9. Demo: How the PDF Compression Tool Works

10. Important Notes from Real-World Use

11. Common Mistakes to Avoid

12. Conclusion

How PDF Compression Works

PDF compression is different from image compression.

A PDF isn't just a single image. It’s a structured document that can include text, images, fonts, and metadata. Because of this, reducing its size involves optimizing multiple parts of the file rather than applying a single compression method.

In most cases, compressing a PDF means lowering image quality where possible, removing unnecessary or unused data, and optimizing how the document is internally structured.

When working in the browser, we don’t have the same level of control as server-side tools. But we can still reduce file size by reprocessing the document and saving it in a more efficient format.

This approach may not achieve extreme compression, but it works well for creating lighter, more efficient files while keeping everything fast and private.

Project Setup

This project is simple.

You only need:

• an HTML file

• JavaScript

• a PDF library

No backend is required. Everything runs locally in the browser.

What Library Are We Using?

We’ll use pdf-lib, which allows us to load and recreate PDF files.

Add it using a CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

Creating the Upload Interface

Start with a simple interface:

<input type="file" id="upload" accept="application/pdf">
<button onclick="compressPDF()">Compress PDF</button>

<a id="download" style="display:none;">Download Compressed PDF</a>

This allows users to upload a PDF, trigger compression, and download the result once ready.

Reading the PDF File

Now read the uploaded file:

const fileInput = document.getElementById("upload");

if (!fileInput.files.length) {
  alert("Please upload a PDF");
  return;
}

const file = fileInput.files[0];
const arrayBuffer = await file.arrayBuffer();

Understanding Compression Strategy

Since we’re working in the browser, we don’t have full low-level control over PDF compression.

Instead, we focus on practical optimizations that help reduce file size without affecting usability too much. This includes recreating the document structure in a more efficient way, removing unnecessary metadata, and reducing image quality where possible.

The goal here isn’t perfect compression, but producing a lighter file while maintaining acceptable visual quality and readability.

Compressing the PDF

Here’s the core logic:

async function compressPDF() {
  const fileInput = document.getElementById("upload");

  if (!fileInput.files.length) {
    alert("Please upload a PDF");
    return;
  }

  const file = fileInput.files[0];
  const arrayBuffer = await file.arrayBuffer();

  const { PDFDocument } = PDFLib;

  const originalPdf = await PDFDocument.load(arrayBuffer);
  const newPdf = await PDFDocument.create();

  const pages = await newPdf.copyPages(
    originalPdf,
    originalPdf.getPageIndices()
  );

  pages.forEach(page => newPdf.addPage(page));

  const pdfBytes = await newPdf.save({
    useObjectStreams: true
  });

  const blob = new Blob([pdfBytes], { type: "application/pdf" });

  const link = document.getElementById("download");
  link.href = URL.createObjectURL(blob);
  link.download = "compressed.pdf";
  link.style.display = "inline";
  link.innerText = "Download Compressed PDF";
}

This recreates the PDF using optimized object streams, which can reduce file size.

Generating and Downloading the File

Once processed:

link.href = URL.createObjectURL(blob);
link.download = "compressed.pdf";

The file is downloaded instantly, without any server interaction.

Demo: How the PDF Compression Tool Works

Here’s how the full flow looks in a real-world scenario using the browser-based PDF compression tool.

Step 1: Upload PDF

Start by uploading your PDF file. You can either drag and drop the file into the upload area or click the “Select PDF” button to choose a file from your device.

Step 2: Preview the PDF

Once the file is loaded, the tool displays a preview of the document. You can navigate between pages to confirm that the correct file has been uploaded before applying compression.

Step 3: Choose Compression Settings

Next, select the compression level based on your needs. Lower compression keeps better quality, while higher compression reduces file size more aggressively. You can also explore advanced options like metadata handling.

Step 4: Compress the PDF

Click the “Compress PDF” button to start the process. The tool processes everything directly in your browser, without uploading files to any server.

Step 5: Download the Compressed File

After compression is complete, you’ll see the final result along with the reduced file size. You can then rename and download the optimized PDF instantly.

Important Notes from Real-World Use

When working with PDF compression in the browser, handling large files becomes important.

If a user uploads a very large PDF, processing everything at once can slow down the browser or even cause it to freeze. Instead of trying to process everything blindly, it’s better to add checks and handle files carefully.

For example, you can limit the file size before processing:

const MAX_SIZE = 10 * 1024 * 1024; // 10MB

if (file.size > MAX_SIZE) {
  alert("File is too large. Please upload a file under 10MB.");
  return;
}

This prevents performance issues and keeps the tool responsive.

Another useful approach is to process files step by step instead of doing everything at once:

const { PDFDocument } = PDFLib;

const originalPdf = await PDFDocument.load(arrayBuffer);
const newPdf = await PDFDocument.create();

for (let i = 0; i < originalPdf.getPageCount(); i++) {
  const [page] = await newPdf.copyPages(originalPdf, [i]);
  newPdf.addPage(page);
}

This spreads the work across smaller steps and avoids blocking the browser.

It’s also important to remember that everything runs client-side. This means files never leave the user’s device, which is great for privacy. But it also means performance depends on the user’s device, so keeping processing efficient is important.

Common Mistakes to Avoid

One common mistake is not validating user input properly before processing the file.

For example, users might try to upload an empty file, a non-PDF file, or even trigger the compression without selecting anything. It’s important to check these cases early to avoid errors later in the process:

const fileInput = document.getElementById("upload");

if (!fileInput.files.length) {
  alert("Please upload a PDF file.");
  return;
}

const file = fileInput.files[0];

if (file.type !== "application/pdf") {
  alert("Only PDF files are supported.");
  return;
}

Another issue is allowing invalid or unexpected input to pass through. Even something as simple as an empty or corrupted file can cause the PDF processing to fail, so basic validation makes the tool much more reliable.

Handling large files without any checks is another common problem. If a very large PDF is processed without limits, it can slow down the browser or even make the page unresponsive. Adding a simple file size check helps prevent this:

const MAX_SIZE = 10 * 1024 * 1024; // 10MB

if (file.size > MAX_SIZE) {
  alert("File is too large. Please upload a file under 10MB.");
  return;
}

Another mistake is assuming that compression will always produce a significantly smaller file. In reality, browser-based compression is limited compared to dedicated server-side tools, so results can vary depending on the content of the PDF.

In practice, most issues come from missing validation and handling edge cases. Adding a few simple checks early makes the tool more stable and improves the overall user experience.

Conclusion

In this tutorial, you built a browser-based PDF compression tool using JavaScript.

You learned how to read and recreate PDF files, apply basic optimizations, and generate a downloadable file entirely in the browser.

If you’d like to try a complete version of this idea, you can check it out here: https://allinonetools.net/pdf-compressor/

This approach keeps everything fast, private, and simple to use.

Once you understand this pattern, you can extend it further to build more advanced document tools.

And that’s where things start getting really interesting.

You may be thinking: school alone is plenty of work! And it often is. But if you set your mind to it, like I did, you'll be amazed at what you can do.

In this story, I’ll share my journey of working through and receiving 15 freeCodeCamp certifications in just four months.

What I'll Cover:

• My Beginning with the Digital World

• Starting My Journey with freeCodeCamp

• Benefits of freeCodeCamp's Methodology

• freeCodeCamp Learning Paths

• 1- Responsive Web Design Certification.

• 2- JavaScript Algorithms and Data Structures

• 3- Scientific Computing with Python

• 4- Data Visualization

• 5- Backend End Development and APIs

• 6- Front End Development Libraries

• 7- Data Analysis with Python

• 8- Machine Learning with Python

• 9- Quality Assurance

• 10- Information Security

• 11- Legacy Certifications

• Personal recommendations

My Beginning with the Digital World

I grew up in a family that really believed in life-long learning.

At an early age – around 10 – my father bought me my first laptop.

From there, learning became part of our daily routine. My father approached it with structure and intention. He designed a complete detailed learning plan for me.

Looking back, it was quite ambitious for someone my age. But my father always believed in high standards and expectations.

Still, we didn’t start with programming right away.

At first, we explored different areas and domains. I focused on trying to find something I though was interesting.

But it didn’t take long before we realized how important programming was becoming and how powerful it could be to start early.

So, we decided that I should start learning programming.

I began with HTML, building my very first web page. I was able to build a complete web page using different elements and tags on my own.

It was simple but it worked. That moment felt like a win.

Then I moved on to CSS. I was able to style and arrange the elements on the web page the way I liked. I grasped many CSS techniques and commands that help control the layout and arragement of elements so I could make them look the way I wanted.

After that came JavaScript. That’s when I was able to make things more alive. I started adding movement, interaction, and behavior to my web pages.

And I didn’t stop there.

I stepped into backend development with PHP, beginning to understand how things worked behind the scenes. Alongside that, I started learning SQL to handle databases – an essential part of building real, functional web applications.

Step by step, the picture was becoming clearer.

Before learning about these languages, the web sound like a black box. But after I finished learning them, I started looking at websites from a different angle, and I started recognizing how web pages are made.

All this learning came through a mix of YouTube lessons and structured courses my father invested in for me, like a 50-hour PHP course on Udemy.

I was absorbing a lot, moving from one concept to another, and building small pieces along the way.

But at some point, something clicked: I realized that watching tutorials – even long, detailed ones – wasn’t enough on its own. There was a gap between understanding concepts and building something real. So I decided I needed to dive deeper.

Starting My Journey with freeCodeCamp

I needed to move beyond lessons into building structured, meaningful web applications. Projects that weren’t just exercises, but had real purpose.

Projects with expectations, constraints, and even real stakeholders.

The kind of work that forces you to think, to make decisions, and to take ownership.

Because there’s a big difference between following along with a video… and sitting alone in front of a blank screen, figuring things out step by step.

That shift helped me avoid what many learners fall into: the endless loop of tutorials without real progress (Tutorial Hell).

And for the first time, I started to feel what it really means to build.

That’s when I made a clear decision to switch to freeCodeCamp. What drew me in was simple: it wasn’t just lessons. It was practice building real, structured, hands-on projects.

Benefits of freeCodeCamp's Methodology

After completing 15 certifications on freeCodeCamp, I was able to build and launch a full platform called Programming Ocean Academy, focused on Data Science and Artificial Intelligence.

It pushed me to think, to solve problems on my own, and to act like an engineer – not just a learner following instructions.

This wasn’t a small project. It included:

• A fully functional frontend and backend system

• More than 25 databases

• Over 150 pages

• Integrated training platforms

But what mattered more than the scale… was what came next.

Because of the strong logical and programming foundation I had built, transitioning into Data Science and AI felt natural and not overwhelming.

I moved into Python and its ecosystem with confidence. From there, I worked with powerful libraries like scikit-learn, TensorFlow, and PyTorch.

The solid foundation I'd built enabled me to deliver multiple training programs in collaboration with Arab universities, and I've helped train more than 5,000 learners.

Looking back, that shift from consuming content to building real systems and delivering courses was the turning point.

freeCodeCamp Learning Paths

Today, I’m happy to share this journey with you and to emphasize something I’ve come to believe deeply: the programs and learning paths offered by freeCodeCamp aren't just courses. They're a structured bridge that'll help take you from being someone who watches tutorials and writes code to someone who builds real applications and creates products that serve people.

Now, you have the context you need to understand the rest of the story.

So let’s begin.

This is where the journey with freeCodeCamp really starts. A journey I would confidently recommend to anyone who wants to enter the world of programming and technology with clarity and direction.

How did it start? And how did I choose my path?

At the beginning, I didn’t approach freeCodeCamp randomly.

I knew that if I wanted real progress, I needed structure.

So instead of jumping between topics, I followed a clear order – one that builds understanding step by step, just like constructing a solid foundation before raising a building.

I asked myself a simple question: What do I need to master first, so everything that comes after becomes easier not harder?

That question influenced everything that followed.

So instead of creating my own path from scratch, I decided to fully trust the methodology of freeCodeCamp, following its order of certifications, lessons, and progression exactly as designed.

That decision made everything simpler.

I started from the very beginning and moved step by step.

My journey began with:

1: Responsive Web Design Certification.

At that time, I was studying for around 8 hours a day on most days, balancing it with my school responsibilities. It wasn’t always easy, but the structure kept me focused.

During this first phase, I built a strong foundation.

I explored HTML in depth:

• Understanding almost all HTML tags

• Knowing the purpose of each element

• Learning which attributes belong to which elements

• When to use each tag properly

• Writing clean, semantic code that follows best practices

Then came CSS. This is where things evolved visually.

I started understanding more deeply how to:

• Style and structure pages

• Create modern, clean layouts

• Build responsive designs that adapt across devices

But the real test wasn’t the lessons.

To earn the certification, I had to complete five full projects, each one requiring me to apply everything I had learned, solve problems independently, and choose the best possible approach rather than just making things “work.”

That’s where the real learning happened.

2: JavaScript Algorithms and Data Structures

For the second certification, JavaScript, things took a different turn.

This is where the web stopped being static.

I learned how to make pages interactive and alive. I learned how to control behavior, respond to user actions, and build logic that does something. But more importantly, I spent time learning how to think logically.

JavaScript pushed me into algorithmic thinking:

• Breaking problems into smaller steps

• Writing logic in a structured, methodical way

• Building solutions that are not just correct but clean and scalable

And after that phase, I didn’t stop at just using freeCodeCamp's curriculum.

I wanted to go deeper.

So I started solving programming challenges on platforms like Codewars and Edabit. Those challenges sharpened my thinking even more. They forced me to face unfamiliar problems and figure things out without guidance.

3: Scientific Computing with Python

Then came the third stage of the journey.

This phase was different. Python had its own elegance, its own logic, and a strong connection to mathematics and data.

It opened a completely new way of thinking.

Through hands-on projects, I learned how to work with data using powerful tools like NumPy, pandas, and Matplotlib. And I didn’t just learn how to use these tools. I got familiar with what they enable.

I practiced:

• Analyzing data

• Exploring patterns

• Visualizing insights

• Thinking statistically

• Moving from raw data to meaningful conclusions

I began to understand how data can be transformed into real insights That’s when my skills started to become more powerful.

My first real encounter with Python and data analysis was through freeCodeCamp.

Unlike web development – which I had explored earlier through different resources – this was my first entry point into the world of data.

And for that, I honestly give freeCodeCamp a lot of credit. It didn’t just introduce me to new tools. It introduced me to a completely new way of thinking.

4: Data Visualization

This phase added a new dimension. It wasn’t just about working with data anymore – it was about communicating it's meaning.

I learned how to transform raw numbers into clear, meaningful visualizations. I explored how to create graphs that don’t just look good but help you understand what’s going on beneath the surface.

That experience was incredibly valuable

It built a foundation that later made my transition from web development into data science and AI much smoother.

And once again, I must acknowledge the role of freeCodeCamp. Because during this phase working with tools like Python, Matplotlib, and pandas, I began to truly understand the importance of data visualization and analysis.

I started to carry this mindset back into the world of web development:

• Into databases

• Into SQL tables

• Into how data is structured, queried, and interpreted

I realized that data isn't just something you store. Its value comes from how well you can understand it, analyze it, and use it.

And for stakeholders, this is just as critical as storage, security, and privacy because without insight, data alone means very little.

This distinction is incredibly important for every developer to understand.

In the world of web development, the focus is often on storing data, securing it, and making sure it’s accessible. But in the world of data analysis, scientific computing, and statistical modeling, the focus shifts completely.

It becomes about studying the data itself transforming it from something silent… into something that speaks. Something that guides decisions. Something that helps you improve systems, refine products, and make smarter long-term choices.

That shift in perspective changed the way I handled everything.

5: Backend End Development and APIs

This was a new world.

Even though I had previous experience with PHP and SQL from Udemy, this path introduced me to a different ecosystem which is modern, fast, and widely used in real-world applications.

Of course, the beginning wasn’t easy. I had no prior experience with tools like Node.js or MongoDB. It felt unfamiliar at first, and there was a learning curve.

But this is where freeCodeCamp stood out again.

They didn’t just throw you alone into the deep end. They supported the journey.

I found dedicated courses on their YouTube channel like a full Node.js course (around 8 hours) and a MongoDB course (around 4 hours).

I went through both of them completely. Step by step, things started to make sense. I built a solid foundation, returned to the certification path, and this time I was ready.

I completed all the challenges and projects successfully, from the first attempt.

And that experience taught me something important: sometimes the path forward isn’t about pushing harder, it’s about stepping back, strengthening your foundations, and then coming back stronger.

One of the most interesting parts of this stage was discovering the difference between how data is handled in SQL versus MongoDB.

It wasn’t just a technical difference, but a shift in mindset.

With SQL, everything is structured, relational, and predefined. With MongoDB, things are more flexible, document-based, and dynamic.

Learning to work with both gave me a broader perspective on how to design and manage data depending on the problem at hand.

6: Front End Development Libraries

This was one of the most enjoyable phases. It felt creative, fast, and powerful.

I explored frameworks and libraries like:

• jQuery

• React

• Vue.js

To strengthen my understanding, I followed additional courses on the freeCodeCamp YouTube channel, making sure I had the right foundations before tackling the projects and passing the certification requirements.

What stood out to me the most during this phase was something new: for the first time, I truly learned how to control HTML and CSS through JavaScript in a structured and scalable way.

This wasn’t just about styling anymore, but it was about building dynamic interfaces, managing state, and creating responsive user experiences.

And honestly, this was the first time I grasped this concept deeply.

7: Data Analysis with Python

Here, things became more precise.

I explored how to:

• Choose the right type of visualization depending on the data

• Analyze datasets using tools like Excel, NumPy, and pandas

• Create advanced visualizations using libraries like D3.js

I was learning how to think with data, how to read it, question it, and turn it into something meaningful.

8: Machine Learning with Python

This new learning path was deeper, more abstract. Sometimes even unfamiliar compared to everything I had learned before.

For the first time, I wasn’t just writing code to build applications. I was building models that learn from data.

Working with tools like TensorFlow, I began to understand how data, mathematics, and algorithms come together to create intelligent systems.

Everything I had learned through freeCodeCamp started to reflect beyond programming itself.

I noticed the impact in school:

• In mathematics, logic became clearer

• In digital technology, concepts felt more intuitive

• Even in subjects like physics and chemistry, problem-solving became easier

Because at its core, my way of thinking had changed. My logical reasoning had become stronger. Working with algorithms and mathematical expressions no longer felt difficult. Instead it felt natural.

One of the most meaningful outcomes of this journey came during high school. A teacher trusted me with a responsibility I didn’t expect: To explain programming lessons to my classmates.

And I did.

Not just by repeating information but by simplifying it, structuring it, and making it understandable. That moment I discovered that learning deeply allows you to teach clearly.

And then came a new and powerful phase: building the engineering mindset.

At this stage, everything started to come together. It was about thinking differently.

An engineering mindset built on:

• Strong logical foundations

• Real project experience

• Understanding how systems behave, not just how code runs

And this introduced me to the upcoming certifications.

9: Quality Assurance

I spent time learning how to write code that's not only functional but reliable, maintainable, and scalable.

Using tools, and practices like Chai.js, I began to:

• Test applications properly

• Catch errors early

• Ensure systems run smoothly under different conditions

And this is where the real transformation started happening. I started moving from being someone who writes code to someone who builds systems.

10: Information Security

Through the cybersecurity path on freeCodeCamp, I was introduced to a completely new dimension of software development: thinking about protecting systems, not only building them blindly.

I picked up essential concepts and practical skills using tools like:

• Helmet.js to secure web applications

• Python for penetration testing and security analysis

• Socket.IO for handling real-time interactions securely

As part of this path, I worked on building five projects including a password cracker. It wasn’t just a technical exercise – it was a way to develop a real security mindset. To understand vulnerabilities, risks, and how attackers think so you can build systems that are stronger and safer.

Then I got into the legacy learning courses:

11: Legacy Certifications

Front End:

Back End:

Data Visualization:

Full Stack:

Legacy Cybersecurity & Quality Assurance:

This phase was incredibly valuable.

It felt like a consolidation of everything I had learned, a chance to revisit key concepts with more maturity and deeper understanding. These certifications focused more on what truly matters in each path, with diverse and practical projects that strengthened both my skills and confidence.

If I had to summarize this entire journey in one idea, it would be this: learning by building changes everything.

This core methodology of freeCodeCamp enabled me to:

• Solve real problems

• Build actual products

• Connect learning with real-world impact

It moved me beyond theory into practice.

Personal Recommendations

Based on my experience, I strongly recommend freeCodeCamp to anyone who wants to:

• Develop programming skills

• Strengthen logical thinking

• Improve problem-solving ability

• Build real-world applications

Because when learning is built on the right methodology, the results are not just visible they are transformative.

Here are resources about freeCodeCamp programs and certifications that structured my learning journey.

Contact Me:

GitHub

Linkedin

X

Sometimes you don’t need the entire document. You just need a few pages — maybe a specific section, a report summary, or selected invoice pages.

Most tools require uploading files or installing software. But modern browsers are powerful enough to handle this locally.

In this tutorial, you’ll learn how to build a browser-based PDF splitter using JavaScript, where everything runs directly in the user’s browser.

By the end, you’ll understand how to extract specific pages from a PDF, create a new document from those pages, and download the result instantly.

Table of Contents

• How PDF Splitting Works in the Browser

• Project Setup

• What Library Are We Using?

• Creating the Upload Interface

• Reading the PDF File

• Selecting Pages to Extract or Split

• Splitting the PDF Using JavaScript

• Generating and Downloading the PDF

• Demo: How the PDF Split Tool Works

• Important Notes from Real-World Use

• Common Mistakes to Avoid

• Conclusion

How PDF Splitting Works in the Browser

Splitting a PDF means taking a single document and extracting specific pages into a new file.

Traditionally, this kind of processing is handled on a server. But with modern JavaScript libraries like pdf-lib, we can do everything directly in the browser.

The process is straightforward. A user uploads a PDF file, the browser reads it, and we can display a preview of its pages to help users understand what they’re working with. Based on the selected split mode or page input, we then extract only the required pages and copy them into a new PDF document.

All of this happens locally in the browser, which makes the process faster and ensures that user files never leave their device.

Project Setup

We’ll keep this project simple.

You only need:

• an HTML file

• JavaScript

• a PDF processing library

No backend or server is required.

What Library Are We Using?

We’ll use pdf-lib, a lightweight JavaScript library for working with PDFs.

Add it using a CDN:

<script src="https://unpkg.com/pdf-lib@1.17.1/dist/pdf-lib.min.js"></script>

This library allows us to:

• load PDFs

• copy pages

• create new documents

Creating the Upload Interface

Start with a simple file input:

<input type="file" id="upload" accept="application/pdf">
<input type="text" id="pages" placeholder="Enter pages (e.g. 1-3,5)">
<button onclick="splitPDF()">Split PDF</button>

<a id="download" style="display:none;">Download Split PDF</a>

This interface allows users to upload a PDF file, specify which pages they want to extract, and trigger the splitting process with a single click. Once the process is complete, the download link becomes visible so they can save the new PDF.

Reading the PDF File

Now let’s read the uploaded file:

const fileInput = document.getElementById("upload");

if (!fileInput.files.length) {
  alert("Please upload a PDF file");
  return;
}

const file = fileInput.files[0];
const arrayBuffer = await file.arrayBuffer();

This converts the file into a format the library can use.

Selecting Pages to Extract or Split

Users can control how the PDF is split in multiple ways.

They can manually enter page ranges like 1-3,5, which allows precise selection of pages. For example, entering 1-3 extracts pages 1 to 3, while 5 selects only page 5.

In addition to manual input, the tool also provides predefined options such as splitting all pages, extracting only even or odd pages, or splitting the document into fixed-size ranges. These options make it easier for users who don’t want to type page ranges manually.

To support manual input, we use a simple parser that converts the user’s input into valid page indexes:

function parsePages(input, totalPages) {
  const pages = [];

  input.split(',').forEach(part => {
    if (part.includes('-')) {
      const [start, end] = part.split('-').map(Number);
      for (let i = start; i <= end; i++) {
        if (i <= totalPages) pages.push(i - 1);
      }
    } else {
      const num = parseInt(part);
      if (num <= totalPages) pages.push(num - 1);
    }
  });

  return pages;
}

This approach gives flexibility, allowing both simple and advanced ways to select pages depending on the user’s needs.

Splitting the PDF Using JavaScript

Now comes the main logic:

async function splitPDF() {
  const fileInput = document.getElementById("upload");
  const pageInput = document.getElementById("pages").value;

  if (!fileInput.files.length || !pageInput.trim()) {
    alert("Please upload a PDF and enter page numbers");
    return;
  }

  const file = fileInput.files[0];
  const arrayBuffer = await file.arrayBuffer();

  const { PDFDocument } = PDFLib;

  const originalPdf = await PDFDocument.load(arrayBuffer);
  const totalPages = originalPdf.getPageCount();

  const selectedPages = parsePages(pageInput, totalPages);

  const newPdf = await PDFDocument.create();

  const copiedPages = await newPdf.copyPages(originalPdf, selectedPages);

  copiedPages.forEach(page => newPdf.addPage(page));

  const pdfBytes = await newPdf.save();

  const blob = new Blob([pdfBytes], { type: "application/pdf" });

  const link = document.getElementById("download");
  link.href = URL.createObjectURL(blob);
  link.download = "split.pdf";
  link.style.display = "inline";
  link.innerText = "Download Split PDF";
}

This:

• loads the original file

• extracts selected pages

• creates a new PDF

• prepares it for download

Generating and Downloading the PDF

Once the PDF is created:

link.href = URL.createObjectURL(blob);
link.download = "split.pdf";

The browser handles the download instantly — no server needed.

Demo: How the PDF Split Tool Works

Here’s how the full flow looks in practice using the tool:

Step 1: Upload Your PDF

Start by dragging and dropping your PDF file into the upload area, or click the button to select a file from your device. Once uploaded, the tool instantly processes the document and prepares it for splitting.

Step 2: Preview Pages

After uploading, all pages of the PDF are displayed as thumbnails. This gives you a clear visual overview of the document so you can decide how you want to split it.

Step 3: Choose Split Mode and Options

Next, choose how you want to split the PDF. You can select options like splitting by page range, extracting all pages, splitting odd or even pages, or dividing the document into fixed-size sections. This flexibility makes it easy to handle different use cases without manually selecting every page.

Step 4: Split the PDF

Once your settings are ready, click the split button. The browser processes the file locally and generates the new PDFs based on your selected mode.

Step 5: Download the Results

After processing, the split files are displayed with download options. You can download individual files or download all of them at once. Everything happens instantly in the browser without uploading your files anywhere.

Important Notes from Real-World Use

When working with PDF splitting, input validation is important.

Users may enter invalid ranges or page numbers that don’t exist. Always validate and limit input to available pages.

Handling large PDFs can also affect performance. Instead of processing everything at once, you can handle operations step by step to keep the browser responsive.

Another key consideration is privacy. Since all processing happens in the browser, files never leave the user’s device. This makes the tool safer for sensitive documents.

In real-world applications, it’s important to clearly communicate that files are not uploaded or stored anywhere.

Common Mistakes to Avoid

One common issue is not validating user input. If users enter incorrect page ranges, the tool may fail or produce unexpected results.

Another mistake is forgetting that page indexes start at zero internally. If you don’t adjust for this, you may extract the wrong pages.

Also, skipping edge cases like empty input or large files can make the tool unreliable.

Conclusion

In this tutorial, you built a browser-based PDF splitter using JavaScript.

You learned how to read PDF files, extract specific pages, and generate a new document entirely in the browser.

This approach removes the need for a backend and keeps everything fast and private.

If you’d like to see a complete working version of this idea, you can try it here: Split PDF

Once you understand this pattern, you can extend it further to build more advanced PDF tools like merging, compression, or editing.

And that’s where things start getting really interesting.

Sometimes you need to combine reports or invoices, or simply merge multiple documents into a single clean file.

Most tools that handle this either require installing software or uploading files to a server, which can be slow and not always ideal – especially when dealing with private documents.

But what if you could merge PDFs directly in the browser, without any backend?

That’s exactly what we’ll build in this tutorial.

By the end, you’ll have a fully working browser-based PDF merger. It will allow users to upload files, preview them, reorder documents using drag-and-drop, select specific pages, and download the final merged PDF instantly.

Table of Contents

1. How PDF Merging Works in the Browser

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Rendering PDF Previews

6. Reordering Files Drag and Drop

7. Sorting and Reordering PDFs (Important)

8. Merging PDFs Using JavaScript

9. Improving User Experience

10. Demo: How the PDF Merger Works

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Conclusion

How PDF Merging Works in the Browser

At a high level, merging PDFs means loading multiple PDF files, extracting pages from each, and combining them into a single document.

Traditionally, this process happens on a server. Files are uploaded, processed, and then returned to the user.

But modern JavaScript libraries make it possible to do all of this directly in the browser. Instead of sending files anywhere, the entire process runs locally on the user’s device.

This approach has a few practical advantages. It makes the process faster because there’s no upload time involved. It also improves privacy, since files never leave the user’s system. And from a development perspective, it removes the need for backend processing altogether.

Project Setup

We’ll keep this project simple.

You only need:

• an HTML file

• JavaScript

• a few libraries

No backend required.

What Library Are We Using?

We’ll use two important libraries:

<script src="https://unpkg.com/pdf-lib@1.17.1/dist/pdf-lib.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/2.16.105/pdf.min.js"></script>

• We'll use pdf-lib to merge and modify PDFs

• We'll use pdf.js to render previews in the browser

This combination is very powerful and commonly used in real projects.

Creating the Upload Interface

Start with a simple drag-and-drop area:

<div id="upload-area">
  <input type="file" id="file-input" multiple accept="application/pdf">
</div>

Users can either drag files or click to select.

Once files are selected, we read them using:

const arrayBuffer = await file.arrayBuffer();

This allows us to pass the file into our PDF libraries.

Rendering PDF Previews

To improve usability, we'll show a preview of each uploaded PDF.

Using pdf.js, we can render pages like this:

const pdf = await pdfjsLib.getDocument(arrayBuffer).promise;
const page = await pdf.getPage(1);

const viewport = page.getViewport({ scale: 1.5 });
canvas.height = viewport.height;
canvas.width = viewport.width;

page.render({
  canvasContext: context,
  viewport: viewport
});

This gives users visual feedback before merging.

Reordering Files (Drag and Drop)

Order matters when merging PDFs.

Instead of forcing users to upload in sequence, we'll allow reordering.

We can use a library like Sortable.js for this:

new Sortable(document.getElementById('pdf-grid'), {
  animation: 150
});

This enables drag-and-drop sorting and instant visual updates.

Sorting and Reordering PDFs (Important)

This is where the tool becomes more practical in real-world use.

Instead of forcing users to upload files in a specific order, the tool allows them to rearrange PDFs before merging.

Users can manually drag and drop files to adjust the sequence, or use built-in sorting options such as arranging files alphabetically or by file size. This makes it easy to quickly organize multiple documents without re-uploading them.

This flexibility ensures that the final merged document follows the exact order the user needs. In real-world scenarios, this is especially useful when combining reports, invoices, or other documents where sequence is important.

Here’s a simple example of how you might sort uploaded files:

function sortFiles(files, type) {
  return files.sort((a, b) => {
    if (type === "name-asc") {
      return a.name.localeCompare(b.name);
    }

    if (type === "name-desc") {
      return b.name.localeCompare(a.name);
    }

    if (type === "size-asc") {
      return a.size - b.size;
    }

    if (type === "size-desc") {
      return b.size - a.size;
    }

    return 0;
  });
}

This allows precise control over what gets merged.

Merging PDFs Using JavaScript

Now comes the core logic. We'll use pdf-lib to combine pages:

const { PDFDocument } = PDFLib;

const mergedPdf = await PDFDocument.create();

for (const file of files) {
  const pdf = await PDFDocument.load(file.arrayBuffer);
  const pages = await mergedPdf.copyPages(pdf, selectedPages);

  pages.forEach(page => mergedPdf.addPage(page));
}

const pdfBytes = await mergedPdf.save();

Finally, we'll create a downloadable file:

const blob = new Blob([pdfBytes], { type: 'application/pdf' });

Improving User Experience

A simple merge tool works, but a good tool feels smooth.

Small improvements make a big difference.

For example:

• showing previews before merging

• allowing users to remove files

• enabling page navigation

• providing instant feedback

These details turn a basic feature into a real product.

Demo: How the PDF Merger Works

Here’s how the full flow looks in practice:

Step 1: Upload PDFs

Users can drag and drop PDF files into the upload area or select them manually.

Step 2: Preview Files

Each uploaded file is displayed with a preview as well as pdf files details (name, size, nos of page, and so on), so users can verify the content before merging.

Step 3: Reorder Files

Users can arrange the order of PDFs using drag-and-drop or sorting options as well as manual options. This ensures the final merged document follows the correct sequence.

Step 4: Merge PDFs

Once everything is arranged, users can click the merge button to combine all selected PDFs into a single file.

Step 5: Download the Final PDF

The merged PDF is generated instantly in the browser, and users can preview , rename, and download it without any server interaction.

Important Notes from Real-World Use

When building tools like a PDF merger, handling large files efficiently becomes important.

If multiple large PDFs are loaded at once, it can slow down the browser or consume too much memory. Instead of processing everything at once, it’s better to handle files step by step.

For example, instead of loading all PDFs together, you can process them one by one:

const { PDFDocument } = PDFLib;

const mergedPdf = await PDFDocument.create();

for (const file of files) {
  const arrayBuffer = await file.arrayBuffer();
  const pdf = await PDFDocument.load(arrayBuffer);

  const pages = await mergedPdf.copyPages(pdf, pdf.getPageIndices());

  pages.forEach(page => mergedPdf.addPage(page));
}

This approach keeps memory usage lower and avoids freezing the browser when working with larger files.

You can also improve performance by limiting file size or the number of files users can upload at once. This helps keep the tool responsive even on lower-powered devices.

Another important aspect is privacy. Since everything runs directly in the browser, files are never uploaded to a server. This means sensitive documents stay on the user’s device.

But it’s still important to be transparent about this. In real-world tools, you should clearly mention that all processing happens locally and no files are stored or transmitted.

This client-side approach improves both performance and user trust, especially when working with private or confidential documents.

Common Mistakes to Avoid

A common mistake is skipping validation. If users upload invalid files or empty inputs, the merge process can fail.

Another issue is ignoring page ranges. If parsing is incorrect, users may get unexpected results.

Also, relying on fixed layouts or assumptions can break the experience across different files. Testing with different PDF types is important.

Conclusion

In this tutorial, you built a browser-based PDF merger using JavaScript.

More importantly, you learned how to process files locally in the browser, render previews for better usability, handle user input safely, and manage dynamic document structures when working with PDFs.

This approach removes the need for a backend and keeps everything fast, private, and efficient.

Once you understand this pattern, you can extend it to build more advanced tools. For example, you could create features like PDF splitting, compression, editing, or other document-based utilities using the same core ideas.

And that’s where things start getting really interesting.

The question for anyone who runs a blog or content site is: how do you become one of those trusted sources? The answer lies in structured data, specifically JSON-LD Knowledge Graphs that help AI models understand not just what your content says, but how it connects to everything else you've published.

In this tutorial, you'll build a PHP function that auto-generates a JSON-LD Knowledge Graph for every blog post on your site. There are no plugins, no external APIs, and just one function. It will detect entities in your content, map relationships between posts, and output a unified schema that both Google and AI models like ChatGPT can parse as a connected system.

Table of Contents

• Why This Matters Now

• Prerequisites

• The Pipeline

• What Static JSON-LD Looks Like (And Why It Falls Short)

• Step 1: Define Your Entity Helpers

• Step 2: Build the BlogPosting Schema

• Step 3: Detect Topics Automatically

• Step 4: Map Relationships Between Posts

• Step 5: Add Multilingual Connections

• Step 6: Assemble the Graph

• What the Output Looks Like in Production

• Testing Your Implementation

• What I Learned After 3 Months in Production

Why This Matters Now

AI search engines are replacing blue links with synthesized answers. When someone asks ChatGPT a question, it doesn't return a list of URLs. It builds a response by citing the sources it trusts.

According to AccuraCast's research on AI search citations, 81% of pages cited by AI engines use schema markup with JSON-LD as the dominant format. Pages with structured schema are 3 to 4 times more likely to be cited by ChatGPT or Perplexity than pages without it.

Most JSON-LD tutorials teach you to paste a static <script> tag with your title and author name. That gets you into Google's index. But it doesn't get you cited by AI.

For that, you need a Knowledge Graph: a system where your entities (author, site, topics, tools, related articles) are connected through persistent identifiers that machines can follow across every page on your site.

I built this system for my own blog. After three months in production with 52 posts in three languages, I asked ChatGPT, Gemini, and Perplexity to audit the resulting schema. ChatGPT scored it 9.1 out of 10 and called it "production-grade graph design." This article walks you through how to build the same thing.

Prerequisites

To follow this tutorial, you'll need:

• PHP 7.4 or higher running on your server

• A MySQL or MariaDB database with a posts table that stores your blog content (title, slug, content, excerpt, created_at, updated_at)

• Basic PHP knowledge: variables, arrays, functions, and database queries with PDO

• A working blog where you can edit PHP files and add schema markup to your HTML output

The tools we'll use are all built into PHP. No external packages or Composer dependencies are required. The entity detection uses simple string matching with strpos(), the database queries use PDO prepared statements, and the JSON-LD output uses PHP's native json_encode(). If you've built a blog with PHP before, you have everything you need.

The Pipeline

The system works in four stages:

Stage 1: PHP queries MariaDB for the post content, metadata, and related post IDs.

Stage 2: The system scans the content for known topics and tools using keyword matching. No NLP libraries needed. A simple associative array maps keywords to schema entities.

Stage 3: Related posts are fetched and mapped as both navigation links (relatedLink) and knowledge relationships (citation).

Stage 4: Everything gets combined into a single @graph array with five connected entities: WebSite, Organization, Person, WebPage, and BlogPosting. Each entity has a stable @id that machines can reference across pages.

What Static JSON-LD Looks Like (And Why It Falls Short)

Here is what a typical tutorial tells you to add:

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "My Blog Post",
  "author": {
    "@type": "Person",
    "name": "Jane"
  },
  "datePublished": "2026-01-15"
}

This tells Google "there is an article by Jane." It doesn't say what topics the article covers, what tools it mentions, how it connects to other articles on your site, who publishes the site, or what makes Jane an authority on the subject.

For a blog with dozens of posts about interconnected topics, every post exists in isolation. Search engines and AI models can't see that your articles form a system of knowledge. They can't tell that your post about Midjourney prompts connects to your post about AI design workflows, which connects to your post about fintech UX.

By the end of this tutorial, that same post will generate a @graph with five linked entities, automatic topic detection, relationship mapping, multilingual connections, and an abstract that LLMs read before deciding whether to cite you.

Step 1: Define Your Entity Helpers

Three PHP functions define your core entities. They return arrays that get reused on every page of your site.

function getSchemaAuthor($baseUrl) {
    return [
        '@type' => 'Person',
        '@id' => $baseUrl . '/#author',
        'name' => 'Your Name',
        'description' => 'Your professional description.',
        'url' => $baseUrl . '/about',
        'image' => $baseUrl . '/photo.png',
        'jobTitle' => 'Your Title',
        'sameAs' => [
            'https://linkedin.com/in/yourprofile',
            'https://x.com/yourhandle',
            'https://dev.to/yourprofile'
        ]
    ];
}

function getSchemaOrganization($baseUrl) {
    return [
        '@type' => 'Organization',
        '@id' => $baseUrl . '/#organization',
        'name' => 'Your Site Name',
        'url' => $baseUrl,
        'logo' => [
            '@type' => 'ImageObject',
            'url' => $baseUrl . '/logo.png'
        ]
    ];
}

function getSchemaWebSite(\(baseUrl, \)siteName, \(siteDesc, \)langCode) {
    return [
        '@type' => 'WebSite',
        '@id' => $baseUrl . '/#website',
        'name' => $siteName,
        'description' => $siteDesc,
        'url' => $baseUrl,
        'inLanguage' => $langCode,
        'publisher' => ['@id' => $baseUrl . '/#organization']
    ];
}

The @id values are the most important detail. /#author, /#organization, and /#website are persistent identifiers that stay the same across every page.

When a machine reads your homepage and then reads a blog post, it recognizes that https://yoursite.com/#author is the same entity in both places. Without @id, each page creates a new floating entity that machines can't connect.

One decision that matters: the publisher should be an Organization, not a Person. AI systems assign more trust to content published by organizations than by individuals. Even if you're a solo creator, define your site as an Organization for publishing purposes and keep yourself as the Person author.

Step 2: Build the BlogPosting Schema

This function takes a post from your database and the current language code, then builds the core BlogPosting entity.

function generateBlogPostingSchema(\(post, \)langCode) {
    $baseUrl = rtrim(SITE_URL, '/');
    \(siteName = getLocalizedSetting('site_name', \)langCode);
    \(siteDesc = getLocalizedSetting('site_description', \)langCode);
    $defaultLang = getDefaultLanguage();
    \(postSlug = \)post['slug'];

    \(postUrl = \)langCode === $defaultLang
        ? \(baseUrl . '/' . \)postSlug
        : \(baseUrl . '/' . \)langCode . '/' . $postSlug;

    \(excerpt = \)post['excerpt']
        ?: mb_substr(strip_tags($post['content']), 0, 160);

    $blogPosting = [
        '@type' => 'BlogPosting',
        '@id' => $postUrl . '#article',
        'headline' => $post['title'],
        'description' => $excerpt,
        'abstract' => $excerpt,
        'url' => $postUrl,
        'datePublished' => date('c', strtotime($post['created_at'])),
        'dateModified' => date('c', strtotime($post['updated_at'])),
        'author' => [
            '@type' => 'Person',
            '@id' => $baseUrl . '/#author',
            'name' => 'Your Name',
            'url' => $baseUrl . '/about'
        ],
        'publisher' => [
            '@type' => 'Organization',
            '@id' => $baseUrl . '/#organization',
            'name' => 'Your Site Name',
            'logo' => [
                '@type' => 'ImageObject',
                'url' => $baseUrl . '/logo.png'
            ]
        ],
        'isPartOf' => ['@id' => $baseUrl . '/#website'],
        'mainEntityOfPage' => [
            '@type' => 'WebPage',
            '@id' => $postUrl
        ],
        'inLanguage' => $langCode,
        'wordCount' => str_word_count(strip_tags($post['content']))
    ];

Two properties deserve attention.

abstract maps the post excerpt. LLMs read the abstract first to decide whether the rest of the page is worth processing. If your excerpt says "In this post I explore some ideas about..." models may skip you entirely. Make it a direct statement: "To implement a Knowledge Graph you need five connected entities with persistent @id references." That's something an LLM can evaluate immediately.

isPartOf connects the article to the WebSite entity. This tells machines "this article belongs to a larger knowledge source." Without it, each post looks like an independent document.

Notice that author and publisher include both @id and inline properties. The @id connects to the full entity in the @graph. The inline properties are a fallback because some parsers (including Google's Rich Results Test) don't always resolve @id references. Including both ensures zero validation warnings.

Step 3: Add Automatic Entity Detection

This is where static JSON-LD tutorials stop and your Knowledge Graph begins. Instead of manually tagging each post with its topics, the system scans the content automatically.

    \(contentLower = strtolower(\)post['content'] . ' ' . $post['title']);

    $topicMap = [
        'midjourney'      => ['name' => 'Midjourney', 'url' => 'https://midjourney.com'],
        'prompt'          => ['name' => 'Prompt Engineering'],
        'fintech'         => ['name' => 'Fintech UX Design'],
        'ux design'       => ['name' => 'UX Design'],
        'llms.txt'        => ['name' => 'llms.txt', 'url' => 'https://llmstxt.org'],
        'knowledge graph' => ['name' => 'Knowledge Graph'],
    ];

    $aboutItems = [];
    $keywordsList = [];
    foreach (\(topicMap as \)keyword => $meta) {
        if (strpos(\(contentLower, \)keyword) !== false) {
            \(item = ['@type' => 'Thing', 'name' => \)meta['name']];
            if (isset(\(meta['url'])) \)item['url'] = $meta['url'];
            \(aboutItems[] = \)item;
            \(keywordsList[] = \)meta['name'];
        }
    }
    if (!empty($aboutItems)) {
        \(blogPosting['about'] = \)aboutItems;
    }

The same pattern detects tools mentioned in the content:

    $toolMap = [
        'midjourney' => ['name' => 'Midjourney', 'url' => 'https://midjourney.com'],
        'claude'     => ['name' => 'Claude', 'url' => 'https://claude.ai'],
        'chatgpt'    => ['name' => 'ChatGPT', 'url' => 'https://chat.openai.com'],
        'figma'      => ['name' => 'Figma', 'url' => 'https://figma.com'],
    ];

    $mentionItems = [];
    foreach (\(toolMap as \)keyword => $meta) {
        if (strpos(\(contentLower, \)keyword) !== false) {
            $mentionItems[] = [
                '@type' => 'Thing',
                'name' => $meta['name'],
                'url' => $meta['url']
            ];
            \(keywordsList[] = \)meta['name'];
        }
    }
    if (!empty($mentionItems)) {
        \(blogPosting['mentions'] = \)mentionItems;
    }

    if (!empty($keywordsList)) {
        \(blogPosting['keywords'] = array_values(array_unique(\)keywordsList));
    }

The difference between about and mentions matters for AI citation. about declares the main topics. mentions declares tools and references that appear in the content. If a post is a Midjourney tutorial that also mentions Claude, about gets Midjourney and mentions gets Claude.

This distinction helps AI models decide whether to cite your page when someone asks about Midjourney versus when they ask about Claude.

A question that comes up often: do you need NLP for entity detection? No. A keyword map with strpos handles the vast majority of cases for a personal blog. NLP adds complexity, latency, and a dependency you don't need. If your topic map has 20 to 30 entries, keyword matching is fast, predictable, and easy to debug.

Step 4: Map Relationships Between Posts

Each post connects to related posts through two properties: relatedLink for navigation and citation for knowledge relationships.

    \(relatedUrls = getRelatedPostUrls(\)post['id'], $langCode);
    if (!empty($relatedUrls)) {
        \(blogPosting['relatedLink'] = \)relatedUrls;
        \(blogPosting['citation'] = \)relatedUrls;
    }

The helper function queries a post_connections table:

function getRelatedPostUrls(\(postId, \)langCode) {
    $pdo = getDB();
    $baseUrl = rtrim(SITE_URL, '/');
    $defaultLang = getDefaultLanguage();

    \(stmt = \)pdo->prepare(
        "SELECT connected_post_id FROM post_connections WHERE post_id = ?"
    );
    \(stmt->execute([\)postId]);
    \(connections = \)stmt->fetchAll(PDO::FETCH_COLUMN);

    $urls = [];
    foreach (\(connections as \)connId) {
        \(slug = getPostSlugForLanguage(\)connId, $langCode);
        if ($slug) {
            \(urls[] = \)langCode === $defaultLang
                ? \(baseUrl . '/' . \)slug
                : \(baseUrl . '/' . \)langCode . '/' . $slug;
        }
    }
    return $urls;
}

Why use both relatedLink and citation on the same URLs? They signal different things to machines. relatedLink says "the reader might want to visit these pages next." citation says "this article builds on the knowledge in these other articles."

AI models weigh citation more heavily when deciding whether your content is part of a larger knowledge system. Using both tells machines that your related posts aren't just navigation. They're sources this article builds upon.

Step 5: Add Multilingual Support

If your blog publishes in multiple languages, workTranslation connects different language versions of the same article.

    $languages = getActiveLanguages();
    $translations = [];
    foreach (\(languages as \)lang) {
        \(lc = \)lang['code'];
        if (\(lc === \)langCode) continue;

        \(translatedSlug = getPostSlugForLanguage(\)post['id'], $lc);
        if ($translatedSlug) {
            \(translatedUrl = \)lc === $defaultLang
                ? \(baseUrl . '/' . \)translatedSlug
                : \(baseUrl . '/' . \)lc . '/' . $translatedSlug;

            \(stmtT = \)pdo->prepare(
                "SELECT title FROM post_translations
                 WHERE post_id = ? AND language_code = ? LIMIT 1"
            );
            \(stmtT->execute([\)post['id'], $lc]);
            \(translatedTitle = \)stmtT->fetchColumn() ?: $post['title'];

            $translations[] = [
                '@type' => 'CreativeWork',
                '@id' => $translatedUrl . '#article',
                'headline' => $translatedTitle,
                'url' => $translatedUrl,
                'inLanguage' => $lc
            ];
        }
    }
    if (!empty($translations)) {
        \(blogPosting['workTranslation'] = \)translations;
    }

Without workTranslation, a blog with 50 posts in three languages looks like 150 independent articles to AI models. With it, the same blog looks like 50 pieces of knowledge with multilingual reach. The authority consolidates instead of fragmenting.

The translations use @type: CreativeWork instead of BlogPosting. This avoids warnings in Google's Rich Results Test where each translation would be flagged as a separate article with missing required fields.

Step 6: Assemble the Graph

Bring everything together:

    $webPage = [
        '@type' => 'WebPage',
        '@id' => $postUrl,
        'url' => $postUrl,
        'name' => $post['title'],
        'isPartOf' => ['@id' => $baseUrl . '/#website']
    ];

    $graph = [
        '@context' => 'https://schema.org',
        '@graph' => [
            getSchemaWebSite(\(baseUrl, \)siteName, \(siteDesc, \)langCode),
            getSchemaOrganization($baseUrl),
            getSchemaAuthor($baseUrl),
            $webPage,
            $blogPosting
        ]
    ];

    return '<script type="application/ld+json">'
        . json_encode($graph,
            JSON_UNESCAPED_SLASHES
            | JSON_UNESCAPED_UNICODE
            | JSON_PRETTY_PRINT)
        . '</script>';
}

The json_encode flags matter. JSON_UNESCAPED_SLASHES prevents URLs from getting escaped. JSON_UNESCAPED_UNICODE keeps non-ASCII characters readable for multilingual content. Without these, a single special character in a blog post title fetched from the database can break the entire JSON-LD block silently.

What the Output Looks Like in Production

Here is the actual JSON-LD generated by a real post on shinobis.com, a blog about AI tools and UX design:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebSite",
      "@id": "https://shinobis.com/#website",
      "name": "Designer in the Age of AI",
      "description": "AI tools and real workflows from a designer who builds with AI.",
      "url": "https://shinobis.com",
      "inLanguage": "en",
      "publisher": { "@id": "https://shinobis.com/#organization" }
    },
    {
      "@type": "Organization",
      "@id": "https://shinobis.com/#organization",
      "name": "Shinobis",
      "url": "https://shinobis.com",
      "logo": { "@type": "ImageObject", "url": "https://shinobis.com/3117045.png" }
    },
    {
      "@type": "Person",
      "@id": "https://shinobis.com/#author",
      "name": "Shinobis",
      "description": "UX/UI Designer with 10+ years in banking and fintech.",
      "url": "https://shinobis.com/en/about",
      "jobTitle": "UX/UI Designer",
      "sameAs": [
        "https://www.linkedin.com/company/shinobis-ai",
        "https://dev.to/shinobis_ia"
      ]
    },
    {
      "@type": "WebPage",
      "@id": "https://shinobis.com/en/one-year-with-ai-open-letter-to-designers",
      "url": "https://shinobis.com/en/one-year-with-ai-open-letter-to-designers",
      "name": "One Year with AI: Open Letter to Designers",
      "isPartOf": { "@id": "https://shinobis.com/#website" }
    },
    {
      "@type": "BlogPosting",
      "@id": "https://shinobis.com/en/one-year-with-ai-open-letter-to-designers#article",
      "headline": "One Year with AI: Open Letter to Designers",
      "description": "One year ago I started this journey. Today I write to all designers who are still doubting, fearing, or ignoring AI.",
      "abstract": "One year ago I started this journey. Today I write to all designers who are still doubting, fearing, or ignoring AI.",
      "url": "https://shinobis.com/en/one-year-with-ai-open-letter-to-designers",
      "datePublished": "2026-02-15T09:00:00-05:00",
      "dateModified": "2026-03-20T14:30:00-05:00",
      "inLanguage": "en",
      "wordCount": 1842,
      "author": {
        "@type": "Person",
        "@id": "https://shinobis.com/#author",
        "name": "Shinobis",
        "url": "https://shinobis.com/en/about"
      },
      "publisher": {
        "@type": "Organization",
        "@id": "https://shinobis.com/#organization",
        "name": "Shinobis",
        "logo": { "@type": "ImageObject", "url": "https://shinobis.com/3117045.png" }
      },
      "isPartOf": { "@id": "https://shinobis.com/#website" },
      "mainEntityOfPage": {
        "@type": "WebPage",
        "@id": "https://shinobis.com/en/one-year-with-ai-open-letter-to-designers"
      },
      "about": [
        { "@type": "Thing", "name": "Midjourney", "url": "https://midjourney.com" },
        { "@type": "Thing", "name": "Prompt Engineering" }
      ],
      "mentions": [
        { "@type": "Thing", "name": "Claude", "url": "https://claude.ai" }
      ],
      "relatedLink": [
        "https://shinobis.com/en/ai-is-not-going-to-take-your-job-your-comfort-zone-will",
        "https://shinobis.com/en/the-designer-as-creative-director-of-machines"
      ],
      "citation": [
        "https://shinobis.com/en/ai-is-not-going-to-take-your-job-your-comfort-zone-will",
        "https://shinobis.com/en/the-designer-as-creative-director-of-machines"
      ],
      "keywords": ["Midjourney", "Prompt Engineering", "Claude"],
      "workTranslation": [
        {
          "@type": "CreativeWork",
          "@id": "https://shinobis.com/un-ano-con-ia-carta-abierta-disenadores#article",
          "headline": "Un año con IA: carta abierta a los diseñadores",
          "url": "https://shinobis.com/un-ano-con-ia-carta-abierta-disenadores",
          "inLanguage": "es"
        },
        {
          "@type": "CreativeWork",
          "@id": "https://shinobis.com/ja/one-year-with-ai-open-letter-to-designers#article",
          "headline": "AIと一年：デザイナーへの公開書簡",
          "url": "https://shinobis.com/ja/one-year-with-ai-open-letter-to-designers",
          "inLanguage": "ja"
        }
      ]
    }
  ]
}

Compare that to the static version: one BlogPosting with a headline and an author name. The difference isn't cosmetic. It's the difference between "there is an article" and "there is a knowledge node connected to an author with verified profiles, published by an organization, linked to related articles through citation relationships, covering specific topics, and available in three languages."

Testing Your Implementation

After deploying, validate at Google's Rich Results Test. Paste any post URL and look for your BlogPosting with all properties.

For a deeper audit, copy the <script type="application/ld+json"> block from your page source and paste it into ChatGPT with this prompt: "Audit this JSON-LD schema for AI citation visibility. Score it 1-10 and tell me what is missing." The feedback is surprisingly specific.

When I did this, ChatGPT identified five improvements that raised the score from 8.7 to 9.1.

What I Learned After 3 Months in Production

I have been running this system on a blog with 52 posts in three languages since early 2026. Google indexed pages went from 26 to 48 in three months. The keyword "llms txt" reached position 4 on Google. AI models started citing my content in responses about JSON-LD implementation.

Three things I would do differently if starting today.

First, add the abstract property from day one. I added it three months in and the impact was immediate. LLMs use abstract as a first filter. Perplexity confirmed that the first 200 characters of a page are critical for whether AI extracts the content.

Second, use citation alongside relatedLink from the beginning. relatedLink is a navigation hint. citation signals a knowledge relationship. AI models interpret the connections between your posts differently depending on which property you use.

Third, define the publisher as an Organization immediately. I started with @type: Person and changed it later. AI systems assign more trust to organizational publishers.

The system generates JSON-LD on every page load. At this scale (under 100 posts) the performance impact is negligible. For thousands of posts, generate on publish and cache the output.

Wrapping Up

This system is one layer of what is now called Generative Engine Optimization: structuring content so AI models cite you in their responses.

The other layers include an llms.txt file at your domain root (which gives AI crawlers a site-level overview) and writing content that AI can extract without needing additional context (direct statements over narrative introductions).

The complete source code is running in production at shinobis.com. Every post uses the exact system described here.

The next SEO battlefield isn't rankings. It's citations. And citations start with structure.

The usual approach involves backend services. You send data to a server, generate the file there, and return it to the user. It works, but it adds complexity, latency, and maintenance overhead.

Modern browsers make this much simpler.

In this tutorial, you’ll learn how to generate PDF files directly in the browser using JavaScript. There’s no server involved, no file uploads, and everything happens instantly on the client side.

To make things practical, we’ll build a simple invoice-style PDF generator so you can see how this works in a real-world scenario.

Table of Contents

1. How PDF Generation Works in the Browser

2. Project Setup

3. What Library Are We Using?

4. Creating the HTML Structure

5. Adding JavaScript to Generate the PDF

6. How the PDF Is Created

7. Handling Dynamic Content (Important)

8. Improving Layout and Spacing

9. How to Download the PDF

10. Important Notes from Real-World Use

11. Common Mistakes to Avoid

12. Demo: How the PDF Generator Works

13. Conclusion

How PDF Generation Works in the Browser

A PDF is essentially a structured document that defines how text and elements are positioned on a page.

Instead of manually constructing that structure, we use a JavaScript library that handles it for us. You pass content into the library, and it generates a downloadable file.

The key advantage here is that everything runs locally. This makes the process faster and avoids sending any data to a server.

Project Setup

This project is intentionally simple.

You only need an HTML file and a JavaScript file. There’s no backend, no API, and no database involved. This keeps the focus on understanding how PDF generation works inside the browser.

What Library Are We Using?

We’ll use jsPDF, a lightweight library that allows you to create PDF files directly in JavaScript.

Add it using a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script>

Creating the HTML Structure

We’ll start with a simple interface where users can enter invoice data and generate a PDF.

<input type="text" id="title" placeholder="Invoice Title">
<textarea id="content" placeholder="Enter invoice details"></textarea>
<button onclick="generatePDF()">Generate PDF</button>

This creates a basic input flow where users can provide the title and content for the PDF.

In real-world applications, this input could include more structured data like customer details, item lists, and pricing. But for this tutorial, we’ll keep things simple and focus on how the PDF generation works.

Adding JavaScript to Generate the PDF

Now we connect the inputs to the PDF logic.

function generatePDF() {
  const { jsPDF } = window.jspdf;
  const doc = new jsPDF();

  const title = document.getElementById("title").value;
  const content = document.getElementById("content").value;

  if (!title.trim() && !content.trim()) {
    alert("Please enter valid content before generating the PDF.");
    return;
  }

  const margin = 10;
  let y = 20;

  const pageWidth = doc.internal.pageSize.getWidth();
  const pageHeight = doc.internal.pageSize.getHeight();
  const maxWidth = pageWidth - margin * 2;

  doc.setFontSize(18);

  // ✅ Wrap title
  const titleLines = doc.splitTextToSize(title, maxWidth);
  doc.text(titleLines, margin, y);

  const titleLineHeight = doc.getLineHeight() / doc.internal.scaleFactor;
  y += titleLines.length * titleLineHeight + 5;

  doc.setFontSize(12);

  // ✅ Wrap content
  const lines = doc.splitTextToSize(content, maxWidth);

  const lineHeight = doc.getLineHeight() / doc.internal.scaleFactor;

  lines.forEach((line) => {
    // ✅ Page break
    if (y > pageHeight - margin) {
      doc.addPage();
      y = margin;
    }

    doc.text(line, margin, y);
    y += lineHeight;
  });

  doc.save("invoice.pdf");
}

This creates a PDF directly in the browser. It handles long text, maintains proper spacing, and automatically adds new pages if the content exceeds the page height.

How the PDF Is Created

When you initialize jsPDF, it creates a blank document.

Each text() call places content at a specific coordinate. This gives you full control over layout, but it also means you need to manage spacing carefully.

Finally, calling save() converts everything into a downloadable file.

Handling Dynamic Content (Important)

In real-world use cases like invoices, content length is rarely fixed. If a user enters multiple lines or longer text, it can overflow or go outside the page.

To handle this, you should wrap text based on the page width instead of using fixed values.

const pageWidth = doc.internal.pageSize.getWidth();
const margin = 10;
const maxWidth = pageWidth - margin * 2;

const lines = doc.splitTextToSize(content, maxWidth);
doc.text(lines, margin, 40);

This ensures your content wraps properly and fits within the page.

If the content is long, you should also update spacing dynamically:

const lineHeight = doc.getLineHeight() / doc.internal.scaleFactor;
let y = 40;

lines.forEach((line) => {
  doc.text(line, margin, y);
  y += lineHeight;
});

This keeps the layout readable and prevents overlapping when working with dynamic input.

Improving Layout and Spacing

Good layout makes a big difference in how your PDF looks and feels.

Instead of placing everything at fixed positions, you can gradually adjust the Y position as content grows. This helps prevent overlapping and keeps the document visually structured.

For example, instead of hardcoding positions, you can do something like this:

const margin = 10;
let y = 20;

const pageWidth = doc.internal.pageSize.getWidth();
const maxWidth = pageWidth - margin * 2;

doc.setFontSize(18);

// Wrap title
const titleLines = doc.splitTextToSize(title, maxWidth);
doc.text(titleLines, margin, y);

const lineHeight = doc.getLineHeight() / doc.internal.scaleFactor;
y += titleLines.length * lineHeight + 5;

doc.setFontSize(12);

// Wrap content
const lines = doc.splitTextToSize(content, maxWidth);
doc.text(lines, margin, y);

y += lines.length * lineHeight;

Here, the y value increases based on actual content height instead of fixed spacing. This ensures consistent spacing between elements and avoids overlapping.

Another important issue is handling long text. If content is too long, it can go outside the page width or overlap with other elements. Instead of using fixed values, you should always calculate width dynamically:

const pageWidth = doc.internal.pageSize.getWidth();
const maxWidth = pageWidth - margin * 2;

const lines = doc.splitTextToSize(content, maxWidth);
doc.text(lines, margin, y);

This automatically breaks the text into multiple lines so it fits properly within the page.

Using dynamic spacing and text wrapping together ensures that your layout remains clean and readable, even when the content size changes. This becomes especially important when generating documents like invoices, where multiple sections need consistent alignment.

How to Download the PDF

The download process is handled using the save() method:

doc.save("invoice.pdf");

This tells the browser to generate the PDF and download it instantly.

You can also customize the file name dynamically based on user input:

const fileName = (title || "document").trim() + ".pdf";
doc.save(fileName);

This makes the downloaded file more meaningful instead of always using a fixed name.

Since everything runs in the browser, no server is involved and no data is uploaded. This makes the process fast and keeps user data private.

Important Notes from Real-World Use

When building tools like invoice generators, layout control becomes more important than the logic itself.

In a browser, layouts are flexible. But in a PDF, everything is fixed. That means you need to carefully control spacing, positioning, and readability.

For example, if you add multiple sections without adjusting spacing, content can easily overlap. Instead of using fixed positions, it’s better to update the Y position dynamically as content grows:

let y = 20;

doc.text("Invoice Title", 10, y);
y += 10;

doc.text("Customer Name", 10, y);
y += 10;

This ensures each section appears below the previous one without overlapping.

Another common issue is long content. If text is too long, it won’t automatically wrap like it does in HTML. You need to handle this manually using dynamic width:

const pageWidth = doc.internal.pageSize.getWidth();
const margin = 10;
const maxWidth = pageWidth - margin * 2;

const lines = doc.splitTextToSize(content, maxWidth);
doc.text(lines, margin, y);

const lineHeight = doc.getLineHeight() / doc.internal.scaleFactor;
y += lines.length * lineHeight;

This keeps the text readable and ensures it fits within the page.

You also need to think about how screen inputs translate into a fixed-size document. For example, a long description in a textarea may look fine on screen, but in a PDF it needs proper spacing, wrapping, and sometimes even pagination.

Optimizing PDF Generation Performance

Performance is another important factor. Generating large PDFs with a lot of content can slow down rendering in the browser.

One simple approach is to limit input size:

if (content.length > 2000) {
  alert("Content is too large. Consider splitting it into multiple sections.");
  return;
}

Another approach is to split content across multiple pages instead of forcing everything onto one page:

const pageHeight = doc.internal.pageSize.getHeight();
const lineHeight = doc.getLineHeight() / doc.internal.scaleFactor;

lines.forEach((line) => {
  if (y > pageHeight - margin) {
    doc.addPage();
    y = margin;
  }

  doc.text(line, margin, y);
  y += lineHeight;
});

This ensures large content is handled efficiently without breaking layout or performance.

In real-world tools, small decisions like spacing, wrapping, pagination, and content limits make a big difference in how usable and professional your generated PDFs feel.

Common Mistakes to Avoid

One common issue is skipping validation. If users generate a PDF with empty fields, the result won’t be useful.

To avoid this, always validate input properly and handle whitespace:

if (!title.trim() && !content.trim()) {
  alert("Please enter valid content before generating the PDF.");
  return;
}

This ensures users don’t download empty or broken PDFs.

Another mistake is ignoring text overflow. In a browser, text wraps automatically, but in a PDF it does not. Without handling this, long content can overlap or go outside the page.

You can fix this using dynamic text wrapping:

const pageWidth = doc.internal.pageSize.getWidth();
const margin = 10;
const maxWidth = pageWidth - margin * 2;

const lines = doc.splitTextToSize(content, maxWidth);
doc.text(lines, margin, 40);

This keeps the content inside the page and improves readability.

A related issue is overlapping content caused by fixed positioning. If you place everything at static coordinates, sections can stack on top of each other.

Instead, update positions dynamically:

let y = 20;

doc.text(title, 10, y);
y += 10;

const lines = doc.splitTextToSize(content, maxWidth);
doc.text(lines, 10, y);

const lineHeight = doc.getLineHeight() / doc.internal.scaleFactor;
y += lines.length * lineHeight;

This keeps spacing consistent and prevents layout issues.

Finally, forgetting to load the jsPDF library properly will break the entire feature. If the script is missing or incorrect, the PDF won’t generate at all.

Always make sure the CDN is included correctly:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script>

In practice, most issues come down to proper validation, dynamic spacing, and handling content size correctly. Fixing these early makes your PDF generator much more reliable.

Demo: How the PDF Generator Works

For this example, we’ll generate a simple invoice PDF to demonstrate how this works in a real-world scenario.

Step 1: Enter Company Details

Start by entering your company details such as name, address, contact information, and other identifiers. This data will appear at the top of the generated invoice.

Step 2: Add Customer Information

Next, fill in the customer details including billing and shipping addresses. This ensures the invoice is correctly assigned.

Step 3: Enter Invoice Details

Provide invoice-specific details such as invoice number, dates, and any additional notes. These values help structure the document properly.

Step 4: Add Items to the Invoice

Add the items or services included in the invoice. Each item can include quantity, pricing, tax, and discounts, which are automatically calculated.

Step 5: Configure Payment and Terms

Define payment instructions, terms, and any additional conditions. This section ensures the invoice is complete and ready for real use.

Step 6: Preview the Generated Invoice

The interface provides a live preview of the invoice so you can review everything before generating the PDF.

Step 7: Generate and Download the PDF

Finally, click the generate button to create and download the PDF instantly. The file is generated directly in the browser without any server interaction.

Conclusion

In this tutorial, you built a PDF generator using JavaScript that runs entirely in the browser.

More importantly, you learned how to think about building real tools using client-side capabilities. This approach reduces complexity, improves performance, and keeps user data private.

Once you understand this pattern, you can extend it to build more advanced tools like invoice systems, report generators, and document exporters.

And that’s where things start to get really interesting.

In this handbook, you'll build a complete marketplace from scratch using TypeScript. You won't need a traditional database. Instead, you'll use Stripe as your product catalog and payment engine.

This is how many real-world marketplaces work: Stripe stores the products, prices, and customer data, while your application handles the user experience.

Here's what you'll build:

1. A merchant onboarding flow where sellers create accounts and connect with Stripe

2. A product management system where merchants can add and list products directly through Stripe

3. A checkout flow that supports both one-time payments and recurring subscriptions

4. Webhooks that listen for payment events in real time

5. A billing portal where customers can manage their subscriptions

6. A complete storefront where customers can browse and buy products

You can also grab the complete source code from the GitHub repository linked at the end.

Table of Contents

• Prerequisites

• What is Stripe Connect?

• How to Set Up the Project

• How to Set Up the Backend

• How to Build the Express Backend

• How to Handle Merchant Onboarding

  • How to Create a Connected Account

  • How to Create the Onboarding Link

• How to Check Account Status

• How to Create Products Through Stripe

• How to Fetch Products

• How to Build the Checkout Flow

• How to Handle Webhooks

• How to Configure Webhooks in the Stripe Dashboard

• How to Test Webhooks Locally

• How to Add the Billing Portal

• How to Build the Next.js Frontend

• How to Create the Account Context

• How to Create the Account Status Hook

• How to Build the Merchant Onboarding Component

• How to Build the Product Create, Product List and Checkout

• How to Build the Product Form

• How to Build the Main Page

• How to Test the Full Flow

• How the Payment Split Works

• Next Steps

• Acknowledgements

• Conclusion

Prerequisites

Before you begin, make sure you have the following:

1. Node.js (version 18 or higher) installed on your machine

2. A basic understanding of React, TypeScript, and REST APIs

3. A Stripe account (sign up for free at stripe.com)

4. A code editor like VS Code

You do not need a database for this project. Stripe will store your products, prices, and customer information. This keeps the architecture simple and mirrors how many production marketplaces actually work.

What is Stripe Connect?

Stripe Connect is a set of APIs designed for platforms and marketplaces. It lets you create accounts for your merchants (Stripe calls them "connected accounts"), route payments to them, and take a platform fee on every transaction.

In this tutorial, you will use Stripe’s V2 Accounts API, which is the newer and recommended way to create connected accounts. With the V2 API, you configure what each account can do (accept card payments, receive payouts) through a configuration object, and Stripe handles all compliance and identity verification through a hosted onboarding flow.

Here's how the payment flow works:

1. A customer selects a product and clicks checkout on your marketplace.

2. Your server creates a Stripe Checkout Session linked to the merchant’s connected account.

3. The customer pays on Stripe’s hosted checkout page.

4. Stripe automatically splits the payment: the merchant gets their share, and your platform keeps an application fee.

5. Stripe sends a webhook event to your server confirming the payment.

6. The merchant can view their earnings and withdraw funds from their Stripe dashboard.

How to Set Up the Project

Create a project folder with separate directories for your backend and frontend:

mkdir marketplace && cd marketplace
mkdir server client

How to Set Up the Backend

Navigate into the server directory and initialize a TypeScript project:

cd server
npm init -y
npm install express cors dotenv stripe
npm install -D typescript ts-node @types/express @types/cors @types/node
npx tsc --init
mkdir src

Open tsconfig.json and update it with these settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"]
}

Then create a .env file in the server root:

STRIPE_SECRET_KEY=sk_test_your_key_here
DOMAIN=http://localhost:3000

You can find your Stripe test secret key in the Stripe Dashboard under Developers > API Keys. The DOMAIN variable tells your server where to redirect customers after checkout.

Add these scripts to your package.json:

{
  "scripts": {
    "dev": "ts-node src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

How to Build the Express Backend

Create the file src/index.ts. This will be your entire backend. Let’s start with the setup and imports:

import express, { Request, Response, Router } from 'express';
import cors from 'cors';
import dotenv from 'dotenv';
import Stripe from 'stripe';

dotenv.config();

const app = express();
const router = Router();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string);

app.use(cors({ origin: process.env.DOMAIN }));
app.use(express.static('public'));

Notice that we don't import any database client. Stripe is our data layer. Every product, price, customer, and transaction lives in Stripe. Your Express server is a thin orchestration layer that talks to the Stripe API on behalf of your frontend.

We also mount express.static("public") so you can serve static files later if needed. The webhook endpoint needs the raw request body, so we'll register it before the JSON parser. Let’s add that now.

How to Handle Merchant Onboarding

The first thing a merchant needs to do is create an account on your platform and connect it to Stripe. This involves two steps: creating a connected account, and then redirecting the merchant to Stripe’s hosted onboarding form.

How to Create a Connected Account

Add the following route to your src/index.ts:

// Type definitions for request bodies
interface CreateAccountBody {
  email: string;
}
interface AccountIdBody {
  accountId: string;
}

// Create a Connected Account using Stripe V2 API
router.post(
  '/create-connect-account',
  async (req: Request<{}, {}, CreateAccountBody>, res: Response) => {
    try {
      const account = await stripe.v2.core.accounts.create({
        display_name: req.body.email,
        contact_email: req.body.email,
        dashboard: 'full',
        defaults: {
          responsibilities: {
            fees_collector: 'stripe',
            losses_collector: 'stripe',
          },
        },
        identity: {
          country: 'GB',
          entity_type: 'company',
        },
        configuration: {
          customer: {},
          merchant: {
            capabilities: {
              card_payments: { requested: true },
            },
          },
        },
      });
      res.json({ accountId: account.id });
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

Let’s break down what this code does. The stripe.v2.core.accounts.create() method creates a new connected account using Stripe’s V2 API. Here are the key configuration options:

1. dashboard: "full" gives the merchant access to their own Stripe dashboard where they can view payments, manage payouts, and handle disputes.

2. responsibilities tells Stripe who collects fees and who is liable for losses. Setting both to "stripe" means Stripe handles this, which is the simplest configuration.

3. identity sets the country and entity type. Change "GB" to your merchants’ country code (for example, "US" for the United States).

4. configuration.merchant.capabilities requests the card_payments capability, which lets the merchant accept credit card payments.

How to Create the Onboarding Link

After creating the account, you need to redirect the merchant to Stripe’s hosted onboarding form. Add this route:

// Create Account Link for onboarding
router.post('/create-account-link', async (req: Request<{}, {}, AccountIdBody>, res: Response) => {
  const { accountId } = req.body;
  try {
    const accountLink = await stripe.v2.core.accountLinks.create({
      account: accountId,
      use_case: {
        type: 'account_onboarding',
        account_onboarding: {
          configurations: ['merchant', 'customer'],
          refresh_url: `${process.env.DOMAIN}`,
          return_url: `\({process.env.DOMAIN}?accountId=\){accountId}`,
        },
      },
    });
    res.json({ url: accountLink.url });
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

The accountLinks.create() method generates a temporary URL that takes the merchant to Stripe’s onboarding form. On that form, Stripe collects the merchant’s identity documents, bank account details, and tax information. You don't need to build any of this yourself.

The return_url is where Stripe redirects the merchant after they complete onboarding. Notice that you append the accountId as a query parameter so your frontend can pick it up and store it.

How to Check Account Status

You need a way to check whether a merchant has finished onboarding and is ready to accept payments. Add this route:

// Get Connected Account Status
router.get(
  '/account-status/:accountId',
  async (req: Request<{ accountId: string }>, res: Response) => {
    try {
      const account = await stripe.v2.core.accounts.retrieve(req.params.accountId, {
        include: ['requirements', 'configuration.merchant'],
      });
      const payoutsEnabled =
        account.configuration?.merchant?.capabilities?.stripe_balance?.payouts?.status === 'active';
      const chargesEnabled =
        account.configuration?.merchant?.capabilities?.card_payments?.status === 'active';
      const summaryStatus = account.requirements?.summary?.minimum_deadline?.status;
      const detailsSubmitted = !summaryStatus || summaryStatus === 'eventually_due';
      res.json({
        id: account.id,
        payoutsEnabled,
        chargesEnabled,
        detailsSubmitted,
        requirements: account.requirements?.entries,
      });
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

This route retrieves the connected account and checks three important statuses:

• chargesEnabled tells you if the merchant can accept payments.

• payoutsEnabled tells you if they can receive payouts to their bank account.

• detailsSubmitted tells you if they have completed the onboarding form.

Your frontend will use these flags to show or hide features.

How to Create Products Through Stripe

Instead of storing products in a database, you'll create them directly in Stripe. Each product is created on the merchant’s connected account using the stripeAccount header. This means each merchant has their own isolated product catalog inside Stripe.

// Type definition for product creation
interface CreateProductBody {
  productName: string;
  productDescription: string;
  productPrice: number;
  accountId: string;
}
// Create a product on the connected account
router.post('/create-product', async (req: Request<{}, {}, CreateProductBody>, res: Response) => {
  const { productName, productDescription, productPrice, accountId } = req.body;
  try {
    // Create the product on the connected account
    const product = await stripe.products.create(
      {
        name: productName,
        description: productDescription,
      },
      { stripeAccount: accountId },
    ); // Create a price for the product
    const price = await stripe.prices.create(
      {
        product: product.id,
        unit_amount: productPrice,
        currency: 'usd',
      },
      { stripeAccount: accountId },
    );
    res.json({
      productName,
      productDescription,
      productPrice,
      priceId: price.id,
    });
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

There are two Stripe API calls happening here. First, stripe.products.create() creates the product (name and description). Then stripe.prices.create() creates a price for that product (amount and currency).

Stripe separates products from prices because a single product can have multiple prices — for example, a monthly plan and an annual plan.

The { stripeAccount: accountId } option on both calls tells Stripe to create these resources on the merchant’s connected account, not on your platform account. This is a critical detail: without it, the products would be created on your platform’s account and the merchant would never see them.

How to Fetch Products

Add a route to list all products for a given merchant:

// Fetch products for a specific account
router.get('/products/:accountId', async (req: Request<{ accountId: string }>, res: Response) => {
  const { accountId } = req.params;
  try {
    const options: Stripe.RequestOptions = {};
    if (accountId !== 'platform') {
      options.stripeAccount = accountId;
    }
    const prices = await stripe.prices.list(
      {
        expand: ['data.product'],
        active: true,
        limit: 100,
      },
      options,
    );
    const products = prices.data.map((price) => {
      const product = price.product as Stripe.Product;
      return {
        id: product.id,
        name: product.name,
        description: product.description,
        price: price.unit_amount,
        priceId: price.id,
        period: price.recurring ? price.recurring.interval : null,
      };
    });
    res.json(products);
  } catch (error) {
    const message = error instanceof Error ? error.message : 'Unknown error';
    res.status(500).json({ error: message });
  }
});

This route fetches all active prices from a merchant’s Stripe account and expands the product data (using expand: ["data.product"]) so you get the product name and description in the same API call. The period field will be null for one-time products and "month" or "year" for subscriptions.

How to Build the Checkout Flow

Your checkout flow needs to handle two scenarios: one-time payments for individual products, and recurring subscriptions. Stripe’s Checkout Sessions handle both — you just need to set the mode based on the price type.

// Type definition for checkout
interface CheckoutBody {
  priceId: string;
  accountId: string;
}
// Create checkout session
router.post(
  '/create-checkout-session',
  async (req: Request<{}, {}, CheckoutBody>, res: Response) => {
    const { priceId, accountId } = req.body;
    try {
      // Retrieve the price to determine if it is
      // one-time or recurring
      const price = await stripe.prices.retrieve(priceId, { stripeAccount: accountId });
      const isSubscription = price.type === 'recurring';
      const mode = isSubscription ? 'subscription' : 'payment';
      const session = await stripe.checkout.sessions.create(
        {
          line_items: [
            {
              price: priceId,
              quantity: 1,
            },
          ],
          mode,
          success_url: `${process.env.DOMAIN}/done?session_id={CHECKOUT_SESSION_ID}`,
          cancel_url: `${process.env.DOMAIN}`,
          ...(isSubscription
            ? {
                subscription_data: {
                  application_fee_percent: 10,
                },
              }
            : {
                payment_intent_data: {
                  application_fee_amount: 123,
                },
              }),
        },
        { stripeAccount: accountId },
      );
      res.redirect(303, session.url as string);
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Unknown error';
      res.status(500).json({ error: message });
    }
  },
);

Here's what this route does step by step. First, it retrieves the price from the merchant’s connected account to check whether it is a one-time price or a recurring subscription. Then it creates a Checkout Session with the appropriate mode — either "payment" or "subscription".

The application_fee_amount is your platform’s cut of the transaction, specified in the smallest currency unit (cents for USD). In this example, you take $1.23 or 10% per transaction. For a real marketplace, you would likely calculate this as a percentage of the product price.

Notice that application_fee_amount goes inside subscription_data for subscriptions but inside payment_intent_data for one-time payments. This is a Stripe requirement — the two modes use different configuration objects.

Finally, the route uses res.redirect(303, session.url) to send the customer directly to Stripe’s hosted checkout page.

How to Handle Webhooks

Webhooks are how Stripe tells your server about events that happen asynchronously — like a successful payment, a failed charge, or a subscription cancellation.

In a production marketplace, you should never rely solely on redirect URLs to confirm payments. A customer might close their browser before the redirect completes. Webhooks are your source of truth.

Add the webhook endpoint before the JSON body parser. Stripe sends webhook payloads as raw bytes, and you need the raw body to verify the signature:

// IMPORTANT: Register this BEFORE app.use(express.json())
app.post(
  '/api/webhook',
  express.raw({ type: 'application/json' }),
  (req: Request, res: Response) => {
    let event: Stripe.Event = JSON.parse(req.body.toString()); // If you have an endpoint secret, verify the
    // signature for security
    const endpointSecret = process.env.WEBHOOK_SECRET;
    if (endpointSecret) {
      const signature = req.headers['stripe-signature'] as string;
      try {
        event = stripe.webhooks.constructEvent(req.body, signature, endpointSecret) as Stripe.Event;
      } catch (err) {
        const message = err instanceof Error ? err.message : 'Unknown error';
        console.log('Webhook signature verification failed:', message);
        res.sendStatus(400);
        return;
      }
    } // Handle the event
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Payment successful for session:', session.id); // Fulfill the order: send email, grant access,
        // update your records, and so on
        break;
      }
      case 'checkout.session.expired': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Session expired:', session.id); // Optionally notify the customer or clean up
        // any pending records
        break;
      }
      case 'checkout.session.async_payment_succeeded': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Delayed payment succeeded for session:', session.id); // Fulfill the order now that payment cleared
        break;
      }
      case 'checkout.session.async_payment_failed': {
        const session = event.data.object as Stripe.Checkout.Session;
        console.log('Payment failed for session:', session.id); // Notify the customer that payment failed
        break;
      }
      case 'customer.subscription.deleted': {
        const subscription = event.data.object as Stripe.Subscription;
        console.log('Subscription cancelled:', subscription.id); // Revoke access for the customer
        break;
      }
      default:
        console.log('Unhandled event type:', event.type);
    }
    res.send();
  },
);

The webhook handler checks for five key events.

• checkout.session.completed fires when a payment succeeds — this is where you would fulfill an order, send a confirmation email, or grant access.

• checkout.session.expired fires when a session expires before the customer completes payment.

• checkout.session.async_payment_succeeded fires when a delayed payment method (like a bank transfer) finally goes through.

• checkout.session.async_payment_failed fires when a delayed payment method fails.

• And customer.subscription.deleted fires when a subscription is cancelled.

How to Configure Webhooks in the Stripe Dashboard

Before you can receive webhook events, you need to tell Stripe where to send them and which events you care about. Follow these steps:

1. Go to the Stripe Dashboard and navigate to Developers > Webhooks.

2. Click "Add destination."

3. Under the account type, select "Connected and V2 accounts" since your payments go through connected merchant accounts.

4. Under "Events to listen for," click "All events" and select the following five events:

   • checkout.session.async_payment_succeeded — Occurs when a payment intent using a delayed payment method finally succeeds.

   • checkout.session.completed — Occurs when a Checkout Session has been successfully completed.

   • checkout.session.expired — Occurs when a Checkout Session expires before completion.

   • checkout.session.async_payment_failed — Occurs when a payment intent using a delayed payment method fails.

   • customer.subscription.deleted — Occurs whenever a customer’s subscription ends.

5. Enter your webhook endpoint URL. For production, this would be something like https://yourdomain.com/api/webhook. For local development, you will use the Stripe CLI instead (covered next).

6. Click "Add destination" to save.

How to Test Webhooks Locally

For local development, you don't need to expose your server to the internet. Install the Stripe CLI and run:

brew install stripe/stripe-cli/stripe
stripe login
stripe listen --forward-to localhost:4242/webhook

The CLI will print a webhook signing secret that starts with whsec_. Add this to your .env file as WEBHOOK_SECRET. The CLI intercepts all webhook events from Stripe and forwards them to your local server, so you can test the full payment flow without deploying anything.

How to Add the Billing Portal

The billing portal lets customers manage their subscriptions without you building any UI for it. Stripe hosts the entire experience — customers can update their payment method, change plans, or cancel their subscription.

// Create a billing portal session
router.post(
  "/create-portal-session",
  async (req: Request, res: Response) => {
    const { session_id } = req.body as {
      session_id: string;
    };
 
    try {
      const session =
        await stripe.checkout.sessions.retrieve(
          session_id
        );
 
      const portalSession =
        await stripe.billingPortal.sessions.create({
          customer_account: session.customer_account as string,
          return_url: `\({process.env.DOMAIN}?session_id=\){session_id}`,
        });
 
      res.redirect(303, portalSession.url);
    } catch (error) {
      const message =
        error instanceof Error
          ? error.message
          : "Unknown error";
      res.status(500).json({ error: message });
    }
  }
);

This route takes a session_id from a previous checkout, retrieves the associated customer, and creates a billing portal session. The customer_account field links the portal to the correct connected account so the customer sees only their subscriptions with that specific merchant.

Now add the JSON parser and mount the router. This must come after the webhook route:

// JSON and URL-encoded parsers (AFTER webhook route)
app.use(express.urlencoded({ extended: true }));
app.use(express.json());

// Mount all routes under /api
app.use('/api', router);
const PORT: number = parseInt(process.env.PORT || '4242', 10);
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

How to Build the Next.js Frontend

Navigate to the client directory and create a new Next.js project with TypeScript:

cd ../client
npx create-next-app@latest . --typescript --app --tailwind --eslint
npm install axios

How to Create the Account Context

You need a way to share the merchant’s account ID across all components. Create a context provider at contexts/AccountContext.tsx:

'use client';
import { createContext, useContext, useState, ReactNode } from 'react';
import { useSearchParams } from 'next/navigation';

interface AccountContextType {
  accountId: string | null;
  setAccountId: (id: string | null) => void;
}

const AccountContext = createContext<AccountContextType | undefined>(undefined);

export function useAccount(): AccountContextType {
  const context = useContext(AccountContext);
  if (!context) {
    throw new Error('useAccount must be used within AccountProvider');
  }
  return context;
}

export function AccountProvider({ children }: { children: ReactNode }) {
  const searchParams = useSearchParams();
  const [accountId, setAccountId] = useState<string | null>(searchParams.get('accountId'));

  return (
    <AccountContext.Provider value={{ accountId, setAccountId }}>
      {children}
    </AccountContext.Provider>
  );
}

This context stores the current merchant’s account ID and makes it available throughout the app. On initial load, it checks the URL for an accountId query parameter — this is how Stripe’s onboarding redirect passes the account ID back to your app.

How to Create the Account Status Hook

Create a custom hook at hooks/useAccountStatus.ts that polls the account status:

'use client';
import { useState, useEffect } from 'react';
import { useAccount } from '@/contexts/AccountContext';
interface AccountStatus {
  id: string;
  payoutsEnabled: boolean;
  chargesEnabled: boolean;
  detailsSubmitted: boolean;
}
export default function useAccountStatus() {
  const [accountStatus, setAccountStatus] = useState<AccountStatus | null>(null);
  const { accountId, setAccountId } = useAccount();
  useEffect(() => {
    if (!accountId) return;
    const fetchStatus = async () => {
      try {
        const res = await fetch(`http://localhost:4242/api/account-status/${accountId}`);
        if (!res.ok) throw new Error('Failed to fetch');
        const data: AccountStatus = await res.json();
        setAccountStatus(data);
      } catch {
        setAccountId(null);
      }
    };
    fetchStatus();
    const interval = setInterval(fetchStatus, 5000);
    return () => clearInterval(interval);
  }, [accountId, setAccountId]);
  return {
    accountStatus,
    needsOnboarding: !accountStatus?.chargesEnabled && !accountStatus?.detailsSubmitted,
  };
}

This hook polls the account status every 5 seconds. This is important because Stripe’s onboarding is asynchronous — a merchant might complete the form, but it can take a moment for Stripe to verify their details and activate their account. The needsOnboarding flag tells your UI whether to show the onboarding button or the merchant dashboard.

How to Build the Merchant Onboarding Component

Create components/ConnectOnboarding.tsx:

'use client';
import { useState } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
export default function ConnectOnboarding() {
  const [email, setEmail] = useState<string>('');
  const { accountId, setAccountId } = useAccount();
  const { accountStatus, needsOnboarding } = useAccountStatus();
  const handleCreateAccount = async () => {
    const res = await fetch(`${API_URL}/create-connect-account`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email }),
    });
    const data = await res.json();
    setAccountId(data.accountId);
  };
  const handleStartOnboarding = async () => {
    const res = await fetch(`${API_URL}/create-account-link`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ accountId }),
    });
    const data = await res.json();
    window.location.href = data.url;
  };
  if (!accountId) {
    return (
      <div className="max-w-md mx-auto p-6">
        <h2 className="text-xl font-bold mb-4">Create Your Seller Account</h2>
        <input
          type="email"
          placeholder="Your email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          className="w-full border p-2 rounded mb-4"
        />
        <button
          onClick={handleCreateAccount}
          className="w-full bg-green-600 text-white p-2 rounded hover:bg-green-700"
        >
          Create Connect Account
        </button>
      </div>
    );
  }
  return (
    <div className="max-w-md mx-auto p-6">
      <h3 className="font-semibold mb-2">Account: {accountId} </h3>
      <p className="mb-2">Charges: {accountStatus?.chargesEnabled ? 'Active' : 'Pending'} </p>
      <p className="mb-4">Payouts: {accountStatus?.payoutsEnabled ? 'Active' : 'Pending'} </p>
      {needsOnboarding && (
        <button
          onClick={handleStartOnboarding}
          className="bg-purple-600 text-white px-6 py-2 rounded hover:bg-purple-700"
        >
          Complete Onboarding
        </button>
      )}
    </div>
  );
}

This component handles both states of the merchant experience. If no account exists, it shows a simple email form. After account creation, it shows the account status and an onboarding button if needed.

How to Build the Product Create, Product List and Checkout

Create components/Products.tsx:

'use client';
import { useState, useEffect } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
interface Product {
  id: string;
  name: string;
  description: string | null;
  price: number | null;
  priceId: string;
  period: string | null;
}
export default function Products() {
  const { accountId } = useAccount();
  const { needsOnboarding } = useAccountStatus();
  const [products, setProducts] = useState<Product[]>([]);
  useEffect(() => {
    if (!accountId || needsOnboarding) return;
    const fetchProducts = async () => {
      const res = await fetch(`\({API_URL}/products/\){accountId}`);
      const data: Product[] = await res.json();
      setProducts(data);
    };
    fetchProducts();
    const interval = setInterval(fetchProducts, 5000);
    return () => clearInterval(interval);
  }, [accountId, needsOnboarding]);
  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mt-6">
      {' '}
      {products.map((product) => (
        <div key={product.priceId} className="border rounded-lg p-4 shadow-sm">
          <h3 className="text-lg font-semibold">  {product.name}</h3>

          <p className="text-gray-600 mt-1">  {product.description}</p>

          <p className="text-xl font-bold mt-3">
            ${((product.price ?? 0) / 100).toFixed(2)}
            {product.period ? ` / ${product.period}` : ''}
          </p>

          <form action={`${API_URL}/create-checkout-session`} method="POST">
            <input type="hidden" name="priceId" value={product.priceId} />
            <input type="hidden" name="accountId" value={accountId ?? ''} />
            <button
              type="submit"
              className="mt-4 w-full bg-blue-600 text-white py-2 rounded hover:bg-blue-700"
            >
              {product.period ? 'Subscribe' : 'Buy Now'}
            </button>
          </form>
        </div>
      ))}
    </div>
  );
}

The Products component fetches all products from the merchant’s Stripe account and displays them in a responsive grid. The checkout button submits a form directly to your backend, which redirects the customer to Stripe’s hosted checkout page. Notice how the button text changes based on whether the product is a one-time purchase or a subscription.

How to Build the Product Form

Merchants need a way to add products from the frontend. Create components/ProductForm.tsx:

'use client';
import { useState } from 'react';
import { useAccount } from '@/contexts/AccountContext';
import useAccountStatus from '@/hooks/useAccountStatus';
const API_URL = 'http://localhost:4242/api';
interface ProductFormData {
  productName: string;
  productDescription: string;
  productPrice: number;
}
export default function ProductForm() {
  const { accountId } = useAccount();
  const { needsOnboarding } = useAccountStatus();
  const [showForm, setShowForm] = useState<boolean>(false);
  const [formData, setFormData] = useState<ProductFormData>({
    productName: '',
    productDescription: '',
    productPrice: 1000,
  });
  const handleSubmit = async (e: React.FormEvent): Promise<void> => {
    e.preventDefault();
    if (!accountId || needsOnboarding) return;
    await fetch(`${API_URL}/create-product`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        ...formData,
        accountId,
      }),
    }); // Reset form and hide it
    setFormData({
      productName: '',
      productDescription: '',
      productPrice: 1000,
    });
    setShowForm(false);
  }; // Only show the form if the merchant has completed
  // onboarding and can accept charges
  if (!accountId || needsOnboarding) return null;
  return (
    <div className="my-6">
      <button
        onClick={() => setShowForm(!showForm)}
        className="bg-green-600 text-white px-4 py-2 rounded hover:bg-green-700"
      >
        {showForm ? 'Cancel' : 'Add New Product'}
      </button>

      {showForm && (
        <form onSubmit={handleSubmit} className="mt-4 max-w-md space-y-4">
          <div>
            <label className="block text-sm font-medium mb-1">Product Name</label>

            <input
              type="text"
              value={formData.productName}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productName: e.target.value,
                })
              }
              className="w-full border p-2 rounded"
              required
            />
          </div>

          <div>
            <label className="block text-sm font-medium mb-1">Description</label>
            <input
              type="text"
              value={formData.productDescription}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productDescription: e.target.value,
                })
              }
              className="w-full border p-2 rounded"
            />
          </div>
          <div>
            <label className="block text-sm font-medium mb-1">Price (in cents)</label>

            <input
              type="number"
              value={formData.productPrice}
              onChange={(e) =>
                setFormData({
                  ...formData,
                  productPrice: parseInt(e.target.value),
                })
              }
              className="w-full border p-2 rounded"
              required
            />
          </div>
          <button
            type="submit"
            className="bg-blue-600 text-white px-4 py-2 rounded hover:bg-blue-700"
          >
            Create Product
          </button>
        </form>
      )}
    </div>
  );
}

This component only renders after the merchant has completed onboarding (the if (!accountId || needsOnboarding) return null check at the top). It toggles a form where the merchant enters a product name, description, and price in cents. When submitted, it calls your /api/create-product endpoint, which creates both the product and its price on the merchant’s connected Stripe account.

The price field uses cents because that is what Stripe expects. So if a merchant wants to sell a product for \(25.00, they enter 2500. In a production app, you would add a friendlier input that lets merchants type \)25.00 and converts it to cents automatically.

How to Build the Main Page

Finally, put it all together in app/page.tsx:

'use client';
import { AccountProvider } from '@/contexts/AccountContext';
import ConnectOnboarding from '@/components/ConnectOnboarding';
import Products from '@/components/Products';
import ProductForm from '@/components/ProductForm';
export default function Home() {
  return (
    <AccountProvider>
      {' '}
      <main className="max-w-6xl mx-auto p-8">
        <h1 className="text-3xl font-bold mb-8"> Marketplace Dashboard </h1>
        <ConnectOnboarding />
        <ProductForm />
        <Products />
      </main>
    </AccountProvider>
  );
}

How to Test the Full Flow

Start both servers:

# Terminal 1 - Backend
cd server
npm run dev
 
# Terminal 2 - Frontend
cd client
npm run dev
 
# Terminal 3 - Stripe webhook listener
stripe listen --forward-to localhost:4242/api/webhook

Now test the complete flow:

1. Go to http://localhost:3000 and enter an email to create a merchant account.

2. Click "Complete Onboarding" and fill out Stripe’s test onboarding form. Use test data like 000-000-0000 for the phone number and 0000 for the last four digits of SSN.

3. Wait a few seconds for the account status to update. Once charges are active, you can add products.

4. Create a product using the product form (set the price in cents — for example, 2500 for $25.00).

5. Click "Buy Now" on a product to start the checkout flow.

6. On Stripe’s checkout page, use the test card number 4242 4242 4242 4242 with any future expiry date and any CVC.

7. Check your terminal — you should see the webhook event confirming the payment.

8. Check the Stripe Dashboard to see the payment, the application fee, and the transfer to the connected account.

How the Payment Split Works

Here is exactly what happens when a customer pays $25.00 for a product:

1. The customer pays $25.00 on Stripe’s checkout page.

2. Stripe deducts its processing fee (approximately 2.9% + $0.30 for US cards).

3. Your platform takes the application fee you set ($1.23 in our example).

4. The remaining amount is transferred to the merchant’s connected Stripe account.

5. The merchant can withdraw their funds to their bank account from the Stripe Dashboard.

You control the application fee in the checkout route. In a production marketplace, you would calculate this as a percentage of the transaction. For example, to take a 10% fee:

onst applicationFee = Math.round(
  (price.unit_amount ?? 0) * 0.1
);

Next Steps

You now have a working marketplace. Here are improvements to consider for production:

• Add authentication with NextAuth.js so merchants can securely log in and manage their accounts across sessions.

• Add runtime validation with Zod to validate all request bodies before they reach Stripe.

• Add image uploads for products using Cloudinary or AWS S3, then pass the image URL to Stripe’s product metadata.

• Build separate merchant and customer views. Right now the app combines both experiences on one page.

• Deploy your backend to Railway or Render and your frontend to Vercel. Update the webhook URL in your Stripe Dashboard to point to your production server.

You can find the complete source code for this tutorial on GitHub: https://github.com/michaelokolo/marketplace

Acknowledgements

Some API usage patterns in this tutorial are inspired by examples from the official Stripe documentation. These examples were adapted to demonstrate how to build a complete multi-vendor marketplace architecture.

Conclusion

In this handbook, you built a complete online marketplace where merchants can onboard through Stripe Connect, create products stored directly in Stripe, and receive payments from customers — all without a traditional database.

You learned how to use Stripe’s V2 Accounts API for merchant onboarding, create products and prices on connected accounts, build a checkout flow that handles both one-time payments and subscriptions, listen for payment events with webhooks, and give customers a billing portal to manage their subscriptions.

The key insight is that Stripe Connect handles the hardest parts of running a marketplace — payment splitting, tax compliance, identity verification, and fund transfers. Your job is to build a great user experience on top of it.

If you found this tutorial helpful, share it with someone who is learning to build full-stack applications. Happy coding!

WebCodecs is a relatively new API that allows browser applications to process video efficiently with very low-level control.

In the past, if you wanted to build, say, a video-editing app or live-streaming studio or anything that required 'heavy lifting', you needed to build a native desktop application. Many SaaS tools like Canva got around this with server-side video processing, which provided a much better UX, but which is much more complex and expensive.

With WebCodecs, it's now possible to build these apps entirely in the browser, without requiring users to download and install software, and without expensive, complex server infrastructure.

This isn't theoretical. Video Editing tools like Capcut saw an 83% boost in traffic after switching to WebCodecs + WebAssembly [1]. Utility apps like Remotion Convert and Free AI Video Upscaler (both open source) process thousands of videos a day with zero server costs and no installation required [2].

WebCodecs is even being used for entirely new use cases, like generating videos programatically [3].

If you're building any kind of video app, it's worthwhile to at least know about WebCodecs as an option for working with video in the browser.

In this guide, we will:

1. Review the basics of Video Processing

2. Introduce the WebCodecs API

3. Discuss Muxing + Demuxing to read and write video files

4. Build our own video conversion utility to convert videos between webm + mp4, and apply basic transformations

5. Cover some production-level concerns

6. Discuss additional resources

The goal of this article is to be a practical entry point and introduction to the WebCodecs API for frontend developers. It'll teach you how the API works and what you can do with it. I'll assume you know the basics of Javascript but you don't need to be a senior developer or a video engineer to follow along.

At the end, I'll mention additional learning resources and references. In future tutorials, I'll go more in-depth on specific topics like building a video editor, or doing live-streaming with WebCodecs. But this handbook should provide a solid starting point for what WebCodecs is, what it can do, and how to build a basic application with it.

Table of Contents

• Prerequisites

• Primer on Video Processing

  • Video Frames

  • Codecs

  • Encoding & Decoding

  • Containers

• What is WebCodecs?

  • Before WebCodecs

  • Core API

• Muxing and Demuxing

  • Demuxing

  • Muxing

• Building a Video Converter Utility

  • Transcoding

  • Transformations

  • Transform Pipeline

  • Complete Demo

• Production Concerns

  • Codecs

  • Bit rate

  • GPU vs CPU

  • Memory

• Further Resources

Prerequisites

You don't need to be a video engineer to follow along, but you should be comfortable with:

• Core JavaScript, including async/await and callbacks

• Basic browser APIs like fetch and the DOM

• What a File object is and how file inputs work in HTML

• A general sense of what HTML5 is (we'll use it briefly, but won't go deep)

No prior knowledge of video processing, codecs, or media APIs is required — that's what the first half of this handbook covers.

Primer on Video Processing

Hold your bunnies, because before getting into WebCodecs, I want to make sure you're aware of what codecs are before we even consider putting codecs on the web.

Video Frames

I presume you know what a video is. Ironically the 'video' below is actually a gif, but you get the idea.

Videos are just a series of images, shown one after the other, in quick succession. Each image is called a Video Frame, and each frame is associated with a timestamp. When a video player plays back the video, it displays each video frame at the time indicated by the timestamp.

Every frame in the video is made of pixels, with a 4K video frame containing approximately 8 million pixels (3840*2160 = 8294400).

Each pixel itself is actually made of 3 components: a Red, Green, and Blue value (also called RGB value).

Each of of the R, G and B color values is stored as an 8-bit integer, ranging from 0 to 255, with the number indicating the intensity of the red, green, or blue color component.

Combining the intensity of each of the R, G, and B components lets you represent any arbitrary color on the color spectrum:

So for each pixel, we need 3 bytes of data: 1 byte for each of the R, G, and B color values (1 byte = 8 bits). A 4K video frame therefore would contain ~25 Megabytes of data.

At 30 frames per second (a typical frame rate), a 1 hour, 4K video would be around 746 Gigabytes of data. If you've ever downloaded a large video or recorded HD video with your phone camera, you'll know that video files can be large, but they're never that large.

In reality, actual video files you might watch on YouTube, record on your phone camera, or download from the internet are ~100x smaller than that. The reason actual video files are much smaller is because of video compression, a family of very sophisticated algorithms that help reduce the data by ~100x.

Without this video compression, you wouldn't be able to record more than 10 minutes of video on the latest high-end smartphones, and you wouldn't be able to stream anything HD on a high-end home internet connection.

As sophisticated as our modern devices and internet connections are, without aggressive video compression, we wouldn't be able to watch, record, or stream anything in HD.

Codecs

A codec is a fancy word for a video compression algorithm. There are a few established codecs / compression algorithms, such as:

• h264: The most common codec. If you see an mp4 file, it most likely uses the h264 codec.

• vp9: An open source codec used commonly by YouTube and in video conferencing, often found in webm files.

• av1: A new open source codec, increasingly being used by platforms like YouTube and Netflix.

How these algorithms work is too complex and out of scope for this handbook. But at a very high level, here are some major ways these algorithms compress video:

Removing detail

All these algorithms use a technique called the Discrete Cosine Transform to "remove details". As you remove "detail" from the video frame, the frame starts looking "blockier". This technique is so effective, though, that you can compress a video frame by ~10x before the differences start becoming visible to the human eye.

For the curious, you can see this video by Computerphile on how the DCT algorithm works.

Encoding frame differences

When you actually look at a sequence of video frames, you'll notice that visually they're quite similar, with only small portions of the video changing, depending on how much movement there is.

These codecs/compression algorithms use sophisticated math and computer vision techniques to encode just the differences between frames,.

You therefore only need to send the first frame (a Key Frame) – then for subsequent frames you can send the "frame differences", also called Delta Frames, to reconstruct the each full frame.

In practice, for an hour long video, we don't just encode the first frame and store millions of delta frames. Instead, algorithms encode every 60th frame or so as a Key Frame, and then the next 59 frames are delta frames.

This technique is also highly effective, reducing data used by another ~10x. The distinction between Key Frames and Delta Frames is one of the few bits of "how these algorithms work" that you actually need to be aware of.

There's a number of other details and compression techniques that go into these compression algorithms that are out of scope for an intro article.

Encoding & Decoding

For video compression to work, we need to be able to both compress video (turn raw video into compressed binary data) and then decompress video (turn the compressed binary data back into raw video frames).

Turning raw video frames into compressed binary data is called encoding, and turning compressed binary data back into raw video frames is called decoding. The word codec is just an abbreviation for "encode decode".

From a practical, developer perspective, you don't need to know how these codecs work, but you do need to know that:

1. There are different video codecs, like h264, vp9, and av1

2. When you encode a video with a codec (like h264), you need a video player that can support the same codec to play back the video.

3. Encoding video takes a lot more computation than decoding video, so playing 4K video on a low-end phone is fine, but encoding 4K video on it would be super slow.

4. Most consumer devices (phones, laptops) have specialized chips designed specifically for encoding and decoding video, making encoding/decoding much faster than if run on the CPU like a normal software program. This is called hardware acceleration.

In practice, there are only a handful of video codecs, because the entire world needs to agree on standards, so that video recorded on an iPhone can be played back on a windows device.

Containers

Most people haven't heard of h264 or vp9. When you think of video files, you typically think of file formats like MP4 or MKV. These are also relevant, but they're a separate thing called containers.

A video file typically has encoded audio, encoded video, and metadata about the video file. A file format like MP4 describes a specific format for storing the encoded audio and video data, as well as the metadata.

Video compression software stores the encoded audio/video and metadata into a file according to the file format / specs. This is called muxing.

Likewise, video players follow the file format specs to read the metadata and find the encoded audio/video. This is called demuxing.

When compressing a video file, you need to both encode it and mux it (in that order). These are two separate stages of the process. Likewise, when playing a video file, you need to both demux it and then decode it (in that order).

When a video player opens, say, an mp4 file, the logic flow is as follows:

• Ok, the file ends in .mp4, so it must be an mp4 file. Let me load the library for parsing mp4 files, and parse then parse file.

• Great, I've parsed the mp4 file, I now have the metadata and know where in the byte offsets are to fetch the encoded audio and video.

• I'll start fetching the first encoded video frames, decode them, and start displaying the decoded video frame to the user.

If you ever see a "video file is corrupt" message from a video player, it's likely that the video file doesn't follow the file format spec and there was an error while trying the parse / demux the video.

What is WebCodecs?

Now that we've covered codecs, let's put them on the Web.

WebCodecs is an API that allows frontend developers to encode and decode video in the browser efficiently (using hardware acceleration), and with very low level control (encode/decode on a frame by frame basis).

The hardware acceleration bit is important, as you can't just poly fill or re-implement the API yourself. WebCodecs gives direct access to specialized hardware for encoding/decoding, making it as performant as a desktop video app.

Before WebCodecs

It's worth taking a moment to understand why WebCodecs exists. Before the WebCodecs API existed, there were several alternatives you could use for video operations in the browser.

• HTMLVideoElement: You can still create a element and use it for decoding a video. It's easy to use, but you lack frame level control. Your only control is setting the 'video.currrentTime' property and waiting for it to seek, often leading to dropped/missing frames.

• Media Recorder API: Essentially allows you to 'screen record' any canvas element or video stream. While it works, it's functionally equivalent to screen recording Adobe Premeire pro instead of clicking render. For editing scenarios, you lose frame level control and can only process video at real-time speed.

• FFMPEG.js: A port of the popular video processing tool ffmpeg, which runs ffmpeg in the browser. Many tools used this in the past, but it lacks hardware acceleration, making it much slower than WebCodecs. It also has file size restrictions stemming from the fact that it runs in WebAssembly, making it difficult to work with videos that are larger than 100 MB.

WebCodecs was built and released in 2021 to enable low-level, hardware accelerated video decoding and encoding. It's great for high-performance streaming and video editing, which were use cases not well-served by the existing APIs.

Core API

The core API for WebCodecs consists of two new "data types", the VideoFrame and EncodedVideoChunk, as well as the VideoEncoder and VideoDecoder interfaces.

VideoFrame

The Javascript VideoFrame object conceptually contains both pixel data and metadata about the video frame.

You can actually create a new VideoFrame object from any image source, as long as you include the metadata:

const bitmapFrame = new VideoFrame(imgBitmap, {timestamp: 0});

const imageFrame = new VideoFrame(htmlImageEl, {timestamp: 0});

const videoFrame = new VideoFrame(htmlVideoEl, {timestamp: 0});

const canvasFrame = new VideoFrame(canvasEl, {timestamp: 0});

For a video editing app, for example, you would typically perform image editing operations on each frame on a canvas, and then you would grab each VideoFrame from the canvas.

You can also draw a VideoFrame to a canvas using the Canvas 2D rendering context:

ctx.drawImage(frame, 0, 0);

You would typically do this when rendering / playing back a video in the browser.

EncodedVideoChunk

An EncodedVideoChunk is just the compressed version of a VideoFrame, containing the binary data as well as the same metadata as the frame.

You would typically get EncodedVideoChunks from a library which extracts them from a File object.

import { getVideoChunks } from 'webcodecs-utils'

const chunks = <EncodedVideoChunk[]> await getVideoChunks(<File> file);

Alternatively, it's the output you get from a VideoEncoder object.

There's not much useful stuff you can do with EncodedVideoChunks – it's just the binary data that you read from files, write to files, or stream over the internet.

The value in EncodedVideoChunk is that it's ~100x smaller than raw video data, which is why you'd send EncodedVideoChunks instead of raw video when streaming (and writing to a file).

VideoEncoder

A VideoEncoder turns VideoFrame objects into EncodedVideoChunk objects.

The core API looks something like this, where you define the callback where the VideoEncoder returns EncodedVideoChunk objects.

const encoder = new VideoEncoder({
    output: function(chunk: EncodedVideoChunk, meta: any){
        // Do something with the chunk
    },
    error: function(e: any)=> console.warn(e);
});

Keep in mind that this is an async process, and not even a typical async process. You can't just treat this as a per-frame operation.

// Does not work like this
const frame  = await encoder.encode(chunk);

This is because of how video encoding actually works under the hood. So you have to accept that the outputs are returned via callback, and you get the outputs when you get them.

Once you define your encoder, you can then configure the VideoEncoder with your choice of codec (we'll get to this), as well as other parameters like width, height, framerate and bitrate.

encoder.configure({
    'codec': 'vp9.00.10.08.00', // We'll get to this
     width: 1280,
     height: 720,
     bitrate: 1000000 //1 MBPS,
     framerate: 25
});

You can then start encoding frames. Here we assume we already have VideoFrame objects, and we make every 60th frame a Key Frame.

for (let i=0; i < frames.length; frames++){
    encoder.encode(frames[i], {keyFrame: i%60 ==0})
}

VideoDecoder

The Video Decoder does the reverse, turning EncodedVideoChunk objects into VideoFrame objects.

Here's a simplified example of how to set up the VideoDecoder. First, extract the EncodedVideoChunk objects and the decoder config from the video file. Here, we don't choose the config – the config was chosen by whoever encoded the file. When decoding, we extract the config from the file.

import { demuxVideo } from 'webcodecs-utils';

const {chunks, config} = await demuxVideo(<File> file);

Next, we set up the VideoDecoder by specifying the callback when VideoFrame objects are generated, and we configure it with the config.

const decoder = new VideoDecoder({
    output: function(frame: VideoFrame){
        //do something with the VideoFrame
    },
    error: function(e: any)=> console.warn(e);
});

decoder.configure(config)

Again, like with VideoEncoder, it returns frames in a callback. Finally we can start decoding chunks.

for (const chunk of chunks){
    decoder.decode(chunk);
}

Putting it all together

At its core, the WebCodecs API is just the two data types (EncodedVideoChunk, VideoFrame) and the VideoEncoder and VideoDecoder interfaces which convert between the two data types.

Keep in mind that the WebCodecs API doesn't actually work with video files. It only applies the encoding and decoding, and EncodedVideoChunk objects just represent binary data.

Reading video files and writing video files are their own, separate thing called muxing/demuxing.

Muxing and Demuxing

To write to a video file, you'll also need to mux the video. And to play a video file, you need to demux the video. This involves following the file format of the video container, parsing the video file (in the case of demuxing), or placing encoded video data in the right place in the file you are writing to (muxing).

Muxing and Demuxing are not included in the WebCodecs API, so you'll need to use a separate library to handle muxing and demuxing.

Demuxing

To play a video back in the browser, we need to both demux the video and decode the video, in that order.

There are several libraries you can use to demux videos, including MediaBunny or web-demuxer. For the purposes of this tutorial, I put a very simplified wrapper around these libraries and exposed it in the webcodecs-utils package, so that demuxing is a very simple 2-liner:

import { demuxVideo } from 'webcodecs-utils'
const {chunks, config} = await demuxVideo(file);

This reads the entire video into memory, so don't do this in practice. But it's helpful in making a simple, readable hello world for WebCodecs.

The following snippet will take in a video file (File object), decode it, and paint the result to a canvas. Here, we get the frames from the output callback, and run the draw calls directly from the callback.

import { demuxVideo } from 'webcodecs-utils'

async function playFile(file: File){

    const {chunks, config} = await demuxVideo(file);
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    const decoder = new VideoDecoder({
        output(frame: VideoFrame) {
            ctx.drawImage(frame, 0, 0);
            frame.close()
        },
        error(e) {}
    });


    decoder.configure(config);

    for (const chunk of chunks){
        decoder.decode(chunk)
    }

}

Here's our super barebones demo for playing back an actual video:

For a more 'correct' demuxing example, here is what demuxing looks like with MediaBunny, where you can extract chunks in an iterative fashion.

import { EncodedPacketSink, Input, ALL_FORMATS, BlobSource } from 'mediabunny';

const input = new Input({
  formats: ALL_FORMATS,
  source: new BlobSource(<File> file),
});

const videoTrack = await input.getPrimaryVideoTrack();
const sink = new EncodedPacketSink(videoTrack);

for await (const packet of sink.packets()) {
  const chunk = <EncodedVideoChunk> packet.toEncodedVideoChunk();
}

Muxing

To write a video file, you not only need to encode it (with the VideoEncoder) you also need to mux it. This involves taking the encoded chunks and placing them in the right place in the output binary file that you're writing to.

Again, you need a library to mux videos ( MediaBunny), but for demo purposes I created a super simple wrapper. Here we define a super basic ExampleMuxer.

import { ExampleMuxer } from 'webcodecs-utils'

const muxer = new ExampleMuxer('video');

for (const chunk of encodedChunks){
    muxer.addChunk(chunk);
}

const outputBlob = await muxer.finish();

As a full encoding + muxing demo, we'll create an encoder, and we'll set it to mux the output encoded chunks as soon as they are returned.

const encoder = new VideoEncoder({
    output: function(chunk, meta){
        muxer.addChunk(chunk, meta);
    },
    error: function(e){}
})

encoder.configure({
    'codec': 'avc1.4d0034', // We'll get to this
     width: 1280,
     height: 720,
     bitrate: 1000000 //1 MBPS,
     framerate: 25
});

We'll then define a canvas animation, which will draw the current frame number to the screen, just to prove it's working.

const canvas = new OffscreenCanvas(640, 360);
const ctx = canvas.getContext('2d');
const TOTAL_FRAMES=300;
let frameNumber = 0;
let chunksMuxed = 0;
const fps = 30;


function renderFrame(){
    ctx.fillStyle = '#000';
    ctx.fillRect(0, 0, canvas.width, canvas.height);
    ctx.fillStyle = 'white';
    ctx.font = `bold ${Math.min(canvas.width / 10, 72)}px Arial`;
    ctx.textAlign = 'center';
    ctx.textBaseline = 'middle';
    ctx.fillText(`Frame ${frameNumber}`, canvas.width / 2, canvas.height / 2);
}

Finally we'll create the encode loop, which will draw the current frame, and then encode it.

let flushed = false;

async function encodeLoop(){

    renderFrame();

    const frame = new VideoFrame(canvas, {timestamp: frameNumber/fps*1e6});
    encoder.encode(frame, {keyFrame: frameNumber %60 ===0});
    frame.close();

    frameNumber++;

    if(frameNumber === TOTAL_FRAMES) {
        if (!flushed) encoder.flush();
    }
    else return requestAnimationFrame(encodeLoop);
}

Putting it all together, you can encode the canvas animation to a video file with frame-level accuracy.

You can download the video and use any video inspection tool to verify that every single frame number is included.

This is one of the critical distinctions that separates this from other web APIs like MediaRecorder which can also encode video, but has no frame-level accuracy. WebCodecs makes sure that you can control and guarantee the consistency of each frame.

Finally, a proper full, muxing example using MediaBunny would look like this:

import {
  EncodedPacket,
  EncodedVideoPacketSource,
  BufferTarget,
  Mp4OutputFormat,
  Output
} from 'mediabunny';

async function muxChunks(chunks: EncodedVideoChunk[]): Promise <Blob>{

    const output = new Output({
        format: new Mp4OutputFormat(),
        target: new BufferTarget(),
    });

    const source = new EncodedVideoPacketSource('avc');
    output.addVideoTrack(source);

    await output.start();

    for (const chunk of chunks){
        source.add(EncodedPacket.fromEncodedChunk(chunk))
    }

    await output.finalize();
    const buffer = <ArrayBuffer> output.target.buffer;
    return new Blob([buffer], { type: 'video/mp4' });

});

Building a Video Converter Utility

Now that we've covered the basics of WebCodecs as well as Muxing, we'll move towards actually building an MVP of something useful: a video converter utility. We'll be able to use it to convert between mp4 and webm, and do some basic operations like resizing and flipping the video.

Transcoding

Before we do resizing and flipping, let's first handle a basic conversion decoding a video, and encoding the video to a new format. This is called transcoding.

To transcode video, we need to set up a pipeline with the following processes:

• Demuxing: Read EncodedVideoChunks from a video file

• Decoding: Convert EncodedVideoChunks to VideoFrames

• Encoding: Convert VideoFrames to new EncodedVideoChunks

• Muxing: Write the EncodedVideoChunks to a new video file

Our pipeline looks something like this:

Using everything we've covered in this article up until now, we could build a full working demo with just VideoEncoder and VideoDecoder as discussed. But then state management and tracking frames becomes complicated and error prone.

We're going to add one more abstraction, using the Streams API, which will make our pipeline look like the below. It ties directly to our mental model of our pipeline and simplifies a ton of details like state management.

const transcodePipeline = demuxerReader
    .pipeThrough(new VideoDecoderStream(videoDecoderConfig))
    .pipeThrough(new VideoEncoderStream(videoEncoderConfig))
    .pipeTo(createMuxerWriter(muxer));

await transcodePipeline;

To do this, we'll create a TransformStream for the VideoDecoder and VideoEncoder.

class VideoDecoderStream extends TransformStream<{ chunk: EncodedVideoChunk; index: number }, { frame: VideoFrame; index: number }> {
  constructor(config: VideoDecoderConfig) {
    let pendingIndices: number[] = [];
    super(
      {
        start(controller) {
          decoder = new VideoDecoder({
            output: (frame) => {
              const index = pendingIndices.shift()!;
              controller.enqueue({ frame, index });
            },
            error: (e) => controller.error(e),
          });

          decoder.configure(config);
        },

        async transform(item, controller) {
          pendingIndices.push(item.index);
          decoder.decode(item.chunk);
        },

        async flush(controller) {
          await decoder.flush();
          if decoder.state !== 'closed' decoder.close();
        },
      }
    );
  }
}

I won't bore you with the full code, but I've packaged these utilities in the webcodecs-utils package, which can be used as such:

import {
  SimpleDemuxer,
  VideoDecodeStream,
  VideoEncodeStream,
  SimpleMuxer,
} from "webcodecs-utils";

Our code for transcoding a file then becomes this:

const demuxer = new SimpleDemuxer(videoFile);
await demuxer.load();
const decoderConfig = await demuxer.getVideoDecoderConfig();

const encoderConfig = {/*Whatever we decide*/};

// Set up muxer
const muxer = new SimpleMuxer({ video: "avc" });

// Build the upscaling pipeline
await demuxer.videoStream()
  .pipeThrough(new VideoDecodeStream(decoderConfig))
  .pipeThrough(new VideoEncodeStream(encoderConfig))
  .pipeTo(muxer.videoSink());

// Get output
const blob = await muxer.finalize();

For this intermediate demo, just to actually get transcoding to work, we'll download a pre-built file, and we'll introduce a toggle to output an mp4 file (using h264) or a webm file (using vp9).

We'll use avc1.4d0034 for h264 (most widely supported h264 codec string) and vp09.00.40.08.00 for vp9 (most widely supported vp9 string).

Here's a basic transcoding demo on CodePen:

Transformations

If we want to do any kind of transformations to the video, like flips, crops, rotations, resizing, and so on, we can't just work with pure VideoFrame objects.

The simplest way to accomplish this would be to introduce a Canvas element, where we'll use a 2d Canvas Context to manipulate our source frame and draw that to a canvas.

const canvas = new OffscreenCanvas(width, height);
const ctx = canvas.getContext('2d');

// Very easy to do transformations
ctx.drawImage(sourceFrame, 0, 0);

We'll then use the Canvas as a source image for our output video frame.

const outFrame = new VideoFrame(canvas, {timestamp: sourceFrame.timestamp});

To apply a resize operation, we'll first set the canvas dimensions to our output height and width.

const canvas = new OffscreenCanvas(outputWidth, outputHeight);
const ctx = canvas.getContext('2d');

// Resize sourceFrame to fit output dimensions
ctx.drawImage(sourceFrame, 0, 0, outputWidth, outputHeight);

To apply a horizontal flip operation with canvas2d, we can do the following:

ctx.scale(-1, 1);
ctx.translate(-outputWidth, 0);
ctx.drawImage(sourceFrame, 0, 0, outputWidth, outputHeight);

You can create a full render function that applies these transformations which looks like this:

function render(videoFrame, outW, outH, flipped) {

  canvas.width  = outW;
  canvas.height = outH;

  if (flipped) {
    ctx.scale(-1, 1);
    ctx.translate(-outW, 0);
  }
  ctx.drawImage(videoFrame, 0, 0, outW, outH);

}

Here's an interactive demo of what these transformations look like:

Transform Pipeline

With these transformations, we need to adjust our pipeline to include a transformation step. It will take in a VideoFrame, apply the transforms, and return a transformed frame.

In the webcodecs-utils package, there is a VideoProcessStream object for this purpose, which takes in an async function which takes in a VideoFrame and returns a VideoFrame:

import { VideoProcessStream} from "webcodecs-utils";
 
new VideoProcessStream(async (frame) => {
      // Apply transformations
      return procesedFrame;
    }),

So to apply our transformations, we can set it up as so:

import { VideoProcessStream} from "webcodecs-utils";
 

const canvas = new OffscreenCanvas(outW, outH);
const ctx = canvas.getContext('2d');

const processStream = new VideoProcessStream(async (frame) => {
  
  if (flipped) {
    ctx.scale(-1, 1);
    ctx.translate(-outW, 0);
  }
  ctx.drawImage(frame, 0, 0, outW, outH);

  return new VideoFrame(canvas, {timestamp: frame.timestamp});

});

And then our full pipeline looks like this:

const demuxer = new SimpleDemuxer(videoFile);
await demuxer.load();
const decoderConfig = await demuxer.getVideoDecoderConfig();

const encoderConfig = {/*Whatever we decide*/};

// Set up muxer
const muxer = new SimpleMuxer({ video: "avc" });

// Build the upscaling pipeline
await demuxer.videoStream()
  .pipeThrough(new VideoDecodeStream(decoderConfig))
  .pipeThrough(processStream) // Just defined this
  .pipeThrough(new VideoEncodeStream(encoderConfig))
  .pipeTo(muxer.videoSink());

// Get output
const blob = await muxer.finalize();

Here's a full working demo with the process pipeline:

Complete Demo

Now, for the complete tool, we'll make some key changes:

• You can upload your own video

• We'll preview the transformations by extracting a frame

• We'll add progress measurement

For the input, that's trivial:

<input type="file" onchange="handler(event)" />

For frame previews, we could use WebCodecs to generate a preview, but because the preview doesn't need frame-level accuracy or high performance, it's easier to just use the HTML5 VideoElement to grab a video frame from the source file.

async function getFirstFrame(file) {
  const video = document.createElement("video");
  video.src = URL.createObjectURL(file);
  video.muted = true;

  await new Promise((resolve) => video.addEventListener("loadeddata", resolve, { once: true }));
  video.currentTime = 0;
  await new Promise((resolve) => video.addEventListener("seeked", resolve, { once: true }));

  return new VideoFrame(video, {timestamp: 0});
}

Finally, we can calculate progress in the process function by using the frame timestamp / the video duration.

const {duration} = await demuxer.getMediaInfo();


const processStream = new VideoProcessStream(async (frame) => {
  
  if (flipped) {
    ctx.scale(-1, 1);
    ctx.translate(-outW, 0);
  }
  ctx.drawImage(frame, 0, 0, outW, outH);

   // Frame timestamps are in microseconds, duration in seconds
  const progress = frame.timestamp/(duration*1e6); 

  return new VideoFrame(canvas, {timestamp: frame.timestamp});

});

Putting this all together, we can finally put together a full working video converter utility:

And that's it! We've built an MVP of something actually useful with WebCodecs 🎉, with Demuxing, Decoding, Canvas Transforms, Encoding, and Muxing.

The only difference between this and a full-fledged browser editing suite like Capcut is the scale and scope of transformations. But the video processing logic would be nearly identical.

Production Concerns

It's great that we've been able to create something useful, but before we wrap up, it's important to cover some production-level concerns.

Codecs

You might have noticed strings like vp09.00.10.08 in the demos, but I glossed over the details. We'll cover that now:

First, WebCodecs works with specific codec strings like vp09.00.10.08, not just 'vp9'. The following won't work:

const codec = VideoEncoder({
    codec: 'vp9', //This won't work!
    //...
})

As discussed previously, when decoding video, you don't really get a choice of codec. The video is already encoded, and so you need to get the codec from the video, as shown in the previous demos.

The demuxing libraries mentioned will identify the correct codec string, so you don't need to worry about that.

const decoderConfig = await demuxer.getVideoDecoderConfig();
//decoderConfig.codec = exact codec string for the video

When encoding a video, you can can choose your codec. Some people care a lot about codec choice, but from a very practical, pragmatic perspective, these rules of thumb should work for most developers:

• If the videos your app generates will be downloaded by users and/or you want to output mp4 files, use h264.

• If the videos generated are for internal use or you control video playback, and you don't care about format, use vp9 with webm (open source, better compression, most widely supported codec).

• For most apps, these two options will cover you — deeper codec selection is a rabbit hole you don't need to go down yet.

Once you have a codec family chosen, you need to choose a specific codec string such as avc1.42001f.

The other numbers in the string specify certain codec parameters which are not as important from a developer perspective. If your goal is maximum compatibility, here's your cheat sheet for what codec strings to use

h264 (for mp4 files)

• avc1.42001f - base profile, most compatible, supports up to 720p (99.6% support)

• avc1.4d0034 - main profile, level 5.2 (supports up to 4K) (98.9% support)

• avc1.42003e - base profile, level 6.2 (supports up to 8k) (86.8% support)

• avc1.64003e - high profile - level 6.2 (supports up to 8k) (85.9% support)

vp9 (for webm files)

• vp09.00.10.08.00 - basic, most compatible, level 1 (99.98% support)

• vp09.00.40.08.00 - level 4 (99.96% support)

• vp09.00.50.08.00 - level 5 (99.97% support)

• vp09.00.61.08.00 - level 6 (99.97% support)

You can also use the getCodecString function from the webcodecs-utils package:

import { getCodecString } from 'webcodecs-utils'

const codec_string = getCodecString('vp9', width, height, bitrate)

You can find a comprehensive list of what codecs and codec strings you can use in WebCodecs here.

Bit rate

On top of height and width (which you presumably know from your content) and a codec string (which we just discussed), you also need to specify a bit rate when encoding video.

Video Compression algorithms have a trade-off between quality and file size. You can have high quality video with big file sizes, or lower quality video with lower file sizes.

Here's a quick visualization of what different quality levels look like for a 1080p video encoded at different bit rates:

300 kbps

1 Mbps

3 Mbps

10 Mbps

Here's a quick lookup table for bitrate guidance:

You can also use this utility function in your own app as a quick approximation:

function getBitrate(width, height, fps, quality = 'good') {
    const pixels = width * height;

    const qualityFactors = {
      'low': 0.05,
      'good': 0.08,
      'high': 0.10,
      'very-high': 0.15
    };

    const factor = qualityFactors[quality] || qualityFactors['good'];

    // Returns bitrate in bits per second
    return pixels * fps * factor;
  }

The same function is also available in the webcodecs-utils package:

import { getBitrate } from 'webcodecs-utils'

GPU vs CPU

Most user devices have some type of graphics card (typically called integrated graphics). These are specialized chips with specific silicon architectures optimized for encoding and decoding video, as well as for basic graphics.

You might hear "GPU" and think AI data centers and gamers. But as far as web applications are concerned, almost everyone has a GPU.

This is important because while most frontend-development almost exclusively deals with the CPU, WebCodecs and video processing work primarily on the GPU.

Here's a quick guide for what kind of data is stored where:

There's a performance cost to moving data around, and this also becomes important for managing memory.

Memory

VideoFrame objects can be quite large – 30MB for a 4K video. A user's graphics card typically reserves some portion of RAM for "Video Memory" or "VRAM" which is where VideoFrame objects would be stored.

So if a user has 8GB of RAM, they would typically have 2GB of VRAM (how much is decided by the operating system).

If the amount of video data exceeds VRAM, your application will crash. This means that for a typical user, if you have more than 67 4K frames in memory (~2 seconds of video) the program will crash.

When VideoFrames are generated

VideoFrame objects are generated whenever you create a new VideoFrame(source) but also from the VideoDecoder, specifically the output callback. Every time a frame is generated, memory usage goes up.

How to remove VideoFrames

You can't rely on standard garbage collection for VideoFrame objects. You have to explicitly call close() on a frame when you're done:

frame.close()

In the Streams/Pipeline code and demo showed earlier, frames are actually being closed as soon as they are encoded in the VideoProcessStream and VideoEncodeStream interfaces.

The other reason Streams are helpful for WebCodecs is the highWaterMark property, which defaults to 10. What this means is that when you run:

await demuxer.videoStream()
  .pipeThrough(new VideoDecodeStream(decoderConfig))
  .pipeThrough(processStream) 
  .pipeThrough(new VideoEncodeStream(encoderConfig))
  .pipeTo(muxer.videoSink());

You ensure that no more than 10 video frames are in memory at any given time. The Streams API allows you to specify that limit while the browser itself deals with the logic of how to make that happen.

If you don't use the Streams API, you'll need to make sure you manage keeping track of memory limits and number of open video frames yourself.

Further Resources

Through this article we've gone over the basics of video processing, introduced the core concepts of the WebCodecs API, and built an MVP of a video converter utility. This is one of the simplest possible demos which actually touches all parts of the API. We also covered some basic production concerns.

This is just an introduction, and only scratches the surface of WebCodecs. For how simple the API looks, building a proper, production-ready WebCodecs application requires moving beyond hello-world demos.

To learn more about WebCodecs, you can check out MDN and the WebCodecsFundamentals, a comprehensive online textbook going much more in depth on WebCodecs.

You can also examine the source code of existing, production tested apps like Remotion Convert (source code) which is most similar to the demo app we covered, and Free AI Video Upscaler (source code, processing pipeline) which is the inspiration for the design patterns presented here and implemented in webcodecs-utils.

Finally, while WebCodecs is harder than it looks, you can make your life a lot easier by using a library like MediaBunny, which simplifies a lot of the details of things like memory management, file I/O, and other details. I use it in my own production WebCodecs applications.

Whether or not you actually build a full, production grade WebCodecs application, you now at least know that it's an option – one that's relatively new, provides better UX with lower server costs, and which is increasingly being adopted by prominent video applications like Capcut and Descript for its benefits.

But when you sit down to build a real SaaS application, you immediately hit a wall of unanswered questions. How do you structure your database? Where does authentication live? How do you make API calls type-safe? How do you handle payments without losing webhooks?

This handbook answers all of those questions. You'll build a production-ready SaaS application from scratch using TanStack Start, Elysia, Drizzle ORM, Neon PostgreSQL, Better Auth, Stripe, and Inngest.

By the end, you will have a deployed application with authentication, a type-safe API, database migrations, payment processing, and background jobs.

I chose this stack after building production applications with Next.js, Express, and Prisma. The combination of TanStack Start and Elysia with Eden Treaty gives you something rare: end-to-end type safety from your database schema to your React components, with zero code generation.

Change a column in your database, and TypeScript tells you everywhere that needs updating. That feedback loop changes how you build software.

Here's what you'll learn:

• How to set up a TanStack Start project with Vite and file-based routing

• How to configure a PostgreSQL database with Drizzle ORM and Neon

• How to build a type-safe API with Elysia embedded in your web app

• How to connect your frontend to your API with Eden Treaty

• How to add GitHub OAuth authentication with Better Auth

• How to build complete features using a repeatable four-layer pattern

• How to process payments with Stripe webhooks

• How to run reliable background jobs with Inngest

• How to deploy everything to Vercel with Neon

Why TanStack Start Instead of Next.js?

You might be wondering – why not just use Next.js? It's the default choice for full-stack React, and for good reason. Next.js pioneered server-side rendering, established conventions that shaped the React ecosystem, and has the largest community of any React framework.

But TanStack Start has three advantages that matter for this kind of project.

1. Deployment flexibility

TanStack Start compiles to standard JavaScript that runs anywhere: Node.js, Bun, Deno, Cloudflare Workers, AWS Lambda, or your own server. Next.js is notoriously difficult to self-host outside of Vercel.

If you search "Next.js Azure App Service container" or "Next.js ISR self-hosted," you'll find years of Stack Overflow questions about edge cases that only appear in production.

2. Simpler mental model

Next.js has grown complex: the App Router, React Server Components, Server Actions, partial prerendering, cache(), unstable_cache(), plus various rendering strategies.

TanStack Start uses full-document SSR with full hydration. There's no opaque server/client boundary confusion. The tradeoff is that you don't get RSC's granular streaming, but you gain clarity and predictability.

3. End-to-end type safety

Combined with Elysia and Eden Treaty, TanStack Start gives you compile-time type inference from your database to your UI. No code generation steps. No schema files to keep in sync.

TanStack Router itself provides fully type-safe routing with inferred path params, search params, and loader data.

This is a handbook, so it goes deep. Set aside a few hours, open your editor, and let's build something real.

Table of Contents

• Prerequisites

• How to Set Up the Project

• How to Configure the Database with Drizzle and Neon

• How to Build the API with Elysia

• How to Add Type-Safe API Calls with Eden Treaty

• How to Add Authentication with Better Auth

• How to Build a Complete Feature (The Four-Layer Pattern)

• How to Add Payments with Stripe

• How to Add Background Jobs with Inngest

• How to Deploy to Vercel with Neon

• Conclusion

Prerequisites

Before you start, make sure you have the following installed:

• Bun (v1.2 or later) for package management and running scripts

• Docker for running PostgreSQL locally

• Git for version control

• Basic knowledge of React and TypeScript

You'll also need free accounts on these services:

• Neon for your production PostgreSQL database

• Vercel for deployment

• GitHub for OAuth authentication (you will create an OAuth app)

• Stripe for payment processing (test mode is free)

All of these services have generous free tiers. You won't need to pay anything to follow this tutorial.

You should also be comfortable reading TypeScript code. This handbook assumes you understand generics, type inference, and async/await. If you're new to TypeScript, the official handbook is a solid starting point.

How to Set Up the Project

Start by creating a new TanStack Start project. TanStack provides a CLI that scaffolds a project with file-based routing, Vite, and server-side rendering out of the box.

bunx @tanstack/cli@latest create my-saas
cd my-saas
bun install

The CLI will ask you a few questions. Choose React as your framework and accept the defaults for the rest.

You're using Bun as your package manager and runtime. Bun is significantly faster than npm for installing dependencies and running scripts. It also natively supports TypeScript execution, which means you can run .ts files directly without a compilation step.

If you prefer npm or pnpm, the commands are similar, but this tutorial uses Bun throughout.

How to Understand the Project Structure

Before writing any code, let's look at how you'll organize this project. The key architectural decision is putting all library code under src/lib/. Each integration (database, auth, payments, and so on) gets its own directory with a clean public API through an index.ts file.

Here's the structure you'll build toward:

my-saas/
├── src/
│   ├── components/          # React components
│   ├── hooks/               # Custom React hooks
│   ├── lib/
│   │   ├── auth/            # Better Auth (server + client)
│   │   ├── db/              # Drizzle ORM + schema
│   │   ├── jobs/            # Inngest background jobs
│   │   └── payments/        # Stripe integration
│   ├── routes/              # TanStack file-based routing
│   ├── server/
│   │   ├── api.ts           # Elysia API definition
│   │   └── routes/          # API route modules
│   └── start.ts             # TanStack Start entry point
├── docker-compose.yml       # Local PostgreSQL + Neon proxy
├── drizzle.config.ts        # Drizzle Kit configuration
├── vite.config.ts           # Vite + TanStack Start config
└── package.json

Here's how all the pieces connect:

TanStack Start handles your frontend. It talks to an Elysia API server embedded in the same project. Elysia connects to three external services: Better Auth for authentication, Stripe for payments, and Inngest for background jobs. Below the API layer, Drizzle ORM provides type-safe database access to Neon PostgreSQL.

You'll build each layer one at a time, starting with the database.

This pattern keeps every integration isolated. When you need to change how authentication works, you go to src/lib/auth/. When you need to modify the database schema, you go to src/lib/db/. Nothing leaks across boundaries.

How to Configure Vite

TanStack Start runs on Vite. Your vite.config.ts needs the TanStack Start plugin, the React plugin, and path resolution for the @/ import alias:

// vite.config.ts
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import { defineConfig } from "vite";
import tsConfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  server: {
    port: 3000,
  },
  plugins: [
    tsConfigPaths({
      projects: ["./tsconfig.json"],
    }),
    tanstackStart(),
    viteReact(),
  ],
});

The tsConfigPaths plugin reads the paths setting from your tsconfig.json, so you can use @/lib/db instead of ../../lib/db throughout your code.

Add this to your tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

How to Install Dependencies

Install the core dependencies you'll need throughout this tutorial:

# Framework and routing
bun add @tanstack/react-router @tanstack/react-start react react-dom

# API layer
bun add elysia @elysiajs/eden

# Database
bun add drizzle-orm @neondatabase/serverless ws
bun add -d drizzle-kit

# Authentication
bun add better-auth

# Payments
bun add stripe

# Background jobs
bun add inngest

# Build tools
bun add -d @vitejs/plugin-react vite vite-tsconfig-paths typescript

Now you have a working TanStack Start project with all the dependencies you'll need. Start the dev server to make sure everything works:

bun run dev

Visit http://localhost:3000 and you should see your app running.

How to Configure the Database with Drizzle and Neon

Every SaaS needs a database. You'll use Drizzle ORM with Neon PostgreSQL. Drizzle gives you type-safe database queries that look like SQL, and Neon gives you a serverless PostgreSQL database that scales to zero when you aren't using it.

Why Drizzle Instead of Prisma?

If you have used an ORM in the TypeScript ecosystem before, it was probably Prisma. Prisma is excellent for many use cases, but it has a key limitation for this architecture: it uses code generation.

You write a .prisma schema file, run prisma generate, and Prisma generates a TypeScript client. That generation step adds friction to your development loop and creates artifacts you need to keep in sync.

Drizzle takes a different approach. Your schema is TypeScript. Your queries are TypeScript. Types are inferred at compile time without any generation step.

When you add a column to a table, the types update immediately. This fits perfectly with the rest of the stack, where types flow from Drizzle through Elysia to Eden Treaty without any intermediate steps.

Drizzle also produces SQL that looks like SQL. If you know PostgreSQL, you can read Drizzle queries. There is no Prisma-specific query language to learn.

How to Set Up Local PostgreSQL with Docker

For local development, you'll run PostgreSQL in Docker with a Neon-compatible proxy. This lets you use the same Neon serverless driver locally that you'll use in production.

Create a docker-compose.yml at the project root:

# docker-compose.yml
services:
  postgres:
    image: postgres:17
    container_name: my-saas-postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: my_saas
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  neon-proxy:
    image: ghcr.io/timowilhelm/local-neon-http-proxy:main
    container_name: my-saas-neon-proxy
    restart: unless-stopped
    environment:
      - PG_CONNECTION_STRING=postgres://postgres:postgres@postgres:5432/my_saas
    ports:
      - "4444:4444"
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:

The neon-proxy container is the important part. It translates HTTP requests into PostgreSQL wire protocol, which means your Neon serverless driver works locally without any code changes.

In production, Neon handles this translation on their infrastructure. Locally, you need this proxy to bridge the gap between the HTTP-based Neon driver and your plain PostgreSQL container.

The healthcheck on the PostgreSQL container ensures the proxy only starts after the database is ready. Without this, the proxy would try to connect to a database that's still initializing, causing connection errors on first startup.

Start the containers:

docker compose up -d

How to Define Your Schema

Create the database client and schema. Start with src/lib/db/index.ts for the connection:

// src/lib/db/index.ts
import { neon, neonConfig } from "@neondatabase/serverless";
import { drizzle } from "drizzle-orm/neon-http";
import ws from "ws";

import * as schema from "./schema";

const isProduction = process.env.NODE_ENV === "production";
const LOCAL_DB_HOST = "db.localtest.me";

let connectionString = process.env.DATABASE_URL;

if (!connectionString) {
  throw new Error("DATABASE_URL environment variable is not set");
}

neonConfig.webSocketConstructor = ws;

if (!isProduction) {
  connectionString = `postgres://postgres:postgres@${LOCAL_DB_HOST}:5432/my_saas`;
  neonConfig.fetchEndpoint = (host) => {
    const [protocol, port] =
      host === LOCAL_DB_HOST ? ["http", 4444] : ["https", 443];
    return `\({protocol}://\){host}:${port}/sql`;
  };
  neonConfig.useSecureWebSocket = false;
  neonConfig.wsProxy = (host) =>
    host === LOCAL_DB_HOST ? `\({host}:4444/v2` : `\){host}/v2`;
}

const client = neon(connectionString);
export const db = drizzle({ client, schema });

export * from "./schema";

The db.localtest.me hostname resolves to 127.0.0.1 and is the standard way to work with the local Neon proxy. In production, the Neon driver connects directly to your Neon database using the DATABASE_URL environment variable.

Now define your schema in src/lib/db/schema.ts. For a SaaS application, you need users, sessions, accounts (for OAuth), and a table for your core business entity. Here's a real production schema:

// src/lib/db/schema.ts
import {
  boolean,
  integer,
  pgEnum,
  pgTable,
  text,
  timestamp,
  varchar,
} from "drizzle-orm/pg-core";

export const purchaseTierEnum = pgEnum("purchase_tier", ["pro"]);
export const purchaseStatusEnum = pgEnum("purchase_status", [
  "completed",
  "partially_refunded",
  "refunded",
]);

export const users = pgTable("users", {
  id: text("id").primaryKey(),
  email: varchar("email", { length: 255 }).notNull().unique(),
  emailVerified: boolean("email_verified").notNull().default(false),
  name: text("name"),
  image: text("image"),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const sessions = pgTable("sessions", {
  id: text("id").primaryKey(),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  token: text("token").notNull().unique(),
  expiresAt: timestamp("expires_at").notNull(),
  ipAddress: text("ip_address"),
  userAgent: text("user_agent"),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const accounts = pgTable("accounts", {
  id: text("id").primaryKey(),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  accountId: text("account_id").notNull(),
  providerId: text("provider_id").notNull(),
  accessToken: text("access_token"),
  refreshToken: text("refresh_token"),
  accessTokenExpiresAt: timestamp("access_token_expires_at"),
  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
  scope: text("scope"),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const verifications = pgTable("verifications", {
  id: text("id").primaryKey(),
  identifier: text("identifier").notNull(),
  value: text("value").notNull(),
  expiresAt: timestamp("expires_at").notNull(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

export const purchases = pgTable("purchases", {
  id: text("id")
    .primaryKey()
    .$defaultFn(() => crypto.randomUUID()),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  stripeCheckoutSessionId: text("stripe_checkout_session_id")
    .notNull()
    .unique(),
  stripeCustomerId: text("stripe_customer_id"),
  stripePaymentIntentId: text("stripe_payment_intent_id"),
  tier: purchaseTierEnum("tier").notNull(),
  status: purchaseStatusEnum("status").notNull().default("completed"),
  amount: integer("amount").notNull(),
  currency: text("currency").notNull().default("usd"),
  purchasedAt: timestamp("purchased_at").notNull().defaultNow(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

// Type exports for use in your application
export type User = typeof users.$inferSelect;
export type NewUser = typeof users.$inferInsert;
export type Purchase = typeof purchases.$inferSelect;
export type NewPurchase = typeof purchases.$inferInsert;

Push the schema to create the tables:

bun run db:push

A few things to notice about this schema:

1. The users, sessions, accounts, and verifications tables are required by Better Auth. You'll configure the auth library to use these tables in the next section.

2. The purchases table is your core business entity. It tracks Stripe checkout sessions and links them to users.

3. Type exports like User and Purchase give you inferred TypeScript types from your schema. You never define types manually. They come from the schema definition.

4. The $defaultFn on the purchases.id column generates a UUID automatically when you insert a row. The auth tables use text IDs because Better Auth generates its own IDs.

How to Configure Drizzle Kit

Create drizzle.config.ts at the project root:

// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./src/lib/db/schema.ts",
  out: "./drizzle",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  verbose: true,
  strict: true,
});

Add these scripts to your package.json:

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:push": "drizzle-kit push",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio"
  }
}

Now push your schema to the local database:

bun run db:push

Drizzle Kit reads your schema file, compares it to the database, and applies any changes. For development, db:push is fast and convenient. For production, you'll use db:generate and db:migrate to create versioned SQL migration files.

You can open Drizzle Studio to inspect your database visually:

bun run db:studio

This opens a web UI at https://local.drizzle.studio where you can browse tables, run queries, and inspect data.

How to Build the API with Elysia

Here's where this stack gets interesting. Instead of running a separate API server, you embed Elysia directly inside TanStack Start. Both your web app and your API live in the same process, share the same types, and deploy as a single unit.

Why Elysia Instead of Express?

If you've built Node.js APIs before, you've probably used Express. It is 15 years old and has a massive ecosystem. But Express was designed before TypeScript, before async/await, and before developers expected type safety across the full stack.

Elysia takes a different approach. It was built for TypeScript from day one. Request bodies, response types, and path parameters are all inferred at compile time.

Combined with Eden Treaty (which you'll set up in the next section), your frontend gets full type safety when calling your API. No code generation. No OpenAPI schemas to keep in sync. Just TypeScript inference.

Elysia also includes built-in request validation using its t (TypeBox) schema builder:

import { Elysia, t } from "elysia";

new Elysia().post(
  "/users",
  ({ body }) => {
    // body is typed as { name: string, email: string }
    return createUser(body);
  },
  {
    body: t.Object({
      name: t.String(),
      email: t.String(),
    }),
  }
);

The schema validates at runtime and provides TypeScript types at compile time. One definition serves both purposes.

How to Define Your API

Create src/server/api.ts. This is where all your API routes live:

// src/server/api.ts
import { Elysia, t } from "elysia";
import { eq } from "drizzle-orm";

import { auth } from "@/lib/auth";
import { db, purchases, users } from "@/lib/db";

export const api = new Elysia({ prefix: "/api" })
  .onRequest(({ request }) => {
    console.log(`[API] \({request.method} \){request.url}`);
  })
  .onError(({ code, error, path }) => {
    console.error(`[API ERROR] \({code} on \){path}:`, error);
  })
  .get("/health", () => ({
    status: "ok",
    timestamp: new Date().toISOString(),
  }))
  .get("/me", async ({ request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    return { user: session.user };
  })
  .get("/payments/status", async ({ request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const purchase = await db
      .select()
      .from(purchases)
      .where(eq(purchases.userId, session.user.id))
      .limit(1);

    return {
      userId: session.user.id,
      purchase: purchase[0] ?? null,
    };
  });

export type Api = typeof api;

That last line is critical. export type Api = typeof api exports the full type signature of your API. Eden Treaty uses this type to generate a fully typed client on the frontend.

You'll see how that works shortly.

Notice the pattern for authenticated endpoints: call auth.api.getSession() with the request headers, check if the session exists, and return a 401 if it does not. This is straightforward and explicit. No decorators, no middleware magic.

The onRequest and onError hooks provide logging for every request. In production, you would replace these with structured logging to your observability platform.

How to Mount Elysia in TanStack Start

TanStack Start uses file-based routing. To handle all API requests with Elysia, create a catch-all route at src/routes/api.$.ts:

// src/routes/api.$.ts
import { createFileRoute } from "@tanstack/react-router";

import { api } from "../server/api";

const handler = ({ request }: { request: Request }) => api.fetch(request);

export const Route = createFileRoute("/api/$")({
  server: {
    handlers: {
      GET: handler,
      POST: handler,
      PUT: handler,
      PATCH: handler,
      DELETE: handler,
      OPTIONS: handler,
    },
  },
});

The $ in the filename is TanStack Router's wildcard syntax. This route matches any path starting with /api/, and the server.handlers object maps HTTP methods to your Elysia handler. Every request to /api/* gets forwarded to Elysia's fetch method.

This is the key architectural insight: Elysia is embedded inside TanStack Start. There is no separate API server. Your web app and API share the same process, the same port, and the same deployment.

This eliminates CORS issues, simplifies deployment, and means your API types are directly importable on the frontend.

Test your API by visiting http://localhost:3000/api/health. You should see:

{ "status": "ok", "timestamp": "2026-03-28T12:00:00.000Z" }

How to Add Type-Safe API Calls with Eden Treaty

Eden Treaty is Elysia's companion client library. It's an end-to-end type-safe HTTP client that mirrors your Elysia API's route structure as a JavaScript object. Instead of writing fetch("/api/users") and manually typing the response, you call api.api.users.get() and get full autocompletion, parameter validation, and return type inference, all derived from your server code at compile time with zero code generation.

This is what makes the stack special. Eden Treaty reads the type exported from your Elysia API and generates a fully typed client. Every endpoint, every parameter, every response shape is inferred at compile time.

How to Set Up the Treaty Client

Since Elysia is embedded in your TanStack Start app (same origin), you don't need to pass a URL to the Treaty client. You can create the client directly from the Elysia app instance for server-side usage and use a URL-based client for browser-side usage.

The simplest approach is to create a helper function that returns a treaty client:

// src/lib/treaty.ts
import { treaty } from "@elysiajs/eden";

import type { Api } from "@/server/api";

// For client-side usage, connect to the same origin
export const api = treaty<Api>(
  typeof window !== "undefined"
    ? window.location.origin
    : (process.env.BETTER_AUTH_URL ?? "http://localhost:3000")
);

Now you can use api anywhere in your application with full type safety:

// Calling GET /api/health
const { data } = await api.api.health.get();
// data is typed as { status: string, timestamp: string }

// Calling GET /api/me (authenticated)
const { data: me, error } = await api.api.me.get();
// data is typed as { user: { id: string, email: string, ... } }
// error is typed as { error: string } | null

Notice how the method chain mirrors your route structure. The /api/health endpoint becomes api.api.health.get(). Path segments become properties, and the HTTP method becomes the final function call.

This is all inferred from the type Api = typeof api export.

How Types Flow from Server to Client

Here's the full picture of how types flow through the stack:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Drizzle Schema  │     │    Elysia API    │     │   Eden Treaty   │
│  (schema.ts)     │────▶│   (api.ts)       │────▶│   (client)      │
│                  │     │                  │     │                  │
│  type User =     │     │  .get("/me",     │     │  api.api.me     │
│  typeof users    │     │    () => user)   │     │    .get()       │
│  .$inferSelect   │     │                  │     │    → { user }   │
└─────────────────┘     └─────────────────┘     └─────────────────┘

First, Drizzle infers TypeScript types from your table definitions. The User type comes from the users table schema.

Then Elysia uses those types in route handlers. When a handler returns { user: session.user }, Elysia captures the return type.

Finally, Eden Treaty reads the type Api = typeof api export and generates a client where every endpoint is fully typed.

If you add a field to your users table schema, Drizzle's inferred types update. If your Elysia handler returns that new field, Eden Treaty's client types update. If your React component accesses a field that no longer exists, TypeScript catches the error at compile time.

Zero code generation. Zero runtime overhead. Just TypeScript inference doing what it does best.

How to Handle Errors with Eden Treaty

Every Eden Treaty call returns a { data, error } tuple. This isn't a thrown exception. It's a discriminated union that forces you to handle both success and failure cases:

const { data, error } = await api.api.me.get();

if (error) {
  // error is typed based on what your Elysia handler can return
  console.error("Failed to fetch user:", error);
  return null;
}

// data is now narrowed to the success type
console.log(data.user.email);

This pattern eliminates the "forgot to handle the error" class of bugs that are common with fetch or Axios, where errors are thrown and easily missed. With Eden Treaty, the TypeScript compiler reminds you.

How to Use Eden Treaty in Route Loaders

TanStack Start routes have loader functions that run on the server during SSR and on the client during navigation. You can use Eden Treaty in these loaders to fetch data before the page renders:

// src/routes/_authenticated/dashboard.tsx
import { createFileRoute } from "@tanstack/react-router";

import { api } from "@/lib/treaty";

export const Route = createFileRoute("/_authenticated/dashboard")({
  loader: async () => {
    const { data } = await api.api.payments.status.get();
    return { purchase: data?.purchase ?? null };
  },
  component: DashboardPage,
});

function DashboardPage() {
  const { purchase } = Route.useLoaderData();

  return (
    <div>
      <h1>Dashboard</h1>
      {purchase ? (
        <p>Your plan: {purchase.tier}</p>
      ) : (
        <p>No active plan.</p>
      )}
    </div>
  );
}

The loader runs before the component renders, so the page never shows a loading spinner for its initial data. Route.useLoaderData() returns fully typed data based on what the loader returns. Change the loader's return type, and TypeScript catches mismatches in the component.

How to Add Authentication with Better Auth

Every SaaS needs authentication. In this tutorial, you'll use Better Auth with GitHub OAuth. Better Auth is a framework-agnostic auth library that works natively with Drizzle and has first-class support for TanStack Start.

How to Create a GitHub OAuth App

Before writing any code, create a GitHub OAuth application:

1. Go to GitHub Developer Settings

2. Click "New OAuth App"

3. Set the Homepage URL to http://localhost:3000

4. Set the Authorization callback URL to http://localhost:3000/api/auth/callback/github

5. Click "Register application"

6. Copy the Client ID and generate a Client Secret

Add these to a .env file at the project root:

# .env
DATABASE_URL=postgres://postgres:postgres@db.localtest.me:5432/my_saas
BETTER_AUTH_SECRET=your-random-32-character-string-here
BETTER_AUTH_URL=http://localhost:3000
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Generate a random secret for BETTER_AUTH_SECRET:

openssl rand -base64 32

How to Configure the Auth Server

Create src/lib/auth/index.ts. This is the server-side auth configuration:

// src/lib/auth/index.ts
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { tanstackStartCookies } from "better-auth/tanstack-start";

import * as schema from "@/lib/db";
import { db } from "@/lib/db";

const isDev = process.env.NODE_ENV !== "production";
const baseURL = process.env.BETTER_AUTH_URL ?? "http://localhost:3000";

export const auth = betterAuth({
  baseURL,
  database: drizzleAdapter(db, {
    provider: "pg",
    usePlural: true,
    schema: {
      users: schema.users,
      sessions: schema.sessions,
      accounts: schema.accounts,
      verifications: schema.verifications,
    },
  }),

  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID ?? "",
      clientSecret: process.env.GITHUB_CLIENT_SECRET ?? "",
    },
  },

  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7 days
    updateAge: 60 * 60 * 24,      // refresh daily
    cookieCache: {
      enabled: true,
      maxAge: 5 * 60, // 5 minutes
    },
  },

  trustedOrigins: isDev
    ? ["http://localhost:3000"]
    : [baseURL],

  plugins: [tanstackStartCookies()],
});

export type Auth = typeof auth;
export type Session = typeof auth.$Infer.Session;

Key details in this configuration:

• drizzleAdapter connects Better Auth to your Drizzle database. The usePlural: true option tells it your tables are named users (not user), sessions (not session), and so on.

• tanstackStartCookies() is a plugin that handles cookie management for TanStack Start's SSR. Without this, sessions won't persist correctly during server-side rendering.

• cookieCache stores session data in the cookie for 5 minutes, reducing database lookups on every request.

How to Configure the Auth Client

Create src/lib/auth/client.ts for the browser-side auth client:

// src/lib/auth/client.ts
import { createAuthClient } from "better-auth/react";

export const authClient = createAuthClient({
  baseURL: "",
});

export const { signIn, signOut, useSession } = authClient;

The baseURL is an empty string because Elysia is embedded in your TanStack Start app. Auth requests go to /api/auth/* on the same origin. No separate auth server needed.

How to Mount Auth Routes

Better Auth needs to handle requests at /api/auth/*. Since Elysia handles all /api/* routes, you mount Better Auth's handler inside Elysia.

Add this to your src/server/api.ts:

// In src/server/api.ts, add Better Auth's handler
export const api = new Elysia({ prefix: "/api" })
  // Mount Better Auth to handle /api/auth/* routes
  .mount(auth.handler)
  // ... rest of your routes

The .mount(auth.handler) call tells Elysia to forward any request matching Better Auth's routes to the auth handler. This covers login, logout, session management, and OAuth callbacks.

How to Protect Routes

TanStack Start uses layout routes to protect groups of pages. Create src/routes/_authenticated.tsx:

// src/routes/_authenticated.tsx
import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
import { createServerFn } from "@tanstack/react-start";
import { getRequestHeaders } from "@tanstack/react-start/server";

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

const getCurrentUser = createServerFn().handler(async () => {
  const rawHeaders = getRequestHeaders();
  const headers = new Headers(rawHeaders as HeadersInit);
  const session = await auth.api.getSession({ headers });
  return session?.user ?? null;
});

export const Route = createFileRoute("/_authenticated")({
  beforeLoad: async ({ location }) => {
    const user = await getCurrentUser();

    if (!user) {
      throw redirect({
        to: "/login",
        search: { redirect: location.pathname },
      });
    }

    return { user };
  },
  component: AuthenticatedLayout,
});

function AuthenticatedLayout() {
  return <Outlet />;
}

The _authenticated prefix (with underscore) makes this a layout route in TanStack Router. Any route nested inside src/routes/_authenticated/ will run the beforeLoad check first. If the user isn't logged in, they get redirected to /login with a redirect parameter so they return to the original page after signing in.

The createServerFn runs on the server during SSR. It reads the request cookies, checks for a valid session, and returns the user. This means your auth check happens server-side before any HTML is sent to the browser.

Now any file you create under src/routes/_authenticated/ is automatically protected. For example, src/routes/_authenticated/dashboard.tsx requires authentication.

How to Build the Login Page

Create a login page at src/routes/login.tsx:

// src/routes/login.tsx
import { createFileRoute } from "@tanstack/react-router";
import { useState } from "react";
import { z } from "zod";

import { signIn } from "@/lib/auth/client";

const searchSchema = z.object({
  redirect: z.string().optional(),
});

export const Route = createFileRoute("/login")({
  validateSearch: searchSchema,
  component: LoginPage,
});

function LoginPage() {
  const { redirect: redirectTo } = Route.useSearch();
  const [isLoading, setIsLoading] = useState(false);

  const handleGitHubLogin = async () => {
    setIsLoading(true);
    const callbackURL = redirectTo
      ? `\({window.location.origin}\){redirectTo}`
      : `${window.location.origin}/dashboard`;

    await signIn.social({
      provider: "github",
      callbackURL,
    });
  };

  return (
    <div className="flex min-h-screen items-center justify-center">
      <div className="w-full max-w-md rounded-lg border p-8">
        <h1 className="mb-6 text-2xl font-bold">Sign In</h1>
        <button
          onClick={handleGitHubLogin}
          disabled={isLoading}
          className="w-full rounded-md bg-gray-900 px-4 py-3 text-white"
        >
          {isLoading ? "Signing in..." : "Sign in with GitHub"}
        </button>
      </div>
    </div>
  );
}

TanStack Router's validateSearch validates query parameters with Zod. The redirect parameter is typed as an optional string, and Route.useSearch() returns a type-safe object. No manual parsing needed.

How to Add Login Redirect Middleware

You also want to redirect authenticated users away from the login page. Create the entry point at src/start.ts:

// src/start.ts
import { redirect } from "@tanstack/react-router";
import { createMiddleware, createStart } from "@tanstack/react-start";
import { getRequestHeaders, getRequestUrl } from "@tanstack/react-start/server";

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

const authMiddleware = createMiddleware({ type: "request" }).server(
  async ({ next }) => {
    const rawHeaders = getRequestHeaders();
    const headers = new Headers(rawHeaders as HeadersInit);
    const url = getRequestUrl();

    if (url.pathname !== "/login") {
      return next();
    }

    const session = await auth.api.getSession({ headers });

    if (session?.user) {
      const redirectTo = url.searchParams.get("redirect");
      throw redirect({
        to: redirectTo || "/dashboard",
      });
    }

    return next();
  }
);

export const startInstance = createStart(() => ({
  requestMiddleware: [authMiddleware],
}));

This middleware runs on every request. If the user is already authenticated and visits /login, they get redirected to the dashboard (or to whatever page they originally wanted to reach).

How to Build a Complete Feature (The Four-Layer Pattern)

Now that you have a database, API, type-safe client, and authentication, it's time to build a real feature. Every feature in this architecture follows the same four-layer pattern:

Once you understand this pattern, adding features becomes mechanical. Let's walk through building a complete purchase status feature that lets authenticated users check their purchase history.

Layer 1: Schema

You already defined the purchases table in your schema earlier. For reference:

// src/lib/db/schema.ts
export const purchases = pgTable("purchases", {
  id: text("id")
    .primaryKey()
    .$defaultFn(() => crypto.randomUUID()),
  userId: text("user_id")
    .notNull()
    .references(() => users.id, { onDelete: "cascade" }),
  stripeCheckoutSessionId: text("stripe_checkout_session_id")
    .notNull()
    .unique(),
  stripeCustomerId: text("stripe_customer_id"),
  stripePaymentIntentId: text("stripe_payment_intent_id"),
  tier: purchaseTierEnum("tier").notNull(),
  status: purchaseStatusEnum("status").notNull().default("completed"),
  amount: integer("amount").notNull(),
  currency: text("currency").notNull().default("usd"),
  purchasedAt: timestamp("purchased_at").notNull().defaultNow(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
  updatedAt: timestamp("updated_at").notNull().defaultNow(),
});

If you're adding a new feature, this is where you start. Define the table, run bun run db:push, and move to Layer 2.

Layer 2: API

Create an API route module at src/server/routes/purchases.ts:

// src/server/routes/purchases.ts
import { eq } from "drizzle-orm";
import { Elysia } from "elysia";

import { auth } from "@/lib/auth";
import { db, purchases } from "@/lib/db";

export const purchasesRoute = new Elysia({ prefix: "/purchases" })
  .get("/status", async ({ request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session?.user) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const purchase = await db
      .select()
      .from(purchases)
      .where(eq(purchases.userId, session.user.id))
      .limit(1);

    return purchase[0] ?? null;
  });

Then register this route module in your main API file:

// src/server/api.ts
import { purchasesRoute } from "./routes/purchases";

export const api = new Elysia({ prefix: "/api" })
  .mount(auth.handler)
  .use(purchasesRoute)
  // ... other routes

The .use() method composes Elysia instances. Each route module is an independent Elysia instance with its own prefix, and use merges them into the main app. Eden Treaty sees the full composed type, so your client automatically knows about the new endpoints.

Layer 3: Hooks

Create a custom hook that connects your React components to the API:

// src/hooks/use-purchase-status.ts
import { useQuery } from "@tanstack/react-query";

import { api } from "@/lib/treaty";

export function usePurchaseStatus() {
  return useQuery({
    queryKey: ["purchase-status"],
    queryFn: async () => {
      const { data, error } = await api.api.purchases.status.get();
      if (error) throw new Error("Failed to fetch purchase status");
      return data;
    },
  });
}

TanStack Query handles caching, refetching, loading states, and error states. The queryKey identifies this data in the cache. If multiple components call usePurchaseStatus(), only one network request is made.

For mutations (creating, updating, or deleting data), use useMutation:

// src/hooks/use-checkout.ts
import { useMutation } from "@tanstack/react-query";

import { api } from "@/lib/treaty";

export function useCheckout() {
  return useMutation({
    mutationFn: async () => {
      const { data, error } = await api.api.payments.checkout.post();
      if (error) throw new Error("Failed to create checkout session");
      return data;
    },
    onSuccess: (data) => {
      // Redirect to Stripe Checkout
      if (data?.url) {
        window.location.href = data.url;
      }
    },
  });
}

Layer 4: UI

Use the hooks in your React components:

// src/components/purchase-status.tsx
import { usePurchaseStatus } from "@/hooks/use-purchase-status";

export function PurchaseStatus() {
  const { data: purchase, isLoading, error } = usePurchaseStatus();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Failed to load purchase status.</div>;
  }

  if (!purchase) {
    return (
      <div className="rounded-lg border p-6">
        <h2 className="text-lg font-semibold">No Active Purchase</h2>
        <p className="mt-2 text-gray-600">
          You have not purchased a plan yet.
        </p>
      </div>
    );
  }

  return (
    <div className="rounded-lg border p-6">
      <h2 className="text-lg font-semibold">
        {purchase.tier.charAt(0).toUpperCase() + purchase.tier.slice(1)} Plan
      </h2>
      <p className="mt-2 text-gray-600">
        Status: {purchase.status}
      </p>
      <p className="text-sm text-gray-500">
        Purchased on{" "}
        {new Date(purchase.purchasedAt).toLocaleDateString()}
      </p>
    </div>
  );
}

That's the complete four-layer pattern. The schema defines the data. The API exposes it. Hooks connect React to the API. The UI renders the result. Every feature you add follows these same four steps.

How the Layers Connect

Here's the full picture of how data flows through the four layers for a read operation:

User clicks "Dashboard"
  → TanStack Router triggers the route loader
    → Loader calls api.api.purchases.status.get() via Eden Treaty
      → Elysia receives GET /api/purchases/status
        → Handler calls auth.api.getSession() to verify the user
        → Handler queries db.select().from(purchases) via Drizzle
        → Handler returns { purchase } with inferred types
      → Eden Treaty receives typed response
    → Loader returns typed data
  → Component renders with Route.useLoaderData()

For a write operation (creating a new resource), the flow is similar but uses a mutation:

User clicks "Buy Now"
  → onClick calls checkout.mutate() from useMutation hook
    → mutationFn calls api.api.payments.checkout.post() via Eden Treaty
      → Elysia receives POST /api/payments/checkout
        → Handler creates a Stripe checkout session
        → Handler returns { url }
      → Eden Treaty receives typed response
    → onSuccess redirects to Stripe Checkout

How to Add a Second Feature

To cement the pattern, let's walk through adding a user profile update feature. This shows all four layers for a write operation.

Layer 1: Schema. The users table already has a name field you can update. No schema change needed.

Layer 2: API. Add a PATCH endpoint:

// In src/server/api.ts
.patch(
  "/me",
  async ({ request, body, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const [updatedUser] = await db
      .update(users)
      .set({
        name: body.name,
        updatedAt: new Date(),
      })
      .where(eq(users.id, session.user.id))
      .returning();

    return { user: updatedUser };
  },
  {
    body: t.Object({
      name: t.String({ minLength: 1, maxLength: 100 }),
    }),
  },
)

The body option validates the request body at runtime and provides TypeScript types at compile time. If someone sends a request without a name field, Elysia returns a 400 error automatically. You don't write any validation logic yourself.

Layer 3: Hooks. Create a mutation hook:

// src/hooks/use-update-profile.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";

import { api } from "@/lib/treaty";

export function useUpdateProfile() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (data: { name: string }) => {
      const { data: result, error } = await api.api.me.patch(data);
      if (error) throw new Error("Failed to update profile");
      return result;
    },
    onSuccess: () => {
      // Invalidate any queries that depend on user data
      queryClient.invalidateQueries({ queryKey: ["me"] });
    },
  });
}

The onSuccess callback invalidates the cache for user-related queries. This means any component displaying user data will automatically refetch and show the updated name.

Layer 4: UI. Use the hook in a form component:

// src/components/profile-form.tsx
import { useState } from "react";

import { useUpdateProfile } from "@/hooks/use-update-profile";

export function ProfileForm({ currentName }: { currentName: string }) {
  const [name, setName] = useState(currentName);
  const updateProfile = useUpdateProfile();

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    updateProfile.mutate({ name });
  };

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="name" className="block text-sm font-medium">
        Display Name
      </label>
      <input
        id="name"
        type="text"
        value={name}
        onChange={(e) => setName(e.target.value)}
        className="mt-1 block w-full rounded-md border px-3 py-2"
      />
      <button
        type="submit"
        disabled={updateProfile.isPending}
        className="mt-4 rounded-md bg-blue-600 px-4 py-2 text-white"
      >
        {updateProfile.isPending ? "Saving..." : "Save"}
      </button>
      {updateProfile.isError && (
        <p className="mt-2 text-sm text-red-600">
          Failed to update profile. Please try again.
        </p>
      )}
    </form>
  );
}

Four layers, second feature. The pattern is identical every time.

The pattern is deliberately repetitive. Repetition is a feature, not a bug. When every feature follows the same structure, you always know where to look.

New code goes in predictable places. And if you use an AI coding assistant, it can learn this pattern from your codebase and generate all four layers for new features.

How to Add Payments with Stripe

Most SaaS applications need to collect payments. You'll integrate Stripe for one-time purchases using Stripe Checkout. The key architectural decision is handling webhooks reliably using background jobs, which you'll add in the next section.

How to Set Up Stripe

Create src/lib/payments/index.ts:

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

let stripeClient: Stripe | null = null;

function getStripe(): Stripe {
  if (!stripeClient) {
    const secretKey = process.env.STRIPE_SECRET_KEY;
    if (!secretKey) {
      throw new Error(
        "STRIPE_SECRET_KEY is not set. Payment functionality is unavailable."
      );
    }
    stripeClient = new Stripe(secretKey);
  }
  return stripeClient;
}

// Lazy-initialized proxy so imports don't crash without env vars
export const stripe = new Proxy({} as Stripe, {
  get(_, prop) {
    return Reflect.get(getStripe(), prop);
  },
});

export async function createOneTimeCheckoutSession(params: {
  priceId: string;
  successUrl: string;
  cancelUrl: string;
  metadata: Record<string, string>;
  customerEmail?: string;
  couponId?: string;
}) {
  const client = getStripe();

  const session = await client.checkout.sessions.create({
    mode: "payment",
    line_items: [{ price: params.priceId, quantity: 1 }],
    success_url: params.successUrl,
    cancel_url: params.cancelUrl,
    metadata: params.metadata,
    ...(params.customerEmail && {
      customer_email: params.customerEmail,
    }),
    ...(params.couponId
      ? { discounts: [{ coupon: params.couponId }] }
      : { allow_promotion_codes: true }),
  });

  return session;
}

export async function retrieveCheckoutSession(sessionId: string) {
  const client = getStripe();
  return client.checkout.sessions.retrieve(sessionId);
}

export async function constructWebhookEvent(
  payload: string | Buffer,
  signature: string
) {
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
  if (!webhookSecret) {
    throw new Error("STRIPE_WEBHOOK_SECRET is not set");
  }
  const client = getStripe();
  return client.webhooks.constructEventAsync(payload, signature, webhookSecret);
}

The Proxy pattern for the Stripe client is a production technique. It lazily initializes the Stripe SDK so your module can be imported without crashing if the STRIPE_SECRET_KEY environment variable is missing. This is useful during builds and in environments where not every service is configured.

How to Create the Checkout Endpoint

Add a checkout endpoint to your API:

// In src/server/api.ts
.post("/payments/checkout", async ({ set }) => {
  const priceId = process.env.STRIPE_PRO_PRICE_ID;

  if (!priceId) {
    set.status = 500;
    return { error: "Price not configured" };
  }

  const baseUrl = process.env.BETTER_AUTH_URL ?? "http://localhost:3000";

  const checkoutSession = await createOneTimeCheckoutSession({
    priceId,
    successUrl: `${baseUrl}/dashboard?purchase=success&session_id={CHECKOUT_SESSION_ID}`,
    cancelUrl: `${baseUrl}/pricing`,
    metadata: { tier: "pro" },
  });

  return { url: checkoutSession.url };
})

The {CHECKOUT_SESSION_ID} placeholder is a Stripe template variable. Stripe replaces it with the actual session ID when redirecting the user back to your app.

How to Handle Webhooks

Stripe sends webhook events when payments are processed. Your webhook handler needs to verify the signature, parse the event, and process it.

Here's the critical design decision: don't do heavy processing inside the webhook handler. Stripe expects a response within a few seconds. If your handler takes too long, Stripe will retry the webhook, potentially causing duplicate processing.

Instead, use the "webhook receives, background job processes" pattern:

// In src/server/api.ts
.post("/payments/webhook", async ({ request, set }) => {
  const body = await request.text();
  const sig = request.headers.get("stripe-signature");

  if (!sig) {
    set.status = 400;
    return { error: "Missing signature" };
  }

  try {
    const event = await constructWebhookEvent(body, sig);
    console.log(`[Webhook] Received ${event.type}`);

    if (event.type === "charge.refunded") {
      const charge = event.data.object as {
        id: string;
        payment_intent: string;
        amount: number;
        amount_refunded: number;
        currency: string;
      };
      await inngest.send({
        name: "stripe/charge.refunded",
        data: {
          chargeId: charge.id,
          paymentIntentId: charge.payment_intent,
          amountRefunded: charge.amount_refunded,
          originalAmount: charge.amount,
          currency: charge.currency,
        },
      });
    }

    return { received: true };
  } catch (error) {
    console.error("[Webhook] Stripe verification failed:", error);
    set.status = 400;
    return { error: "Webhook verification failed" };
  }
})

The webhook handler does three things: verifies the signature, identifies the event type, and forwards the data to Inngest for background processing. It responds immediately with { received: true }. The actual business logic (sending emails, granting access, updating records) happens in the background job, which you'll build next.

How to Claim Purchases on the Frontend

After a successful checkout, Stripe redirects the user back to your app with a session ID. You need an endpoint that claims the purchase by verifying the session and creating a database record:

// In src/server/api.ts
.post(
  "/purchases/claim",
  async ({ body, request, set }) => {
    const session = await auth.api.getSession({
      headers: request.headers,
    });

    if (!session) {
      set.status = 401;
      return { error: "Unauthorized" };
    }

    const { sessionId } = body;

    // Check if already claimed (idempotency)
    const existing = await db
      .select()
      .from(purchases)
      .where(eq(purchases.stripeCheckoutSessionId, sessionId))
      .limit(1);

    if (existing[0]) {
      return { success: true, alreadyClaimed: true, tier: existing[0].tier };
    }

    // Verify payment with Stripe
    const stripeSession = await retrieveCheckoutSession(sessionId);

    if (stripeSession.payment_status !== "paid") {
      set.status = 400;
      return { error: "Payment not completed" };
    }

    const tier = (stripeSession.metadata?.tier ?? "pro") as "pro";

    // Create purchase record
    await db.insert(purchases).values({
      userId: session.user.id,
      stripeCheckoutSessionId: sessionId,
      stripeCustomerId:
        typeof stripeSession.customer === "string"
          ? stripeSession.customer
          : stripeSession.customer?.id ?? null,
      stripePaymentIntentId:
        typeof stripeSession.payment_intent === "string"
          ? stripeSession.payment_intent
          : stripeSession.payment_intent?.id ?? null,
      tier,
      status: "completed",
      amount: stripeSession.amount_total ?? 0,
      currency: stripeSession.currency ?? "usd",
    });

    // Trigger background processing
    await inngest.send({
      name: "purchase/completed",
      data: {
        userId: session.user.id,
        tier,
        sessionId,
      },
    });

    return { success: true, tier };
  },
  {
    body: t.Object({
      sessionId: t.String(),
    }),
  }
)

Notice the idempotency check at the top. If the user refreshes the success page or the frontend retries the claim request, the endpoint returns the existing purchase instead of creating a duplicate.

This is essential for payment flows. You never want to accidentally charge someone twice or create duplicate records.

The inngest.send() call triggers background processing for the purchase. That's where you send confirmation emails, grant access to resources, track analytics events, and perform any other post-purchase work.

How to Test Payments Locally

Install the Stripe CLI and forward webhooks to your local server:

# Install Stripe CLI (macOS)
brew install stripe/stripe-cli/stripe

# Login to Stripe
stripe login

# Forward webhooks to your local server
stripe listen --forward-to localhost:3000/api/payments/webhook

The Stripe CLI gives you a webhook signing secret that starts with whsec_. Add it to your .env:

STRIPE_WEBHOOK_SECRET=whsec_your-local-webhook-secret

Create a test product and price in your Stripe dashboard (or use the Stripe CLI), then add the price ID to your .env:

STRIPE_SECRET_KEY=sk_test_your-test-secret-key
STRIPE_PRO_PRICE_ID=price_your-test-price-id

How to Add Background Jobs with Inngest

Background jobs are critical for any SaaS. You use them for processing webhooks, sending emails, granting access to resources, and any work that shouldn't block your API response. Inngest provides durable, retry-able functions with built-in checkpointing.

Why Background Jobs Matter

Consider what happens when someone purchases your SaaS product:

1. Verify the payment with Stripe

2. Create a purchase record in the database

3. Send a confirmation email to the customer

4. Send a notification email to the admin

5. Grant access to a private GitHub repository

6. Track the purchase event in your analytics platform

7. Schedule a follow-up email sequence

If you try to do all of this inside an API endpoint, several things can go wrong. The email service might be down. The GitHub API might rate-limit you. Your analytics call might time out.

Any failure means the user sees an error, and you have to figure out which steps completed and which did not.

Inngest solves this with durable execution. Each step is checkpointed. If step 3 fails, Inngest retries step 3 without re-running steps 1 and 2.

If the entire function fails, Inngest retries the whole thing. You get at-least-once execution with automatic deduplication.

How to Set Up Inngest

Create the Inngest client at src/lib/jobs/client.ts:

// src/lib/jobs/client.ts
import { Inngest } from "inngest";

export const inngest = new Inngest({
  id: "my-saas",
});

How to Write Your First Inngest Function

Create src/lib/jobs/functions/stripe.ts with the purchase completion handler:

// src/lib/jobs/functions/stripe.ts
import { eq } from "drizzle-orm";

import { inngest } from "../client";
import { db, purchases, users } from "@/lib/db";

export const handlePurchaseCompleted = inngest.createFunction(
  {
    id: "purchase-completed",
    triggers: [{ event: "purchase/completed" }],
  },
  async ({ event, step }) => {
    const { userId, tier, sessionId } = event.data as {
      userId: string;
      tier: string;
      sessionId: string;
    };

    // Step 1: Look up user and purchase details
    const { user, purchase } = await step.run(
      "lookup-user-and-purchase",
      async () => {
        const userResult = await db
          .select({
            id: users.id,
            email: users.email,
            name: users.name,
          })
          .from(users)
          .where(eq(users.id, userId))
          .limit(1);

        const foundUser = userResult[0];
        if (!foundUser) {
          throw new Error(`User not found: ${userId}`);
        }

        const purchaseResult = await db
          .select({
            amount: purchases.amount,
            currency: purchases.currency,
          })
          .from(purchases)
          .where(eq(purchases.stripeCheckoutSessionId, sessionId))
          .limit(1);

        return {
          user: foundUser,
          purchase: purchaseResult[0] ?? {
            amount: 0,
            currency: "usd",
          },
        };
      }
    );

    // Step 2: Send purchase confirmation email
    await step.run("send-purchase-confirmation", async () => {
      // Send email using your email service (Resend, SendGrid, and so on)
      console.log(
        `Sending purchase confirmation to ${user.email}`
      );
      // await sendEmail({
      //   to: user.email,
      //   subject: "Your purchase is confirmed!",
      //   template: PurchaseConfirmationEmail,
      // });
    });

    // Step 3: Send admin notification
    await step.run("send-admin-notification", async () => {
      const adminEmail = process.env.ADMIN_EMAIL;
      if (!adminEmail) return;

      console.log(
        `Notifying admin about purchase from ${user.email}`
      );
      // await sendEmail({
      //   to: adminEmail,
      //   subject: `New sale: ${user.email}`,
      //   template: AdminNotificationEmail,
      // });
    });

    // Step 4: Update purchase record
    await step.run("update-purchase-record", async () => {
      await db
        .update(purchases)
        .set({ updatedAt: new Date() })
        .where(eq(purchases.stripeCheckoutSessionId, sessionId));
    });

    return { success: true, userId, tier };
  }
);

export const stripeFunctions = [handlePurchaseCompleted];

Each step.run() is a checkpoint. If the function fails after step 2, Inngest retries from step 3, not from the beginning. The results of completed steps are cached.

How to Register Your Functions

Create an index file that collects all your functions:

// src/lib/jobs/functions/index.ts
import { stripeFunctions } from "./stripe";

export const functions = [...stripeFunctions];

And a barrel export:

// src/lib/jobs/index.ts
export { inngest } from "./client";
export { functions } from "./functions";

How to Connect Inngest to Your API

Mount the Inngest handler in your Elysia API. Add this to src/server/api.ts:

// src/server/api.ts
import { serve } from "inngest/bun";

import { inngest, functions } from "@/lib/jobs";

const inngestHandler = serve({
  client: inngest,
  functions,
});

export const api = new Elysia({ prefix: "/api" })
  // Inngest endpoint - handles function registration and execution
  .all("/inngest", async (ctx) => {
    return inngestHandler(ctx.request);
  })
  // ... rest of your routes

The .all("/inngest") route handles both GET (for function registration) and POST (for function execution) requests from Inngest.

How to Run Inngest Locally

Inngest provides a dev server that runs locally and provides a dashboard for monitoring your functions:

npx inngest-cli@latest dev -u http://localhost:3000/api/inngest --no-discovery

This starts the Inngest dev server at http://localhost:8288. Open that URL in your browser to see a dashboard showing your registered functions, event history, and function execution logs.

The -u flag tells Inngest where your app is running. The --no-discovery flag disables automatic app discovery, which is more reliable for local development.

Add this as a script in your package.json:

{
  "scripts": {
    "inngest:dev": "npx inngest-cli@latest dev -u http://localhost:3000/api/inngest --no-discovery"
  }
}

Now you can trigger your functions by sending events from your API:

await inngest.send({
  name: "purchase/completed",
  data: {
    userId: "user_123",
    tier: "pro",
    sessionId: "cs_test_abc",
  },
});

The event appears in the Inngest dashboard, the function executes step by step, and you can see the output of each step. If a step fails, you can retry it manually from the dashboard.

How to Handle Refunds with Background Jobs

Here's a more complex example that shows why durable execution matters. When processing a refund, you need to update the purchase status, revoke access, send notifications, and track analytics. If any step fails, the others should still complete:

// src/lib/jobs/functions/stripe.ts
export const handleRefund = inngest.createFunction(
  {
    id: "refund-processed",
    triggers: [{ event: "stripe/charge.refunded" }],
  },
  async ({ event, step }) => {
    const { paymentIntentId, amountRefunded, originalAmount, currency } =
      event.data as {
        chargeId: string;
        paymentIntentId: string;
        amountRefunded: number;
        originalAmount: number;
        currency: string;
      };

    const isFullRefund = amountRefunded >= originalAmount;

    // Step 1: Find the purchase and user
    const { user, purchase } = await step.run(
      "lookup-purchase",
      async () => {
        const purchaseResult = await db
          .select()
          .from(purchases)
          .where(eq(purchases.stripePaymentIntentId, paymentIntentId))
          .limit(1);

        if (!purchaseResult[0]) {
          return { user: null, purchase: null };
        }

        const userResult = await db
          .select()
          .from(users)
          .where(eq(users.id, purchaseResult[0].userId))
          .limit(1);

        return {
          user: userResult[0] ?? null,
          purchase: purchaseResult[0],
        };
      }
    );

    if (!purchase || !user) {
      return { success: false, reason: "no_matching_purchase" };
    }

    // Step 2: Update purchase status
    await step.run("update-purchase-status", async () => {
      await db
        .update(purchases)
        .set({
          status: isFullRefund ? "refunded" : "partially_refunded",
          updatedAt: new Date(),
        })
        .where(eq(purchases.id, purchase.id));
    });

    // Step 3: Send customer notification
    await step.run("notify-customer", async () => {
      console.log(
        `Sending \({isFullRefund ? "full" : "partial"} refund notification to \){user.email}`
      );
      // await sendEmail({ ... });
    });

    return { success: true, isFullRefund };
  }
);

Even if the email service is down in step 3, step 2 (updating the database) has already completed and will not be re-run. Inngest retries only the failed step.

This is what makes durable execution valuable for payment processing. You get reliable, idempotent processing without building your own retry logic.

How to Deploy to Vercel with Neon

You now have a working application with authentication, a database, a type-safe API, payments, and background jobs. Time to deploy it.

How to Provision a Neon Database

1. Sign up at neon.tech and create a new project

2. Choose a region close to your users (Neon supports multiple AWS regions)

3. Copy the connection string from the dashboard

The connection string looks like this:

postgresql://username:password@ep-something.us-east-1.aws.neon.tech/my_saas?sslmode=require

How to Run Migrations in Production

For production, you should use versioned migrations instead of db:push. Generate a migration from your schema:

bun run db:generate

This creates SQL files in the drizzle/ directory. Review the generated SQL to make sure it matches your expectations. Then apply the migration:

DATABASE_URL="your-neon-connection-string" bun run db:migrate

How to Deploy to Vercel

1. Push your code to a GitHub repository

2. Go to vercel.com/new and import your repository

3. Vercel will auto-detect TanStack Start and configure the build settings

Set the following environment variables in Vercel's dashboard:

Click "Deploy." Vercel builds your app and deploys it to a .vercel.app URL.

How to Update OAuth Callbacks

After deploying, update your GitHub OAuth app's callback URL:

1. Go to your GitHub OAuth app settings

2. Change the Authorization callback URL to https://your-app.vercel.app/api/auth/callback/github

3. Add https://your-app.vercel.app as the Homepage URL

How to Configure Stripe Webhooks for Production

Create a webhook endpoint in the Stripe dashboard:

1. Go to Stripe Dashboard > Developers > Webhooks

2. Click "Add endpoint"

3. Set the URL to https://your-app.vercel.app/api/payments/webhook

4. Select the events you want to receive (charge.refunded, checkout.session.expired, and so on)

5. Copy the webhook signing secret and add it to Vercel's environment variables

How to Set Up Inngest in Production

Inngest has a cloud service that handles function execution in production:

1. Sign up at inngest.com

2. Create an app and copy your event key and signing key

3. Add INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY to Vercel's environment variables

4. In Inngest's dashboard, set your app URL to https://your-app.vercel.app/api/inngest

Inngest automatically discovers your functions and starts processing events.

Common Deployment Pitfalls

1. SSR externals. Some packages do not work with Vite's SSR bundling. If you see errors about packages like elysia or inngest during the build, add them to the ssr.external array in vite.config.ts:

// vite.config.ts
export default defineConfig({
  ssr: {
    external: ["elysia", "inngest"],
  },
  // ...
});

2. Environment variable access. In TanStack Start, server-side code can access process.env directly. Client-side code can only access variables prefixed with VITE_. Your Stripe secret key and database URL should never have the VITE_ prefix.

3. Neon connection pooling. For production, use the pooled connection string from Neon (it uses port 5432 instead of the direct connection on port 5433). The pooled connection handles concurrent requests better.

4. Build failures. If your build fails, the most common cause is a TypeScript error. Run bun run type-check locally before pushing. Fix all errors before deploying.

5. Missing environment variables. If your app crashes immediately after deployment, check the Vercel function logs. The most common issue is a missing environment variable. Neon connection strings, Stripe keys, and Better Auth secrets all need to be set before the first deployment.

How to Set Up a Custom Domain

Once your app is deployed to Vercel:

1. Go to your project's Settings in Vercel

2. Click "Domains"

3. Add your custom domain

4. Update your DNS records as instructed (usually a CNAME record pointing to cname.vercel-dns.com)

After adding a custom domain, update these environment variables in Vercel:

• Set BETTER_AUTH_URL to https://yourdomain.com

• Update your GitHub OAuth app's callback URL to https://yourdomain.com/api/auth/callback/github

• Update your Stripe webhook endpoint to https://yourdomain.com/api/payments/webhook

Vercel automatically provisions an SSL certificate for your custom domain. No additional configuration needed.

How to Verify Your Deployment

After deploying, run through this checklist:

1. Health check. Visit https://yourdomain.com/api/health. You should see a JSON response with { "status": "ok" }.

2. Authentication. Click "Sign in with GitHub" and complete the OAuth flow. You should be redirected to your dashboard.

3. Database. After signing in, check your Neon dashboard. You should see a new row in the users table.

4. Payments. On your pricing page, click "Buy" and use Stripe's test card (4242 4242 4242 4242) to complete a purchase. Check that a purchase record appears in your database.

5. Background jobs. After a test purchase, check the Inngest dashboard. You should see a purchase/completed event and the corresponding function execution.

If any of these steps fail, check the Vercel function logs (Settings, Functions, Logs) for error messages. Most deployment issues are misconfigured environment variables or missing webhook secrets.

Conclusion

You just built a production-ready SaaS application. Let's recap what you have:

• TanStack Start handles server-side rendering, file-based routing, and the dev server

• Elysia provides a type-safe API embedded in the same process as your web app

• Eden Treaty gives you a fully typed API client with zero code generation

• Drizzle ORM with Neon handles your database with type-safe queries and serverless PostgreSQL

• Better Auth provides GitHub OAuth with session management and route protection

• Stripe processes payments with webhook handling

• Inngest runs reliable background jobs with automatic retries and checkpointing

• Vercel hosts everything with zero infrastructure management

The four-layer pattern (Schema, API, Hooks, UI) gives you a repeatable process for adding new features. Every feature follows the same structure. Define the data, expose it through the API, connect it to React with hooks, and render it in your components.

This architecture scales well. The explicit boundaries between layers mean you can swap out individual pieces without rewriting everything.

If you outgrow Neon, switch to a self-hosted PostgreSQL. If you need a different payment provider, replace the Stripe module. The rest of the application doesn't change.

What you build next is up to you. Here are natural next steps:

• Email notifications with Resend and React Email for transactional emails (purchase confirmations, password resets, welcome sequences)

• Analytics with PostHog for tracking user behavior and feature flags

• Error tracking with Sentry for catching production errors before your users report them

• Content management with MDX for a blog or documentation section

• File uploads with S3-compatible storage for user-generated content

The src/lib/ pattern makes adding new integrations straightforward. Create a new directory, add an index.ts, and import it where you need it. Each integration stays isolated, so adding analytics does not affect your payment code.

If you want to skip the setup and start building your product immediately, Eden Stack includes everything from this article (and more), pre-configured and production-tested. It ships with 30+ Claude Code skills that encode the patterns described here, so AI coding assistants can generate features following your codebase conventions out of the box.

Whatever you build, build it with type safety. The feedback loop of "change the schema, see the errors, fix the errors" is the fastest way I know to ship reliable software.

Magnus Rodseth builds AI-native applications and is the creator of Eden Stack, a production-ready starter kit with 30+ Claude skills encoding production patterns for AI-native SaaS development.

We (Jess, Carmen, and Eda) are excited to announce the next installation of our free and online bootcamp. We support learners as they work their way through the freeCodeCamp Responsive Web Design curriculum. The bootcamp will start Friday, April 24th, and will run for 10 weeks until Friday, July 3rd.

Here’s what to expect:

• Live Streams: We’ll be streaming Monday to Friday at 15.00 UTC (you can check your timezone here), where we’ll go through the course material together on our YouTube channel, on Jess' Twitch channel and Carmen's Twitch channel. It’s also a chance to ask your questions! If you can’t join us live, the streams will be available offline to watch later.

• Guest Sessions: We’ll expand on our studies with guest sessions where professionals working in software engineering and related fields will talk about their craft.

• Community: To support each other and work together, we have a dedicated Discord channel in the freeCodeCamp Discord server (you can join here: https://discord.gg/KVUmVXA) to help you establish better connections with other learners working on freeCodeCamp material. We’ll also be including shared notes on our website.

• Calendar: We have a shared calendar of lessons we’ll be covering with a supportive and friendly group of learners alongside you.

• Newsletter: There’s no signup needed, but if you want weekly emails, you can also sign up for our newsletter.

How Does the Bootcamp Work?

Bad Website Club bootcamps have been running for a while, so if you've joined us in the past, this one is going to feel a little different.

As the freeCodeCamp course material has expanded, we have adapted our learning structure to reflect what’s in it.

We’re experimenting with a flipped classroom model, where learners do pre-reading and more solo work before classes to come into streamed sessions, prepared to support each other’s learning.

Also, learners will be able to contribute to shared lesson notes which we’ll be going over in unit reviews. We’ll be talking through some (not all!) of the workshop steps and offer space for Q&A in our live streams.

The labs and certification projects need to be done as solo work, but we’ll be looking at how to approach them together on streams and covering them in Q&As.

We’ll be moving fast, but there are no fixed deadlines! If you need more time, your progress will be saved on your freeCodeCamp account. Also, the videos and our Discord are available after the bootcamp ends.

Note that the bootcamp doesn't offer job placement support or 1:1 instructor support for learners due to the size and global distribution of our learners. But we’ll help you learn the skills that prepare you to pursue opportunities on your own.

Who We Are

Bad Website Club has been running free and online developer education programs since 2020. It's run by a small volunteer team (Jessica Rose, Carmen Huidobro, and Eda Eren – also thank you to wonderful Kiri who made all the art!). We focus on learning and experimenting over perfection, and believe that the web can be better when it includes everyone.

Also, it really is free: there’s no way to pay for it.

If you want to join us, you can download or subscribe to the full lesson calendar (for Google Calendar, use the iCal feed with these subscription instructions), follow us on our YouTube channel, on Jess' Twitch channel and Carmen's Twitch channel. You can also sign up for our weekly newsletter for lesson notes, show and tell projects, extra resources, and more.

Hope to see you soon!

That work is deterministic. An agent can do it.

In this tutorial, you'll build a local SEO audit agent from scratch using Python, Browser Use, and the Claude API. The agent visits real pages in a visible browser window, extracts SEO signals using Claude, checks for broken links asynchronously, handles edge cases with a human-in-the-loop pause, and writes a structured report — all resumable if interrupted.

By the end, you'll have a working agent you can run against any list of URLs. It costs less than $0.01 per URL to run.

What You'll Build

A seven-module Python agent that:

• Reads a URL list from a CSV file

• Visits each URL in a real Chromium browser (not a headless scraper)

• Extracts title, meta description, H1s, and canonical tag via Claude API

• Checks for broken links asynchronously using httpx

• Detects edge cases (404s, login walls, redirects) and pauses for human input

• Writes results to report.json incrementally — safe to interrupt and resume

• Generates a plain-English report-summary.txt on completion

The full code is on GitHub at dannwaneri/seo-agent.

Prerequisites

• Python 3.11 or higher

• An Anthropic API key (get one at console.anthropic.com)

• Windows, macOS, or Linux

• Basic familiarity with Python and the command line

Table of Contents

1. Why Browser Use Instead of a Scraper

2. Project Structure

3. Setup

4. Module 1: State Management

5. Module 2: Browser Integration

6. Module 3: Claude Extraction Layer

7. Module 4: Broken Link Checker

8. Module 5: Human-in-the-Loop

9. Module 6: Report Writer

10. Module 7: The Main Loop

11. Running the Agent

12. Scheduling for Agency Use

13. What the Results Look Like

Why Browser Use Instead of a Scraper

The standard approach to SEO auditing is to fetch page HTML with requests and parse it with BeautifulSoup. That works on static pages. It breaks on JavaScript-rendered content, misses dynamically injected meta tags, and fails entirely on authenticated pages.

Browser Use (84,000+ GitHub stars, MIT license) takes a different approach. It controls a real Chromium browser, reads the DOM after JavaScript executes, and exposes the page through Playwright's accessibility tree. The agent sees what a human would see.

The practical difference: a requests-based scraper might miss a meta description injected by a React component. Browser Use won't.

The other difference worth naming: Browser Use reads pages semantically. A Playwright script breaks when a button's CSS class changes from btn-primary to button-main. Browser Use identifies it's still a "Submit" button and acts accordingly. The extraction logic lives in the Claude prompt, not in brittle CSS selectors.

Project Structure

seo-agent/
├── index.py          # Main audit loop
├── browser.py        # Browser Use / Playwright page driver
├── extractor.py      # Claude API extraction layer
├── linkchecker.py    # Async broken link checker
├── hitl.py           # Human-in-the-loop pause logic
├── reporter.py       # Report writer
├── state.py          # State persistence (resume on interrupt)
├── input.csv         # Your URL list
├── requirements.txt
├── .env.example
└── .gitignore

Setup

Create a project folder and install dependencies:

mkdir seo-agent && cd seo-agent
pip install browser-use anthropic playwright httpx
playwright install chromium

Create input.csv with your URLs:

url
https://example.com
https://example.com/about
https://example.com/contact

Create .env.example:

ANTHROPIC_API_KEY=your-key-here

Set your API key as an environment variable before running:

# macOS/Linux
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Create .gitignore:

state.json
report.json
report-summary.txt
.env
__pycache__/
*.pyc

Module 1: State Management

The agent needs to track which URLs it has already audited. If the run is interrupted — power cut, keyboard interrupt, network error — it should resume from where it stopped, not start over.

state.py handles this with a flat JSON file:

import json
import os

STATE_FILE = os.path.join(os.path.dirname(__file__), "state.json")

_DEFAULT_STATE = {"audited": [], "pending": [], "needs_human": []}


def load_state() -> dict:
    if not os.path.exists(STATE_FILE):
        save_state(_DEFAULT_STATE.copy())
    with open(STATE_FILE, encoding="utf-8") as f:
        return json.load(f)


def save_state(state: dict) -> None:
    with open(STATE_FILE, "w", encoding="utf-8") as f:
        json.dump(state, f, indent=2)


def is_audited(url: str) -> bool:
    return url in load_state()["audited"]


def mark_audited(url: str) -> None:
    state = load_state()
    if url not in state["audited"]:
        state["audited"].append(url)
    save_state(state)


def add_to_needs_human(url: str) -> None:
    state = load_state()
    if url not in state["needs_human"]:
        state["needs_human"].append(url)
    save_state(state)

The design is intentional: mark_audited() is called immediately after a URL is processed and written to the report. If the agent crashes mid-run, it loses at most one URL's work.

Module 2: Browser Integration

browser.py does the actual page navigation. It uses Playwright directly (which Browser Use installs as a dependency) to open a visible Chromium window, navigate to the URL, capture HTTP status and redirect information, and extract the raw SEO signals from the DOM.

The key design decisions:

Visible browser, not headless. Set headless=False so you can watch the agent work. This matters for the demo and for debugging.

Status capture via response listener. Playwright raises an exception on 4xx/5xx responses, but the on("response", ...) handler fires before the exception. We capture status there.

2-second delay between visits. Prevents triggering rate limiting or bot detection on agency client sites.

Here is the core navigation function:

import asyncio
import sys
import time
from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeout

TIMEOUT = 20_000  # 20 seconds


def fetch_page(url: str) -> dict:
    result = {
        "final_url": url,
        "status_code": None,
        "title": None,
        "meta_description": None,
        "h1s": [],
        "canonical": None,
        "raw_links": [],
    }

    first_status = {"code": None}

    with sync_playwright() as p:
        browser = p.chromium.launch(headless=False)
        page = browser.new_page()

        def on_response(response):
            if first_status["code"] is None:
                first_status["code"] = response.status

        page.on("response", on_response)

        try:
            page.goto(url, wait_until="domcontentloaded", timeout=TIMEOUT)
            result["status_code"] = first_status["code"] or 200
            result["final_url"] = page.url

            # Extract SEO signals from DOM
            result["title"] = page.title() or None
            result["meta_description"] = page.evaluate(
                "() => { const m = document.querySelector('meta[name=\"description\"]'); "
                "return m ? m.getAttribute('content') : null; }"
            )
            result["h1s"] = page.evaluate(
                "() => Array.from(document.querySelectorAll('h1')).map(h => h.innerText.trim())"
            )
            result["canonical"] = page.evaluate(
                "() => { const c = document.querySelector('link[rel=\"canonical\"]'); "
                "return c ? c.getAttribute('href') : null; }"
            )
            result["raw_links"] = page.evaluate(
                "() => Array.from(document.querySelectorAll('a[href]'))"
                ".map(a => a.href).filter(Boolean).slice(0, 100)"
            )

        except PlaywrightTimeout:
            result["status_code"] = first_status["code"] or 408
        except Exception as exc:
            print(f"[browser] Error: {exc}", file=sys.stderr)
            result["status_code"] = first_status["code"]
        finally:
            browser.close()

    time.sleep(2)
    return result

A few things worth noting:

The raw_links cap at 100 is deliberate. DEV.to profile pages have hundreds of links — you don't need all of them for broken link detection.

The wait_until="domcontentloaded" setting is faster than networkidle and sufficient for meta tag extraction. JavaScript-rendered content needs the DOM to be ready, not all network requests to complete.

Module 3: Claude Extraction Layer

extractor.py takes the raw page snapshot from browser.py and calls Claude to produce a structured SEO audit result.

This is where most tutorials go wrong. They either write complex parsing logic in Python (fragile) or ask Claude for a free-form response and try to parse prose (unreliable). The right approach: give Claude a strict JSON schema and tell it to return nothing else.

The prompt engineering that makes this reliable:

import json
import os
import sys
from datetime import datetime, timezone
import anthropic

MODEL = "claude-sonnet-4-20250514"
client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))


def _strip_fences(text: str) -> str:
    """Remove accidental markdown code fences from Claude's response."""
    text = text.strip()
    if text.startswith("```"):
        lines = text.splitlines()
        # Drop opening fence
        lines = lines[1:] if lines[0].startswith("```") else lines
        # Drop closing fence
        if lines and lines[-1].strip() == "```":
            lines = lines[:-1]
        text = "\n".join(lines).strip()
    return text


def extract(snapshot: dict) -> dict:
    if not os.environ.get("ANTHROPIC_API_KEY"):
        raise OSError("ANTHROPIC_API_KEY is not set.")

    prompt = f"""You are an SEO auditor. Analyze this page snapshot and return ONLY a JSON object.
No prose. No explanation. No markdown fences. Raw JSON only.

Page data:
- URL: {snapshot.get('final_url')}
- Status code: {snapshot.get('status_code')}
- Title: {snapshot.get('title')}
- Meta description: {snapshot.get('meta_description')}
- H1 tags: {snapshot.get('h1s')}
- Canonical: {snapshot.get('canonical')}

Return this exact schema:
{{
  "url": "string",
  "final_url": "string",
  "status_code": number,
  "title": {{"value": "string or null", "length": number, "status": "PASS or FAIL"}},
  "description": {{"value": "string or null", "length": number, "status": "PASS or FAIL"}},
  "h1": {{"count": number, "value": "string or null", "status": "PASS or FAIL"}},
  "canonical": {{"value": "string or null", "status": "PASS or FAIL"}},
  "flags": ["array of strings describing specific issues"],
  "human_review": false,
  "audited_at": "ISO timestamp"
}}

PASS/FAIL rules:
- title: FAIL if null or length > 60 characters
- description: FAIL if null or length > 160 characters  
- h1: FAIL if count is 0 (missing) or count > 1 (multiple)
- canonical: FAIL if null
- flags: list every failing field with a clear description
- audited_at: use current UTC time in ISO 8601 format"""

    response = client.messages.create(
        model=MODEL,
        max_tokens=1000,
        messages=[{"role": "user", "content": prompt}],
    )

    raw = response.content[0].text
    clean = _strip_fences(raw)

    try:
        return json.loads(clean)
    except json.JSONDecodeError as exc:
        print(f"[extractor] JSON parse error: {exc}", file=sys.stderr)
        return _error_result(snapshot, str(exc))


def _error_result(snapshot: dict, reason: str) -> dict:
    return {
        "url": snapshot.get("final_url", ""),
        "final_url": snapshot.get("final_url", ""),
        "status_code": snapshot.get("status_code"),
        "title": {"value": None, "length": 0, "status": "ERROR"},
        "description": {"value": None, "length": 0, "status": "ERROR"},
        "h1": {"count": 0, "value": None, "status": "ERROR"},
        "canonical": {"value": None, "status": "ERROR"},
        "flags": [f"Extraction error: {reason}"],
        "human_review": True,
        "audited_at": datetime.now(timezone.utc).isoformat(),
    }

Two things make this reliable in production:

First, _strip_fences() handles the case where Claude wraps its response in ```json fences despite being told not to. This happens occasionally with Sonnet and consistently breaks json.loads() if you don't handle it.

Second, the _error_result() fallback means the agent never crashes on a bad Claude response — it logs the error and marks the URL for human review, then continues to the next URL.

Cost: Claude Sonnet 4 is priced at \(3 per million input tokens and \)15 per million output tokens. A typical page snapshot is around 500 input tokens; the structured JSON response is around 300 output tokens. That works out to roughly \(0.006 per URL — about \)0.12 for a 20-URL audit.

Module 4: Broken Link Checker

linkchecker.py takes the raw_links list from the browser snapshot and checks same-domain links for broken status using async HEAD requests.

The design choices:

• Same-domain only. Checking every external link on a page would take minutes and isn't what agency clients need. Filter to links on the same domain as the page being audited.

• HEAD requests, not GET. Faster, lower bandwidth, sufficient for status code detection.

• Cap at 50 links. Pages like DEV.to article listings have hundreds of internal links. Checking all of them would dominate the runtime.

• Concurrent requests via asyncio. All links are checked in parallel, not sequentially.

import asyncio
import logging
from urllib.parse import urlparse
import httpx

CAP = 50
TIMEOUT = 5.0
logger = logging.getLogger(__name__)


def _same_domain(link: str, final_url: str) -> bool:
    if not link:
        return False
    lower = link.strip().lower()
    if lower.startswith(("#", "mailto:", "javascript:", "tel:", "data:")):
        return False
    try:
        page_host = urlparse(final_url).netloc.lower()
        parsed = urlparse(link)
        return parsed.scheme in ("http", "https") and parsed.netloc.lower() == page_host
    except Exception:
        return False


async def _check_link(client: httpx.AsyncClient, url: str) -> tuple[str, bool]:
    try:
        resp = await client.head(url, follow_redirects=True, timeout=TIMEOUT)
        return url, resp.status_code != 200
    except Exception:
        return url, True  # Timeout or connection error = broken


async def _run_checks(links: list[str]) -> list[str]:
    async with httpx.AsyncClient() as client:
        results = await asyncio.gather(*[_check_link(client, url) for url in links])
    return [url for url, broken in results if broken]


def check_links(raw_links: list[str], final_url: str) -> dict:
    same_domain = [l for l in raw_links if _same_domain(l, final_url)]

    capped = len(same_domain) > CAP
    if capped:
        logger.warning("Page has %d same-domain links — capping at %d.", len(same_domain), CAP)
        same_domain = same_domain[:CAP]

    broken = asyncio.run(_run_checks(same_domain))

    return {
        "broken": broken,
        "count": len(broken),
        "status": "FAIL" if broken else "PASS",
        "capped": capped,
    }

Module 5: Human-in-the-Loop

This is the part most automation tutorials skip. What happens when the agent hits a login wall? A page that returns 403? A URL that redirects to a "Subscribe to continue reading" page?

Most scripts either crash or silently skip. Neither is acceptable in an agency context.

hitl.py handles this with two functions: one that detects whether a pause is needed, and one that handles the pause itself.

from state import add_to_needs_human

LOGIN_KEYWORDS = {"login", "sign in", "sign-in", "access denied", "log in", "unauthorized"}
REDIRECT_CODES = {301, 302, 307, 308}


def should_pause(snapshot: dict) -> bool:
    code = snapshot.get("status_code")

    # Navigation failed entirely
    if code is None:
        return True

    # Non-200, non-redirect
    if code != 200 and code not in REDIRECT_CODES:
        return True

    # Login wall detection
    title = (snapshot.get("title") or "").lower()
    h1s = [h.lower() for h in (snapshot.get("h1s") or [])]

    if any(kw in title for kw in LOGIN_KEYWORDS):
        return True
    if any(kw in h1 for kw in LOGIN_KEYWORDS for h1 in h1s):
        return True

    return False


def pause_reason(snapshot: dict) -> str:
    code = snapshot.get("status_code")
    if code is None:
        return "Navigation failed (None status)"
    if code != 200 and code not in REDIRECT_CODES:
        return f"Unexpected status code: {code}"
    return "Possible login wall detected"


def pause_and_prompt(url: str, reason: str) -> str:
    print(f"\n⚠️  HUMAN REVIEW NEEDED")
    print(f"   URL:    {url}")
    print(f"   Reason: {reason}")
    print(f"   Options: [s] skip  [r] retry  [q] quit\n")

    while True:
        choice = input("Your choice: ").strip().lower()
        if choice in ("s", "r", "q"):
            return {"s": "skip", "r": "retry", "q": "quit"}[choice]
        print("   Enter s, r, or q.")

The should_pause() function catches four cases: navigation failure, unexpected HTTP status, login keywords in the title, and login keywords in H1 tags. The login keyword check is what catches "Please sign in to continue" pages that return 200 but are effectively inaccessible.

In --auto mode (for scheduled runs), the main loop skips the pause_and_prompt() call and automatically handles these cases by logging the URL to needs_human[] in state and continuing.

Module 6: Report Writer

reporter.py writes results incrementally. This is important: results are written after each URL is audited, not batched at the end. If the run is interrupted, you don't lose completed work.

import json
import os
from datetime import datetime, timezone

REPORT_JSON = os.path.join(os.path.dirname(__file__), "report.json")
REPORT_TXT = os.path.join(os.path.dirname(__file__), "report-summary.txt")


def _load_report() -> list:
    if not os.path.exists(REPORT_JSON):
        return []
    with open(REPORT_JSON, encoding="utf-8") as f:
        return json.load(f)


def write_result(result: dict) -> None:
    """Append or update a result in report.json."""
    entries = _load_report()
    url = result.get("url", "")

    # Update existing entry if URL already present (handles retries)
    for i, entry in enumerate(entries):
        if entry.get("url") == url:
            entries[i] = result
            break
    else:
        entries.append(result)

    with open(REPORT_JSON, "w", encoding="utf-8") as f:
        json.dump(entries, f, indent=2, ensure_ascii=False)


def _is_overall_pass(result: dict) -> bool:
    fields = ["title", "description", "h1", "canonical"]
    for field in fields:
        if result.get(field, {}).get("status") not in ("PASS",):
            return False
    if result.get("broken_links", {}).get("status") == "FAIL":
        return False
    return True


def write_summary() -> None:
    entries = _load_report()
    passed = sum(1 for e in entries if _is_overall_pass(e))

    lines = []
    for entry in entries:
        overall = "PASS" if _is_overall_pass(entry) else "FAIL"
        failed_fields = [
            f for f in ["title", "description", "h1", "canonical", "broken_links"]
            if entry.get(f, {}).get("status") == "FAIL"
        ]
        suffix = f" [{', '.join(failed_fields)}]" if failed_fields else ""
        lines.append(f"{entry.get('url', 'unknown'):<60} | {overall}{suffix}")

    lines.append("")
    lines.append(f"{passed}/{len(entries)} URLs passed")

    with open(REPORT_TXT, "w", encoding="utf-8") as f:
        f.write("\n".join(lines))

The deduplication in write_result() handles retries cleanly. If a URL is retried after a human reviews a login wall and authenticates, the new result replaces the old one rather than creating a duplicate entry.

Module 7: The Main Loop

index.py wires everything together. It reads the URL list, loads state, skips already-audited URLs, and runs the audit loop.

import csv
import os
import sys
import time
import argparse

from state import load_state, is_audited, mark_audited, add_to_needs_human
from browser import fetch_page
from extractor import extract
from linkchecker import check_links
from hitl import should_pause, pause_reason, pause_and_prompt
from reporter import write_result, write_summary

INPUT_CSV = os.path.join(os.path.dirname(__file__), "input.csv")


def read_urls(path: str) -> list[str]:
    with open(path, newline="", encoding="utf-8") as f:
        return [row["url"].strip() for row in csv.DictReader(f) if row.get("url", "").strip()]


def run(auto: bool = False):
    if not os.environ.get("ANTHROPIC_API_KEY"):
        print("Error: ANTHROPIC_API_KEY environment variable is not set.")
        sys.exit(1)

    urls = read_urls(INPUT_CSV)
    pending = [u for u in urls if not is_audited(u)]

    print(f"Starting audit: {len(pending)} pending, {len(urls) - len(pending)} already done.\n")

    total = len(urls)

    try:
        for i, url in enumerate(pending, start=1):
            position = urls.index(url) + 1
            print(f"[{position}/{total}] {url}", end=" -> ", flush=True)

            # Browser navigation
            snapshot = fetch_page(url)

            # Human-in-the-loop check
            if should_pause(snapshot):
                reason = pause_reason(snapshot)

                if auto:
                    print(f"AUTO-SKIPPED ({reason})")
                    add_to_needs_human(url)
                    mark_audited(url)
                    continue

                action = pause_and_prompt(url, reason)
                if action == "quit":
                    print("Exiting.")
                    break
                elif action == "skip":
                    add_to_needs_human(url)
                    mark_audited(url)
                    continue
                # "retry" falls through to re-fetch below
                snapshot = fetch_page(url)

            # Claude extraction
            result = extract(snapshot)

            # Broken link check
            links = check_links(snapshot.get("raw_links", []), snapshot.get("final_url", url))
            result["broken_links"] = links

            # Write result immediately
            write_result(result)
            mark_audited(url)

            overall = "PASS" if all(
                result.get(f, {}).get("status") == "PASS"
                for f in ["title", "description", "h1", "canonical"]
            ) and links["status"] == "PASS" else "FAIL"

            print(overall)

    except KeyboardInterrupt:
        print("\n\nInterrupted. Progress saved. Re-run to continue.")
        return

    write_summary()
    passed = sum(
        1 for e in [r for r in []]
        if all(e.get(f, {}).get("status") == "PASS" for f in ["title", "description", "h1", "canonical"])
    )
    print(f"\nAudit complete. Report saved to report.json and report-summary.txt")


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--auto", action="store_true", help="Auto-skip URLs requiring human review")
    args = parser.parse_args()
    run(auto=args.auto)

The KeyboardInterrupt handler is the resume mechanism. When you press Ctrl+C, the handler prints a message and exits cleanly. Because mark_audited() is called after write_result() for each URL, the next run skips everything already processed.

Running the Agent

Interactive mode (pauses on edge cases):

python index.py

Auto mode (skips edge cases, adds to needs_human[]):

python index.py --auto

When it runs, you'll see the browser window open for each URL and the terminal print progress:

Starting audit: 7 pending, 0 already done.

[1/7] https://example.com -> PASS
[2/7] https://example.com/about -> FAIL
[3/7] https://example.com/contact -> AUTO-SKIPPED (Unexpected status code: 404)
...
Audit complete. Report saved to report.json and report-summary.txt

To resume after an interruption:

python index.py --auto
# Starting audit: 4 pending, 3 already done.

Scheduling for Agency Use

For recurring weekly audits, create a batch file and schedule it with Windows Task Scheduler.

Create run-audit.bat:

@echo off
set ANTHROPIC_API_KEY=your-key-here
cd /d C:\Users\yourname\Desktop\seo-agent
python index.py --auto

In Windows Task Scheduler:

1. Create a new Basic Task

2. Set the trigger to Weekly, Monday at 7:00 AM

3. Set the action to "Start a program"

4. Browse to your run-audit.bat file

Check report-summary.txt on Monday morning. URLs in needs_human[] in state.json need manual review — login walls, paywalls, or pages that returned unexpected status codes.

For macOS/Linux, use cron:

# Run every Monday at 7am
0 7 * * 1 cd /path/to/seo-agent && ANTHROPIC_API_KEY=your-key python index.py --auto

What the Results Look Like

I ran this agent against seven of my own published pages across Hashnode, freeCodeCamp, and DEV.to. Every single one failed.

https://hashnode.com/@dannwaneri                    | FAIL [h1]
https://freecodecamp.org/news/claude-code-skill     | FAIL [description]
https://freecodecamp.org/news/stop-letting-ai-guess | FAIL [description]
https://freecodecamp.org/news/rag-system-handbook   | FAIL [title, description]
https://freecodecamp.org/news/author/dannwaneri     | FAIL [description]
https://dev.to/dannwaneri/gatekeeping-panic         | FAIL [title]
https://dev.to/dannwaneri/production-rag-system     | FAIL [title]

0/7 URLs passed

The freeCodeCamp description issues are partly platform-level — freeCodeCamp's template sometimes truncates or omits meta descriptions for article listing pages. The DEV.to title issues are mine. Article titles that work as headlines often exceed 60 characters in the <title> tag.

A note on the 60-character title rule: this is a display threshold, not a ranking penalty. Google indexes titles of any length. The 60-character guideline reflects approximately how many characters fit in a desktop SERP result before truncation. Titles over 60 characters often still rank — they just get cut off in search results, which can hurt click-through rate. The agent flags display risk, not a ranking violation.

Next Steps

The agent as built handles the core SEO audit workflow. Obvious extensions:

• Performance metrics — add a Lighthouse or PageSpeed Insights API call per URL

• Structured data validation — check for JSON-LD schema markup and validate it

• Email delivery — send report-summary.txt via SMTP after the run completes

• Multi-client support — separate input.csv files per client, separate report directories

The full code including all seven modules is at dannwaneri/seo-agent. Clone it, add your URLs, and run it.

If you found this useful, I write about practical AI agent setups for developers and agencies at DEV.to/@dannwaneri. The DEV.to companion piece covers the design decisions behind the agent — why HITL matters, why Browser Use over scrapers, and what the audit results mean for your own published content.