JavaScript - freeCodeCamp.org

A Guide to Modern React Form Architecture: TanStack Form + Zod + Shadcn

Tapas Adhikary — Tue, 28 Jul 2026 16:29:03 +0000

Building production-grade forms in React can be a painful experience. It's one of the parts of front-end engineering that most developers are uncomfortable with.

Usually, you'll start with a simple controlled form using the useState hook. But as the form grows, you realise that typing a single character into an input field triggers a re-render of the entire component tree. The application becomes sluggish and ends up creating a terrible user experience.

You might even try mitigating this re-rendering issue by switching to an uncontrolled form using the useRef hook. But this introduces horrible scalability issues, and as the form grows, maintaining the code becomes a nightmare.

Vibe coding might get you to a working demo, but actual engineering gets you to production. To fix these performance and scalability issues in the production apps, we need to rethink how inputs work.

In this article, we'll build a production-ready form architecture. We'll use TanStack Form as a headless state machine to solve the performance and scalability problems, Zod for bulletproof validations, and ShadCN UI for accessible, beautiful components.

If you're a visual learner, I've recorded a full masterclass video covering this exact architecture over on my YouTube channel, tapaScript. You can watch it right here:

The Problem with Traditional Forms
- The Uncontrolled "Ref" Workaround
- Why Not Just Use Native HTML Forms?
Introducing TanStack Form
Fine-Grained Reactivity
Validation with Zod
Headless TanStack Form with ShadCN UI
Handling Nested Dynamic Arrays with TanStack Form
TanStack Form's Granular Reactivity: useSelector vs form.Subscribe
- With useSelector()
- With form.Subscribe()
TanStack Form vs. React Hook Form
Conclusion & Important Resources
If You've Read This Far...

The Problem with Traditional Forms

When developers realize that useState gives them the control to manage forms using React's state, they often create form components like this:

import { useState } from "react";

export function StandardRegistrationForm() {
 
  const [formData, setFormData] = useState({
    firstName: "",
    lastName: "",
    email: "",
    password: "",
  });

  console.log("Form Re-rendered! Current state:", formData.firstName);

  const handleChange = (e: React.ChangeEvent) => {
    setFormData((prev) => ({
      ...prev,
      [e.target.name]: e.target.value,
    }));
  };

  return (
    
      
        The Problem
        Standard Controlled Form
      

      
        
          
            First Name
          
          
        

        
          
            Last Name
          
          
        

        
          
            Email
          
          
        

        
      
    
  );
}

The component uses a centralized useState object, which is the standard way most developers are taught to build forms. The moment a value changes for any input fields, the state gets updated.

In React, every time you update a state, the component re-renders to display the current state value. This introduces a performance issue that you need to solve.

The image below shows the exact performance problem of the form component getting re-rendered with every keystroke inside the input elements.

The Uncontrolled "Ref" Workaround

Acknowledging the problem we've seen with the controlled form component, devs found a workaround. Instead of using state, if we use ref, the components don't re-render on ref's current value changes. That sounds like an AHA! moment until we figure out that it introduces completely different architectural headaches.

Here's the same form, but managed using refs instead of states:

import { useRef } from "react";

export function RefRegistrationForm() {
 
  const firstNameRef = useRef(null);
  const lastNameRef = useRef(null);
  const emailRef = useRef(null);

  console.log("Form Rendered (Notice it doesn't log when typing)");

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

    const formData = {
      firstName: firstNameRef.current?.value,
      lastName: lastNameRef.current?.value,
      email: emailRef.current?.value,
    };

    console.log("Submitted Data:", formData);

  };

  return (
    
      
        The Ref Workaround
        Fast, but scales horribly.
      

      
        
          
            First Name
          
          
        

        
          
            Last Name
          
          
        

        
          
            Email
          
          
        

        
      
    
  );
}

Let's talk about the problems with this approach:

The Ref Soup: We've created a separate ref for every single input. Imagine this form grows to 20+ fields, and you have to manage all those refs!
We need to extract the data manually and stitch the object back together. There's no mechanism like setState() that exists here.
How do we do real-time validation? Since the field/component doesn't re-render here as you type, showing a dynamic error message under the inputs becomes incredibly hard without introducing new state variables, and doing that would defeat the whole purpose of refs.

Why Not Just Use Native HTML Forms?

Oh yes! We shouldn't ignore this possibility as well. Why use a library at all? Can't we just use native HTML forms and grab the data with FormData on submit?

If you're building a simple "Contact Us" or "Login Form", the native HTML forms are actually the best tool for the job. They're lean, require zero library knowledge, and are incredibly efficient.

But for complex, production-grade web applications, the native approach quickly hits a wall:

Complex data structures: FormData is a flat object. If you're dealing with deeply nested objects or dynamic arrays, manually parsing speakers[0][firstName] out of a flat FormData object could be messy.
Dynamic UI: If you have a requirement where Field B should appear if Field A is set to "Yes", you need client-side state to track Field A's value anyway. FormData only exists at the exact moment of submission.
UX & Real-time Validations: Native HTML validations are rigid and hard to style cleanly across browsers. If you need complex cross-field validations (like confirming passwords match) or async validations (checking if a username is taken while the user types), you need JavaScript.

When native forms aren't enough, we move to React.

Introducing TanStack Form

TanStack Form is a headless state machine for your inputs. It gives you the strict typing and easy data management of a controlled form, but uses fine-grained reactivity to ensure that only the specific field you're typing in re-renders, and nothing else.

Let's set it up in a modern Vite + TypeScript environment. First, install the TanStack Form using this command:

npm install @tanstack/react-form # Or use, equivallent yarn, pnpm commands

Instead of a massive list of individual state hooks, you just need the useForm hook to spin up the form engine:

import { useForm } from '@tanstack/react-form';

export function SpeakerForm() {
  const form = useForm({
    defaultValues: {
      firstName: '',
      lastName: '',
      twitterHandle: '',
    },
    onSubmit: async ({ value }) => {
      console.log('Form Submitted!', value);
    },
  });

  return (
    
      Add New Speaker
      {/* We will build the fields here */}
    
  );
}

Notice the defaultValues. TanStack Form automatically infers your entire form structure from this object. If you try to reference an invalid field name later, TypeScript will throw an error immediately.

Fine-Grained Reactivity

Let's now connect the form inputs to the engine. To do that, we need to wrap them in TanStack's Field component. This uses the standard JSX render prop pattern to pass the isolated field state directly into our UI.

 {
    e.preventDefault();
    e.stopPropagation();
    form.handleSubmit();
  }}
  className="space-y-4"
>
  
    {(field) => {
      // PROOF: This log will only fire when firstName changes!
      console.log("Rendering First Name Field");
      
      return (
        
          
            First Name
          
           field.handleChange(e.target.value)}
            className="p-2 rounded-md bg-neutral-950 border border-neutral-700 focus:border-emerald-500 outline-none"
          />
        
      );
    }}

If you place a console.log in the parent component and one inside the field, you'll see the magic. When you type in the First Name input, the parent component doesn't re-render. Here's a visual of only the form field re-rendering.

The state update is strictly isolated to the function inside that specific Field component.

Validation with Zod

A form is only useful if it has field validations. In the current ecosystem, Zod is the industry standard. First, install Zod and the zod form adapter.

npm install zod @tanstack/zod-form-adapter # Or use, equivallent yarn, pnpm commands

Then inject the Zod adapter into your form engine:

import { zodValidator } from '@tanstack/zod-form-adapter';
import { z } from 'zod';

// Inside your component...
const form = useForm({
  defaultValues: { firstName: '', lastName: '' },
  validatorAdapter: zodValidator(),
  onSubmit: async ({ value }) => { /* ... */ },
});

Next, we'll update our field to use Zod rules. Here we opted for a rule that the first name must be at least 2 characters. Also, by checking the field.state.meta.isTouched, we ensure the error only shows after the user interacts with the input.



  {(field) => (
    
      
        First Name
      
      
       field.handleChange(e.target.value)}
        className="bg-neutral-950 border-neutral-700 focus-visible:ring-emerald-500"
      />
      {field.state.meta.isTouched && field.state.meta.errors.length ? (
        
        {
           field.state.meta.errors.map((error) =>  error.message)
         }
        ) : null}
    
    
  )}

The image below shows how the error message appears below the field when the First Name field value is changed and it fails validation.

Headless TanStack Form with ShadCN UI

TanStack Form is headless. This means you can map it to any design system seamlessly. Let's take one of the modern design systems available today: ShadCN UI.

If you are using a Vite-TypeScript-based React project, you can integrate the ShadCN UI in a few simple steps:

First, open the tsconfig.json file and add this compiler option:

"compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "./src/*"
      ]
    }
  }

Then open the vite.config.json file and add the mapping for the @ alias:

import react from '@vitejs/plugin-react'
import path from "path"
import { defineConfig } from 'vite'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
})

Install shadcn and its components like label, input, and button:

npx shadcn@latest add input label button

Now, you can import these ShadCN components into your form component and replace the native HTML label, input, and button.

import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";


  {(field) => (
    
      
        First Name
      
      
       field.handleChange(e.target.value)}
        className="bg-neutral-950 border-neutral-700 focus-visible:ring-emerald-500"
      />
      
       {field.state.meta.isTouched && field.state.meta.errors.length ? (
        
        {
           field.state.meta.errors.map((error) =>  error.message)
         }
        ) : null}
    
    
  )}

Handling Nested Dynamic Arrays with TanStack Form

Suppose we're building a speaker form for a meetup. What if we want to feature multiple speakers for a talk in our meetup? Now we need to manage a data structure to hold more than one speaker's details. We'll need an array of objects.

In classic React, managing an array of objects with complex states leads to spaghetti code. TanStack Form treats arrays exactly like a typical form field. We just need to update our defaultValues to an array:

defaultValues: {
  speakers: [ { firstName: '', lastName: '' } ],
},

Now, set the mode to array on your field and map over it:


  {(field) => (
    
      {field.state.value.map((_, index) => (
        
          
          
            {/* Nested Fields use bracket notation! */}
            
              {(subField) => (
                 
                    First Name
                     subField.handleChange(e.target.value)} 
                    />
                 
              )}
            
          

          {/* Remove Button */}
          {field.state.value.length > 1 && (
            
          )}
        
      ))}
      
      {/* Add Button */}
      
    
  )}

To append data, we call field.pushValue() and to remove, we call field.removeValue(index). Typing into the newest row leaves the previous array fields completely static. It's incredibly performant.

The image above shows the multi-speaker form and its output when submitted.

TanStack Form's Granular Reactivity: `useSelector` vs `form.Subscribe`

Sometimes, you need to access form state outside an input. For example, you want to show the "Unsaved Changes!" notification the moment the user changes the value in the input fields.

Notice that here the notification is outside the form, but it solely depends on the form field values.

TanStack gives you two distinct tools for this, and knowing when to use them is the key to mastering this architecture.

With `useSelector()`

If the state change affects the macro-layout of your page (like showing a global "unsaved Changes" banner like the above), you want the parent component to re-render. We'll use the standalone useSelector() hook for this:

import { useForm, useSelector } from "@tanstack/react-form";

export function ReactivityDemo() {
  const form = useForm({ defaultValues: { bio: "" } });

  // This isolates the exact piece of state we want the parent to track
  const isFormDirty = useSelector(form.store, (state) => state.isDirty);

  return (
    
      {isFormDirty && (
        
          Unsaved Changes!
        
      )}
      {/* Form goes here */}
    
  );
}

With `form.Subscribe()`

If the state change only affects a micro-interaction like disabling a submit button while the form is being saved, we don't want the whole form to re-render. In that case, we wrap the button tightly inside .

 [state.canSubmit, state.isSubmitting]}>
  {([canSubmit, isSubmitting]) => (
    
  )}

This isolates the re-render exclusively to the button. The rest of the component stays completely undisturbed.

TanStack Form vs. React Hook Form

If you've been building React applications for a while, you're probably thinking: "Why not just use React Hook Form?"

React Hook Form is an extraordinary library and has been the industry standard for years. It solves the performance problem by leveraging uncontrolled components and useRef under the hood. It isolates re-renders perfectly and handles validation well.

But as applications scale in complexity, the TanStack Form architecture offers three distinct advantages over React Hook Form:

Dynamic Arrays

If you've ever built a complex form with React Hook Form that needs dynamic, nested arrays (like adding multiple speakers in our example above), you probably need a hook like useFieldArray. Managing complex useFieldArray implementations often needs huge boilerplate, careful index tracking, and jumping through to maintain strict TypeScript safety deep within the tree.

TanStack Form eliminates this. It treats arrays the same as a string input. The form is a centralized state machine: you simply inform a field that it has a mode=array, and you instantly get access to pushValue() and removeValue() along with deeply nested type-safety.

Deeply Nested Components

React Hook Form relies on uncontrolled inputs to achieve performance. While this is fast, passing refs around deeply nested component trees can get messy, especially when integrating with complex UI libraries.

TanStack Form gives us the strict, predictable architecture of a controlled component but uses fine-grained reactivity to ensure only the specific parts of the UI that change are re-rendered.

The Ecosystem Sync

If you're moving towards modern, production-ready stacks using TanStack Query (React Query) for data fetching and TanStack Router for navigation, TanStack Form shares the exact same mental model and family. It integrates seamlessly into the ecosystem, providing a unified DX across your entire application architecture.

Conclusion & Important Resources

By combining TanStack Form, Zod, and ShadCN UI, we've created a strictly typed, reactive, production-ready form architecture that handles everything from basic text inputs to complex nested arrays without sacrificing any bit of performance.

You can grab the complete starter code and the final project from my GitHub:

All the source code used in the article and the complete project source code: https://github.com/tapascript/full-stack-vibe-to-prod/tree/main/11-tanstack-form
A code scaffolding repo for React projects using TypeScript, Vite, and TailwindCSS: https://github.com/atapas/code-react19-ts

If you found this helpful, you'll find these two in-depth video tutorials helpful, too:

If You've Read This Far...

Thank You!

I'm thrilled to announce that I've started a Full Stack FREE Course to take developers from vibe coding to a production-ready mental model. I'd be delighted if you check it out and take part.

Subscribe to my YouTube Channel
Follow on LinkedIn and X
Catch up with my React Clean Code Rules Book
All the source code used in this article is on my GitHub Repository.

See you soon with my next article. Until then, please take care of yourself and keep learning.

How to Build a Browser-Based PDF Blur Tool Using JavaScript

Bhavin Sheth — Fri, 24 Jul 2026 20:44:56 +0000

Many PDF documents contain information that shouldn't be shared publicly. Personal details, financial figures, signatures, addresses, account numbers, employee information, or confidential business data often need to be hidden before a file is sent to someone else.

A PDF Blur Tool makes this process simple. Instead of permanently removing content, it places a blur effect over selected areas of a PDF so sensitive information becomes difficult to read while the rest of the document remains unchanged.

In this tutorial, you'll build a browser-based PDF Blur Tool using JavaScript. Users will be able to upload a PDF, preview every page, draw blur boxes over sensitive content, adjust the blur intensity, apply the blur to selected pages, preview the final result, and download the processed PDF, all without uploading files to a server.

We'll use PDF.js to render PDF pages inside the browser, HTML Canvas to create and manage blur regions, and PDF-lib to generate the final blurred PDF.

By the end of this tutorial, you'll have a fully functional client-side PDF editing tool similar to the one available on my site, AllInOneTools.

What This PDF Blur Tool Does and How It Works
Project Setup
Creating the HTML Layout
Uploading and Previewing PDFs
Creating Blur Regions
Applying Blur to Pages
Generating the Final PDF
Previewing the Result
Renaming and Downloading
Demo: How the PDF Blur Tool Works
Performance Tips
Common Mistakes
Conclusion

What This PDF Blur Tool Does and How It Works

A PDF Blur Tool helps protect sensitive information before a document is shared. Instead of editing or deleting the original content, it applies a visual blur effect over selected areas so confidential information becomes unreadable while the rest of the document remains unchanged.

This approach is useful for hiding personal details, financial information, account numbers, signatures, addresses, faces, or any other private content that shouldn't be visible in the final document.

In this project, users can upload a PDF directly from their browser, preview every page, and draw one or more blur regions over the areas they want to hide. The tool also allows users to adjust the blur intensity, blur either selected areas or entire pages, apply the effect to the current page, all pages, or specific page ranges, preview the completed document, rename the output file, and download the final PDF.

Because everything runs inside the browser, no files are uploaded to a server, helping maintain document privacy.

Behind the scenes, the application first renders each PDF page onto an HTML canvas using PDF.js. Rather than modifying the original PDF immediately, it records the position, size, page number, and blur intensity for every blur region that the user creates.

When the user clicks Apply & Finalize, those stored regions are converted from browser coordinates into actual PDF page coordinates. The selected blur effect is then applied to the rendered page, and PDF-lib generates a new PDF containing the blurred content while preserving the rest of the document.

This workflow provides an interactive editing experience while keeping the original PDF unchanged until the final document is generated.

For example, each blur region can be represented as an object like this:

const blurRegion = {

    page: 2,

    x: 180,

    y: 240,

    width: 260,

    height: 90,

    intensity: 6

};

Each object stores all the information required to recreate the blur effect during the final PDF generation process.

Project Setup

Before writing any code, let's create a simple project structure for our PDF Blur Tool.

We'll use plain HTML, CSS, and JavaScript, along with two libraries:

PDF.js for rendering PDF pages inside the browser.
PDF-lib for generating the final blurred PDF.

Our project structure looks like this:

pdf-blur-tool/

│── index.html
│── style.css
│── script.js
│── pdf.worker.min.js
│── assets/

Keeping the project simple makes it easier to understand how each part works.

Add PDF.js and PDF-lib before loading your own JavaScript.

Configure the PDF worker.

pdfjsLib.GlobalWorkerOptions.workerSrc =
    "pdf.worker.min.js";

The worker processes PDF rendering in a background thread, helping keep the interface responsive while pages are rendered.

Creating the HTML Layout

The application consists of four main sections:

Upload area
PDF preview
Blur settings panel
Final download section

Create the basic layout:

Initially, only the upload section is visible.

After a PDF is selected, the editor becomes visible.

Selecting DOM Elements

Create references to the elements used throughout the application.

const uploadSection =
    document.getElementById(
        "uploadSection"
    );

const editorSection =
    document.getElementById(
        "editorSection"
    );

const resultSection =
    document.getElementById(
        "resultSection"
    );

const fileInput =
    document.getElementById(
        "pdfInput"
    );

const pdfCanvas =
    document.getElementById(
        "pdfCanvas"
    );

const canvasContext =
    pdfCanvas.getContext("2d");

These references allow the application to switch between the upload, editing, and download stages.

Uploading and Previewing PDFs

The upload section accepts both drag-and-drop and traditional file selection.

When a PDF is chosen, verify that it's actually a PDF before continuing.

async function handlePdfUpload(
    file
) {

    if (
        !file ||
        file.type !==
        "application/pdf"
    ) {

        alert(
            "Please select a PDF file."
        );

        return;

    }

    await loadPdf(file);

}

If validation succeeds, the document is loaded into memory.

Reading the PDF

Use the File API to convert the uploaded file into an ArrayBuffer.

async function loadPdf(
    file
) {

    const bytes =
        await file.arrayBuffer();

    pdfDocument =
        await pdfjsLib
            .getDocument({
                data: bytes
            })
            .promise;

    currentPage = 1;

    await renderPage(
        currentPage
    );

}

The uploaded bytes will also be reused later when generating the blurred PDF.

Rendering the First Page

PDF.js renders each page onto an HTML canvas.

Start by retrieving the requested page.

async function renderPage(
    pageNumber
) {

    const page =
        await pdfDocument
            .getPage(
                pageNumber
            );

    const viewport =
        page.getViewport({
            scale: 1.5
        });

Resize the canvas to match the page dimensions.

pdfCanvas.width =
    viewport.width;

pdfCanvas.height =
    viewport.height;

Render the page.

await page.render({

    canvasContext,

    viewport

}).promise;

After rendering finishes, the PDF page becomes visible inside the editor.

Most PDF documents contain multiple pages.

Allow users to move between pages using Previous and Next buttons.

let currentPage = 1;

let pdfDocument = null;

Move to the previous page.

previousButton
.addEventListener(
    "click",
    async () => {

        if (
            currentPage === 1
        ) {

            return;

        }

        currentPage--;

        await renderPage(
            currentPage
        );

    }
);

Move to the next page.

nextButton
.addEventListener(
    "click",
    async () => {

        if (
            currentPage ===
            pdfDocument.numPages
        ) {

            return;

        }

        currentPage++;

        await renderPage(
            currentPage
        );

    }
);

Update the page counter whenever the current page changes.

pageIndicator.textContent =
    `Page ${currentPage} of ${pdfDocument.numPages}`;

This provides users with clear feedback while navigating large PDF documents.

Preparing for Blur Editing

Once the current page is rendered, the application prepares a transparent layer above the PDF canvas.

This overlay captures mouse interactions without modifying the original page preview.

Create the overlay.

Match its size to the PDF preview.

overlayCanvas.width =
    pdfCanvas.width;

overlayCanvas.height =
    pdfCanvas.height;

Later in the tutorial, this overlay will allow users to draw blur regions while keeping the underlying PDF page untouched.

Showing the Editor

After the first page finishes rendering, switch from the upload screen to the editor interface.

uploadSection.hidden =
    true;

editorSection.hidden =
    false;

Users can now preview the document, navigate between pages, and begin selecting areas that should be blurred.

Creating Blur Regions

Now that the PDF preview is working, we can build the most important feature of the application: allowing users to blur sensitive information.

Instead of editing the PDF immediately, users first draw one or more blur regions over the page preview.

Each region stores its own position, size, and blur intensity. These regions are later converted into actual PDF coordinates during final processing.

Creating the Blur Area Object

Every blur region is represented as a JavaScript object.

For example:

const blurArea = {

    page: currentPage,

    x: 0,

    y: 0,

    width: 0,

    height: 0,

    intensity: 6

};

Rather than modifying the PDF immediately, the application simply keeps track of these objects until the user clicks Apply & Finalize.

Storing Multiple Blur Regions

Users often need to hide more than one piece of information.

Store all blur areas inside an array.

const blurAreas = [];

Whenever a new blur box is created, push it into the array.

blurAreas.push({

    page: currentPage,

    x,

    y,

    width,

    height,

    intensity:
        blurIntensity

});

This makes it easy to redraw, edit, or remove individual blur regions later.

Starting a Blur Selection

The transparent overlay canvas captures mouse interactions.

When the user presses the mouse button, record the starting position.

let isDrawing = false;

let startX = 0;

let startY = 0;

overlayCanvas
.addEventListener(
    "mousedown",
    event => {

        isDrawing = true;

        startX = event.offsetX;

        startY = event.offsetY;

    }
);

The blur rectangle begins at this point.

Drawing the Blur Rectangle

As the mouse moves, update the rectangle dimensions.

overlayCanvas
.addEventListener(
    "mousemove",
    event => {

        if (
            !isDrawing
        ) {

            return;

        }

        drawPreviewBox(

            startX,

            startY,

            event.offsetX,

            event.offsetY

        );

    }
);

The preview updates continuously while the user drags the mouse.

Finishing the Selection

When the mouse button is released, save the completed blur region.

overlayCanvas
.addEventListener(
    "mouseup",
    event => {

        isDrawing = false;

        blurAreas.push({

            page:
                currentPage,

            x:
                startX,

            y:
                startY,

            width:
                event.offsetX -
                startX,

            height:
                event.offsetY -
                startY,

            intensity:
                blurIntensity

        });

        redrawBlurAreas();

        updateBlurList();

    }
);

Each blur region becomes part of the current editing session.

Drawing Existing Blur Areas

Whenever the page changes or a blur region is added, redraw every blur box.

function redrawBlurAreas() {

    overlayContext.clearRect(

        0,

        0,

        overlayCanvas.width,

        overlayCanvas.height

    );

    blurAreas

        .filter(

            area =>

                area.page ===
                currentPage

        )

        .forEach(

            drawBlurArea

        );

}

This ensures that previously created blur regions remain visible while editing.

Displaying Blur Boxes

Render every stored region with a dashed outline.

function drawBlurArea(
    area
) {

    overlayContext
        .setLineDash([6, 4]);

    overlayContext
        .strokeStyle =
        "#4f6cff";

    overlayContext
        .strokeRect(

            area.x,

            area.y,

            area.width,

            area.height

        );

}

The outline acts as a guide and doesn't become part of the final PDF.

Blur Options

Users can choose how the blur should be applied.

The tool supports two modes:

Blur selected areas
Blur entire page(s)

The selected option controls the editing behavior.

const blurMode =
document.querySelector(

    'input[name="blurMode"]:checked'

).value;

If Blur selected areas is chosen, users draw blur rectangles manually.

If Blur entire page(s) is selected, the application skips manual selection and prepares to blur the entire page during final processing.

Adjusting Blur Intensity

Different documents require different levels of blur.

A slider lets users control the blur strength before applying the effect.

const blurSlider =
document.getElementById(
    "blurIntensity"
);

let blurIntensity = 6;

blurSlider
.addEventListener(
    "input",
    event => {

        blurIntensity =
        Number(
            event.target.value
        );

    }
);

The selected value is stored with every newly created blur region.

blurArea.intensity =
blurIntensity;

Higher values produce a stronger blur effect.

Managing Multiple Blur Areas

Many documents contain several pieces of confidential information.

Instead of limiting users to a single blur rectangle, the application displays every saved region.

For example:

Blur Area #1

Blur Area #2

Blur Area #3

Each entry includes a remove button.

function removeBlurArea(
    index
) {

    blurAreas.splice(
        index,
        1
    );

    redrawBlurAreas();

    updateBlurList();

}

This allows users to delete only the blur region they no longer need.

To remove all blur regions from the current page:

function clearCurrentPage() {

    const remaining =

    blurAreas.filter(

        area =>

            area.page !==
            currentPage

    );

    blurAreas.length = 0;

    blurAreas.push(
        ...remaining
    );

    redrawBlurAreas();

}

Applying Blur to Pages

Users may want to blur only one page or several pages within a document.

The editor provides three options:

Current page only
All pages
Specific pages

const pageOption =
document.querySelector(

'input[name="pageOption"]:checked'

).value;

If the user selects Specific pages, they can enter values such as:

1, 3-5, 8

These values will later be converted into an array of page numbers before the final PDF is generated.

Applying the Blur Effect

So far, users have uploaded a PDF, selected one or more blur regions, adjusted the blur intensity, and chosen which pages should be processed.

The final step is converting those blur regions into actual blurred content inside the generated PDF.

Rather than modifying the original document directly, the application creates a new PDF while preserving the original file.

Loading the Original PDF

Start by loading the uploaded PDF into PDF-lib.

async function applyBlur() {

    const pdfDoc =

        await PDFLib.PDFDocument.load(
            originalPdfBytes.slice()
        );

    const pages =
        pdfDoc.getPages();

}

Using a copy of the original bytes ensures that the uploaded document remains unchanged.

Processing the Selected Pages

Determine which pages should receive the blur effect.

const selectedPages =

parsePageSelection(

    pageSelection,

    pdfDoc.getPageCount()

);

For example:

Current Page

↓

[2]


All Pages

↓

[1,2,3,4]


Specific Pages

↓

[1,3,5]

Only these pages will be modified during processing.

Rendering Each Page as an Image

Since blur is a pixel-based effect, each selected PDF page is rendered into an off-screen canvas.

const page =

await pdfDocument.getPage(
    pageNumber
);

const viewport =
page.getViewport({

    scale: 2

});

const canvas =
document.createElement(
    "canvas"
);

canvas.width =
viewport.width;

canvas.height =
viewport.height;

Render the page.

await page.render({

    canvasContext:
    canvas.getContext("2d"),

    viewport

}).promise;

The canvas now contains a bitmap version of the PDF page that can be edited.

Applying Blur to Selected Regions

Retrieve all blur regions that belong to the current page.

const pageRegions =

blurAreas.filter(

    area =>

        area.page === pageNumber

);

Loop through every blur region.

pageRegions.forEach(

    area => {

        blurCanvasRegion(

            canvas,

            area

        );

    }

);

Each region is blurred independently.

Blurring the Canvas Region

The browser's Canvas API allows filters to be applied while drawing.

Set the blur filter based on the selected intensity.

context.filter =

`blur(${area.intensity}px)`;

Redraw only the selected region.

context.drawImage(

    canvas,

    area.x,

    area.y,

    area.width,

    area.height,

    area.x,

    area.y,

    area.width,

    area.height

);

After drawing, reset the filter.

context.filter = "none";

Only the selected rectangle becomes blurred while the rest of the page remains unchanged.

Blurring an Entire Page

If the user chooses Blur entire page(s), the process is much simpler.

Apply the filter to the full canvas.

context.filter =

`blur(${blurIntensity}px)`;

context.drawImage(

    canvas,

    0,

    0

);

context.filter =
"none";

The entire rendered page receives the selected blur effect.

Converting the Canvas Back into a PDF Image

After editing the canvas, convert it into an image.

const imageData =

canvas.toDataURL(
    "image/png"
);

Convert the image into bytes.

const bytes =

await fetch(imageData)

.then(

response =>

response.arrayBuffer()

);

Embed the image inside PDF-lib.

const image =

await pdfDoc.embedPng(
    bytes
);

Replace the page contents.

const pdfPage =

pages[
pageNumber - 1
];

const size =
pdfPage.getSize();

pdfPage.drawImage(

    image,

    {

        x: 0,

        y: 0,

        width:
        size.width,

        height:
        size.height

    }

);

Repeat the same process for every selected page.

Showing the Processing State

Generating large PDF files may take a few seconds.

Display a loading state while processing.

applyButton.disabled =
true;

applyButton.textContent =
"Applying...";

After processing finishes:

applyButton.disabled =
false;

applyButton.textContent =
"Apply & Finalize";

This gives users clear feedback that the application is working.

During processing:

Generating the Final PDF

After every page has been processed, save the completed document.

const pdfBytes =

await pdfDoc.save();

const outputBlob =
new Blob(

[pdfBytes],

{

type:
"application/pdf"

}

);

Store the result so it can be previewed and downloaded later.

generatedPdfBlob =
outputBlob;

At this point, the blurred PDF has been successfully generated.

Previewing the Result

Hide the editing interface and display the completed document.

editorSection.hidden =
true;

resultSection.hidden =
false;

The result screen displays:

Final PDF preview
Editable filename
Total pages
File size
Download button

The user can review the processed document before downloading it.

Renaming and Downloading

Before downloading, users may want to rename the generated file.

Create a filename field.

Validate the filename.

function getFilename() {

    let filename =
    outputFilename.value.trim();

    if (!filename) {

        filename =
        "blurred-document.pdf";

    }

    if (
        !filename
        .toLowerCase()
        .endsWith(".pdf")
    ) {

        filename += ".pdf";

    }

    return filename;

}

Display additional file information.

pageCount.textContent =

`Pages:
${finalPdfDocument.numPages}`;

fileSize.textContent =

formatFileSize(
generatedPdfBlob.size
);

Download the processed document.

downloadButton
.addEventListener(

"click",

() => {

    const url =

    URL.createObjectURL(
        generatedPdfBlob
    );

    const link =
    document.createElement(
        "a"
    );

    link.href = url;

    link.download =
    getFilename();

    link.click();

    URL.revokeObjectURL(
        url
    );

});

The browser downloads the completed PDF without sending any files to a remote server.

Demo: How the PDF Blur Tool Works

Let's walk through the complete workflow.

Step 1: Upload the PDF

Users upload a PDF using drag-and-drop or the Select PDF button.

The browser validates the file and prepares it for rendering.

Step 2: Preview the Document

The uploaded PDF appears inside the preview window.

Users can move through the document using the page navigation controls.

Step 3: Configure Blur Settings

Users choose whether to blur selected areas or entire pages.

They can also configure the blur intensity before creating any blur regions.

Step 4: Draw Blur Areas

Users click and drag directly on the PDF preview to create blur rectangles over sensitive content.

Multiple blur regions can be created on the same page.

Step 5: Adjust Blur Intensity

The blur intensity slider controls how strong the blur effect should appear.

Higher values produce a stronger blur.

Step 6: Manage Blur Regions

Individual blur areas can be removed, or all blur regions on the current page can be cleared.

This makes editing much easier before generating the final PDF.

Step 7: Choose the Pages

Users decide whether the blur should be applied to:

Current page
All pages
Specific pages

For example:

1,3-5,8

Step 8: Apply the Blur

After reviewing the settings, users click Apply & Finalize.

The application generates a new PDF containing the selected blur effects.

Step 9: Review the Final Document

The completed PDF appears in the preview window.

Users can verify every blurred region before downloading.

Step 10: Rename and Download

Finally, users rename the output file if needed and click Download.

The browser saves the completed PDF locally.

Performance Tips

Large PDF files can take longer to render and process, but a few simple optimizations can keep the editor responsive.

Render only the page the user is currently viewing instead of loading the entire document.

await renderPage(
    currentPage
);

Reuse the same canvas and redraw only the blur regions when changes are made.

overlayContext.clearRect(
    0,
    0,
    overlayCanvas.width,
    overlayCanvas.height
);

redrawBlurAreas();

During final processing, generate only the pages selected by the user.

for (const page of selectedPages) {

    await processPage(page);

}

Finally, release temporary resources after the download completes.

URL.revokeObjectURL(
    downloadUrl
);

These optimizations reduce memory usage and help the PDF Blur Tool perform smoothly, even with large multi-page documents.

Common Mistakes

One common issue is storing blur coordinates before accounting for the current zoom level.

Always convert preview coordinates into the PDF's coordinate system before generating the final document.

const scaleX =

pdfWidth /
canvas.width;

const scaleY =

pdfHeight /
canvas.height;

Another mistake is allowing blur regions to extend beyond the page boundaries.

Clamp the values before processing.

blurArea.x = Math.max(
0,
blurArea.x
);

blurArea.y = Math.max(
0,
blurArea.y
);

Users should also verify the final preview before downloading, especially when multiple blur regions exist across different pages.

Finally, remember that this project applies a visual blur effect to the rendered PDF pages. If your application requires permanent removal of sensitive content rather than visual obscuring, additional document-redaction techniques are needed.

Conclusion

In this tutorial, you built a browser-based PDF Blur Tool using JavaScript.

You learned how to upload and preview PDF documents, navigate between pages, create and manage multiple blur regions, adjust blur intensity, apply blur to selected pages, generate a new PDF with PDF-lib, preview the processed document, and download the final file – all without uploading data to a server.

By combining PDF.js, the HTML Canvas API, and PDF-lib, you created a privacy-focused PDF editing tool that runs entirely inside the browser.

You can explore the complete workflow using the PDF Blur Tool.

From here, you could extend the project with features such as movable and resizable blur regions, undo and redo support, reusable blur presets, keyboard shortcuts, touch-device editing, or additional annotation tools for even more advanced browser-based PDF editing.

How to Build an AI Agent with Function Calling in Node.js Using Google Gemini

Zia Ullah — Fri, 24 Jul 2026 18:30:52 +0000

Last year, a client asked me to add a conversational interface to their internal reporting tool. Staff would type a question, and the system would pull a live answer from the database.

I had the first version running in a day. Single questions worked. But a week in, a tester typed: "What is the weather in Berlin, and how much would 500 EUR convert to in USD right now?"

The model called the weather function, returned that answer, and ignored the second half of the question entirely.

That is the gap between a chatbot and an agent. A chatbot works from training data. That's its limit. An agent doesn't have that limit. It calls a tool, reads what came back, and decides whether to keep going.

Most questions resolve in one or two tool calls. Multi-step ones take a few more. Remove that loop, and they all break.

This tutorial shows you how to build that loop with Google Gemini's function calling API and Node.js. You'll build an agent that can call real external tools: Open-Meteo for live weather, frankfurter.app for live currency rates, and a math evaluator for calculations. All three are completely free. The only API key you need is Gemini, which is also free on Google AI Studio at 1,500 requests per day.

Everything is on GitHub: github.com/ziaongit/nodejs-gemini-agent.

How Function Calling Works
What We're Building
Prerequisites
Project Setup
Defining the Tools
Implementing the Tool Functions
Building the Agentic Loop
The CLI Entry Point
Adding an Express HTTP Server
Testing the Agent
Troubleshooting
What to Build Next

How Function Calling Works

Most LLM tutorials show function calling as: define a function, the model calls it, done. That framing skips the part that actually matters.

The model doesn't call your function. It can't. What happens is more like a negotiation.

You send the model a message along with a list of tool descriptions. Each description is a JSON schema: the function name, what it does, and what arguments it needs. Gemini reads those at request time to decide which tool, if any, fits what the user asked.

Here's the part that surprises people. Gemini doesn't run your code. It sends back a structured object that says: call get_weather, city = Berlin. Your code picks that up, runs the actual function, and sends the result back. Gemini checks whether that's enough to answer. If not, it requests another tool.

That exchange is the loop:

User message
      │
      ▼
Model + tool schemas
      │
      ▼
Response: functionCall?
      │
   YES │                          NO
      ▼                            ▼
Run the function(s)         Return text answer
      │
      ▼
Send result(s) back to model
      │
      └──── loop back ────────────┘

The loop keeps running until the model decides it has enough to answer. That's what allows it to chain calls: check the weather, see the temperature is above 25°C, then decide it should also fetch the exchange rate before answering.

There's one detail that trips people up the first time. When Gemini requests multiple tools in the same response, you run all of them and return all results in a single message. Returning them one at a time in separate messages breaks the model's turn-tracking and produces unreliable output.

What We're Building

In this tutorial, we'll build an AI agent with three working tools:

get_weather — fetches current weather for any city via Open-Meteo (free, no API key)
calculate — evaluates a math expression safely in JavaScript
get_exchange_rate — fetches live currency rates via frankfurter.app (free, no API key)

There are two ways to run it: a readline CLI for quick local testing, and an Express HTTP endpoint to wire into a real application.

Full tech stack:

Node.js 20: runtime (Node 18 minimum for native fetch)
@google/generative-ai: official Gemini SDK
dotenv: environment variable loading
Express: HTTP server for the API endpoint
Open-Meteo API: free weather and geocoding, no key required
frankfurter.app: free currency exchange rates, no key required

Architecture:

┌─────────────────────────────────────────────────┐
│                   Client                         │
│         CLI (readline) / HTTP POST               │
└──────────────────────┬──────────────────────────┘
                       │  user message
                       ▼
┌─────────────────────────────────────────────────┐
│               agent.js — Agentic Loop            │
│                                                  │
│  1. Send message + tool schemas to Gemini        │
│  2. Receive response                             │
│  3. functionCalls() present?                     │
│      YES → execute tools in parallel             │
│            send all results back                 │
│            go to step 2                          │
│      NO  → return final text answer              │
└──────────────────────┬──────────────────────────┘
                       │  tool calls
                       ▼
┌─────────────────────────────────────────────────┐
│                  Tool Handlers                   │
│                                                  │
│  get_weather(city)                               │
│    └─► geocoding-api.open-meteo.com              │
│        api.open-meteo.com                        │
│                                                  │
│  calculate(expression)                           │
│    └─► JS safe evaluator (no external call)      │
│                                                  │
│  get_exchange_rate(from, to, amount?)            │
│    └─► api.frankfurter.app                       │
└─────────────────────────────────────────────────┘

Prerequisites

Before you start, you should have:

Node.js 18 or higher — run node --version to check
A Gemini API key from aistudio.google.com — free, no card. The free tier gives you 1,500 requests a day.
You should also know how async/await works in Node.js. That's about it.

Project Setup

mkdir nodejs-gemini-agent && cd nodejs-gemini-agent
npm init -y
npm install @google/generative-ai dotenv express
mkdir src

Add a .gitignore, as you don't want .env in your repo:

node_modules/
.env

Drop a .env at the root:

GEMINI_API_KEY=your_api_key_here
PORT=3000

# Optional: override the default model (gemini-2.0-flash)
# Uncomment if you hit free-tier quota limits
# GEMINI_MODEL=gemini-2.0-flash-lite

Project structure:

nodejs-gemini-agent/
├── src/
│   ├── tools.js        ← tool schemas for Gemini
│   ├── functions.js    ← actual implementations
│   ├── agent.js        ← the agentic loop
│   ├── index.js        ← CLI entry point
│   └── server.js       ← Express HTTP server
├── .env
├── .env.example
├── .gitignore
└── package.json

Defining the Tools

Gemini can't see your code. It picks tools based entirely on the JSON schemas you pass in. Each schema has a name, a description, and the parameter definitions.

The description is what drives routing. Gemini reads it at request time to decide which tool fits the user's question. Focus on when to call the function, not just what it does.

// src/tools.js

const toolDefinitions = [
  {
    name: 'get_weather',
    description:
      'Get the current weather for a city. Returns temperature in Celsius, ' +
      'humidity percentage, and wind speed. Use this when the user asks about ' +
      'weather, temperature, or climate conditions in any location.',
    parameters: {
      type: 'OBJECT',
      properties: {
        city: {
          type: 'STRING',
          description: 'The city name, e.g. Tokyo, London, New York',
        },
      },
      required: ['city'],
    },
  },
  {
    name: 'calculate',
    description:
      'Evaluate a mathematical expression and return the numeric result. ' +
      'Use this for arithmetic, percentage calculations, or any numeric computation ' +
      'the user asks for. Do not guess at math — always call this tool.',
    parameters: {
      type: 'OBJECT',
      properties: {
        expression: {
          type: 'STRING',
          description:
            'A valid mathematical expression, e.g. "47.50 * 0.18" or "1500 / 12"',
        },
      },
      required: ['expression'],
    },
  },
  {
    name: 'get_exchange_rate',
    description:
      'Get the current exchange rate between two currencies. Can also convert ' +
      'a specific amount. Use this when the user asks about currency conversion, ' +
      'exchange rates, or how much a foreign currency amount is worth.',
    parameters: {
      type: 'OBJECT',
      properties: {
        from: {
          type: 'STRING',
          description: 'The source currency code, e.g. USD, EUR, JPY, GBP',
        },
        to: {
          type: 'STRING',
          description: 'The target currency code, e.g. USD, EUR, JPY, GBP',
        },
        amount: {
          type: 'NUMBER',
          description:
            'Amount to convert. Optional — defaults to 1 if not provided.',
        },
      },
      required: ['from', 'to'],
    },
  },
];

module.exports = { toolDefinitions };

Vague descriptions work most of the time. The problems show up at the edges. "Does currency stuff" routes fine on a simple question. It falls apart on anything ambiguous. "Get the current exchange rate between two currencies. Use this when the user asks about currency conversion." holds up. The extra words cost basically nothing. Debugging bad routing costs a lot more.

Implementing the Tool Functions

These are the actual functions that run when the model requests them. Each receives the arguments the model decided to pass, does real work, and returns a plain JavaScript object.

// src/functions.js

async function get_weather({ city }) {
  // Open-Meteo uses a two-step approach: geocode the city first, then fetch weather.
  // Both APIs are free with no key required.
  const geoUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`;
  const geoRes  = await fetch(geoUrl);
  const geoData = await geoRes.json();

  if (!geoData.results?.length) {
    return { error: `City not found: ${city}` };
  }

  const { latitude, longitude, name, country } = geoData.results[0];

  const weatherUrl =
    `https://api.open-meteo.com/v1/forecast` +
    `?latitude=${latitude}&longitude=${longitude}` +
    `¤t=temperature_2m,relative_humidity_2m,wind_speed_10m,weather_code`;

  const weatherRes  = await fetch(weatherUrl);
  const weatherData = await weatherRes.json();
  const current     = weatherData.current;

  return {
    city:        `${name}, ${country}`,
    temperature: `${current.temperature_2m}°C`,
    humidity:    `${current.relative_humidity_2m}%`,
    wind_speed:  `${current.wind_speed_10m} km/h`,
  };
}

function calculate({ expression }) {
  try {
    // Strip anything that is not a number or basic operator before eval.
    // This is not a complete sandbox — use a proper math parser like mathjs
    // in production if expressions come from untrusted users.
    const safe = expression.replace(/[^0-9+\-*/.() %]/g, '');
    if (!safe.trim()) return { error: 'Invalid or empty expression' };

    const result = Function('"use strict"; return (' + safe + ')')();
    return { expression, result };
  } catch {
    return { error: `Could not evaluate: ${expression}` };
  }
}

async function get_exchange_rate({ from, to, amount = 1 }) {
  const url  = `https://api.frankfurter.app/latest?from=${from.toUpperCase()}&to=${to.toUpperCase()}`;
  const res  = await fetch(url);
  const data = await res.json();

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

  const rate      = data.rates[to.toUpperCase()];
  if (!rate) return { error: `No rate found for ${from} → ${to}` };

  const converted = parseFloat((amount * rate).toFixed(4));

  return { from: from.toUpperCase(), to: to.toUpperCase(), rate, amount, converted };
}

module.exports = { get_weather, calculate, get_exchange_rate };

There are a few things worth pointing out here.

Open-Meteo uses geocoding before the weather fetch. Passing latitude and longitude directly to the weather endpoint is more reliable than a city name string, and the geocoding API handles misspellings reasonably well. There are two fetch calls, but that's the trade-off for accuracy.

The calculate function strips everything except digits and operators before evaluation. It narrows the injection risk, but it's not a real sandbox. If you expose this over HTTP with anonymous users, use a proper math parser like mathjs.

Frankfurter converts currency codes to uppercase before the request. Users will type "usd" or "Usd" and both should work. The API is case-sensitive on its end.

Building the Agentic Loop

This is the file everything else supports. The loop itself is about 20 lines. The rest is logging and error handling.

// src/agent.js
const { GoogleGenerativeAI } = require('@google/generative-ai');
const { toolDefinitions }    = require('./tools');
const { get_weather, calculate, get_exchange_rate } = require('./functions');

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);

// Map tool names to handler functions
const toolHandlers = { get_weather, calculate, get_exchange_rate };

async function runAgent(userMessage) {
  const model = genAI.getGenerativeModel({
    model: process.env.GEMINI_MODEL || 'gemini-2.0-flash',
    tools: [{ functionDeclarations: toolDefinitions }],
  });

  const chat = model.startChat();

  console.log(`\nUser: ${userMessage}`);
  console.log('---');

  let response = await chat.sendMessage(userMessage);
  let iterations = 0;
  const MAX_ITERATIONS = 10; // safety cap against infinite loops

  // Agentic loop
  while (iterations < MAX_ITERATIONS) {
    iterations++;
    const calls = response.response.functionCalls();

    // No tool calls — model is done, return the answer
    if (!calls || calls.length === 0) break;

    // Run all requested tools, collect results
    const toolResults = await Promise.allSettled(
      calls.map(async (call) => {
        console.log(`Calling tool: ${call.name}(${JSON.stringify(call.args)})`);

        const handler = toolHandlers[call.name];

        if (!handler) {
          return {
            functionResponse: {
              name:     call.name,
              response: { error: `Unknown tool: ${call.name}` },
            },
          };
        }

        try {
          const result = await handler(call.args);
          console.log(`Tool result: ${JSON.stringify(result)}`);
          return {
            functionResponse: {
              name:     call.name,
              response: result,
            },
          };
        } catch (err) {
          return {
            functionResponse: {
              name:     call.name,
              response: { error: err.message },
            },
          };
        }
      })
    );

    // Extract values from allSettled (fulfilled only — errors already caught above)
    const parts = toolResults
      .filter(r => r.status === 'fulfilled')
      .map(r => r.value);

    // Send all results back to the model in one message
    response = await chat.sendMessage(parts);
  }

  return response.response.text();
}

module.exports = { runAgent };

The MAX_ITERATIONS cap isn't paranoia. A model can get into a loop if a tool keeps returning an error and the model keeps retrying. 10 iterations is more than enough for any real query. A complex multi-tool question typically resolves in two or three turns.

Promise.allSettled runs all requested tools in parallel rather than sequentially. When the model requests both weather and exchange rate in the same response, they fetch simultaneously. Individual tool failures get caught inside the map rather than letting one failure abort the others.

The logging is intentional. When you're building and testing an agent, watching the tool calls happen in real time tells you whether the routing is working. Production code would route these to a structured logger instead of console output, but the information is the same.

The CLI Entry Point

require('dotenv').config() runs first so your API key loads before anything else. After that it's a standard readline loop: each line you type goes to runAgent, the response prints, and the loop waits for the next input.

// src/index.js
require('dotenv').config();
const readline     = require('readline');
const { runAgent } = require('./agent');

const rl = readline.createInterface({
  input:  process.stdin,
  output: process.stdout,
});

function ask(prompt) {
  return new Promise(resolve => rl.question(prompt, resolve));
}

async function main() {
  console.log('Gemini Agent — type your question, or "exit" to quit\n');

  while (true) {
    const input = await ask('You: ');
    if (input.toLowerCase() === 'exit') break;
    if (!input.trim()) continue;

    try {
      const answer = await runAgent(input);
      console.log(`\nAgent: ${answer}\n`);
    } catch (err) {
      console.error(`Error: ${err.message}`);
    }
  }

  rl.close();
}

main();

Adding an Express HTTP Server

The CLI is useful for testing. For integrating into an app, you need an HTTP endpoint.

// src/server.js
require('dotenv').config();
const express      = require('express');
const { runAgent } = require('./agent');

const app  = express();
const PORT = process.env.PORT || 3000;

app.use(express.json());

app.post('/agent', async (req, res) => {
  const { message } = req.body;

  if (!message || typeof message !== 'string') {
    return res.status(400).json({ error: 'message is required and must be a string' });
  }

  try {
    const answer = await runAgent(message);
    res.json({ answer });
  } catch (err) {
    console.error('[agent error]', err.message);
    res.status(500).json({ error: 'Agent failed to process the request' });
  }
});

app.listen(PORT, () => {
  console.log(`Agent server running on http://localhost:${PORT}`);
});

Start it:

node src/server.js

Call it:

curl -X POST http://localhost:3000/agent \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the weather in Paris?"}'

Response:

{
  "answer": "The current weather in Paris, France is 19°C with 65% humidity and wind speeds of 12 km/h."
}

The POST body is a plain { message } object. The response is a plain { answer } string. The agent handles the rest.

Testing the Agent

Start the CLI:

node src/index.js

The You: prompt comes from the readline in index.js. The User: line and --- separator are logged by agent.js at the start of each run. This is the same logging discussed in the agentic loop section.

Single tool — weather:

You: What's the weather in Tokyo?

User: What's the weather in Tokyo?
---
Calling tool: get_weather({"city":"Tokyo"})
Tool result: {"city":"Tokyo, JP","temperature":"31°C","humidity":"72%","wind_speed":"8 km/h"}

Agent: The current weather in Tokyo, Japan is 31°C with 72% humidity and wind speeds of 8 km/h.

Two tools — chained reasoning:

You: What is the weather in Tokyo? If it's above 20°C, convert 10000 JPY to EUR.

User: What is the weather in Tokyo? If it's above 20°C, convert 10000 JPY to EUR.
---
Calling tool: get_weather({"city":"Tokyo"})
Tool result: {"city":"Tokyo, JP","temperature":"31°C","humidity":"72%","wind_speed":"8 km/h"}

Calling tool: get_exchange_rate({"from":"JPY","to":"EUR","amount":10000})
Tool result: {"from":"JPY","to":"EUR","rate":0.006,"amount":10000,"converted":60.0}

Agent: The current temperature in Tokyo is 31°C, which is above 20°C.
Converting 10,000 JPY to EUR at the current exchange rate gives approximately 60.00 EUR.

Notice what happened: the model called get_weather, read the result (31°C), applied the conditional logic from the user's question on its own, and then called get_exchange_rate. You didn't write any of that branching logic. The model handled it from the description alone.

Calculator:

You: How much is 18% tip on a $47.50 restaurant bill?

User: How much is 18% tip on a $47.50 restaurant bill?
---
Calling tool: calculate({"expression":"47.50 * 0.18"})
Tool result: {"expression":"47.50 * 0.18","result":8.55}

Agent: An 18% tip on a $47.50 bill is $8.55, making your total $56.05.

Three tools in one query:

You: What's the weather in London and Berlin? And what is 250 GBP in EUR?

User: What's the weather in London and Berlin? And what is 250 GBP in EUR?
---
Calling tool: get_weather({"city":"London"})
Calling tool: get_weather({"city":"Berlin"})
Calling tool: get_exchange_rate({"from":"GBP","to":"EUR","amount":250})
Tool result: {"city":"London, GB","temperature":"16°C","humidity":"78%","wind_speed":"20 km/h"}
Tool result: {"city":"Berlin, DE","temperature":"22°C","humidity":"55%","wind_speed":"14 km/h"}
Tool result: {"from":"GBP","to":"EUR","rate":1.17,"amount":250,"converted":292.5}

Agent: London is currently 16°C with 78% humidity and 20 km/h winds.
Berlin is warmer at 22°C with 55% humidity and lighter winds of 14 km/h.
250 GBP converts to approximately 292.50 EUR at the current exchange rate.

All three tools ran in parallel. Promise.allSettled is why. A sequential loop would have made three serial network requests. Parallel gives you the same result in roughly the time of the slowest single request.

Troubleshooting

Here are a few common issues you might encounter, and how to fix them:

1. `[404 Not Found] models/gemini-1.5-flash is not found for API version v1beta`

The model name is outdated. Google deprecates older aliases over time. Swap it out for gemini-2.0-flash in agent.js. To check what models your key can actually access, run:

node -e "
const { GoogleGenerativeAI } = require('@google/generative-ai');
require('dotenv').config();
const g = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
g.listModels().then(r => r.models.forEach(m => console.log(m.name)));
"

2. `[429 Too Many Requests] You exceeded your current quota`

The gemini-2.0-flash free tier caps you at 1,500 requests a day. Hit that and every call returns a 429 until midnight Pacific resets the counter.

The error names the quota ID directly. GenerateRequestsPerDayPerProjectPerModel-FreeTier means you hit the daily cap. GenerateRequestsPerMinutePerProjectPerModel-FreeTier means the per-minute rate.

For the per-minute limit, the error includes a retryDelay field. Wait that many seconds and retry. For the daily limit, the quota is per-project. All models under the same project share it.

There are three ways out:

New project (fastest): head to aistudio.google.com, spin up a new project, grab a new API key, and swap it into .env. You get a fresh quota immediately.
Enable billing: billing-enabled projects get much higher limits while keeping the free usage tier. Set up at aistudio.google.com.
Wait: resets daily at midnight Pacific.

Because agent.js reads the model name from process.env.GEMINI_MODEL, you can also switch models without touching code. Add this to your .env to test with a lighter model:

GEMINI_MODEL=gemini-2.0-flash-lite

Remove the line when your quota resets and the agent goes back to gemini-2.0-flash.

3. `Error: GEMINI_API_KEY is not set`

Nine times out of ten, require('dotenv').config() is either missing or buried below other requires. Drag it to the very top of index.js. Your .env also needs to live at the project root with your actual key in it, not your_api_key_here.

4. `GoogleGenerativeAIError: 400 INVALID_ARGUMENT`

Almost always a malformed tool schema. Gemini uses uppercase type strings: 'OBJECT', 'STRING', 'NUMBER'. JSON Schema uses lowercase. Check your parameters.type values.

5. Model Answers Without Calling Any Tools

The description is too vague or the user's question doesn't match well enough for the model to route it. Add more context to the description about when the tool should be used. The phrase "use this when the user asks about X" directly improves routing accuracy.

6. `TypeError: fetch is not a function`

Node 17 and below don't have native fetch. It was added in Node 18. Run node --version to check yours.

If you can't upgrade, install it with npm install node-fetch. Every file that calls fetch then needs const fetch = require('node-fetch') as its first line.

7. Tool Works in Isolation but Agent Loop Doesn't Call it

The name in toolDefinitions must exactly match the key in toolHandlers. Case matters in JavaScript. get_Weather and get_weather are two different things.

8. Exchange Rate Returns `No rate found`

The currency code you passed isn't supported by frankfurter.app. The API covers ~30 major currencies. Check supported codes at frankfurter.app.

What to Build Next

The three tools here are a foundation. The loop works the same way regardless of how many tools you add.

Database lookup tool: A search_products function that queries your PostgreSQL table turns the agent into a product assistant. Point it at your catalog, and it can answer questions about availability, pricing, and specs without you writing any routing logic.

Write tools: get_* functions make the agent read-only. Add a create_ticket or send_notification function and the agent can take actions: file a support request, trigger a workflow, update a record. Once you add write tools, think carefully about which queries should require confirmation before executing.

Memory across sessions: Right now model.startChat() creates a fresh conversation on every call. Pass a history array when starting the chat and the model remembers prior turns. Store that history in PostgreSQL or Redis keyed to the user ID, and the agent carries context across sessions.

Streaming responses: For a UI that shows the answer as it types rather than waiting for the full response, replace chat.sendMessage with chat.sendMessageStream. The tool call loop stays the same. Only the final response delivery changes.

Swap the model: The model string in getGenerativeModel is the only thing that pins you to Gemini 2.0 Flash. gemini-2.0-flash-lite is lighter and faster for simpler queries. For stronger reasoning on complex tasks, run the listModels script from the Troubleshooting section to find the latest available models. The function calling interface is identical across all Gemini models, so swapping takes one line.

The full source code for this article is on GitHub at github.com/ziaongit/nodejs-gemini-agent.

How to Make a Static HTML Page Editable in the Browser with Vanilla JavaScript

timothy ogbemudia — Wed, 22 Jul 2026 20:22:03 +0000

When you maintain a document for someone else, such as a résumé, a one-page portfolio, or a printable menu, the bottleneck is rarely the layout. It's the edit loop.

Every small change ("move this bullet up", "delete that line", "this link is dead") goes through you, the person with the code editor, even though the person requesting the change knows exactly what they want.

I ran into this maintaining a family member's résumé as a single static HTML file. The design was done. The content was theirs. But every revision, whether it was reordering a role, adding a certification, fixing a link, or nudging a print page break, meant another round of "send me the change, I'll edit the file." After the tenth round, the fix became obvious: make the page edit itself.

In this article, you'll build an in-browser editing layer for a static HTML page using contenteditable, about a hundred lines of vanilla JavaScript, and no build step. The person editing can change any text, reorder or delete any block, add new content, edit links, control print pagination, and print to PDF. A refresh restores the original file, untouched.

Prerequisites
What You Will Learn
What Iscontenteditable?
Why Not a React App?
How to Prepare the Markup for Reordering
How to Attach Controls to Every Block
How to Show Controls Only on the Innermost Block
How to Move and Delete Blocks
How to Edit Links Insidecontenteditable
How to Let Users Control Print Pagination
How to Add New Content from Templates
Why Nothing Persists
Conclusion

Prerequisites

To follow along, you should have:

Working knowledge of HTML and CSS, including CSS Grid and @media print
Basic understanding of JavaScript DOM APIs (querySelector, event listeners, creating elements)
No frameworks, libraries, or build tools. That's the point.

What You Will Learn

What contenteditable gives you for free, and where it stops
How to attach move/delete controls to repeatable blocks with one reusable function
How to show controls only on the innermost hovered block using :has()
How to reorder DOM nodes without a framework, and the markup prep that makes it safe
How to edit link URLs inside an editable region
How to let users place print page breaks themselves
How to add new content from templates, with placeholder text pre-selected
Why "nothing persists" can be a feature, not a limitation

What Is `contenteditable`?

contenteditable is an HTML attribute that turns any element into an editable region. The browser handles the hard parts: caret placement, text selection, typing, deletion, clipboard, and undo history.

That one attribute gets you further than you might expect. Clicking any paragraph places a caret. Cmd+Z undoes typing. Pressing Enter inside a

. The browser understands list semantics natively, so "add a bullet by pressing Enter" works with zero code.

But contenteditable alone isn't an editor. It has no concept of blocks. It won't move a job entry above another one, delete a card cleanly, or change an href. Clicking a link inside an editable region just places the caret in its text. Everything structural is on you. The rest of this article is about filling that gap.

Why Not a React App?

The obvious alternative is to rebuild the page as a "real" app: components, state, a form per section, and an export button. I decided against it, and the tradeoff is important.

The file lives in a public/ folder and is served as a static asset. It works from a URL, from disk, or from an email attachment. It has no dependencies to install, no build to run, and no way to rot when a toolchain updates.

The editing needs are small and bounded: change text, move blocks, delete blocks, add blocks, and print. That's DOM manipulation, the thing the DOM API is already good at.

A framework earns its complexity when state outlives the DOM: persistence, collaboration, validation, and syncing. This page has none of those requirements. When your state is the DOM and the lifetime is one session, a framework is an extra layer that buys you nothing.

How to Prepare the Markup for Reordering

Before writing any JavaScript, look at your markup for anything positional, meaning elements that only make sense between other elements. In my case, jobs were separated by
dividers:
```
...

...
```
The moment blocks can move or be deleted, separators like this become landmines. Delete a job and its divider survives as an orphaned line. Move a job and the divider stays behind.

The fix is to delete the
elements entirely and derive the separator from adjacency:
```
.section .job + .job {
  border-top: 0.5px solid var(--rule);
  padding-top: 18px;
}
```
The sibling combinator draws a rule above every job that follows another job. Reorder them, delete them, add new ones, and the separators are always exactly where they should be, because they're computed from structure rather than stored in it. This is the same principle as deriving state instead of duplicating it, applied to CSS.

How to Attach Controls to Every Block

Each movable block gets a small control cluster with move up, move down, and delete actions, injected by one reusable function:
```
const SELECTORS = ['.section', '.job', '.bullets li', '.cert-card', '.skills-row', '.edu-row'];
const BREAKABLE = new Set(['.section', '.job']);

function makeBlock(el, sel) {
  el.classList.add('blk');
  el.dataset.sel = sel;
  const ctl = document.createElement('span');
  ctl.className = 'ctl';
  ctl.setAttribute('contenteditable', 'false');
  ctl.innerHTML =
    '' +
    '' +
    (BREAKABLE.has(sel) ? '' : '') +
    '';
  el.appendChild(ctl);
}

SELECTORS.forEach(sel => {
  page.querySelectorAll(sel).forEach(el => makeBlock(el, sel));
});
```
A few design decisions are worth calling out.

First, contenteditable="false" on the control cluster. Editable regions inherit. Everything inside the page is editable unless you opt out. Without this, the user could place a caret inside your buttons and delete them like text.

Second, el.dataset.sel records which selector matched. This matters later: when a block moves, it should only swap with siblings of its own kind. A bullet moves among bullets, a job among jobs. Storing the selector on the element makes that check trivial.

Third, the controls live inside the block they control. That gives you positioning for free, with position: absolute against the block's own position: relative, and means a block carries its controls with it wherever it moves.

How to Show Controls Only on the Innermost Block

Blocks nest: a bullet sits inside a job, which sits inside a section. Hovering a bullet technically hovers all three, and naïve CSS shows three control clusters at once. The result is visual noise exactly where the user is trying to focus.

Modern CSS solves this in one line:
```
.blk:hover:not(:has(.blk:hover)) > .ctl { display: inline-flex; }
```
Read it inside out: show a block's controls when it's hovered, unless some descendant block is also hovered, in which case that deeper block wins. Hover a bullet, you get bullet controls. Hover the job's title (outside any bullet), you get job controls. One rule, no JavaScript.

:has() is supported in every current browser, but a fallback costs one more rule:
```
@supports not selector(:has(*)) {
  .blk:hover > .ctl { display: inline-flex; }
}
```
Older browsers get the noisier all-ancestors behavior instead of no controls at all. Degrade loudly, not silently.

How to Move and Delete Blocks

With controls attached, the actual reordering is short. One delegated listener handles every button on the page:
```
function siblings(el) {
  return [...el.parentElement.children].filter(c =>
    c.classList.contains('blk') && c.dataset.sel === el.dataset.sel);
}

page.addEventListener('click', e => {
  const btn = e.target.closest('.ctl button');
  if (!btn) return;
  e.preventDefault();
  const el = btn.closest('.blk');
  const sibs = siblings(el);
  const i = sibs.indexOf(el);
  const act = btn.dataset.act;
  if (act === 'up' && i > 0) sibs[i - 1].before(el);
  else if (act === 'down' && i < sibs.length - 1) sibs[i + 1].after(el);
  else if (act === 'del') el.remove();
  else if (act === 'brk') el.classList.toggle('page-break');
});
```
siblings() is where dataset.sel pays off: it filters the parent's children down to blocks of the same kind, so a job can never swap into the middle of a bullet list. before() and after() move the live node with no cloning or re-rendering, and the block's own controls travel with it.

There's one subtle bug to prevent. Clicking a button inside an editable region moves the text caret first, which can scroll the page or collapse a selection. Suppress it at mousedown, before the browser acts:
```
page.addEventListener('mousedown', e => {
  if (e.target.closest('.ctl, .add-btn')) e.preventDefault();
});
```
Forgetting this is the kind of thing you only notice as a vague feeling that clicking buttons "jumps." It's worth ruling out before it ships.

How to Edit Links Inside contenteditable

Inside an editable region, single-clicking a link places the caret instead of navigating. That's correct for text editing but leaves no way to change the URL itself. The href isn't text, it's an attribute.

Double-click is unclaimed real estate, so hang URL editing off it:
```
page.addEventListener('dblclick', e => {
  const a = e.target.closest('a');
  if (!a) return;
  e.preventDefault();
  const url = prompt('Link URL (leave empty to remove the link):', a.getAttribute('href'));
  if (url === null) return;
  if (!url.trim()) a.replaceWith(document.createTextNode(a.textContent));
  else a.setAttribute('href', url.trim());
});
```
Yes, prompt(). It's unfashionable, but consider what a custom modal would cost: markup, styles, focus management, and an escape handler, all for a dialog that asks one question. prompt() is native, keyboard-accessible, and can't break.

The empty-string branch is a nice touch: it unwraps the link entirely, replacing it with its own text, so "remove this link" doesn't require knowing any HTML.

Since none of this is discoverable, tell the user. A title attribute on every link ("Double-click to change this link") surfaces the affordance exactly where it's needed.

How to Let Users Control Print Pagination

If the document's destination is a printed PDF, page breaks are content decisions, like "start my Skills section on page three," and the user should own them. CSS makes the break itself easy:
```
@media print {
  .page-break { break-before: page; page-break-before: always; }
  .job { break-inside: avoid; page-break-inside: avoid; }
}
```
The interesting part is the interface. The ⇟ button you saw in makeBlock just toggles the page-break class on a job or section. On screen, the class renders as a dashed accent line above the block, a visible seam showing where the printed page will end:
```
.page .page-break {
  border-top: 1.5px dashed var(--accent) !important;
  padding-top: 14px !important;
}

@media print {
  .page .page-break { border-top: none !important; padding-top: 0 !important; }
}
```
The dashed line exists only on screen. In print it vanishes and the actual break takes its place. The user toggles, glances at the seam, and prints. Nobody edits CSS to re-paginate a document, and just as importantly, nobody asks me to.

The same @media print block hides every piece of editing chrome (.toolbar, .ctl, .add-btn { display: none !important; }), so the printed output is indistinguishable from the original static page.

How to Add New Content from Templates

Editing and deleting only go so far. Eventually someone needs a new bullet, a new role, or a new certification. Each repeatable container gets a dashed "+ Add" button that builds a blank block from a template:
```
skillsSection.appendChild(newAddBtn('+ Add skill row', 'Adds a blank row. Type over the placeholder.', btn => {
  const row = document.createElement('div');
  row.className = 'skills-row';
  row.innerHTML =
    'Label' +
    'Skill one, skill two, skill three';
  skillsSection.insertBefore(row, btn);
  makeBlock(row, '.skills-row');
  selectText(row.querySelector('.skill-label'));
}));
```
Two details here do most of the work.

New blocks go through the same makeBlock as everything parsed at load. There is exactly one code path for "this is a block now", so added content is immediately movable and deletable. For roles it gets its own nested "+ Add bullet" button.

If you find yourself writing a second registration path for dynamic content, stop. You're about to fork behavior that must stay identical.

And selectText pre-selects the placeholder:
```
function selectText(node) {
  const range = document.createRange();
  range.selectNodeContents(node);
  const sel = getSelection();
  sel.removeAllRanges();
  sel.addRange(range);
}
```
Click "+ Add skill row" and the word Label is already highlighted, so typing replaces it. No clicking into the field, no manually deleting placeholder text, and no placeholders accidentally left in the printed document.

One caveat: select the text node, not the block. The block contains your contenteditable="false" control cluster, and a selection spanning it will delete your buttons along with the placeholder on the first keystroke.

Why Nothing Persists

Every edit lives in the DOM and dies on refresh. That sounds like the missing feature, but it's the design.

The workflow this page serves is: open, adjust, print to PDF, close. The PDF is the artifact. The page is a template you stamp from. Ephemerality gives you a free, bulletproof undo-everything (refresh), zero risk of a half-finished edit becoming the new baseline, and a canonical version that always matches source control.

The toolbar says it plainly: "Nothing is saved. Refresh resets everything." Stated upfront, it reads as a guarantee rather than a gotcha.

Persistence would also be the complexity cliff. The moment edits survive refresh you inherit serialization, versioning, merge conflicts with the source file, and "which copy is real?" Those are the exact problems this design exists to avoid.

Conclusion

You now have a static HTML page that edits itself: contenteditable for text, one makeBlock function for structure, :has() for focused hover controls, a class toggle for print pagination, and templates with pre-selected placeholders for new content. Around a hundred lines of JavaScript, with no dependencies and no build.

Just as important is knowing when this approach stops being right. If edits must persist, if multiple people edit concurrently, or if the content needs validation and workflow, you've outgrown the DOM-as-state model. In those cases, reach for a real application and a database.

But for the wide middle ground of documents that one person adjusts and prints, such as résumés, invoices, certificates, and programmes, the browser already ships the editor. You just have to turn it on.

How to Build a Reusable Date-Time Picker in React with shadcn/ui

Vaibhav Gupta — Wed, 22 Jul 2026 16:47:40 +0000

A date and time picker is one of those components that looks small in a design file and turns into a real time sink once you start building it. You need a calendar, a time selector, a state that keeps both in sync, and usually a range mode and a translated version somewhere down the line, too.

This guide walks through ready-made picker patterns you can drop into a React project today: a combined date and time picker, a date range picker, and a time picker.

Every one of these is available as a Shadcn Date Picker component you can install with a single CLI command instead of building from scratch.

These components are built on both Radix and Base UI primitives, and the versions below use Base UI. They also support copy-prompt functionality, so you can paste them straight into v0, Lovable, or Bolt if that's part of your workflow.

Prerequisites
What You'll Build
How to Install a Shadcn Date Time Picker
How to Build a Date and Time Picker
How to Build a Date Range Picker
How to Build a Time Picker
Live Preview of the components
Key Concepts Recap
Conclusion
Resources

Prerequisites

To follow along, you should know:

The basics of React, including useState and props
How to install components with the shadcn/ui CLI
Basic Tailwind CSS class names

You also need a React project with shadcn/ui already set up. If you haven't done that yet, run the shadcn/ui CLI setup command in your project before continuing.

What You'll Build

A DateTimePicker component that combines a calendar and time slots into one value.
A TimePicker variant that reuses the same time-slot logic without a calendar.
A DateRangePicker that lets a user pick a start and end date.

How to Install a Shadcn Date Time Picker

All the components below install through the same CLI pattern. Pick the package manager you use:

pnpm

pnpm dlx shadcn@latest add @shadcn-space/date-picker-01

npm

npx shadcn@latest add @shadcn-space/date-picker-01

yarn

yarn dlx shadcn@latest add @shadcn-space/date-picker-01

bun

bunx --bun shadcn@latest add @shadcn-space/date-picker-01

Every other component below installs the same way: just swap the package name at the end of the command. If you haven't set up the CLI in your project yet, this getting-started guide covers that first and shows how to integrate these components when you're working through an MCP-connected editor.

How to Build a Date and Time Picker

This is the combined picker: a calendar popover for the date, plus start and end time fields, wrapped around a booking confirmation flow.

Folder structure:

components
└── shadcn-space
    └── date-picker
        └── date-picker-01.tsx

Component code:

"use client";
import { useState } from "react";
import { format } from "date-fns";
import { CalendarIcon, Clock, ChevronDown, Check } from "lucide-react";
import { cn } from "@/lib/utils";

import { Button } from "@/components/ui/button";
import { Calendar } from "@/components/ui/calendar";
import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";

const DateAndTimePickerDemo = () => {
  const [open, setOpen] = useState(false);
  const [date, setDate] = useState(undefined);
  const [bookingStatus, setBookingStatus] = useState<
    "idle" | "loading" | "success"
  >("idle");

  const handleBooking = () => {
    setBookingStatus("loading");
    setTimeout(() => setBookingStatus("success"), 1500);
  };

  return (
    <>
      
        
          
            Select Date
          
          
             setBookingStatus("idle")}
              render={
                
              }
            />
            
               {
                  setDate(d);
                  setOpen(false);
                }}
                className="rounded-md border-none"
              />
            
          
        

        
          
            
               Start Time
            
            
          
          
            
               End Time
            
            
          
        

        
      
    
  );
};

export default DateAndTimePickerDemo;

How This Component Works

This component combines three pieces of state into a simple booking flow:

The selected date
Start and end times
The booking status (idle, loading, success)

The date is stored using React state:

const [date, setDate] = useState(undefined);

When a user selects a day from the calendar, the onSelect callback updates the state and closes the popover:

onSelect={(d) => {
  setDate(d);
  setOpen(false);
}}

The calendar itself lives inside a Popover, which keeps the UI compact. Clicking the trigger button opens the calendar panel:

The displayed date uses date-fns formatting:

format(date, "PPP")

This converts a JavaScript Date object into a readable format such as:

July 22, 2026

The time fields use native HTML inputs:

Native time inputs provide built-in browser support, mobile pickers, keyboard accessibility, and locale-aware formatting without additional libraries.

The booking button demonstrates how UI state can change during an async action:

"idle" → "loading" → "success"

In a real application, handleBooking() would typically call an API endpoint instead of using setTimeout.

This pattern works well for:

Meeting schedulers
Appointment systems
Interview booking tools
Event registration forms
SaaS scheduling workflows

How to Build a Date Range Picker

For anything involving a stay, a rental, or a multi-day booking, you need a range instead of a single date. This component pairs a two-month calendar view with a formatted range label and a computed night count.

Folder structure:

components
└── shadcn-space
    └── date-picker
        └── date-picker-02.tsx

Install this Shadcn Date Range Picker with:

npx shadcn@latest add @shadcn-space/date-picker-02

Component code:

"use client";
import * as React from "react";
import { CalendarIcon, ChevronDown } from "lucide-react";
import { addDays, format } from "date-fns";
import { DateRange } from "react-day-picker";

import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import { Calendar } from "@/components/ui/calendar";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";
import { Label } from "@/components/ui/label";

const DateRangePickerDemo = () => {
  const [date, setDate] = React.useState({
    from: new Date(),
    to: addDays(new Date(), 7),
  });

  return (
    
      
        Select Travel Dates
      
      
        
          
                
                {date?.from ? (
                  date.to ? (
                    <>
                      {format(date.from, "LLL dd, y")} -{" "}
                      {format(date.to, "LLL dd, y")}
                    
                  ) : (
                    format(date.from, "LLL dd, y")
                  )
                ) : (
                  Pick a range
                )}
                
              
            }
          />
          
            
          
        
      
      
        {date?.from && date?.to
          ? `Stay duration: ${Math.round((date.to.getTime() - date.from.getTime()) / (1000 * 60 * 60 * 24))} nights`
          : "Please select a valid date range."}
      
    
  );
};

export default DateRangePickerDemo;

How the Date Range Picker Works

This version switches the Calendar component from single-date mode to range mode:

mode="range"

Instead of storing one Date, the component stores a DateRange object:

{
  from: Date,
  to: Date
}

This makes it easy to work with booking systems, hotel stays, travel forms, and rental applications.

The component displays two calendar months:

numberOfMonths={2}

Showing two months reduces navigation and improves the selection experience for longer stays.

The stay duration is calculated directly from the selected dates:

(date.to.getTime() - date.from.getTime())

This avoids additional libraries and keeps the logic simple.

Compared to the first example:

Uses DateRange instead of a single Date
Uses mode="range"
Displays two months
Adds derived data like total nights

How to Build a Time Picker

Not every form needs a calendar. This one wraps the native in an InputGroup with a clock icon that triggers the browser's own time picker UI on click.

Folder structure:

components
└── shadcn-space
    └── date-picker
        └── date-picker-03.tsx

Install this Shadcn Time Picker with:

npx shadcn@latest add @shadcn-space/date-picker-03

Component code:

"use client";
import { useRef } from "react";
import { Label } from "@/components/ui/label";
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
} from "@/components/ui/input-group";
import { Clock8Icon } from "lucide-react";

const TimePickerWithIconDemo = () => {
  const inputRef = useRef(null);

  const handleShowPicker = () => {
    if (inputRef.current && "showPicker" in inputRef.current) {
      try {
        inputRef.current.showPicker();
      } catch (error) {
        console.error("Failed to open native picker:", error);
      }
    }
  };

  return (
    
      Select Slot
      
        
          
        
        
      
    
  );
};
export default TimePickerWithIconDemo;

How the Time Picker Works

This component uses the browser's native time picker instead of building a custom dropdown.

The input is referenced with useRef:

const inputRef = useRef(null);

This allows the icon button to access the input element directly.

When users click the clock icon, the browser's picker opens programmatically:

inputRef.current.showPicker();

The showPicker() method is a modern browser API that opens the same interface users would see if they clicked the input manually.

The component wraps the input inside an InputGroup:

This creates a cleaner layout where the icon behaves as part of the field rather than a separate button.

The browser's default picker icon is hidden:

[&::-webkit-calendar-picker-indicator]:hidden

This prevents duplicate icons and gives full control over the UI.

The benefit of this approach is that it keeps:

Native accessibility
Mobile keyboard support
Locale-aware formatting
Better browser compatibility

Instead of rebuilding time selection from scratch, the component improves the native experience with custom styling.

Live Preview of the Components

Key Concepts Recap

Pick the pattern that matches the data you're collecting: A single date and time for bookings, a range for stays, a bare time field for slots.
Every component installs the same way: One CLI command per component: pnpm, npm, yarn, and bun. All are supported. Adding a new picker to a project takes one line, not a manual build.
The date and time picker separates date state from time state, then combines them at the confirmation step. This keeps the calendar and the time inputs from getting out of sync.
The range picker leans on the Calendar's built-in mode="range": The two-month view and the night count come from the selection state, not custom range math.
The time picker wraps the native instead of replacing it: This keeps native accessibility and mobile keyboard behavior intact.

Conclusion

You now have working picker patterns for React: a date and time picker for bookings, a date range picker for stays, and a plain time picker for slots.

Each one installs with a single CLI command, so you can pick whichever one matches the form you're building and have it running in minutes.

Resources

shadcn/ui documentation: For the official Popover, Calendar, and Button component APIs
date-fns documentation: For the date helper functions and locale files used in this tutorial
react-day-picker documentation: For the range and multi-date selection modes that power the shadcn/ui Calendar
MDN: ARIA live regions: For more on how role="alert" works
Shadcn Date Time Picker components: If you want more prebuilt date and time picker variants to compare against.
Full Shadcn components library: For other shadcn/ui-compatible components
Guide to free Shadcn date and time pickers

How to Use Apple’s Foundation Models in a Web App with a macOS Companion

Balogun Wahab — Mon, 20 Jul 2026 21:27:11 +0000

Not every AI feature needs a cloud model, with its per-token bills, network round-trips, and private data leaving your machine. If you're on a modern Mac, a capable language model is already on your disk.

Foundation Models is Apple's Swift framework for working with large language models. It's the on-device model behind Apple Intelligence, Apple's Private Cloud Compute, or another provider's server model.

This tutorial targets the on-device model: you send it a prompt and it runs entirely on the Mac's own hardware locally, free-per-call, and offline-friendly.

Paired with Apple Vision for reading images on device, that's enough to build real AI features like summaries, classification, and structured extraction without the data ever leaving your machine.

What You Will Build
Prerequisites
Why a macOS Companion App?
Foundation Models Can't Read Images Directly
Project Structure
Build the React App
Build the macOS Companion App
Check Foundation Models Availability
Extract Text with Apple Vision
Ask Foundation Models to Explain the Vision Output
Return JSON to the Browser
Run the App
Conclusion
Resources

What You Will Build

You'll build Vision Bridge, a web app that sends an image to a local macOS companion. The companion reads the image with Apple Vision, reasons about it with Foundation Models, and returns structured JSON to the browser: private, on-device AI behind a plain web interface.

You can find the complete source code in this GitHub repository: github.com/03balogun/vision-bridge.

The goal isn't to build a giant product but rather to understand the architecture behind how this works.

Vision Bridge has two parts:

A React app with a split-screen interface.
A macOS companion app that exposes a local API.

The React app has:

An image upload area
An image preview
Automatic analysis after upload
A JSON output viewer
A companion health status indicator

The macOS companion app has:

GET /v1/health
POST /v1/analyze-image
Apple Vision OCR
Foundation Models availability checks
Foundation Models reasoning over Vision output

The final response looks like this:

{
  "support": {
    "visionAvailable": true,
    "foundationModelAvailable": true,
    "foundationModelStatus": "available"
  },
  "image": {
    "filename": "screenshot.png",
    "contentType": "image/png",
    "byteCount": 1048576,
    "width": 1440,
    "height": 900
  },
  "vision": {
    "detectedText": [
      {
        "text": "Build failed",
        "confidence": 0.96,
        "boundingBox": {
          "x": 0.12,
          "y": 0.31,
          "width": 0.45,
          "height": 0.08
        }
      }
    ]
  },
  "model": {
    "summary": "The image appears to show a software build failure.",
    "description": "A developer tool window is showing an error state with diagnostic text.",
    "suggestedTags": ["screenshot", "developer-tool", "error"],
    "possibleUses": [
      "Generate alt text",
      "Summarize screenshots",
      "Extract document data"
    ]
  }
}

Prerequisites

To follow along, you need:

macOS 26 or newer
Xcode with the macOS 26 SDK
Node.js 20 or newer
Basic React knowledge
Basic Swift knowledge
A Mac that supports Apple Intelligence

Foundation Models availability depends on the Mac, the OS version, and Apple Intelligence settings. The companion checks this at runtime, which we'll cover below.

Why a macOS Companion App?

You can't write this in a regular React app:

import FoundationModels from "apple-frameworks";

That API doesn't exist in the browser. A native macOS app, however, can use any Apple framework, so the companion acts as a local bridge. The same pattern works for any native capability the web platform doesn't expose.

Foundation Models Can't Read Images Directly

The public Foundation Models framework is a language model interface. It doesn't currently expose direct image input the way a multimodal cloud model might, so this tutorial never sends the image to the model. Instead, the companion feeds the Vision OCR observations and image metadata into the prompt. The model reasons over structured text, never the original pixels.

That split plays to each framework's strength: Vision is excellent at pulling machine-readable information out of images, and Foundation Models turns that information into summaries, labels, explanations, and structured output.

The above diagram shows the round trip that the rest of this tutorial builds. The browser sends the uploaded image as base64 JSON over localhost to the Swift companion. Inside the companion, Apple Vision runs OCR on the image and produces text observations: the recognized strings, their confidence scores, and their bounding boxes.

Those observations, not the image itself, are formatted into a prompt for Foundation Models, which generates a summary, description, and tags. The companion then bundles the Vision output and the model output into one JSON response and returns it to the browser.

Project Structure

Create a project with this structure:

vision-bridge/
  apps/
    web/
      src/
        main.tsx
        styles.css
      package.json
      vite.config.ts
    macos-companion/
      Package.swift
      Sources/
        VisionBridgeCompanion/
          main.swift
  package.json
  README.md

The root package.json gives us a few convenient commands:

{
  "scripts": {
    "dev": "npm --workspace apps/web run dev",
    "build": "npm --workspace apps/web run build",
    "companion": "swift run --package-path apps/macos-companion VisionBridgeCompanion"
  },
  "workspaces": ["apps/web"]
}

Build the React App

The web app is intentionally simple. It has one job: let the user pick an image and show the JSON returned by the companion.

The web app uses Vite, React, Lucide icons, and a JSON viewer:

{
  "dependencies": {
    "@vitejs/plugin-react": "^6.0.3",
    "lucide-react": "^0.468.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-json-view-lite": "^2.5.0",
    "vite": "^8.1.3"
  }
}

After defining the dependencies, install them:

npm install

The API base URL points to the local companion:

const API_BASE_URL = "http://127.0.0.1:43119";

Check Companion Health

The web app pings the companion so the UI can show whether the native bridge is online:

async function checkHealth() {
  setHealthError(null);

  try {
    const response = await fetch(`${API_BASE_URL}/v1/health`);
    if (!response.ok) {
      throw new Error(`Health check failed with ${response.status}`);
    }

    const payload = await response.json();
    setHealth(payload);
  } catch (error) {
    setHealth(null);
    setHealthError(error instanceof Error ? error.message : "Companion unavailable");
  }
}

Convert the Image to Base64

When the user selects a file, the app converts it to base64 so it can be sent as JSON:

function readFileAsBase64(file: File) {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => {
      const result = String(reader.result);
      resolve(result.includes(",") ? result.split(",")[1] : result);
    };
    reader.onerror = () => reject(reader.error);
    reader.readAsDataURL(file);
  });
}

This isn't the only way to upload files. You could also use multipart/form-data, but JSON keeps the demo easy to inspect.

Analyze Immediately After Upload

The app starts analysis as soon as an image is uploaded:

async function handleFile(file: File) {
  if (!file.type.startsWith("image/")) {
    setError("Choose a PNG, JPEG, HEIC, or another browser-readable image.");
    return;
  }

  const base64 = await readFileAsBase64(file);
  const nextImage = {
    file,
    previewUrl: URL.createObjectURL(file),
    base64,
  };

  setSelectedImage(nextImage);
  setAnalysis(null);
  setError(null);
  setCopied(false);

  analyzeImage(nextImage);
}

handleFile does the preparation work for every new image. It rejects anything that isn't a browser-readable image, converts the file to base64, and builds a single object holding everything the rest of the flow needs: the original File (for its name and MIME type), an object URL for the preview, and the base64 payload for the API call.

It then clears out the previous run the old analysis, any error message, and the "copied" indicator so the UI never shows results from the last image next to a new one. Finally, it kicks off analyzeImage(nextImage) immediately.

Note that it passes the fresh object directly instead of relying on the selectedImage state: React state updates don't apply until the next render, so reading the state here would still give you the previous image.

The Analyze button still exists in the UI, but it works as a manual rerun button.

Send the Image to the Companion

Here's the core request:

const analysisRequestId = useRef(0);

async function analyzeImage(image = selectedImage) {
  if (!image) {
    setError("Choose an image first.");
    return;
  }

  const requestId = analysisRequestId.current + 1;
  analysisRequestId.current = requestId;

  setRequestState("loading");
  setError(null);
  setCopied(false);

  try {
    const response = await fetch(`${API_BASE_URL}/v1/analyze-image`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        filename: image.file.name,
        mimeType: image.file.type || "application/octet-stream",
        base64: image.base64,
      }),
    });

    const payload = await response.json();

    if (requestId !== analysisRequestId.current) {
      return;
    }

    if (!response.ok) {
      throw new Error(payload.error?.message ?? `Analysis failed with ${response.status}`);
    }

    setAnalysis(payload);
    setRequestState("success");
  } catch (error) {
    if (requestId !== analysisRequestId.current) {
      return;
    }

    setRequestState("error");
    setError(error instanceof Error ? error.message : "Could not analyze image");
  }
}

This function is the entire client side of the bridge. It flips requestState to loading (which drives the spinner and disables the button), then sends a POST to /v1/analyze-image with a JSON body containing three fields: the filename, the MIME type, and the base64 image data. That body maps one-to-one onto the AnalyzeImageRequest struct the Swift companion decodes later.

Notice that the response is parsed as JSON before checking response.ok. That's deliberate: when the companion rejects a request (bad base64, oversized image), it still returns a JSON body with an error.message field, so the UI can show the companion's own explanation instead of a generic status code. On success, the payload goes straight into state, and the JSON viewer re-renders with the result.

The requestId bookkeeping guards against stale responses. If a user uploads a second image while the first is still analyzing, whichever request finishes last would win, and OCR plus model generation takes long enough that responses can genuinely arrive out of order. So every call increments a counter stored in a ref and remembers its own ID.

After the await, it checks whether it's still the newest request; if a newer upload started in the meantime, the older response is silently discarded instead of overwriting the latest image's result. The same check runs in the catch block, so an old failure can't clobber a newer success either. If you also want to cancel the in-flight HTTP request rather than just ignore its result, an AbortController is the natural next step.

Render the JSON Output

The output pane uses react-json-view-lite:

Build the macOS Companion App

The companion is a Swift command-line app. It exposes a small local HTTP API.

If you come from the web side, the mapping is simple: Swift Package Manager is Swift's npm, Package.swift is its package.json, and swift run is its npm start. It ships with Xcode, so there's nothing extra to install.

The Package.swift file looks like this:

// swift-tools-version: 6.0

import PackageDescription

let package = Package(
    name: "VisionBridgeCompanion",
    platforms: [
        .macOS("26.0")
    ],
    products: [
        .executable(
            name: "VisionBridgeCompanion",
            targets: ["VisionBridgeCompanion"]
        )
    ],
    targets: [
        .executableTarget(
            name: "VisionBridgeCompanion"
        )
    ]
)

The companion imports the Apple frameworks it needs:

import Foundation
import FoundationModels
import ImageIO
import Network
import Vision

It listens on 127.0.0.1:43119:

private let defaultPort: UInt16 = 43119

The app exposes two routes:

switch (request.method, request.path) {
case ("GET", "/v1/health"):
    let health = HealthResponse(support: ModelSupport.current)
    return try json(health)

case ("POST", "/v1/analyze-image"):
    let payload = try JSONDecoder().decode(AnalyzeImageRequest.self, from: request.body)
    let response = try await service.analyze(payload)
    return try json(response)

default:
    return try json(
        ErrorResponse(error: APIErrorPayload(message: "Route not found")),
        status: .notFound
    )
}

This switch is the companion's entire routing layer — no web framework, just pattern matching on the method and path.

The two routes split the work cleanly:

GET /v1/health is the cheap, read-only route. It runs no analysis, it just reports whether Vision and Foundation Models are usable on this Mac via ModelSupport.current (covered in the next section). The React app calls it on load to render the online/offline status pill, so the user knows the bridge is up before they upload anything.
POST /v1/analyze-image is where the real work happens. It decodes the request body into an AnalyzeImageRequest (with the same filename, mimeType, and base64 fields the browser sent) and hands it to the analysis service. This validates the image, runs Vision OCR, prompts Foundation Models, and returns the combined result. The try await matters here: analysis is asynchronous, and the route simply waits for it before serializing the response.

Anything else falls through to a JSON 404, so even unknown routes respond in the same format the browser already knows how to parse.

Errors work the same way: thrown errors are caught in one place and converted into JSON error responses with an appropriate status code, which is exactly what the web app's payload.error?.message check reads.

One practical detail: because the browser calls the companion from a different origin (the Vite dev server), every response also carries CORS headers, and the router answers preflight OPTIONS requests with an empty 204. Without that, the browser would block the fetch before it ever reached these routes.

Check Foundation Models Availability

The companion shouldn't assume that the model is available. Check it first:

private struct ModelSupport: Encodable {
    let visionAvailable: Bool
    let foundationModelAvailable: Bool
    let foundationModelStatus: String

    static var current: ModelSupport {
        let model = SystemLanguageModel.default

        switch model.availability {
        case .available:
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: true,
                foundationModelStatus: "available"
            )

        case .unavailable(let reason):
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: false,
                foundationModelStatus: "unavailable.\(reason.description)"
            )

        @unknown default:
            return ModelSupport(
                visionAvailable: true,
                foundationModelAvailable: false,
                foundationModelStatus: "unavailable.unknown"
            )
        }
    }
}

A user might have an unsupported Mac, Apple Intelligence might be disabled, or the model might not be ready yet. The response tells the browser which case it's dealing with.

Extract Text with Apple Vision

The companion decodes the base64 image, checks its metadata, then runs Vision OCR.

Here's the text recognition flow:

private func recognizeText(in imageData: Data) async throws -> [DetectedText] {
    var request = RecognizeTextRequest()
    request.recognitionLevel = .accurate
    request.automaticallyDetectsLanguage = true
    request.usesLanguageCorrection = true

    let observations = try await request.perform(on: imageData)

    var detectedText: [DetectedText] = []

    for observation in observations {
        guard let candidate = observation.topCandidates(1).first else {
            continue
        }

        let bounds = NormalizedBox.from(points: [
            observation.topLeft,
            observation.topRight,
            observation.bottomRight,
            observation.bottomLeft
        ])

        detectedText.append(DetectedText(
            text: candidate.string,
            confidence: Double(candidate.confidence),
            boundingBox: bounds
        ))
    }

    return detectedText
}

Vision gives us structured observations:

recognized text
confidence scores
normalized bounding boxes

Those observations become the model’s context.

Ask Foundation Models to Explain the Vision Output

Now the companion creates a prompt from the image metadata and OCR results.

Notice the instruction:

You cannot see the original image. Use only the metadata and OCR observations below.

That keeps the model honest. It shouldn't pretend to see pixels it never received.

Here's the prompt shape:

let textPreview = detectedText
    .prefix(30)
    .map { "- \($0.text) (confidence: \(String(format: "%.2f", $0.confidence)))" }
    .joined(separator: "\n")

let prompt = """
You are summarizing Apple Vision OCR output for a developer tool named Vision Bridge.
You cannot see the original image. Use only the metadata and OCR observations below.

Image:
- filename: \(image.filename)
- content type: \(image.contentType)
- size: \(image.width ?? 0)x\(image.height ?? 0)

OCR observations:
\(textPreview.isEmpty ? "- No text detected." : textPreview)

Return a compact JSON object with these exact keys:
summary: one sentence
description: one short paragraph
suggestedTags: 3 to 6 short tags
possibleUses: 3 to 5 practical use cases for this kind of image analysis
"""

Then call the model:

let session = LanguageModelSession(
    model: .default,
    instructions: "Return valid JSON only. Do not include Markdown fences."
)

let response = try await session.respond(to: prompt)
let raw = response.content.trimmingCharacters(in: .whitespacesAndNewlines)

Even when you ask for JSON, always validate the output. Models can still return Markdown fences or malformed text. The sample app strips simple Markdown code fences and falls back to a raw response if parsing fails.

Return JSON to the Browser

The companion combines the support state, image metadata, Vision results, and model output:

return AnalyzeImageResponse(
    support: support,
    image: metadata,
    vision: VisionPayload(detectedText: detectedText),
    model: modelInsight
)

The browser doesn't need to know how Vision or Foundation Models work. It just receives JSON. The native app owns the native capabilities, while the web app owns the interface.

It's worth pausing on what each of the four blocks actually gives you, because they're not all the same kind of data:

support tells you what was possible on this Mac. If foundationModelAvailable is false, the model block still exists but contains a fallback message rather than real analysis, and the foundationModelStatus string (for example, unavailable.appleIntelligenceNotEnabled) tells the UI why, so it can explain rather than silently degrade.
image echoes back the file's metadata plus the measured pixel dimensions. It's useful as a sanity check, and you need the width and height to do anything spatial with the Vision results.
vision is the ground truth. Each entry in detectedText is a string Vision actually found, with a confidence score between 0 and 1 and a normalized bounding box: coordinates expressed as fractions of the image size, so x: 0.12, width: 0.45 means "starts 12% from the left and spans 45% of the width." Because the boxes are normalized, you can draw highlight overlays on the preview at any display size by multiplying by the rendered dimensions. Low-confidence entries are worth filtering or flagging before you trust them.
model is interpretation, not observation. The summary, description, suggestedTags, and possibleUses fields are generated by the language model from the OCR text. This is useful as alt text, captions, or tag suggestions, but they inherit whatever the OCR missed and should be treated as a draft, not a fact. When the model's output can't be parsed as JSON, rawResponse carries the unparsed text so nothing is lost.

For a screenshot of a failed build, the model block might come back like this:

{
  "model": {
    "summary": "The image appears to show a software build failure.",
    "description": "A developer tool window is showing an error state with diagnostic text.",
    "suggestedTags": ["screenshot", "developer-tool", "error"],
    "possibleUses": [
      "Generate alt text",
      "Summarize screenshots",
      "Extract document data"
    ]
  }
}

That combination (exact text with positions from Vision, plus a human-readable interpretation from the model) is enough to build real features on top of a searchable screenshot library indexed by detectedText and suggestedTags, automatic alt text for uploaded images, or click-to-highlight overlays powered by the bounding boxes.

And because the prompt lives in the companion, changing what comes back (say, extracting line items from receipts instead of tagging screenshots) is a prompt edit, not an architecture change.

Run the App

Start the companion:

npm run companion

In another terminal, start the web app:

npm run dev

Open the Vite URL:

http://127.0.0.1:5173

If that port is busy, Vite will choose another one.

The companion should be available at:

http://127.0.0.1:43119

You can test it directly:

curl http://127.0.0.1:43119/v1/health

Expected response:

{
  "app": "Vision Bridge Companion",
  "ok": true,
  "support": {
    "foundationModelAvailable": true,
    "foundationModelStatus": "available",
    "visionAvailable": true
  },
  "version": "0.1.0"
}

Conclusion

You now have a React interface that uploads an image, a Swift companion that analyzes it with Apple-native frameworks, and structured JSON flowing between them.

Vision Bridge is intentionally small, but the bridge itself is reusable. Once you have a trusted native companion, a web app can do more than send prompts to a remote model: it can ask the Mac to work with local context, use any Apple framework, and return structured data the browser can render, store, or sync.

Resources

How to Build a Browser-Based PDF Signature Tool Using JavaScript

Bhavin Sheth — Mon, 20 Jul 2026 20:47:13 +0000

PDF documents are commonly used for agreements, forms, approvals, invoices, reports, applications, and other documents that may need a signature or additional text before they are shared.

A traditional workflow often involves printing the document, signing it by hand, scanning it again, and sending the new file. For a simple electronic signature, that process adds unnecessary steps.

In this tutorial, you'll build a browser-based PDF Signature Tool using JavaScript. Users will be able to upload a PDF, preview and navigate its pages, and add content directly to the document.

The application will support two main element types: Signature and Text/Stamp.

For signatures, users can draw directly in the browser, type their name and choose a signature style, or upload an existing signature image. For text-based elements, they can enter custom text or use preset stamps such as APPROVED, CONFIDENTIAL, DRAFT, and PAID.

After creating an element, users can position it on the PDF preview and adjust properties such as scale, rotation, opacity, font size, and color. The element can then be applied to the current page, every page, or a specific set of pages.

Once processing is complete, the application generates a new PDF for review. Users can preview the result, rename the output file, check its page count and file size, and download it directly from the browser.

The project uses PDF.js for document rendering and PDF-lib for modifying and generating the final PDF.

By the end of this tutorial, you'll understand how to build an interactive PDF editing workflow that combines canvas-based input, image embedding, text placement, coordinate conversion, page selection, and client-side file generation.

What We'll Cover:

What This PDF Signature Tool Can Do
Electronic Signatures vs Digital Signatures
How the Browser-Based Workflow Works
Project Setup
What Libraries Are We Using?
Uploading and Previewing the PDF
Choosing an Element to Add
Creating a Signature
Drawing a Signature
Typing a Signature
Uploading a Signature Image
Adding Text and Preset Stamps
Positioning and Styling the Element
Applying the Element to Selected Pages
Applying and Finalizing the PDF
Generating the Signed PDF
Previewing the Final PDF
Renaming and Downloading the Final PDF
Demo: How the PDF Signature Tool Works
Handling Signature Transparency
Important Notes and Common Mistakes
Conclusion

What This PDF Signature Tool Can Do

The application provides a single editing workflow for adding signatures, text, and common document stamps to PDF pages.

When Signature is selected, users can create the signature in three different ways.

The Draw option provides a canvas where the user can write a signature using a mouse, trackpad, stylus, or touch input.
The Type option converts entered text into a signature-style element. Users can type their name, adjust the size, and choose from the available signature styles.
The Upload option accepts an existing signature image. This is useful for someone who already has a transparent PNG or another supported image of their handwritten signature.

The second element type is Text/Stamp. Users can enter custom text such as:

Signed on: 08-09-2025

They can also quickly choose a predefined stamp:

APPROVED
CONFIDENTIAL
DRAFT
PAID

After an element has been created, the application provides controls for its placement and appearance. Users can move it to the required location and adjust its scale, rotation, opacity, and position.

Text and stamp elements can additionally use configurable font sizes and colors.

The page controls determine where the selected element will be applied. A signature may belong only on the final page of a contract, while a CONFIDENTIAL stamp may need to appear on every page.

The application therefore supports:

Current page only
All pages
Specific pages

The goal is to provide one consistent workflow for several common PDF editing tasks without requiring separate tools for each element type.

Electronic Signatures vs Digital Signatures

Before building the application, it's important to distinguish between an electronic signature and a digital signature.

The tool in this tutorial creates an electronic signature workflow.

A drawn signature, typed signature, or uploaded signature image is placed visually onto the PDF page. This is similar to signing a document by hand and inserting a visible representation of that signature into the file.

For example, a user might draw a signature on a canvas:

const signatureImage =
    signatureCanvas.toDataURL("image/png");

The generated image can then be embedded into the PDF.

A digital signature is technically different.

Certificate-based digital signatures use cryptographic methods to help verify document integrity and the identity associated with a signing certificate. They may involve digital certificates, private keys, signature validation, and trust chains.

Simply placing a handwritten signature image on a PDF doesn't create that type of cryptographic verification.

This distinction matters because the terms are sometimes used interchangeably in everyday conversation even though the underlying technologies are different.

The project we're building focuses on visual electronic signatures and document elements. It doesn't create certificate-based cryptographic digital signatures.

Keeping that distinction clear makes it easier to understand exactly what the application does and what would require a more advanced signing system.

How the Browser-Based Workflow Works

The process begins when a user selects a PDF file.

PDF.js loads the document and renders the current page into a browser canvas. Previous and next buttons allow the user to navigate through the PDF before choosing where to place an element.

The user then selects one of two element types:

Signature
Text/Stamp

If Signature is selected, the application provides three creation methods:

Draw
Type
Upload

The selected signature is converted into an element that can be displayed over the PDF preview.

If Text/Stamp is selected, the application instead creates a text element using either custom content or one of the predefined stamp values.

The complete workflow looks like this:

Upload PDF
    ↓
Render and Navigate Pages
    ↓
Choose Signature or Text/Stamp
    ↓
Create the Element
    ↓
Position and Style It
    ↓
Choose Target Pages
    ↓
Apply & Finalize
    ↓
Generate the New PDF
    ↓
Preview the Result
    ↓
Rename and Download

During editing, the element displayed over the PDF preview is only a browser-side representation. Its position must later be translated into coordinates that match the actual PDF page.

For example, the application may store an element like this:

const element = {
    type: "signature",
    x: 622,
    y: 496,
    scale: 1.14,
    rotation: 0,
    opacity: 1
};

When the user clicks Apply & Finalize, those values are used to calculate the final placement inside the PDF.

This separation between the interactive preview and the final PDF generation is the foundation of the project. It allows users to visually prepare the document first and create the modified PDF only after the placement is ready.

Project Setup

To keep the project easy to understand, we'll use three main files:

pdf-signature-tool/
│
├── index.html
├── style.css
└── script.js

The HTML file contains the upload interface, PDF preview, editing controls, final preview, and download section.

The CSS file handles the layout and visual states.

The JavaScript file manages PDF loading, page rendering, signature creation, text and stamp elements, positioning, final PDF generation, and downloading.

Start with the basic HTML structure:





    

    

    PDF Signature Tool

    





    

        

            PDF Signature Tool

            
                Upload your PDF to add your
                electronic signature.
            

            

                Drag & Drop PDF Here

                Or click to browse file

                

                

            

        

        

            

                

                    

                    

                

                

                    

                    
                        Page 1 of 1

The previewContainer is especially important.

It contains two layers:

PDF Canvas
    +
Interactive Element Layer

The PDF page is rendered onto the canvas, while signatures, text, and stamps are displayed in a separate overlay.

This allows users to move and style an element without modifying the original PDF every time they make a small adjustment.

The overlay should match the dimensions and position of the PDF canvas.

#previewContainer {
    position: relative;
    display: inline-block;
}

#pdfCanvas {
    display: block;
}

#elementLayer {
    position: absolute;
    inset: 0;
    pointer-events: none;
}

Individual signature and text elements can later enable their own pointer interactions.

.pdf-element {
    position: absolute;
    cursor: move;
    pointer-events: auto;
    transform-origin: center;
}

This layered structure becomes the foundation of the interactive editor.

What Libraries Are We Using?

This project uses two JavaScript libraries for different parts of the PDF workflow.

PDF.js for Rendering and Previewing

PDF.js is responsible for reading the uploaded document and rendering its pages inside the browser.

A page can be loaded like this:

const page =
    await pdfDocument.getPage(
        currentPage
    );

The page is then rendered to a canvas:

const viewport =
    page.getViewport({
        scale: 1.5
    });

const context =
    pdfCanvas.getContext("2d");

pdfCanvas.width =
    viewport.width;

pdfCanvas.height =
    viewport.height;

await page.render({

    canvasContext: context,

    viewport

}).promise;

PDF.js handles the visual preview.

PDF-lib for Modifying the PDF

PDF-lib is used later when the user clicks Apply & Finalize.

It allows us to load the original PDF bytes and add content to its pages.

For example:

const pdfDoc =
    await PDFLib.PDFDocument.load(
        originalPdfBytes
    );

An uploaded PNG signature can then be embedded:

const signatureImage =
    await pdfDoc.embedPng(
        signatureBytes
    );

Text can also be drawn directly onto a PDF page:

page.drawText(
    "APPROVED",
    {
        x: 100,
        y: 100,
        size: 18
    }
);

The two libraries therefore have separate responsibilities:

PDF.js
→ Load and visually render PDF pages

PDF-lib
→ Modify pages and generate the final PDF

Separating these responsibilities keeps the editor easier to manage.

Include both libraries in the project before script.js.

Configure the PDF.js worker as well:

pdfjsLib.GlobalWorkerOptions.workerSrc =
    "https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js";

For a production project, pin and test the exact library versions you use rather than automatically loading an unspecified latest release.

Uploading and Previewing the PDF

The first interactive step is accepting the user's PDF.

Get references to the required elements:

const pdfInput =
    document.getElementById(
        "pdfInput"
    );

const selectPdfButton =
    document.getElementById(
        "selectPdfButton"
    );

const dropZone =
    document.getElementById(
        "dropZone"
    );

const uploadSection =
    document.getElementById(
        "uploadSection"
    );

const editorSection =
    document.getElementById(
        "editorSection"
    );

const pdfCanvas =
    document.getElementById(
        "pdfCanvas"
    );

We also need a few variables to store the current document state.

let pdfDocument = null;

let originalPdfBytes = null;

let currentPage = 1;

let totalPages = 0;

Clicking the custom button opens the hidden file input.

selectPdfButton.addEventListener(
    "click",
    () => {

        pdfInput.click();

    }
);

When a file is selected, pass it to the PDF loading function.

pdfInput.addEventListener(
    "change",
    event => {

        const file =
            event.target.files[0];

        if (file) {

            loadPdf(file);

        }

    }
);

Before processing the file, validate its type.

async function loadPdf(file) {

    if (
        file.type !==
        "application/pdf"
    ) {

        alert(
            "Please select a valid PDF file."
        );

        return;

    }

}

Read the file as an ArrayBuffer.

const arrayBuffer =
    await file.arrayBuffer();

Keep a copy of the original bytes because PDF.js and PDF-lib will use the document at different stages.

originalPdfBytes =
    new Uint8Array(
        arrayBuffer
    );

Now load the document with PDF.js.

pdfDocument =
    await pdfjsLib
        .getDocument({
            data:
                originalPdfBytes.slice()
        })
        .promise;

Store the number of pages.

totalPages =
    pdfDocument.numPages;

currentPage = 1;

Switch from the upload interface to the editor.

uploadSection.hidden = true;

editorSection.hidden = false;

Finally, render the first page.

await renderPage(currentPage);

The complete loading function becomes:

async function loadPdf(file) {

    if (
        file.type !==
        "application/pdf"
    ) {

        alert(
            "Please select a valid PDF file."
        );

        return;

    }

    const arrayBuffer =
        await file.arrayBuffer();

    originalPdfBytes =
        new Uint8Array(
            arrayBuffer
        );

    pdfDocument =
        await pdfjsLib
            .getDocument({
                data:
                    originalPdfBytes.slice()
            })
            .promise;

    totalPages =
        pdfDocument.numPages;

    currentPage = 1;

    uploadSection.hidden = true;

    editorSection.hidden = false;

    await renderPage(currentPage);

}

For drag-and-drop support, prevent the browser's default behavior.

dropZone.addEventListener(
    "dragover",
    event => {

        event.preventDefault();

        dropZone.classList.add(
            "drag-active"
        );

    }
);

Remove the active state when the file leaves the drop area.

dropZone.addEventListener(
    "dragleave",
    () => {

        dropZone.classList.remove(
            "drag-active"
        );

    }
);

Handle the dropped file:

dropZone.addEventListener(
    "drop",
    event => {

        event.preventDefault();

        dropZone.classList.remove(
            "drag-active"
        );

        const file =
            event.dataTransfer.files[0];

        if (file) {

            loadPdf(file);

        }

    }
);

Rendering the Current PDF Page

The renderPage() function loads one page from the PDF and displays it on the canvas.

async function renderPage(
    pageNumber
) {

    const page =
        await pdfDocument.getPage(
            pageNumber
        );

    const viewport =
        page.getViewport({
            scale: 1.5
        });

    const context =
        pdfCanvas.getContext("2d");

    pdfCanvas.width =
        viewport.width;

    pdfCanvas.height =
        viewport.height;

    await page.render({

        canvasContext: context,

        viewport

    }).promise;

    updatePageInfo();

}

Because the interactive element layer sits above the canvas, it must use the same dimensions.

const elementLayer =
    document.getElementById(
        "elementLayer"
    );

elementLayer.style.width =
    `${viewport.width}px`;

elementLayer.style.height =
    `${viewport.height}px`;

Add those lines inside renderPage() after setting the canvas dimensions.

The page information can then be updated:

function updatePageInfo() {

    pageInfo.textContent =
        `Page ${currentPage} of ${totalPages}`;

}

At this point, the uploaded PDF page is visible, but users still need a way to move through multi-page documents.

Get the navigation controls:

const previousPage =
    document.getElementById(
        "previousPage"
    );

const nextPage =
    document.getElementById(
        "nextPage"
    );

const pageInfo =
    document.getElementById(
        "pageInfo"
    );

The previous button decreases the page number.

previousPage.addEventListener(
    "click",
    async () => {

        if (currentPage <= 1) {
            return;
        }

        currentPage--;

        await renderPage(
            currentPage
        );

    }
);

The next button moves forward.

nextPage.addEventListener(
    "click",
    async () => {

        if (
            currentPage >=
            totalPages
        ) {
            return;
        }

        currentPage++;

        await renderPage(
            currentPage
        );

    }
);

The boundary checks prevent navigation outside the document.

For a 12-page PDF, the interface may display:

Page 12 of 12

The previous button remains available, while the next action can be disabled because the user is already on the final page.

function updateNavigationState() {

    previousPage.disabled =
        currentPage === 1;

    nextPage.disabled =
        currentPage ===
        totalPages;

}

Call this function whenever a new page is rendered.

function updatePageInfo() {

    pageInfo.textContent =
        `Page ${currentPage} of ${totalPages}`;

    updateNavigationState();

}

The user can now upload a PDF, preview its pages, and navigate to the exact page where a signature, custom text, or document stamp needs to be placed.

Choosing an Element to Add

Once the PDF is loaded and the correct page is visible, the user can choose what type of element to place on the document.

The editor provides two options:

Signature
Text/Stamp

Create the element selector:



    1. Choose Element

    
        
        Signature
    

    
        
        Text/Stamp

Get the controls in JavaScript:

const elementTypeInputs =
    document.querySelectorAll(
        'input[name="elementType"]'
    );

const signatureControls =
    document.getElementById(
        "signatureControls"
    );

const textControls =
    document.getElementById(
        "textControls"
    );

Listen for changes:

elementTypeInputs.forEach(
    input => {

        input.addEventListener(
            "change",
            event => {

                const type =
                    event.target.value;

                if (
                    type ===
                    "signature"
                ) {

                    signatureControls.hidden =
                        false;

                    textControls.hidden =
                        true;

                } else {

                    signatureControls.hidden =
                        true;

                    textControls.hidden =
                        false;

                }

            }
        );

    }
);

This keeps the interface focused. Signature-specific controls appear only when the user is creating a signature, while text and stamp controls appear when that element type is selected.

Creating a Signature

The signature workflow supports three methods:

Draw
Type
Upload

Create the method selector:



    2. Create Signature

Track the currently selected method:

let signatureMethod =
    "draw";

Switch between the three panels:

const signatureTabs =
    document.querySelectorAll(
        ".signature-tabs button"
    );

signatureTabs.forEach(
    button => {

        button.addEventListener(
            "click",
            () => {

                signatureMethod =
                    button.dataset.method;

                showSignatureMethod(
                    signatureMethod
                );

            }
        );

    }
);

The panel switching function can hide the inactive methods:

function showSignatureMethod(
    method
) {

    drawPanel.hidden =
        method !== "draw";

    typePanel.hidden =
        method !== "type";

    uploadPanel.hidden =
        method !== "upload";

}

Each method creates the same type of final element (a signature) but the source of that signature is different.

Drawing a Signature

The Draw option allows users to create a handwritten signature directly in the browser.

Add a canvas to the Draw panel:

Get the drawing context:

const signatureCanvas =
    document.getElementById(
        "signatureCanvas"
    );

const signatureContext =
    signatureCanvas.getContext(
        "2d"
    );

let isDrawing = false;

Begin drawing when the pointer touches the canvas:

signatureCanvas.addEventListener(
    "pointerdown",
    event => {

        isDrawing = true;

        const rect =
            signatureCanvas
                .getBoundingClientRect();

        signatureContext.beginPath();

        signatureContext.moveTo(

            event.clientX -
                rect.left,

            event.clientY -
                rect.top

        );

    }
);

Continue the line while the pointer moves:

signatureCanvas.addEventListener(
    "pointermove",
    event => {

        if (!isDrawing) {
            return;
        }

        const rect =
            signatureCanvas
                .getBoundingClientRect();

        signatureContext.lineTo(

            event.clientX -
                rect.left,

            event.clientY -
                rect.top

        );

        signatureContext.stroke();

    }
);

Stop drawing when the pointer is released:

signatureCanvas.addEventListener(
    "pointerup",
    () => {

        isDrawing = false;

    }
);

signatureCanvas.addEventListener(
    "pointerleave",
    () => {

        isDrawing = false;

    }
);

Set a few drawing properties:

signatureContext.lineWidth = 2;

signatureContext.lineCap =
    "round";

signatureContext.lineJoin =
    "round";

For touch devices, prevent the browser from interpreting drawing gestures as page scrolling:

#signatureCanvas {
    touch-action: none;
    cursor: crosshair;
}

The Clear button resets the drawing canvas:

clearSignature.addEventListener(
    "click",
    () => {

        signatureContext.clearRect(

            0,
            0,

            signatureCanvas.width,
            signatureCanvas.height

        );

    }
);

Once the signature is ready, convert the canvas into a PNG data URL:

const drawnSignature =
    signatureCanvas.toDataURL(
        "image/png"
    );

Because the canvas can preserve transparency, the resulting signature can be placed over the PDF without adding an unwanted rectangular background.

The generated image can now be displayed inside the interactive element layer.

function useDrawnSignature() {

    const image =
        new Image();

    image.src =
        signatureCanvas.toDataURL(
            "image/png"
        );

    image.onload =
        () => {

            createSignatureElement(
                image.src
            );

        };

}

This gives the user a visual signature element that can later be positioned over the PDF page.

Typing a Signature

Not every user has a touchscreen, stylus, or existing signature image.

The Type option allows users to enter their name and choose a signature-style appearance.

Add the input controls:



    

    
        Font Size

Listen for text changes:

typedSignature.addEventListener(
    "input",
    updateTypedSignatures
);

Create several style previews:

const signatureFonts = [

    "cursive",

    "'Brush Script MT', cursive",

    "'Segoe Script', cursive"

];

Render the available options:

function updateTypedSignatures() {

    const value =
        typedSignature.value.trim();

    signatureStyles.innerHTML = "";

    if (!value) {
        return;
    }

    signatureFonts.forEach(
        font => {

            const option =
                document.createElement(
                    "button"
                );

            option.textContent =
                value;

            option.style.fontFamily =
                font;

            option.style.fontSize =
                `${signatureFontSize.value}px`;

            option.addEventListener(
                "click",
                () => {

                    createTypedSignature(
                        value,
                        font
                    );

                }
            );

            signatureStyles.appendChild(
                option
            );

        }
    );

}

A typed signature can be converted to an image using another canvas.

function createTypedSignature(
    text,
    fontFamily
) {

    const canvas =
        document.createElement(
            "canvas"
        );

    const context =
        canvas.getContext("2d");

    const fontSize =
        Number(
            signatureFontSize.value
        );

    context.font =
        `${fontSize}px ${fontFamily}`;

    const width =
        context.measureText(
            text
        ).width;

    canvas.width =
        Math.ceil(width + 40);

    canvas.height =
        Math.ceil(fontSize * 2);

    context.font =
        `${fontSize}px ${fontFamily}`;

    context.textBaseline =
        "middle";

    context.fillText(
        text,
        20,
        canvas.height / 2
    );

    const imageUrl =
        canvas.toDataURL(
            "image/png"
        );

    createSignatureElement(
        imageUrl
    );

}

The typed signature is now treated like the drawn signature: it becomes an image element that can be positioned and later embedded into the PDF.

Uploading a Signature Image

The third option allows users to upload an existing signature image.

Add a file input:



    

    
        No file chosen

Listen for file selection:

signatureUpload.addEventListener(
    "change",
    event => {

        const file =
            event.target.files[0];

        if (!file) {
            return;
        }

        loadSignatureImage(file);

    }
);

Validate the image:

function loadSignatureImage(
    file
) {

    const allowedTypes = [

        "image/png",

        "image/jpeg"

    ];

    if (
        !allowedTypes.includes(
            file.type
        )
    ) {

        alert(
            "Please upload a PNG or JPEG image."
        );

        return;

    }

}

Read the selected image:

const reader =
    new FileReader();

reader.onload =
    event => {

        createSignatureElement(
            event.target.result
        );

};

reader.readAsDataURL(file);

Display the selected filename:

selectedSignatureFile.textContent =
    `Selected: ${file.name}`;

The complete function becomes:

function loadSignatureImage(
    file
) {

    const allowedTypes = [

        "image/png",

        "image/jpeg"

    ];

    if (
        !allowedTypes.includes(
            file.type
        )
    ) {

        alert(
            "Please upload a PNG or JPEG image."
        );

        return;

    }

    selectedSignatureFile.textContent =
        `Selected: ${file.name}`;

    const reader =
        new FileReader();

    reader.onload =
        event => {

            createSignatureElement(
                event.target.result
            );

        };

    reader.readAsDataURL(file);

}

A transparent PNG usually works particularly well because only the signature strokes remain visible over the document.

Creating the Signature Preview Element

All three signature methods eventually call the same function:

createSignatureElement(imageUrl);

This means the rest of the editor doesn't need separate positioning logic for drawn, typed, and uploaded signatures.

Create the preview element:

let activeElement = null;

function createSignatureElement(
    imageUrl
) {

    elementLayer.innerHTML = "";

    const image =
        document.createElement(
            "img"
        );

    image.src =
        imageUrl;

    image.className =
        "pdf-element signature-element";

    image.style.left =
        "100px";

    image.style.top =
        "100px";

    image.style.width =
        "180px";

    elementLayer.appendChild(
        image
    );

    activeElement = {

        type: "signature",

        source: imageUrl,

        element: image,

        x: 100,

        y: 100,

        scale: 1,

        rotation: 0,

        opacity: 1

    };

}

The preview now represents the signature that will eventually be written into the PDF.

The same state object can later be updated when the user changes the signature's position, scale, rotation, or opacity.

Adding Text and Preset Stamps

The second main element type is Text/Stamp.

This mode is useful when a document needs a short label, status, date, or other text rather than a handwritten signature.

Create the controls:



    2. Add Text or Stamp

    

    

        

        

        

        

    

    
        Size

        
    

    
        Color

Custom text can be displayed as the user types:

customText.addEventListener(
    "input",
    () => {

        createTextElement(
            customText.value
        );

    }
);

Preset stamps can update the same text input:

const stampButtons =
    document.querySelectorAll(
        "[data-stamp]"
    );

stampButtons.forEach(
    button => {

        button.addEventListener(
            "click",
            () => {

                const stamp =
                    button.dataset.stamp;

                customText.value =
                    stamp;

                createTextElement(
                    stamp
                );

            }
        );

    }
);

Create the text preview:

function createTextElement(
    text
) {

    if (!text.trim()) {

        elementLayer.innerHTML = "";

        activeElement = null;

        return;

    }

    elementLayer.innerHTML = "";

    const textElement =
        document.createElement(
            "div"
        );

    textElement.className =
        "pdf-element text-element";

    textElement.textContent =
        text;

    textElement.style.left =
        "100px";

    textElement.style.top =
        "100px";

    textElement.style.fontSize =
        `${textSize.value}px`;

    textElement.style.color =
        textColor.value;

    elementLayer.appendChild(
        textElement
    );

    activeElement = {

        type: "text",

        text,

        element:
            textElement,

        x: 100,

        y: 100,

        fontSize:
            Number(
                textSize.value
            ),

        color:
            textColor.value,

        rotation: 0,

        opacity: 1

    };

}

When the size changes, update the current element:

textSize.addEventListener(
    "input",
    () => {

        if (
            activeElement?.type !==
            "text"
        ) {
            return;
        }

        activeElement.fontSize =
            Number(
                textSize.value
            );

        activeElement
            .element
            .style
            .fontSize =
                `${textSize.value}px`;

    }
);

Do the same for the color:

textColor.addEventListener(
    "input",
    () => {

        if (
            activeElement?.type !==
            "text"
        ) {
            return;
        }

        activeElement.color =
            textColor.value;

        activeElement
            .element
            .style
            .color =
                textColor.value;

    }
);

The user can now enter custom content such as:

Signed on: 08-09-2025

or quickly select a predefined document stamp.

At this point, the application can create content using all of the available input methods: a drawn signature, typed signature, uploaded signature image, custom text, or preset document stamp.

Positioning and Styling the Element

After creating a signature, text label, or preset stamp, the next step is positioning it correctly on the PDF page.

The preview element sits inside the elementLayer created earlier. Because this layer matches the PDF canvas dimensions, users can move the element visually before anything is written into the final PDF.

The editor also provides controls for:

Scale
Rotation
Opacity
X position
Y position

The exact controls can vary depending on the active element. For example, scale is particularly useful for signatures, while text size and color are handled by the Text/Stamp controls from the previous section.

Create the placement controls:



    3. Placement & Style

    
        Rotation (°)

        
    

    
        Opacity

        
    

    
        X Position

        
    

    
        Y Position

For signature elements, add a scale control:


    Scale (100%)

Get the controls in JavaScript:

const scaleInput =
    document.getElementById(
        "scaleInput"
    );

const scaleValue =
    document.getElementById(
        "scaleValue"
    );

const rotationInput =
    document.getElementById(
        "rotationInput"
    );

const opacityInput =
    document.getElementById(
        "opacityInput"
    );

const xPosition =
    document.getElementById(
        "xPosition"
    );

const yPosition =
    document.getElementById(
        "yPosition"
    );

We'll use a single function to update the visual transformation.

function updateElementTransform() {

    if (!activeElement) {
        return;
    }

    activeElement.element.style.transform =
        `
            scale(${activeElement.scale})
            rotate(${activeElement.rotation}deg)
        `;

    activeElement.element.style.opacity =
        activeElement.opacity;

}

For text elements, initialize scale as 1 so the same transformation function can still be used.

activeElement = {

    type: "text",

    text,

    element: textElement,

    x: 100,

    y: 100,

    scale: 1,

    rotation: 0,

    opacity: 1

};

Changing the Element Scale

When the user moves the scale slider, convert the percentage into a decimal value.

scaleInput.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        const percentage =
            Number(
                scaleInput.value
            );

        activeElement.scale =
            percentage / 100;

        scaleValue.textContent =
            `${percentage}%`;

        updateElementTransform();

    }
);

A value of 100% represents the original preview size.

50%  → 0.5
100% → 1
114% → 1.14
200% → 2

This makes it easy to enlarge or reduce an uploaded, drawn, or typed signature without creating a new image.

Rotating the Element

The rotation input stores the angle in degrees.

rotationInput.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        activeElement.rotation =
            Number(
                rotationInput.value
            );

        updateElementTransform();

    }
);

A rotation of 0 keeps the element horizontal, while positive or negative values rotate it around its center.

Adjusting Opacity

Opacity can be useful for stamps, watermarks, and other document labels.

Convert the percentage slider to a value between 0 and 1.

opacityInput.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        activeElement.opacity =
            Number(
                opacityInput.value
            ) / 100;

        updateElementTransform();

    }
);

For example:

100% → 1
75%  → 0.75
50%  → 0.5

The same opacity value will later be used when generating the final PDF.

Dragging an Element Across the PDF Preview

Typing X and Y coordinates manually is useful for precise adjustments, but most users will prefer to drag the element directly to the required location.

Track the dragging state:

let isDragging = false;

let dragOffsetX = 0;

let dragOffsetY = 0;

When a signature or text element is created, attach the dragging behavior.

function enableDragging(
    element
) {

    element.addEventListener(
        "pointerdown",
        event => {

            isDragging = true;

            const elementRect =
                element
                    .getBoundingClientRect();

            dragOffsetX =
                event.clientX -
                elementRect.left;

            dragOffsetY =
                event.clientY -
                elementRect.top;

            element.setPointerCapture(
                event.pointerId
            );

        }
    );

}

Call this function when creating an element.

enableDragging(image);

or:

enableDragging(textElement);

Next, listen for pointer movement.

elementLayer.addEventListener(
    "pointermove",
    event => {

        if (
            !isDragging ||
            !activeElement
        ) {
            return;
        }

        const layerRect =
            elementLayer
                .getBoundingClientRect();

        const x =
            event.clientX -
            layerRect.left -
            dragOffsetX;

        const y =
            event.clientY -
            layerRect.top -
            dragOffsetY;

        moveActiveElement(
            x,
            y
        );

    }
);

Create a reusable movement function:

function moveActiveElement(
    x,
    y
) {

    if (!activeElement) {
        return;
    }

    activeElement.x = x;

    activeElement.y = y;

    activeElement.element.style.left =
        `${x}px`;

    activeElement.element.style.top =
        `${y}px`;

    xPosition.value =
        Math.round(x);

    yPosition.value =
        Math.round(y);

}

Stop dragging when the pointer is released.

elementLayer.addEventListener(
    "pointerup",
    () => {

        isDragging = false;

    }
);

elementLayer.addEventListener(
    "pointercancel",
    () => {

        isDragging = false;

    }
);

Now the signature or text element can be moved directly over the document.

For example, an uploaded signature may be positioned near the bottom-right corner of the final page.

Updating the Position Manually

The X and Y fields provide another way to position the element.

Listen for changes to the X coordinate:

xPosition.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        const x =
            Number(
                xPosition.value
            );

        moveActiveElement(
            x,
            activeElement.y
        );

    }
);

Do the same for Y:

yPosition.addEventListener(
    "input",
    () => {

        if (!activeElement) {
            return;
        }

        const y =
            Number(
                yPosition.value
            );

        moveActiveElement(
            activeElement.x,
            y
        );

    }
);

Dragging and manual coordinate entry remain synchronized. Moving the element updates the fields, while changing the fields moves the preview element.

Keeping the Element Inside the Page

Without boundaries, users could accidentally drag an element completely outside the PDF preview.

We can limit the position before saving it.

function clampPosition(
    x,
    y
) {

    const element =
        activeElement.element;

    const maxX =
        elementLayer.clientWidth -
        element.offsetWidth;

    const maxY =
        elementLayer.clientHeight -
        element.offsetHeight;

    return {

        x:
            Math.max(
                0,
                Math.min(x, maxX)
            ),

        y:
            Math.max(
                0,
                Math.min(y, maxY)
            )

    };

}

Use it inside moveActiveElement():

const position =
    clampPosition(
        x,
        y
    );

activeElement.x =
    position.x;

activeElement.y =
    position.y;

When scale or rotation is applied, the element's transformed visual bounds can extend beyond its original box. A production editor can use getBoundingClientRect() for more precise transformed-boundary calculations.

The basic clamp shown here is sufficient to demonstrate the positioning workflow.

Applying the Element to Selected Pages

After positioning the element, the user decides which PDF pages should receive it.

The interface provides three options:

Current page only
All pages
Specific pages

Create the controls:



    4. Apply to Pages

    
        
        Current page only
    

    
        
        All pages
    

    
        
        Specific pages

Read the selected mode:

function getTargetPages() {

    const mode =
        document.querySelector(
            'input[name="applyMode"]:checked'
        ).value;

    if (
        mode ===
        "current"
    ) {

        return [
            currentPage
        ];

    }

    if (
        mode ===
        "all"
    ) {

        return Array.from(

            {
                length:
                    totalPages
            },

            (_, index) =>
                index + 1

        );

    }

    return parsePageRange(
        specificPages.value
    );

}

Parse custom values such as:

1, 3-5, 10

with:

function parsePageRange(
    value
) {

    const pages =
        new Set();

    value
        .split(",")
        .forEach(part => {

            const item =
                part.trim();

            if (!item) {
                return;
            }

            if (
                item.includes("-")
            ) {

                const [
                    start,
                    end
                ] =
                    item
                        .split("-")
                        .map(Number);

                for (
                    let page = start;
                    page <= end;
                    page++
                ) {

                    if (
                        page >= 1 &&
                        page <= totalPages
                    ) {

                        pages.add(page);

                    }

                }

            } else {

                const page =
                    Number(item);

                if (
                    page >= 1 &&
                    page <= totalPages
                ) {

                    pages.add(page);

                }

            }

        });

    return [...pages];

}

The result becomes:

This allows a signature or stamp to be placed once and then applied to multiple target pages.

Just keep in mind that page dimensions may differ within the same PDF. Applying the same coordinates across pages works best when those pages use a consistent size and layout.

Applying and Finalizing the PDF

Once the element is created, positioned, styled, and assigned to the correct pages, the user can click Apply & Finalize.

Create the action buttons:

Get the buttons:

const applyButton =
    document.getElementById(
        "applyButton"
    );

const startOverButton =
    document.getElementById(
        "startOverButton"
    );

Before generating the final PDF, make sure an element exists.

applyButton.addEventListener(
    "click",
    async () => {

        if (!activeElement) {

            alert(
                "Please add a signature, text, or stamp first."
            );

            return;

        }

        const targetPages =
            getTargetPages();

        if (
            targetPages.length === 0
        ) {

            alert(
                "Please select at least one valid page."
            );

            return;

        }

        await generateFinalPdf(
            targetPages
        );

    }
);

The generateFinalPdf() function will handle the actual PDF modification in the next section.

The Start Over button clears the current document and resets the application.

startOverButton.addEventListener(
    "click",
    resetTool
);

Create the reset function:

function resetTool() {

    pdfDocument = null;

    originalPdfBytes = null;

    currentPage = 1;

    totalPages = 0;

    activeElement = null;

    pdfInput.value = "";

    elementLayer.innerHTML = "";

    editorSection.hidden = true;

    resultSection.hidden = true;

    uploadSection.hidden = false;

}

This returns the application to its original upload state.

The interactive editing stage is now complete. Users can create a signature or text element, position it directly over the PDF, adjust its appearance, choose the target pages, and prepare the document for final processing.

Generating the Signed PDF

The element shown over the browser preview hasn't yet been added to the actual PDF. When users click Apply & Finalize, the application loads the original document with PDF-lib and writes the selected signature, text, or stamp onto the target pages.

Start by loading the original PDF bytes:

async function generateFinalPdf(
    targetPages
) {

    const pdfDoc =
        await PDFLib.PDFDocument.load(
            originalPdfBytes.slice()
        );

    const pages =
        pdfDoc.getPages();

}

Before placing the element, we need to convert its browser coordinates into PDF coordinates.

The preview canvas may be displayed at a different size from the actual PDF page. The coordinate systems also use different Y-axis origins.

For each target page, calculate the scale:

const {
    width: pdfWidth,
    height: pdfHeight
} = page.getSize();

const scaleX =
    pdfWidth /
    pdfCanvas.width;

const scaleY =
    pdfHeight /
    pdfCanvas.height;

Convert the preview position:

const pdfX =
    activeElement.x *
    scaleX;

const pdfY =
    pdfHeight -
    (
        activeElement.y +
        activeElement.element.offsetHeight
    ) * scaleY;

This conversion maps the element from the browser's top-left coordinate system to the PDF page's coordinate system.

Embedding a Signature

Drawn, typed, and uploaded signatures are all represented as images by the time they reach the final processing stage.

Convert the signature data URL into bytes:

async function dataUrlToBytes(
    dataUrl
) {

    const response =
        await fetch(dataUrl);

    return await response.arrayBuffer();

}

Embed the signature image:

const signatureBytes =
    await dataUrlToBytes(
        activeElement.source
    );

const signatureImage =
    await pdfDoc.embedPng(
        signatureBytes
    );

If uploaded JPEG signatures are supported, the application should preserve the original image format and use embedJpg() when appropriate.

Calculate the final dimensions:

const previewWidth =
    activeElement
        .element
        .offsetWidth *
    activeElement.scale;

const previewHeight =
    activeElement
        .element
        .offsetHeight *
    activeElement.scale;

const finalWidth =
    previewWidth *
    scaleX;

const finalHeight =
    previewHeight *
    scaleY;

Then draw the signature:

page.drawImage(
    signatureImage,
    {
        x: pdfX,

        y:
            pdfHeight -
            (
                activeElement.y *
                scaleY
            ) -
            finalHeight,

        width:
            finalWidth,

        height:
            finalHeight,

        rotate:
            PDFLib.degrees(
                activeElement.rotation
            ),

        opacity:
            activeElement.opacity
    }
);

The same processing logic works whether the signature was drawn, typed, or uploaded because all three methods produce an image element before finalization.

Adding Text or a Stamp

Text and preset stamps are written directly onto the PDF page.

First, convert the selected color from hexadecimal to RGB values.

function hexToRgb(
    hex
) {

    const value =
        hex.replace(
            "#",
            ""
        );

    return {

        r:
            parseInt(
                value.substring(0, 2),
                16
            ) / 255,

        g:
            parseInt(
                value.substring(2, 4),
                16
            ) / 255,

        b:
            parseInt(
                value.substring(4, 6),
                16
            ) / 255

    };

}

Apply the text:

const color =
    hexToRgb(
        activeElement.color
    );

page.drawText(
    activeElement.text,
    {
        x:
            activeElement.x *
            scaleX,

        y:
            pdfHeight -
            (
                activeElement.y *
                scaleY
            ) -
            activeElement.fontSize,

        size:
            activeElement.fontSize *
            scaleY,

        color:
            PDFLib.rgb(
                color.r,
                color.g,
                color.b
            ),

        rotate:
            PDFLib.degrees(
                activeElement.rotation
            ),

        opacity:
            activeElement.opacity
    }
);

After processing every target page, save the modified document:

const finalPdfBytes =
    await pdfDoc.save();

const finalPdfBlob =
    new Blob(
        [finalPdfBytes],
        {
            type:
                "application/pdf"
        }
    );

await showFinalPreview(
    finalPdfBlob
);

At this point, the selected signature, text, or stamp has been added to the generated PDF.

Previewing the Final PDF

Before downloading the document, the application displays the completed PDF in a separate preview area.

This allows users to confirm that the element appears on the correct page and in the expected position.

Load the generated file with PDF.js:

let finalPdfDocument = null;

let finalPage = 1;

async function showFinalPreview(
    blob
) {

    const bytes =
        await blob.arrayBuffer();

    finalPdfDocument =
        await pdfjsLib
            .getDocument({
                data: bytes
            })
            .promise;

    finalPage = 1;

    editorSection.hidden =
        true;

    resultSection.hidden =
        false;

    await renderFinalPage(
        finalPage
    );

}

Render the current result page:

async function renderFinalPage(
    pageNumber
) {

    const page =
        await finalPdfDocument
            .getPage(
                pageNumber
            );

    const viewport =
        page.getViewport({
            scale: 1.4
        });

    finalCanvas.width =
        viewport.width;

    finalCanvas.height =
        viewport.height;

    await page.render({

        canvasContext:
            finalCanvas
                .getContext("2d"),

        viewport

    }).promise;

    finalPageInfo.textContent =
        `Page ${pageNumber} of ${finalPdfDocument.numPages}`;

}

Previous and next controls can use the same navigation pattern as the original PDF preview.

Renaming and Downloading the Final PDF

After reviewing the processed document, users can rename the file before downloading it.

For example:

document_signed.pdf

Create the filename input:

Make sure the filename has the correct extension:

function getOutputFilename() {

    let filename =
        outputFilename
            .value
            .trim();

    if (!filename) {

        filename =
            "document_signed.pdf";

    }

    if (
        !filename
            .toLowerCase()
            .endsWith(".pdf")
    ) {

        filename += ".pdf";

    }

    return filename;

}

The result section can also display the total page count and generated file size.

function formatFileSize(
    bytes
) {

    if (
        bytes <
        1024 * 1024
    ) {

        return (
            bytes / 1024
        ).toFixed(2) + " KB";

    }

    return (
        bytes /
        1024 /
        1024
    ).toFixed(2) + " MB";

}

Update the file information:

filePageCount.textContent =
    `Total Pages: ${finalPdfDocument.numPages}`;

fileSize.textContent =
    `File Size: ${
        formatFileSize(
            finalPdfBlob.size
        )
    }`;

Download the file using a temporary object URL:

downloadButton.addEventListener(
    "click",
    () => {

        const url =
            URL.createObjectURL(
                finalPdfBlob
            );

        const link =
            document.createElement(
                "a"
            );

        link.href =
            url;

        link.download =
            getOutputFilename();

        link.click();

        URL.revokeObjectURL(
            url
        );

    }
);

After downloading, the Start Over button resets the application so another PDF can be processed.

Demo: How the PDF Signature Tool Works

Let's walk through the complete workflow from upload to download.

Step 1: Upload the PDF

Users begin by dragging a PDF into the upload area or clicking Select PDF.

The browser reads the document and prepares it for local processing.

Step 2: Preview and Navigate the Document

After upload, the current page appears in the PDF preview.

Previous and next controls allow users to navigate through multi-page documents and find the page where an element needs to be added.

Step 3: Choose What to Add

The user chooses between Signature and Text/Stamp.

This determines which creation controls appear in the editor.

Step 4: Create the Signature

If Signature is selected, users can choose Draw, Type, or Upload.

Drawing works directly inside the signature canvas. The Type option creates a signature-style element from entered text, while Upload accepts an existing signature image.

Step 5: Add Custom Text or a Preset Stamp

Instead of a signature, users can select Text/Stamp.

They can enter custom content or choose a preset such as APPROVED, CONFIDENTIAL, DRAFT, or PAID.

Step 6: Position and Style the Element

The created element appears over the PDF preview.

Users can drag it to the required position and adjust properties such as scale, rotation, opacity, X position, and Y position.

Text elements also support configurable font size and color.

Step 7: Choose the Target Pages

The element can be applied to the current page, every page, or a specific page selection.

For example:

1, 3-5, 10

This is useful when the same stamp or document label needs to appear on several pages.

Step 8: Apply and Finalize

After checking the element and target pages, users click Apply & Finalize.

The browser converts the preview position into PDF coordinates and generates the modified document.

Step 9: Preview the Completed PDF

The generated document appears in a final preview.

Users can navigate through the pages and verify that the signature, text, or stamp appears correctly before downloading.

Step 10: Rename and Download

The final section allows users to change the output filename and review the total number of pages and file size.

Clicking Download saves the generated PDF locally.

Afterward, Start Over clears the session and returns to the upload interface.

Handling Signature Transparency

Uploaded signatures often look best when the background is transparent.

A transparent PNG contains only the visible signature strokes, allowing the original PDF content to remain visible around the signature.

A JPEG image, by comparison, usually includes a solid background. If the image was scanned from white paper, placing it on a colored PDF area may create a visible white rectangle.

For uploaded signatures, transparent PNG files are therefore usually the better option.

The same principle applies to drawn and typed signatures. When converting a canvas to PNG, avoid filling the canvas with a background color unless that background is intentionally required.

const signatureImage =
    signatureCanvas.toDataURL(
        "image/png"
    );

The transparent canvas can then be embedded directly into the PDF.

Important Notes and Common Mistakes

One common mistake is assuming that the browser preview and the actual PDF use identical coordinates.

Always calculate the relationship between the canvas dimensions and the target PDF page before placing the final element.

const scaleX =
    pdfWidth /
    pdfCanvas.width;

const scaleY =
    pdfHeight /
    pdfCanvas.height;

Another issue occurs when the same element is applied to pages with different dimensions. A position that looks correct on an A4 page may not appear in the same visual location on a landscape or differently sized page.

Uploaded signature images should also be validated before processing.

const allowedTypes = [
    "image/png",
    "image/jpeg"
];

if (
    !allowedTypes.includes(
        file.type
    )
) {

    alert(
        "Please upload a PNG or JPEG image."
    );

    return;

}

Very large image files should be resized before embedding to avoid unnecessarily increasing the final PDF size.

Users should also review the completed document before downloading it. Rotation, scaling, or coordinate conversion errors are much easier to identify in the final preview than after the file has already been shared.

Finally, remember that this project adds a visual electronic signature to a PDF. It does not create a certificate-based cryptographic digital signature or provide automatic identity verification.

Conclusion

In this tutorial, you built a browser-based PDF Signature Tool using JavaScript.

You learned how to upload and preview PDF documents, navigate between pages, create signatures by drawing, typing, or uploading an image, add custom text and preset stamps, position elements directly over a PDF preview, adjust their appearance, choose target pages, and generate the completed document with PDF-lib.

You also learned how browser coordinates are converted into PDF coordinates and why signature transparency matters when embedding images into a document.

The final workflow allows users to preview the completed PDF, rename the output file, review its page count and size, and download it directly from the browser.

You can explore the complete workflow using the PDF Signature Tool.

The project can be extended further with multiple elements per page, reusable signature profiles, date fields, initials, custom fonts, signature removal before finalization, or certificate-based digital signing through a dedicated signing infrastructure.

How to Manage Secrets Securely with Azure Key Vault in Node.js

Zia Ullah — Mon, 20 Jul 2026 13:50:42 +0000

Last year a client called me about exactly this. Someone ran git log -p on a hunch and found a .env committed two years earlier, never caught. Database password, Stripe secret, JWT signing key — all still active. All still in production.

IBM's 2024 breach cost report put the average data breach at $4.88 million — and that's the average, not the worst cases.

Exposed credentials are consistently near the top of root causes. GitHub found over a million secrets leaked in public repos in 2023 alone, before you even count the private ones nobody ever discovered.

It's not a people problem. The developers I've worked with aren't careless — the architecture is just set up to fail them. A .env file gets committed once by accident. Credentials get copied and pasted into a Slack message to unblock a teammate. A Docker image gets published with secrets baked into a layer. A server gets shut down, and nobody rotates the credentials it was holding.

Azure Key Vault solves this differently. Your application fetches credentials at runtime from a centralized, encrypted service — the .env file stops being a liability because it stops holding anything worth stealing.

What you'll build is a Node.js Express API that fetches every secret from Azure Key Vault at startup. No passwords in the code. When someone quits, there's nothing in the repo to rotate. The .env ends up with one line — the vault name.

Prerequisites

Node.js 18+
An Azure account (free tier works)
Azure CLI installed and logged in (az login)
Basic knowledge of Express.js
Docker (optional — only needed for the local database test section)

What We Will Build

A Node.js Express API that:

Connects to PostgreSQL using credentials fetched from Key Vault at startup
Uses Managed Identity for authentication — no client secrets or passwords anywhere
Caches secrets in memory, so Key Vault isn't called on every request
Works locally via Azure CLI auth and in production via Managed Identity — same code, zero changes

How the Architecture Works
What Is Azure Key Vault?
Set Up the Key Vault
Create the Node.js Project
Connect to Key Vault with Managed Identity
Cache Secrets at Startup
Use Secrets in Your Express API
Test Locally
Deploy to Azure App Service
Grant Key Vault Access to the App
Rotate Secrets Without Redeploying
Troubleshooting
Wrapping Up

How the Architecture Works

Before writing any code, it helps to see the full picture:

 LOCAL DEVELOPMENT
.-------------------------------------------------------.
|                                                        |
|   [Node.js App]                                        |
|        |                                               |
|        v                                               |
|   [DefaultAzureCredential] ---> az login session       |
|        |                                               |
|        v                                               |
|   [Azure Key Vault]  ---> Returns secrets              |
|        |                                               |
|        v                                               |
|   [In-memory cache]  ---> App uses secrets at runtime  |
'-------------------------------------------------------'

 PRODUCTION (Azure)
.-------------------------------------------------------.
|                                                        |
|   [Azure App Service]                                  |
|        |                                               |
|        v                                               |
|   [DefaultAzureCredential] ---> Managed Identity       |
|        |                                               |
|        v                                               |
|   [Azure Key Vault]  ---> Returns secrets              |
|        |                                               |
|        v                                               |
|   [In-memory cache]  ---> App uses secrets at runtime  |
'-------------------------------------------------------'

Both environments run the exact same code. DefaultAzureCredential figures out where it is — locally it picks up your az login session, on Azure it uses Managed Identity. You don't switch config files and you don't manage credentials. It just works.

What Is Azure Key Vault?

Azure Key Vault is Microsoft's managed secret store — it handles secrets, keys, and certificates. For this tutorial, we're only using the secrets part: database passwords, API keys, JWT signing keys, anything your app needs to run but has no business being in your Git history.

Compared to .env files, the practical differences are worth understanding before you write any code.

Rotation is the one I notice most on real projects. Update a secret in Key Vault and every app picks it up on the next restart — no hunting down five different environment configs across staging and production.

Access control is the other big one. Each application only gets permission to read the secrets it actually needs. If one service gets compromised, it can't read credentials belonging to other services.

And every read gets logged. When something goes wrong — and eventually something will — you can see exactly which app accessed which secret, and when. That log is what auditors actually want to see.

I've sat in enough security reviews to know that "we use .env files and tell people not to commit them" doesn't satisfy an auditor. SOC 2, HIPAA, GDPR — they all want demonstrable controls. A vault with an access log is demonstrable.

Set Up the Key Vault

Run these commands. The vault name has to be globally unique across all of Azure — not just your own subscription — so pick something specific. Letters, numbers, and hyphens, 3 to 24 characters.

# Create a resource group (skip if you already have one)
az group create \
  --name keyvault-demo-rg \
  --location eastus

# Create the Key Vault (RBAC enabled by default — required for the role assignment later)
az keyvault create \
  --name your-vault-name \
  --resource-group keyvault-demo-rg \
  --location eastus

# Grant yourself permission to manage secrets (required with RBAC — creators are not auto-assigned)
az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee-object-id $(az ad signed-in-user show --query id -o tsv) \
  --scope $(az keyvault show \
    --name your-vault-name \
    --resource-group keyvault-demo-rg \
    --query id -o tsv)

# Add your secrets
az keyvault secret set \
  --vault-name your-vault-name \
  --name "DB-HOST" \
  --value "your-db-host.postgres.database.azure.com"

az keyvault secret set \
  --vault-name your-vault-name \
  --name "DB-PASSWORD" \
  --value "your-super-secret-password"

az keyvault secret set \
  --vault-name your-vault-name \
  --name "JWT-SECRET" \
  --value "your-jwt-signing-secret"

Verify the secrets were stored:

az keyvault secret list --vault-name your-vault-name --query "[].name" -o tsv

You should see:

DB-HOST
DB-PASSWORD
JWT-SECRET

Create the Node.js Project

Set up the project structure:

mkdir nodejs-azure-keyvault
cd nodejs-azure-keyvault
npm init -y
npm install express pg jsonwebtoken @azure/keyvault-secrets @azure/identity dotenv

The two Azure packages do all the work:

@azure/keyvault-secrets — connects to your vault and pulls secrets out
@azure/identity — handles auth. Locally, it uses your az login session, in production, it switches to Managed Identity automatically

Add a start script to package.json:

npm pkg set scripts.start="node server.js"

Create the following file structure:

nodejs-azure-keyvault/
|-- src/
|   |-- config/
|   |   `-- secrets.js   # Key Vault client and secret loader
|   |-- db/
|   |   `-- index.js     # PostgreSQL pool using secrets
|   `-- routes/
|       `-- users.js     # Example route
|-- app.js               # Express app
`-- server.js            # Entry point -- loads secrets first

Connect to Key Vault with Managed Identity

Create the secrets config file:

// src/config/secrets.js
const { SecretClient } = require('@azure/keyvault-secrets');
const { DefaultAzureCredential } = require('@azure/identity');

const VAULT_URL = `https://${process.env.KEY_VAULT_NAME}.vault.azure.net`;

const credential = new DefaultAzureCredential();
const client = new SecretClient(VAULT_URL, credential);

async function getSecret(name) {
  const secret = await client.getSecret(name);
  return secret.value;
}

module.exports = { getSecret };

DefaultAzureCredential is the most important part of this setup. It tries a chain of authentication methods in order:

Environment variables (for CI/CD pipelines)
Azure CLI credentials (for local development — az login)
Managed Identity (for deployed apps on Azure)

This means the exact same code works locally and in production with zero changes. Locally, it uses your az login session. In production, it uses the app's Managed Identity. You never touch credentials.

Cache Secrets at Startup

Calling Key Vault on every request adds latency and costs money. Load all secrets once at startup and cache them in memory. Replace src/config/secrets.js with this complete version:

// src/config/secrets.js
const { SecretClient } = require('@azure/keyvault-secrets');
const { DefaultAzureCredential } = require('@azure/identity');

const VAULT_URL = `https://${process.env.KEY_VAULT_NAME}.vault.azure.net`;

const credential = new DefaultAzureCredential();
const client = new SecretClient(VAULT_URL, credential);

// In-memory cache
const cache = {};

async function getSecret(name) {
  if (cache[name]) return cache[name];
  const secret = await client.getSecret(name);
  cache[name] = secret.value;
  return secret.value;
}

async function loadAllSecrets() {
  console.log('Loading secrets from Azure Key Vault...');
  const secretNames = ['DB-HOST', 'DB-PASSWORD', 'JWT-SECRET'];

  await Promise.all(
    secretNames.map(async (name) => {
      cache[name] = await getSecret(name);
      console.log(`  ✓ ${name} loaded`);
    })
  );

  console.log('All secrets loaded successfully.');
}

function getFromCache(name) {
  if (!cache[name]) throw new Error(`Secret "${name}" not loaded. Did loadAllSecrets() run?`);
  return cache[name];
}

module.exports = { loadAllSecrets, getFromCache };

The loadAllSecrets function runs once when the application starts. After that, all secrets are served from the in-memory cache with zero latency and zero Key Vault calls.

Use Secrets in Your Express API

Set up the database connection using the cached secrets:

// src/db/index.js
const { Pool } = require('pg');
const { getFromCache } = require('../config/secrets');

let pool;

function getPool() {
  if (!pool) {
    pool = new Pool({
      host:     getFromCache('DB-HOST'),
      database: process.env.DB_NAME || 'myapp',
      user:     process.env.DB_USER || 'dbadmin',
      password: getFromCache('DB-PASSWORD'),
      port:     parseInt(process.env.DB_PORT || '5432'),
      ssl:      process.env.NODE_ENV === 'production'
                  ? { rejectUnauthorized: false }
                  : false,
    });

    pool.on('error', (err) => {
      console.error('Unexpected database pool error:', err.message);
    });
  }

  return pool;
}

module.exports = { getPool };

Notice the distinction: DB-HOST and DB-PASSWORD come from Key Vault because they're sensitive. The database name, username, and port are not — they don't need to be protected, so they use environment variables with sensible defaults. Key Vault is for credentials, not all configuration.

The SSL flag is environment-aware: forced on in production, off locally so Docker connections work without a certificate. The rejectUnauthorized: false setting accepts Azure Database for PostgreSQL's certificate without verifying the CA chain — this is standard for Azure-managed databases. For stricter environments, you can download the Azure root CA and pass it via the ca option in the pool config instead.

Create a sample route that uses JWT verification with the secret from Key Vault:

// src/routes/users.js
const express = require('express');
const jwt     = require('jsonwebtoken');
const { getFromCache } = require('../config/secrets');
const { getPool }      = require('../db');

const router = express.Router();

// Auth middleware — JWT secret comes from Key Vault, not process.env
function authMiddleware(req, res, next) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing or malformed Authorization header' });
  }

  const token = authHeader.split(' ')[1];

  try {
    req.user = jwt.verify(token, getFromCache('JWT-SECRET'));
    next();
  } catch (err) {
    return res.status(401).json({ error: 'Invalid or expired token' });
  }
}

// GET /api/users — list users (authenticated)
router.get('/', authMiddleware, async (req, res) => {
  try {
    const result = await getPool().query(
      'SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 20'
    );
    res.json(result.rows);
  } catch (err) {
    console.error('Database error:', err.message);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// GET /api/users/:id — single user (authenticated)
router.get('/:id', authMiddleware, async (req, res) => {
  try {
    const result = await getPool().query(
      'SELECT id, email, created_at FROM users WHERE id = $1',
      [req.params.id]
    );
    if (!result.rows[0]) return res.status(404).json({ error: 'User not found' });
    res.json(result.rows[0]);
  } catch (err) {
    console.error('Database error:', err.message);
    res.status(500).json({ error: 'Internal server error' });
  }
});

module.exports = router;

Notice the error handler returns 'Internal server error' instead of err.message. Database errors are surprisingly chatty — they'll hand an attacker your table names, column names, and query structure if you let them through.

Set up the Express application. Both files define authMiddleware locally — yes, it's duplicated. In production, I'd pull this into a shared middleware file. For this tutorial, keeping it local means you can read either file without bouncing between three others:

// app.js
const express = require('express');
const jwt = require('jsonwebtoken');
const { getFromCache } = require('./src/config/secrets');
const usersRouter = require('./src/routes/users');

const app = express();
app.use(express.json());

// Auth middleware — JWT secret comes from Key Vault, not process.env
function authMiddleware(req, res, next) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing or malformed Authorization header' });
  }
  const token = authHeader.split(' ')[1];
  try {
    req.user = jwt.verify(token, getFromCache('JWT-SECRET'));
    next();
  } catch (err) {
    return res.status(401).json({ error: 'Invalid or expired token' });
  }
}

// Health check — no auth required
app.get('/health', (req, res) => {
  res.json({ status: 'healthy', timestamp: new Date().toISOString() });
});

// Status endpoint — proves Key Vault integration without needing a database
app.get('/api/status', authMiddleware, (req, res) => {
  res.json({
    message: 'All secrets loaded from Azure Key Vault',
    vault: process.env.KEY_VAULT_NAME,
    secrets_loaded: ['DB-HOST', 'DB-PASSWORD', 'JWT-SECRET'],
    authenticated_as: req.user.email,
    timestamp: new Date().toISOString()
  });
});

app.use('/api/users', usersRouter);

app.use((req, res) => res.status(404).json({ error: 'Route not found' }));
app.use((err, req, res, next) => {
  console.error('Unhandled error:', err.message);
  res.status(500).json({ error: 'Internal server error' });
});

module.exports = app;

The entry point loads secrets before starting the server. The server doesn't start unless all secrets load successfully:

// server.js
require('dotenv').config();
const app = require('./app');
const { loadAllSecrets } = require('./src/config/secrets');

const PORT = process.env.PORT || 3000;

async function start() {
  try {
    await loadAllSecrets();
    app.listen(PORT, () => {
      console.log(`Server running on port ${PORT}`);
    });
  } catch (err) {
    console.error('Failed to start server:', err.message);
    console.error('Hint: Run "az login" for local development, or check Managed Identity for Azure deployments.');
    process.exit(1);
  }
}

start();

That process.exit(1) is deliberate. I'd rather the app crash loudly at startup than limp along with missing credentials and fail on the first real request two hours later.

Test Locally

Create a .env file for local development. This only contains the Key Vault name, nothing sensitive:

# .env
KEY_VAULT_NAME=your-vault-name
PORT=3000

Add .env and the deployment zip to .gitignore:

echo ".env" >> .gitignore
echo "app.zip" >> .gitignore

Make sure you're logged into Azure CLI:

az login

Start the application:

npm start

You should see:

Loading secrets from Azure Key Vault...
  ✓ JWT-SECRET loaded
  ✓ DB-PASSWORD loaded
  ✓ DB-HOST loaded
All secrets loaded successfully.
Server running on port 3000

The order secrets load may vary — Promise.all fetches them in parallel and resolves as each one completes. What matters is that all three are confirmed before the server starts.

Test the health endpoint:

curl http://localhost:3000/health
# {"status":"healthy","timestamp":"2026-07-14T19:38:11.659Z"}

Now prove the integration end-to-end. Grab the value you stored as JWT-SECRET and use it to sign a test token — paste it in for YOUR-JWT-SECRET-VALUE. Then hit /api/status with it:

node -e "const jwt = require('jsonwebtoken'); console.log(jwt.sign({id:1, email:'test@test.com'}, 'YOUR-JWT-SECRET-VALUE', {expiresIn:'1h'}));"

On Linux/macOS:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/api/status

On Windows PowerShell:

Invoke-RestMethod -Uri "http://localhost:3000/api/status" -Headers @{Authorization = "Bearer YOUR_TOKEN"}

You should see:

{
  "message": "All secrets loaded from Azure Key Vault",
  "vault": "your-vault-name",
  "secrets_loaded": ["DB-HOST", "DB-PASSWORD", "JWT-SECRET"],
  "authenticated_as": "test@test.com",
  "timestamp": "2026-07-14T19:50:08.687Z"
}

If you got that response, the whole chain worked. The JWT was signed and verified using a secret that lived only in Key Vault — not in your code, not in your.env, not anywhere in the repo. Your az login session handled the auth locally. In production, Managed Identity takes over. Same code, nothing changes.

Test the Full Database Flow with Docker

The app reads DB-HOST and DB-PASSWORD from Key Vault, so those secrets need to match your local Docker container. Update them now:

az keyvault secret set --vault-name your-vault-name --name "DB-HOST" --value "localhost"
az keyvault secret set --vault-name your-vault-name --name "DB-PASSWORD" --value "demopassword123"

Docker up a Postgres container. The password has to match demopassword123 — that's what you just put in Key Vault:

docker run --name pg-demo \
  -e POSTGRES_USER=dbadmin \
  -e POSTGRES_PASSWORD=demopassword123 \
  -e POSTGRES_DB=myapp \
  -p 5432:5432 \
  -d postgres:15

Get the table created and throw in some test rows:

docker exec -it pg-demo psql -U dbadmin -d myapp -c \
  "CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, email VARCHAR(255) UNIQUE NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW());"

docker exec -it pg-demo psql -U dbadmin -d myapp -c \
  "INSERT INTO users (email) VALUES ('alice@example.com'), ('bob@example.com'), ('carol@example.com');"

Kill the server and bring it back up — secrets load at startup, so it needs a fresh run to pick up what you just changed in Key Vault:

npm start

Call the users endpoint with a valid JWT:

# Generate a token (use the same value you stored as JWT-SECRET in Key Vault)
node -e "const jwt = require('jsonwebtoken'); console.log(jwt.sign({id:1, email:'test@test.com'}, 'YOUR-JWT-SECRET-VALUE', {expiresIn:'1h'}));"

On Linux/macOS:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/api/users

On Windows PowerShell:

Invoke-RestMethod -Uri "http://localhost:3000/api/users" -Headers @{Authorization = "Bearer YOUR_TOKEN"}

You should see:

[
  { "id": 1, "email": "alice@example.com", "created_at": "2026-07-14T19:59:21.064Z" },
  { "id": 2, "email": "bob@example.com",   "created_at": "2026-07-14T19:59:21.064Z" },
  { "id": 3, "email": "carol@example.com", "created_at": "2026-07-14T19:59:21.064Z" }
]

That query ran using a password that came straight from Key Vault. It's not in your .env, not hardcoded anywhere, and not in a local variable. The repo has nothing worth stealing.

Before you deploy, put the real production values back in Key Vault:

az keyvault secret set --vault-name your-vault-name --name "DB-HOST" --value "your-db-host.postgres.database.azure.com"
az keyvault secret set --vault-name your-vault-name --name "DB-PASSWORD" --value "your-super-secret-password"

If you skip this, the deployed app will try to connect to localhost and fail immediately — localhost doesn't exist on App Service.

Deploy to Azure App Service

Note: This section creates the App Service infrastructure. The actual code deployment (zip upload) happens at the end of the next section — the app must have Key Vault access configured before its first startup, or it will fail immediately and exit.

Create the App Service:

# Create an App Service Plan (B1 is the cheapest paid tier)
az appservice plan create \
  --name keyvault-demo-plan \
  --resource-group keyvault-demo-rg \
  --sku B1 \
  --is-linux

# Create the Web App
az webapp create \
  --name my-keyvault-node-app \
  --resource-group keyvault-demo-rg \
  --plan keyvault-demo-plan \
  --runtime "NODE:18-lts"

# Set app settings — KEY_VAULT_NAME tells the app which vault to use
# NODE_ENV=production enables SSL for the database connection
az webapp config appsettings set \
  --name my-keyvault-node-app \
  --resource-group keyvault-demo-rg \
  --settings KEY_VAULT_NAME=your-vault-name NODE_ENV=production

Grant Key Vault Access to the App

Enable Managed Identity on the app. This gives it an identity in Microsoft Entra ID that Key Vault can trust:

# Enable system-assigned managed identity
az webapp identity assign \
  --name my-keyvault-node-app \
  --resource-group keyvault-demo-rg

The following commands capture the principalId automatically and use it to grant the role:

# Get the principal ID
PRINCIPAL_ID=$(az webapp identity show \
  --name my-keyvault-node-app \
  --resource-group keyvault-demo-rg \
  --query principalId \
  --output tsv)

# Get the Key Vault resource ID
KV_ID=$(az keyvault show \
  --name your-vault-name \
  --resource-group keyvault-demo-rg \
  --query id \
  --output tsv)

# Grant the app the "Key Vault Secrets User" role
az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee-object-id $PRINCIPAL_ID \
  --scope $KV_ID

The Key Vault Secrets User role allows the app to read secrets. It can't create, update, or delete them. This is the principle of least privilege — the application can only do what it needs to do.

Time to ship it. Linux/macOS can run this directly — Windows users, open Git Bash (it ships with Git for Windows):

zip -r app.zip . -x "node_modules/*" ".git/*" ".env" "app.zip"

Then deploy:

az webapp deployment source config-zip \
  --name my-keyvault-node-app \
  --resource-group keyvault-demo-rg \
  --src app.zip

The deployed application authenticates to Key Vault using its Managed Identity automatically. No passwords, no client secrets, no credentials of any kind in the deployment.

Check the health endpoint to confirm it's running:

curl https://my-keyvault-node-app.azurewebsites.net/health
# {"status":"healthy","timestamp":"..."}

If it won't start, pull the logs:

az webapp log tail --name my-keyvault-node-app --resource-group keyvault-demo-rg

Nine times out of ten, it's that the Key Vault role assignment has not been propagated yet. Give it 2–3 minutes, then restart:

az webapp restart --name my-keyvault-node-app --resource-group keyvault-demo-rg

Rotate Secrets Without Redeploying

One of the biggest practical benefits of Key Vault is secret rotation. When a database password needs to change, you update it in Key Vault — not in your app:

az keyvault secret set \
  --vault-name your-vault-name \
  --name "DB-PASSWORD" \
  --value "new-rotated-password"

The cache builds at startup, so you don't need a redeploy — a restart is enough:

az webapp restart \
  --name my-keyvault-node-app \
  --resource-group keyvault-demo-rg

No code change. No new deployment. The secret is rotated, and the app is using the new value in seconds.

If you need zero-downtime rotation, add a /refresh-secrets endpoint behind admin auth that clears the cache and then calls loadAllSecrets(). The order matters — loadAllSecrets() uses getSecret() which returns cached values if they exist, so you must clear the cache first, or it will reload nothing. This is optional but useful for long-running processes that can't afford a restart.

Troubleshooting

CredentialUnavailableError: DefaultAzureCredential failed to retrieve a token

You're not logged into Azure CLI. Run az login and try again. On Azure App Service, check that Managed Identity is enabled and the role assignment was created correctly.

RestError: Forbidden — The user does not have secrets get permission

The Managed Identity isn't wired up to Key Vault yet. Go back and run the az role assignment create command. If you already did, it might just need time. Azure can take 2–3 minutes to propagate role assignments, so give it a moment before you dig further.

Error: Secret "DB-PASSWORD" not loaded. Did loadAllSecrets() run?

getFromCache() ran before loadAllSecrets() finished, meaning the startup sequence is out of order. Open server.js and confirm await loadAllSecrets() comes before app.listen(). If the order's fine, the secret might just not be in the vault yet. Run az keyvault secret list --vault-name YOUR_VAULT to double-check. (A name mismatch — wrong case, typo — throws SecretNotFound instead, which is the entry below.)

App starts locally but fails on Azure App Service

Almost always, the app setting. Either KEY_VAULT_NAME isn't in App Service configuration at all, or the vault name has a typo. Run az webapp log tail to see the actual startup error — that'll tell you which one.

AuthorizationFailed when running az role assignment create

You are a guest user in your Azure tenant and lack the Owner role needed to assign roles. Switch the existing vault to the access policy model — no need to recreate it or lose your secrets:

az keyvault update \
  --name your-vault-name \
  --resource-group keyvault-demo-rg \
  --enable-rbac-authorization false

If this happened during Set Up the Key Vault (granting yourself access), run:

az keyvault set-policy \
  --name your-vault-name \
  --object-id $(az ad signed-in-user show --query id -o tsv) \
  --secret-permissions get set list delete

If this happened during Grant Key Vault Access to the App (granting the Managed Identity access), run:

az keyvault set-policy \
  --name your-vault-name \
  --object-id $PRINCIPAL_ID \
  --secret-permissions get list

Key Vault returns SecretNotFound

The secret was never added, was deleted, or its name doesn't match exactly what your code requests — Key Vault secret names are case-sensitive. A secret named db-password and a request for DB-PASSWORD are different names. Run az keyvault secret list --vault-name YOUR_VAULT and compare what's actually in the vault against what loadAllSecrets() is asking for in src/config/secrets.js. Usually, it's a casing issue or a stray hyphen.

Wrapping Up

The .env file in this project contains exactly one value: the Key Vault name. That's not sensitive. Every actual secret — database passwords, API keys, signing secrets — lives in Key Vault and never touches your codebase or your deployment pipeline.

This is the pattern I use on Azure projects now. The startup check is the part I find most useful in practice: if Key Vault is unreachable or a secret is missing, the server exits immediately with a clear error instead of starting up broken and failing on the first real request. You find out right away, rather than getting an obscure database connection error two hours later.

To add another secret, put it in Key Vault and drop its name into the secretNames array — that's it. Everything else scales with it.

The full working code is on GitHub: nodejs-azure-keyvault

How to Build a Browser-Based PDF Redaction Tool Using JavaScript

Bhavin Sheth — Fri, 17 Jul 2026 20:33:11 +0000

PDF documents are frequently used to share invoices, contracts, reports, legal records, customer documents, financial statements, and internal business files. But before these documents are shared, they may contain information that shouldn't be visible to the recipient.

An invoice might include an account number. A customer document may contain a home address or phone number. A legal file could reveal confidential case information, while an internal report may contain names, references, or business data intended only for employees.

This is where PDF redaction becomes useful.

Redaction allows users to select sensitive areas of a document and permanently cover those areas before creating a new PDF. A practical redaction tool should also support multiple redaction areas, page selection, document preview, and final output verification.

In this tutorial, you'll build a browser-based PDF Redaction Tool using JavaScript. Users will upload a PDF, navigate through its pages, draw redaction boxes directly on the document preview, manage multiple redactions, apply them to selected pages, preview the processed document, rename the final file, and download the redacted PDF.

The entire workflow runs inside the browser. This is particularly useful for privacy-focused document tools because PDF processing can happen locally without requiring a backend server.

By the end of this tutorial, you'll understand not only how to draw redaction areas but also how to translate browser coordinates into PDF coordinates and apply those selections to the actual document.

Redaction Is Not the Same as Drawing a Black Box
How Browser-Based PDF Redaction Works
Understanding PDF and Canvas Coordinates
Project Setup
What Libraries Are We Using?
Creating the PDF Upload Interface
Previewing Uploaded PDF Pages
Drawing Redaction Areas on the PDF
Storing and Managing Redactions
Applying Redactions to Selected Pages
Generating the Redacted PDF
Previewing and Renaming the Final PDF
Downloading the Final PDF
Demo: How the PDF Redaction Tool Works
How to Verify the Redacted PDF
Performance Optimization Tips
Important Notes and Common Mistakes
Conclusion

Redaction Is Not the Same as Drawing a Black Box

A common mistake is assuming that placing a black rectangle over text automatically makes the information secure.

Visually, the document may look redacted. But depending on how the PDF is modified, the original text or image content may still exist underneath the rectangle.

For example, imagine adding a black box as a new annotation layer above an account number. The number is no longer visible on the page, but the underlying PDF content may still be present.

In some poorly redacted documents, users may be able to select, copy, search, or recover the hidden content.

This is why redaction must be treated differently from simple visual decoration.

In our browser-based workflow, the selected areas are applied while generating the processed PDF. The final document should then be reviewed carefully before it's shared.

Never assume that a black rectangle alone guarantees secure removal of underlying PDF content. For high-security or legally sensitive documents, the final file should be validated with a dedicated redaction verification process.

How Browser-Based PDF Redaction Works

The redaction workflow can be divided into a few clear stages.

First, the browser reads the uploaded PDF and renders a page preview. The preview gives users a visual surface where they can identify sensitive information.

Next, users click and drag over the preview to create redaction rectangles.

Each rectangle is stored as a set of coordinates.

const redaction = {
    page: 7,
    x: 420,
    y: 35,
    width: 310,
    height: 220
};

The application can store multiple rectangles for the same page.

redactions.push(redaction);

When users click Apply & Finalize, the application determines which pages should receive the selected redactions.

The redaction coordinates are then converted from preview coordinates to actual PDF page coordinates. Finally, the application modifies the PDF and generates a new document for preview and download.

The overall workflow looks like this:

Upload PDF
    ↓
Render Page Preview
    ↓
Draw Redaction Areas
    ↓
Store Coordinates
    ↓
Select Target Pages
    ↓
Apply Redactions
    ↓
Generate New PDF
    ↓
Preview and Download

Separating the interface from the PDF processing logic makes the application easier to manage and debug.

Understanding PDF and Canvas Coordinates

One of the most important technical parts of this project is coordinate conversion.

The PDF page shown inside the browser is usually scaled to fit the available screen space. A PDF page may have an actual width of 842 points, while the browser preview is displayed at only 600 pixels wide.

This means a rectangle drawn at x = 300 on the preview can't simply be placed at x = 300 in the PDF.

We'll first calculate the scale difference.

const scaleX =
    pdfPageWidth / canvasWidth;

const scaleY =
    pdfPageHeight / canvasHeight;

The selected rectangle can then be converted.

const pdfX =
    redaction.x * scaleX;

const pdfWidth =
    redaction.width * scaleX;

const pdfHeight =
    redaction.height * scaleY;

The Y coordinate requires extra attention because browser canvases and PDF pages commonly use different coordinate origins.

Canvas coordinates generally begin at the top-left corner. PDF coordinates commonly work from the bottom-left.

The Y position can therefore be converted like this:

const pdfY =
    pdfPageHeight -
    ((redaction.y + redaction.height) * scaleY);

This small calculation is critical.

Without correct coordinate conversion, a redaction box drawn over a phone number might appear several centimeters away from that number in the generated PDF.

Accurate coordinate mapping ensures that the redaction users draw in the browser matches the same area in the final document.

Project Setup

We'll keep the project structure simple because the redaction workflow runs entirely inside the browser.

Create a new project folder with three files:

pdf-redaction-tool/
│
├── index.html
├── style.css
└── script.js

The index.html file contains the upload interface, PDF preview, redaction controls, and final download section.

The style.css file handles the page layout and redaction overlay styling.

The script.js file contains the PDF loading, rendering, coordinate tracking, redaction management, and final PDF generation logic.

Start with a basic HTML structure.





    

    

    PDF Redaction Tool

Separating the upload, editor, and result sections makes it easier to show and hide different parts of the interface as users move through the redaction workflow.

What Libraries Are We Using?

We'll use PDF.js and PDF-lib for this project.

PDF.js handles PDF loading and page rendering. It allows us to display an uploaded PDF page inside a canvas so users can visually select the areas they want to redact.

PDF-lib handles the final document modification. After the user creates redaction areas, PDF-lib opens the original PDF, accesses the selected pages, and applies the redaction rectangles before generating a new file.

Add both libraries before your main JavaScript file.

Configure the PDF.js worker.

pdfjsLib.GlobalWorkerOptions.workerSrc =
    "https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js";

We'll also create a few variables for storing the active document and redaction data.

let pdfDocument = null;

let pdfBytes = null;

let currentPage = 1;

let redactions = {};

Instead of storing every redaction in one flat array, we can organize them by page number.

redactions = {
    1: [],
    2: [],
    7: []
};

This structure makes page navigation and per-page redaction management much easier.

Creating the PDF Upload Interface

The first screen users see is the PDF upload area.

Users can drag a document onto the upload box or click the Select PDF button to open the browser's file picker.

Create the upload interface.



    PDF Redaction Tool

    
        Upload your PDF to permanently black out
        sensitive information.
    

    

        ☁

        Drag & Drop PDF Here

        Or click to browse file

Connect the button to the hidden file input.

const pdfInput =
    document.getElementById("pdfInput");

const selectPdfButton =
    document.getElementById("selectPdfButton");

selectPdfButton.addEventListener("click", () => {

    pdfInput.click();

});

Next, listen for file selection.

pdfInput.addEventListener("change", async event => {

    const file = event.target.files[0];

    if (!file) {
        return;
    }

    await loadPdfFile(file);

});

Before loading the document, validate the selected file.

async function loadPdfFile(file) {

    if (file.type !== "application/pdf") {

        alert("Please select a valid PDF file.");

        return;

    }

    pdfBytes =
        await file.arrayBuffer();

}

We can also support drag-and-drop uploads.

dropZone.addEventListener("dragover", event => {

    event.preventDefault();

    dropZone.classList.add("dragging");

});

dropZone.addEventListener("dragleave", () => {

    dropZone.classList.remove("dragging");

});

dropZone.addEventListener("drop", async event => {

    event.preventDefault();

    dropZone.classList.remove("dragging");

    const file =
        event.dataTransfer.files[0];

    if (file) {

        await loadPdfFile(file);

    }

});

After reading the file, load it with PDF.js.

pdfDocument =
    await pdfjsLib
        .getDocument({
            data: pdfBytes.slice(0)
        })
        .promise;

currentPage = 1;

await renderPage(currentPage);

At this point, the document is ready for preview and redaction.

Previewing Uploaded PDF Pages

Once the PDF has loaded, the application displays the current page inside a canvas.

The canvas serves two purposes. First, it gives users an accurate preview of the document. Second, it becomes the visual surface where redaction rectangles will be drawn.

Create the editor preview.



    

        

            

            

        

        

            

            
                Page 1 of 1

The pdfCanvas displays the PDF page.

The redactionLayer sits above the canvas and contains the selection boxes created by the user.

Render the active page using PDF.js.

async function renderPage(pageNumber) {

    const page =
        await pdfDocument.getPage(pageNumber);

    const viewport =
        page.getViewport({
            scale: 1.4
        });

    const canvas =
        document.getElementById("pdfCanvas");

    const context =
        canvas.getContext("2d");

    canvas.width =
        viewport.width;

    canvas.height =
        viewport.height;

    await page.render({

        canvasContext: context,

        viewport: viewport

    }).promise;

    updatePageInformation();

    renderSavedRedactions();

}

Update the page navigation information.

function updatePageInformation() {

    document
        .getElementById("pageInfo")
        .textContent =
        `Page ${currentPage} of ${pdfDocument.numPages}`;

}

Users can move to the previous page.

previousPage.addEventListener("click", async () => {

    if (currentPage <= 1) {
        return;
    }

    currentPage--;

    await renderPage(currentPage);

});

The next-page button works in the same way.

nextPage.addEventListener("click", async () => {

    if (
        currentPage >= pdfDocument.numPages
    ) {
        return;
    }

    currentPage++;

    await renderPage(currentPage);

});

Whenever users change pages, the canvas renders the selected PDF page and restores any redaction boxes already saved for that page.

This is important because redactions are page-specific. A rectangle created on page 7 should not automatically appear on page 8 unless the user later chooses to apply that selection to multiple pages.

The PDF is now loaded, rendered, and ready for user interaction.

Drawing Redaction Areas on the PDF

Now that the PDF page is visible, users need a simple way to mark the information they want to hide.

In this project, users can click and drag directly over the page preview to create a redaction rectangle. The interaction is similar to selecting an area in an image editor.

We'll first track the starting position of the pointer.

let isDrawing = false;

let startX = 0;
let startY = 0;

let activeBox = null;

Listen for the pointer-down event on the redaction layer.

redactionLayer.addEventListener(
    "pointerdown",
    event => {

        isDrawing = true;

        const bounds =
            redactionLayer.getBoundingClientRect();

        startX =
            event.clientX - bounds.left;

        startY =
            event.clientY - bounds.top;

        activeBox =
            document.createElement("div");

        activeBox.className =
            "redaction-box";

        activeBox.style.left =
            `${startX}px`;

        activeBox.style.top =
            `${startY}px`;

        redactionLayer.appendChild(activeBox);

    }
);

As the pointer moves, update the rectangle dimensions.

redactionLayer.addEventListener(
    "pointermove",
    event => {

        if (!isDrawing) {
            return;
        }

        const bounds =
            redactionLayer.getBoundingClientRect();

        const currentX =
            event.clientX - bounds.left;

        const currentY =
            event.clientY - bounds.top;

        const width =
            Math.abs(currentX - startX);

        const height =
            Math.abs(currentY - startY);

        activeBox.style.width =
            `${width}px`;

        activeBox.style.height =
            `${height}px`;

        activeBox.style.left =
            `${Math.min(startX, currentX)}px`;

        activeBox.style.top =
            `${Math.min(startY, currentY)}px`;

    }
);

The Math.min() calls are important because users may drag in any direction. They can begin at the top-left and move down, or start at the bottom-right and drag upward.

When the pointer is released, save the completed rectangle.

redactionLayer.addEventListener(
    "pointerup",
    () => {

        if (!isDrawing) {
            return;
        }

        isDrawing = false;

        saveRedaction(activeBox);

        activeBox = null;

    }
);

The redaction area can be styled as a semi-transparent black rectangle during editing.

.redaction-box {
    position: absolute;
    background: rgba(0, 0, 0, 0.8);
    border: 1px dashed #ffffff;
    cursor: move;
}

Using a transparent preview helps users see which content is currently covered while still recognizing the surrounding page.

Storing and Managing Redactions

Drawing a rectangle visually is only the first step. The application also needs to remember its position and dimensions.

When a redaction box is completed, read its current coordinates.

function saveRedaction(box) {

    const redaction = {

        x: parseFloat(box.style.left),

        y: parseFloat(box.style.top),

        width: box.offsetWidth,

        height: box.offsetHeight

    };

    if (!redactions[currentPage]) {

        redactions[currentPage] = [];

    }

    redactions[currentPage].push(redaction);

    renderSavedRedactions();

    updateRedactionList();

}

Because redactions are stored by page, users can navigate through the document without losing their selections.

For example:

redactions = {

    7: [
        {
            x: 420,
            y: 35,
            width: 310,
            height: 220
        },

        {
            x: 160,
            y: 320,
            width: 150,
            height: 140
        }
    ]

};

Page 7 now contains two redaction areas.

The interface can display them as Redaction #1 and Redaction #2.

function updateRedactionList() {

    const list =
        document.getElementById(
            "redactionList"
        );

    list.innerHTML = "";

    const pageRedactions =
        redactions[currentPage] || [];

    pageRedactions.forEach(
        (redaction, index) => {

            const item =
                document.createElement("div");

            item.textContent =
                `Redaction #${index + 1}`;

            list.appendChild(item);

        }
    );

}

This list gives users a clear overview of the areas selected on the current page.

Removing One Redaction

Users may accidentally cover the wrong section of a document. They shouldn't have to clear every selection and begin again.

Add a remove button to each redaction item.

const removeButton =
    document.createElement("button");

removeButton.textContent = "×";

removeButton.addEventListener(
    "click",
    () => {

        removeRedaction(index);

    }
);

item.appendChild(removeButton);

Remove only the selected rectangle.

function removeRedaction(index) {

    redactions[currentPage]
        .splice(index, 1);

    renderSavedRedactions();

    updateRedactionList();

}

The remaining redactions stay unchanged.

Clearing All Redactions from the Current Page

The Clear All on This Page button removes every selection from the active page.

clearPageButton.addEventListener(
    "click",
    () => {

        redactions[currentPage] = [];

        renderSavedRedactions();

        updateRedactionList();

    }
);

Notice that this doesn't remove redactions created on other pages.

If page 7 is cleared, selections saved on pages 2 or 5 remain available.

Applying Redactions to Selected Pages

A redaction tool needs to handle more than a single page.

Sometimes the sensitive information appears only once. In other documents, the same information may repeat across several pages.

For example, a confidential reference number may appear in the header of every page. Manually drawing the same rectangle 50 times would be inefficient.

Our interface provides three page selection modes:

Current page only applies the redaction to the active page.
All pages copies the current page's redaction positions across the complete document.
Specific pages applies the selections only to page numbers or ranges entered by the user.

Create the page selection controls.

3. Apply to Pages


    
    Current page only



    
    All pages



    
    Specific pages

Read the selected mode.

const applyMode =
    document.querySelector(
        'input[name="applyMode"]:checked'
    ).value;

For the current page, only one page number is required.

if (applyMode === "current") {

    targetPages = [currentPage];

}

For all pages, generate the complete page list.

if (applyMode === "all") {

    targetPages =
        Array.from(
            {
                length:
                    pdfDocument.numPages
            },
            (_, index) => index + 1
        );

}

Specific page ranges require a small parser.

function parsePageRange(value) {

    const pages = new Set();

    value.split(",").forEach(part => {

        const range =
            part.trim().split("-");

        if (range.length === 2) {

            const start =
                Number(range[0]);

            const end =
                Number(range[1]);

            for (
                let page = start;
                page <= end;
                page++
            ) {

                pages.add(page);

            }

        } else {

            pages.add(Number(range[0]));

        }

    });

    return [...pages];

}

The value:

1, 3-5, 10

becomes:

[1, 3, 4, 5, 10]

Before processing, remove invalid page numbers.

targetPages =
    targetPages.filter(page =>

        page >= 1 &&

        page <= pdfDocument.numPages

    );

This page selection feature is particularly useful for repeated headers, footers, document IDs, or other information positioned consistently across several pages.

Applying and Finalizing the Redactions

After users have created their redaction areas and selected the target pages, they can click Apply & Finalize.

Create the action controls.

Connect the finalize button to the processing function.

applyButton.addEventListener(
    "click",
    async () => {

        const pageRedactions =
            redactions[currentPage] || [];

        if (pageRedactions.length === 0) {

            alert(
                "Please add at least one redaction."
            );

            return;

        }

        await generateRedactedPdf();

    }
);

The Start Over button clears the current document and returns users to the upload interface.

startOverButton.addEventListener(
    "click",
    () => {

        pdfDocument = null;

        pdfBytes = null;

        currentPage = 1;

        redactions = {};

        pdfInput.value = "";

        location.reload();

    }
);

In a production application, you can reset individual interface sections instead of reloading the complete page.

At this stage, users can draw several redaction boxes, remove individual selections, clear all redactions from the active page, and choose exactly which pages should receive the selected redaction areas.

Generating the Redacted PDF

The redaction boxes currently exist only in the browser preview. To create the final document, we need to apply those positions to the actual PDF pages.

Load the original PDF using PDF-lib.

async function generateRedactedPdf() {

    const pdfDoc =
        await PDFLib.PDFDocument.load(
            pdfBytes.slice(0)
        );

    const pages =
        pdfDoc.getPages();

    const sourceRedactions =
        redactions[currentPage] || [];

    const targetPages =
        getTargetPages();

}

Next, loop through the selected pages.

targetPages.forEach(pageNumber => {

    const page =
        pages[pageNumber - 1];

    applyPageRedactions(
        page,
        sourceRedactions
    );

});

The browser preview and PDF page may have different dimensions, so each rectangle must be scaled before it's applied.

function applyPageRedactions(
    page,
    pageRedactions
) {

    const {
        width: pdfWidth,
        height: pdfHeight
    } = page.getSize();

    const canvas =
        document.getElementById(
            "pdfCanvas"
        );

    const scaleX =
        pdfWidth / canvas.width;

    const scaleY =
        pdfHeight / canvas.height;

    pageRedactions.forEach(
        redaction => {

            const x =
                redaction.x * scaleX;

            const width =
                redaction.width * scaleX;

            const height =
                redaction.height * scaleY;

            const y =
                pdfHeight -
                (
                    redaction.y +
                    redaction.height
                ) * scaleY;

            page.drawRectangle({

                x,
                y,
                width,
                height,

                color:
                    PDFLib.rgb(0, 0, 0)

            });

        }
    );

}

Here, the black rectangles are written into the generated PDF page content rather than remaining browser-only preview elements.

Finally, save the processed document.

const outputBytes =
    await pdfDoc.save();

const outputBlob =
    new Blob(
        [outputBytes],
        {
            type: "application/pdf"
        }
    );

showFinalPreview(outputBlob);

This distinction is important because the visual result alone should never be used as proof that hidden content has been securely removed.

Previewing and Renaming the Final PDF

Before downloading the document, users should be able to review the processed pages.

The final preview helps confirm that each selected area appears in the expected position.

Create a new PDF.js document from the processed file.

async function showFinalPreview(blob) {

    const bytes =
        await blob.arrayBuffer();

    const finalPdf =
        await pdfjsLib
            .getDocument({
                data: bytes
            })
            .promise;

    renderFinalPage(
        finalPdf,
        1
    );

}

The preview can use the same page navigation approach we used earlier.

let finalPage = 1;

nextFinalPage.addEventListener(
    "click",
    async () => {

        if (
            finalPage >=
            finalPdf.numPages
        ) {
            return;
        }

        finalPage++;

        await renderFinalPage(
            finalPdf,
            finalPage
        );

    }
);

Users can move through the generated PDF and visually check the applied areas before saving the file.

The tool also allows users to change the output filename.

For example, the automatically generated name might be:

combined-images (12)_redacted.pdf

Create an editable filename input.

Before downloading, make sure the filename ends with .pdf.

function getOutputFilename() {

    let filename =
        outputFilename.value.trim();

    if (
        !filename
            .toLowerCase()
            .endsWith(".pdf")
    ) {

        filename += ".pdf";

    }

    return filename;

}

Allowing the filename to be changed is useful when users process several versions of the same document.

Downloading the Final PDF

The final result section displays basic information about the processed document.

In this project, users can see the filename, total number of pages, and final file size before downloading.

Calculate the file size in megabytes.

function formatFileSize(bytes) {

    return (
        bytes / 1024 / 1024
    ).toFixed(2) + " MB";

}

Update the result information.

filePageCount.textContent =
    `Total Pages: ${pdfDocument.numPages}`;

fileSize.textContent =
    `File Size: ${
        formatFileSize(
            outputBlob.size
        )
    }`;

To download the document, create a temporary object URL.

downloadButton.addEventListener(
    "click",
    () => {

        const url =
            URL.createObjectURL(
                outputBlob
            );

        const link =
            document.createElement("a");

        link.href = url;

        link.download =
            getOutputFilename();

        link.click();

        URL.revokeObjectURL(url);

    }
);

The browser downloads the generated PDF using the filename selected by the user.

.After downloading, users can click Start Over to clear the existing document and process another PDF.

function resetTool() {

    pdfDocument = null;

    pdfBytes = null;

    redactions = {};

    currentPage = 1;

    pdfInput.value = "";

    showUploadSection();

}

The complete processing workflow is now connected: users can mark areas on a page, apply those selections, preview the result, rename the generated file, review its details, and download the processed PDF.

Demo: How the PDF Redaction Tool Works

Now that the complete redaction workflow is connected, let's walk through the application from upload to download.

Step 1: Upload the PDF Document

Users begin by uploading a PDF through the drag-and-drop area or by clicking the Select PDF button.

The browser validates the file, reads the document into memory, and prepares it for local processing. No backend server is required for this workflow.

Step 2: Preview and Navigate the PDF

After the file loads, the current PDF page appears inside the preview area.

Page navigation controls allow users to move backward and forward through the document. The current page number and total page count are displayed below the preview.

Users can review the document first and navigate to the page containing the information they want to cover.

Step 3: Configure the Redaction

The redaction settings appear beside the PDF preview.

Users draw a rectangle directly over the document by clicking and dragging across the sensitive area. The selected region appears as a dark overlay, making the chosen position easy to verify.

The page application controls also let users choose whether the same redaction position should be applied to the current page, all pages, or specific page numbers.

This is helpful when the same field appears in a consistent position across several pages.

Step 4: Manage Multiple Redaction Areas

A single page may contain several areas that need to be covered.

For example, users may select a name near the top of the page and another piece of information farther down the document.

Each selection appears separately as Redaction #1, Redaction #2, and so on.

Individual remove controls allow users to delete one selection without affecting the others. The Clear All on This Page option removes every redaction area from the active page.

This gives users a chance to correct selections before processing the PDF.

Step 5: Apply and Finalize the PDF

Once the redaction areas and target pages are ready, users click Apply & Finalize.

The application converts the browser selection coordinates into PDF page coordinates and applies the opaque areas to the selected pages while generating the processed document.

If the wrong PDF was uploaded or users want to begin again, the Start Over button resets the current workflow.

Step 6: Preview the Processed PDF

After processing finishes, the generated PDF appears in a new preview section.

Users can navigate through the document and visually confirm that the selected areas are covered in the expected locations.

This review stage is important. A small coordinate or page-selection mistake could leave information visible on another page.

Step 7: Rename the PDF

Before downloading, users can edit the generated filename.

The application may automatically add _redacted to the original filename, but users can replace it with a name that better matches their document workflow.

For example:

customer-record_redacted.pdf

or:

public-report-copy.pdf

Step 8: Review File Details and Download

The final section displays the output filename, number of pages, and generated file size.

After reviewing these details, users click Download to save the PDF locally.

The browser creates the download directly from the processed document data.

Step 9: Start Over with Another PDF

After downloading the file, users can click Start Over.

The application clears the current PDF, page preview, stored coordinates, and generated result before returning to the upload interface.

Users can then process another document without manually refreshing the browser.

How to Verify the Redacted PDF

A document that looks correct in the preview should still be checked before it's shared.

First, navigate through every affected page and confirm that each intended area is fully covered. Pay particular attention to redactions applied across multiple pages because page layouts may not always be identical.

The application can perform a simple check to confirm that redaction areas exist before finalization.

const totalRedactions =
    Object.values(redactions)
        .reduce(
            (total, items) =>
                total + items.length,
            0
        );

if (totalRedactions === 0) {

    alert(
        "No redaction areas were added."
    );

    return;

}

You should also verify that every selected target page exists.

const validPages =
    targetPages.every(page =>

        page >= 1 &&

        page <= pdfDocument.numPages

    );

For visual masking workflows like the rectangle-based implementation shown here, remember that an opaque rectangle does not by itself prove that the underlying PDF content has been securely removed.

If the document contains legally protected, highly confidential, or compliance-sensitive information, use a standards-based redaction and sanitization process that removes the underlying content objects, then test the result for text selection, searchability, annotations, metadata, and other recoverable content before sharing it.

That verification distinction is especially important in a redaction project.

Performance Optimization Tips

PDF redaction itself may appear simple, but page rendering and document generation can consume noticeable browser memory when working with large files.

Avoid rendering every PDF page at full resolution simultaneously. Render the active page when users navigate to it.

await renderPage(currentPage);

Store redaction coordinates as small JavaScript objects rather than saving complete canvas images.

redactions[currentPage].push({

    x,
    y,
    width,
    height

});

When generating the output, modify only the required pages.

for (
    const pageNumber of targetPages
) {

    const page =
        pages[pageNumber - 1];

    applyPageRedactions(
        page,
        sourceRedactions
    );

}

Temporary object URLs should also be released after use.

URL.revokeObjectURL(url);

These choices keep the interface responsive and reduce unnecessary memory use, particularly when processing long reports or multi-page business documents.

Important Notes and Common Mistakes

The most common mistake in a redaction interface is incorrect coordinate conversion.

The canvas preview and actual PDF page may have different dimensions. Applying browser coordinates directly to the PDF can move the rectangle away from the intended content.

Always calculate the scale values first.

const scaleX =
    pdfWidth / canvas.width;

const scaleY =
    pdfHeight / canvas.height;

Another mistake is forgetting that PDF and canvas Y coordinates may use different origins.

const pdfY =
    pdfHeight -
    (
        redaction.y +
        redaction.height
    ) * scaleY;

Users should also be careful when applying one selection to all pages. A header may appear in the same position throughout a document, but other page layouts can change. Always preview the processed result.

Validate custom page ranges before processing.

targetPages =
    targetPages.filter(page =>

        Number.isInteger(page) &&

        page >= 1 &&

        page <= pdfDocument.numPages

    );

Finally, don't describe a visually covered area as securely removed unless the implementation actually removes the underlying text, image, annotation, and related content from the PDF structure.

For a simple browser project, opaque masking demonstrates coordinate mapping and PDF modification well. A production redaction system handling sensitive information requires stronger content-removal and output-sanitization logic.

Conclusion

In this tutorial, you built a browser-based PDF redaction interface using JavaScript.

You learned how to upload a PDF, render document pages with PDF.js, navigate between pages, draw redaction areas, store rectangle coordinates, manage multiple selections, choose target pages, convert canvas coordinates into PDF coordinates, generate a processed PDF, preview the result, rename the output file, and download it locally.

You also saw an important security distinction: visually covering content with an opaque rectangle is not automatically the same as permanently removing the underlying PDF content. That difference matters when moving from a learning project to a production-grade redaction system.

You can explore the browser-based workflow with the PDF Redaction Tool.

Once you understand the coordinate and page-processing workflow, you can extend the project with searchable-text detection, automatic pattern identification, annotation cleanup, metadata sanitization, redaction verification, or a true content-removal pipeline.

The same coordinate-mapping concepts can also be reused when building PDF annotation, signature, highlighting, cropping, and document review tools.

Intro to Shaders: JavaScript and p5.js Course for Beginners

Beau Carnes — Thu, 16 Jul 2026 11:35:18 +0000

Are you ready to unlock the true rendering power of your computer and create breathtaking visuals? We just published a new course on the freeCodeCamp.org YouTube channel that will teach you the fundamentals of graphics programming.

This beginner-friendly course, developed by Patt Vira, is designed for anyone eager to break into WebGL and the math of motion, requiring absolutely zero prior shader experience.

In this course, you will learn exactly why shaders are so much faster than traditional CPU rendering by understanding the difference between how CPUs and GPUs handle data. You will dive into the GLSL language to write code that executes on millions of pixels simultaneously. You will progressively master core concepts like mapping coordinate spaces, leveraging shaping functions to sculpt colors, domain repetition for tiling, and using distance functions to draw and animate complex shapes.

By following along using JavaScript and the p5.js library, you will apply these exact techniques to build a stunning, animated, glowing fractal heart entirely from scratch. You will learn how to structure your files, pass dynamic variables from your JavaScript code to the GPU, and mix colors using cosine-based palettes for a rich, professional spectrum.

You can watch the full course on the YouTube channel (1-hour watch).

How to Build a RAG Chatbot for Your Docs with Node.js, Google Gemini, and pgvector

Zia Ullah — Wed, 15 Jul 2026 15:26:34 +0000

I was helping a team that had a 200-page API documentation PDF. Every new engineer spent their first two weeks Ctrl+F-ing through it, asking the same questions in Slack, getting redirected to the same paragraphs on page 47.

The doc was accurate. It was even well-written. But nobody could find anything in it fast enough for it to be useful.

That's the problem RAG, or Retrieval-Augmented Generation, solves.

The naïve approach is to stuff your entire PDF into a prompt and let the model figure it out. That breaks down fast: context windows overflow, costs spike on every request, and the model loses the thread somewhere in the wall of text.

RAG takes a different approach. Your documents get broken into small chunks upfront. Ask it a question and it digs out the 3 or 4 chunks that best match it — those are what the model actually sees. The model gets a tight, focused context. The answer comes from what your document actually says — not from whatever the LLM memorized during training.

In this tutorial, you'll build that from scratch. Upload any PDF — an API reference, an internal spec, a research paper — and ask questions about it in plain English. The system finds the relevant sections and answers from the document itself, not from general training data.

The stack: Node.js with Express, Google Gemini for embeddings, Groq for text generation, and pgvector running in Docker. Every piece of it is free — no credit card, no trial period.

The complete code is on GitHub at nodejs-rag-chatbot.

How RAG Works
What We're Building
Prerequisites
Project Setup
Set Up Postgres with pgvector Using Docker
Connect to the Database
Build the Ingestion Pipeline
Build the Query Pipeline
Build the Chat API with Express
Test the Chatbot
Troubleshooting
How to Swap in OpenAI
What to Build Next

How RAG Works

RAG has two phases, and the code maps directly to both.

Ingestion phase — runs once when you upload a document:

Pull the raw text out of the PDF
Break it into chunks of 400 to 600 characters each, with a bit of overlap so nothing important gets cut at a boundary
Run each chunk through an embedding model, which turns it into a vector (a long list of numbers that captures what the text means)
Store each chunk and its vector in Postgres

Query phase — runs every time someone asks a question:

Embed the user's question using the same model
Search the database for chunks whose vectors are closest to the question vector
Take the top 5 matching chunks and assemble them into a context block
Send context + question to the LLM and return its answer

The reason this works better than keyword search: the embedding model captures meaning, not just exact words. If your doc says "terminate the process" and the user asks "how do I stop it?", vector similarity finds that match. Regular string matching doesn't.

One thing that trips people up: you must use the same embedding model at query time as you did at ingestion. The model defines the geometric space those vectors live in. Switch models halfway through and the coordinates stop meaning the same thing — you'd be comparing apples to completely different apples.

What We're Building

The architecture is intentionally minimal: two endpoints, with nothing you don't need:

POST /ingest: accepts a PDF upload, chunks it, embeds each chunk, stores vectors in pgvector
POST /chat: accepts a question, retrieves the most relevant chunks, returns an LLM-generated answer

The full tech stack:

Node.js + Express — API layer
Google Gemini free API — gemini-embedding-001 for embeddings (3,072 dimensions per chunk)
Groq free API — llama-3.1-8b-instant for text generation
PostgreSQL + pgvector — vector storage and cosine similarity search, running in Docker
pdf-parse — extracts raw text from PDF buffers

Gemini handles embeddings and Groq handles generation. Splitting them across two providers isn't arbitrary. Gemini's generation API has a quota limit of zero in certain regions (including Pakistan), while Groq works everywhere with no restrictions. Using Groq for generation means this tutorial runs the same way regardless of where you are.

Prerequisites

Before you start:

Node.js 20+ installed on your machine
Docker Desktop running (this is how we'll run Postgres locally)
A free Google Gemini API key (for embeddings)
A free Groq API key (for text generation)

How to Get Your Free Gemini API Key

Go to aistudio.google.com/app/apikey and sign in with a Google account
Click "Create API key"
Select "Create API key in new project"
Copy the key — it starts with AIzaSy...

No credit card or billing required.

How to Get Your Free Groq API Key

Go to console.groq.com and sign up with Google
Click "API Keys" in the left sidebar
Click "Create API Key", give it a name, copy the key — it starts with gsk_...

Groq is free with generous rate limits and works in all regions.

Project Setup

Create the project directory and initialize it:

mkdir nodejs-rag-chatbot
cd nodejs-rag-chatbot
npm init -y

Install dependencies:

npm install express pg pdf-parse uuid dotenv multer
npm install --save-dev nodemon

A quick note on the packages: multer is what makes file uploads work on the /ingest endpoint. Without it, Express can't parse multipart form data.

pdf-parse does the heavy lifting on PDFs, though watch out for scanned PDFs. Those are just images with no text layer underneath, so you'll get back an empty string.

pg talks to Postgres, uuid gives each row a unique ID, and dotenv loads your keys before the app does anything.

Create a .env in the project root. It needs seven values:

GEMINI_API_KEY=AIzaSy...         ← your Gemini key from Google AI Studio
GROQ_API_KEY=gsk_...             ← your Groq key from console.groq.com
POSTGRES_USER=rag_user
POSTGRES_PASSWORD=rag_pass       ← choose any password, this is local only
POSTGRES_DB=rag_db
DATABASE_URL=postgresql://rag_user:rag_pass@localhost:5432/rag_db
PORT=3000

One thing: the password in POSTGRES_PASSWORD and the one in DATABASE_URL must match exactly. I changed just one of them once and spent way too long debugging a "password authentication failed" error before realising the two values were out of sync.

Update package.json scripts:

"scripts": {
  "start": "node src/index.js",
  "dev": "nodemon src/index.js"
}

Create the src directory:

mkdir src

Your final folder structure will look like this:

nodejs-rag-chatbot/
├── src/
│   ├── index.js        ← Express app entry point
│   ├── db.js           ← Postgres connection and schema setup
│   ├── embeddings.js   ← Gemini embedding + Groq generation
│   ├── ingest.js       ← Document ingestion pipeline
│   └── query.js        ← RAG query pipeline
├── docker-compose.yml
├── .env
└── package.json

Set Up Postgres with pgvector Using Docker

pgvector adds a vector column type to Postgres and the operators needed to search it by similarity. Normally you'd have to install it yourself, but the pgvector/pgvector Docker image ships with it already baked in. Just pull the image and you're good.

Now add docker-compose.yml to the project root:

services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Those ${VARIABLE} references get swapped out from .env when Compose starts — so docker-compose.yml itself stays clean. This is worth doing from day one. I've seen people skip this and regret it after a repo goes public.

Start it:

docker compose up -d

Connect to the Database

Create src/db.js. This sets up the connection pool and creates the documents table on first run:

const { Pool } = require('pg');

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

async function initDb() {
  await pool.query(`CREATE EXTENSION IF NOT EXISTS vector`);

  await pool.query(`
    CREATE TABLE IF NOT EXISTS documents (
      id UUID PRIMARY KEY,
      content TEXT NOT NULL,
      source TEXT NOT NULL,
      embedding VECTOR(3072)
    )
  `);

  console.log('Database ready');
}

module.exports = { pool, initDb };

The VECTOR(3072) dimension matches the output of Gemini's gemini-embedding-001 model exactly. If you use a different embedding model in the future, check its output dimensions and update this number to match.

Build the Ingestion Pipeline

Start with embeddings.js. This file is the bridge to both external APIs — Gemini for turning text into vectors, Groq for generating the final answer. Keeping both in one place means a single file to touch if you ever swap providers.

src/embeddings.js:

const GEMINI_KEY = process.env.GEMINI_API_KEY;
const GEMINI_BASE = 'https://generativelanguage.googleapis.com/v1/models';

async function embedText(text) {
  const res = await fetch(
    `${GEMINI_BASE}/gemini-embedding-001:embedContent?key=${GEMINI_KEY}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ content: { parts: [{ text }] } }),
    }
  );
  const data = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(data));
  return data.embedding.values;
}

async function generateAnswer(context, question) {
  const res = await fetch(
    'https://api.groq.com/openai/v1/chat/completions',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.GROQ_API_KEY}`,
      },
      body: JSON.stringify({
        model: 'llama-3.1-8b-instant',
        messages: [
          {
            role: 'system',
            content: 'You are a helpful assistant. Answer the question using only the context provided. If the context does not contain enough information, say so clearly.',
          },
          {
            role: 'user',
            content: `Context:\n${context}\n\nQuestion: ${question}`,
          },
        ],
      }),
    }
  );
  const data = await res.json();
  if (!res.ok) throw new Error(JSON.stringify(data));
  return data.choices[0].message.content;
}

module.exports = { embedText, generateAnswer };

We're calling both APIs directly with Node.js's built-in fetch rather than the official SDKs. The reason is practical: Google's Node.js SDK routes requests through the v1beta endpoint by default, and gemini-embedding-001 isn't available there — only on v1. Direct fetch sidesteps that entirely and keeps the dependency count low.

src/ingest.js:

const pdfParse = require('pdf-parse');
const { v4: uuidv4 } = require('uuid');
const { pool } = require('./db');
const { embedText } = require('./embeddings');

function chunkText(text, chunkSize = 500, overlap = 50) {
  const chunks = [];
  let start = 0;

  while (start < text.length) {
    const end = Math.min(start + chunkSize, text.length);
    chunks.push(text.slice(start, end).trim());
    start += chunkSize - overlap;
  }

  return chunks.filter(chunk => chunk.length > 50);
}

async function ingestDocument(buffer, filename) {
  const { text } = await pdfParse(buffer);
  const chunks = chunkText(text);

  console.log(`Processing ${chunks.length} chunks from "${filename}"`);

  for (const chunk of chunks) {
    const embedding = await embedText(chunk);

    await pool.query(
      `INSERT INTO documents (id, content, source, embedding)
       VALUES ($1, $2, $3, $4::vector)`,
      [uuidv4(), chunk, filename, JSON.stringify(embedding)]
    );
  }

  return chunks.length;
}

module.exports = { ingestDocument };

500 characters per chunk, with 50 characters of overlap between neighbours.

Why the overlap? Without it, a sentence that straddles a boundary gets split, half in one chunk, half in the next — and neither piece makes sense on its own when retrieved. The overlap keeps those boundary sentences intact.

For most technical docs, 500 is a good starting point. Dense legal or financial text tends to need something closer to 300.

Build the Query Pipeline

src/query.js:

const { pool } = require('./db');
const { embedText, generateAnswer } = require('./embeddings');

async function queryDocuments(question) {
  const questionEmbedding = await embedText(question);

  const { rows } = await pool.query(
    `SELECT content, source,
            1 - (embedding <=> $1::vector) AS similarity
     FROM documents
     ORDER BY embedding <=> $1::vector
     LIMIT 5`,
    [JSON.stringify(questionEmbedding)]
  );

  if (rows.length === 0) {
    return { answer: 'No relevant documents found.', sources: [] };
  }

  const context = rows.map(r => r.content).join('\n\n---\n\n');
  const answer = await generateAnswer(context, question);

  return {
    answer,
    sources: [...new Set(rows.map(r => r.source))],
    topSimilarity: parseFloat(rows[0].similarity).toFixed(3),
  };
}

module.exports = { queryDocuments };

The <=> operator is pgvector's cosine distance. Semantically similar text produces vectors that point in the same direction — so the distance between them is small. Flip that with 1 - distance and you get a similarity score, where anything close to 1 means a strong match.

I found 0.7 to be a reliable threshold in my testing — chunks above that were almost always relevant. Anything below 0.5 and the retrieval was really stretching, pulling chunks that shared a keyword or two but weren't actually answering the question.

When that happens, the system prompt instruction ("if the context does not contain enough information, say so clearly") becomes important. A well-behaved model will tell the user it doesn't know rather than guess.

We also surface the source filename. Once you've ingested more than one document, users need to know whether that answer came from the architecture spec or the incident report.

Build the Chat API with Express

src/index.js:

require('dotenv').config();
const express = require('express');
const multer = require('multer');
const { initDb } = require('./db');
const { ingestDocument } = require('./ingest');
const { queryDocuments } = require('./query');

const app = express();
const upload = multer({ storage: multer.memoryStorage() });

app.use(express.json());

app.post('/ingest', upload.single('file'), async (req, res) => {
  if (!req.file) {
    return res.status(400).json({ error: 'No file uploaded' });
  }

  if (!req.file.mimetype.includes('pdf')) {
    return res.status(400).json({ error: 'Only PDF files are supported' });
  }

  try {
    const count = await ingestDocument(req.file.buffer, req.file.originalname);
    res.json({ message: `Ingested ${count} chunks from "${req.file.originalname}"` });
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: 'Ingestion failed', detail: err.message });
  }
});

app.post('/chat', async (req, res) => {
  const { question } = req.body;

  if (!question || typeof question !== 'string') {
    return res.status(400).json({ error: 'question is required' });
  }

  try {
    const result = await queryDocuments(question);
    res.json(result);
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: 'Query failed', detail: err.message });
  }
});

const PORT = process.env.PORT || 3000;

initDb().then(() => {
  app.listen(PORT, () => {
    console.log(`RAG chatbot running on port ${PORT}`);
  });
});

memoryStorage() keeps the uploaded file in a buffer instead of writing it to disk. We parse it and store the chunks immediately, so there's nothing to save.

Test the Chatbot

Start the server:

npm run dev

You should see:

Database ready
RAG chatbot running on port 3000

Upload a PDF. Any PDF works. I tested with a copy of a Node.js best practices guide:

# Linux / macOS
curl -X POST http://localhost:3000/ingest -F "file=@your-document.pdf"

# Windows PowerShell
curl.exe -X POST http://localhost:3000/ingest -F "file=@your-document.pdf"

Response:

{ "message": "Ingested 142 chunks from \"your-document.pdf\"" }

Now ask a question:

# Linux / macOS
curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{ "question": "How should I handle errors in async functions?" }'

# Windows PowerShell
curl.exe -X POST http://localhost:3000/chat -H "Content-Type: application/json" -d "{\"question\": \"How should I handle errors in async functions?\"}"

Response:

{
  "answer": "For async functions in Node.js, wrap your logic in a try/catch block to handle rejected promises. In Express, pass the caught error to next(err) to trigger your error-handling middleware. Alternatively, you can create a wrapper function that wraps any async route handler in a promise and calls next on rejection, keeping your route handlers clean...",
  "sources": ["your-document.pdf"],
  "topSimilarity": "0.841"
}

The topSimilarity score tells you how well the retrieval went. Above 0.7 and the chunks pulled were genuinely relevant. Below 0.5, and the search was struggling: it found something, but not something that actually answers the question.

Try asking about something your PDF doesn't mention. If the system prompt is doing its job, the model should say it doesn't have enough information rather than making something up. That's the behaviour you want in production.

The repo includes two diagnostic scripts that are useful if anything isn't working:

node test-keys.js — tests both API keys live and reports whether each one succeeds
node list-models.js — fetches the full list of Gemini models available to your API key

Run these before diving into the troubleshooting section below.

Troubleshooting

Everything in this section is a real error I hit while building this. Nothing hypothetical.

Port 5432 is already in use

Error: bind: address already in use

Something else — probably a local Postgres install — is already on that port. Two fixes are needed. First, in docker-compose.yml:

ports:
  - "5433:5432"

Second, update DATABASE_URL in .env:

DATABASE_URL=postgresql://rag_user:rag_pass@localhost:5433/rag_db

The container itself still listens on 5432 internally. You're just changing which port your machine uses to reach it.

Password authentication failed for user "rag_user"

Error: password authentication failed for user "rag_user"

The password Postgres was initialized with doesn't match what your app is sending. Open .env and compare POSTGRES_PASSWORD with the password embedded in DATABASE_URL. They need to be character-for-character identical.

After fixing the mismatch, the old volume still has the wrong password baked into it. You must destroy it and start fresh:

docker compose down -v
docker compose up -d

The -v flag deletes the data volume. Postgres reinitializes on the next start with the credentials from your current .env.

Gemini model not found (404)

{ "error": { "code": 404, "message": "models/text-embedding-004 is not found" } }

The Google AI model naming has changed. Older tutorials and blog posts reference model names that no longer exist on the v1 endpoint. The correct model for this stack is gemini-embedding-001. That's what this repo uses.

If you want to see every model available to your API key, run:

node list-models.js

That script fetches the live list directly from the API so you're not guessing.

Vector dimension mismatch

ERROR: expected 768 dimensions, not 3072

This error appears when your database table was created with a different dimension count than what your embedding model produces. gemini-embedding-001 outputs 3,072-dimensional vectors. The documents table in this tutorial uses VECTOR(3072) to match.

If you get this error, it means either an old table exists with the wrong dimension, or you changed embedding models without recreating the table. Drop the data volume and restart:

docker compose down -v
docker compose up -d

Vector index dimension limit

ERROR: ivfflat index type only supports up to 2000 dimensions

pgvector's ivfflat and hnsw index types have a maximum dimension of 2000. Since gemini-embedding-001 produces 3,072-dimensional vectors, neither index type works.

This tutorial drops the index and lets pgvector do a full scan — fine for development and any reasonably sized corpus. Scaling to thousands of documents in production? Pick a model under 2000 dimensions. OpenAI's text-embedding-3-small outputs 1536 and plays nicely with both index types.

Port 3000 is already in use

Error: EADDRINUSE: address already in use :::3000

Some other process got there first. Swap the port number in .env:

PORT=3002

Save it and restart the server.

Gemini generation returns quota exceeded (limit: 0)

{ "error": { "status": "RESOURCE_EXHAUSTED", "message": "Quota exceeded for quota metric ... with limit 0" } }

That limit 0 means Google has switched off free generation in your country entirely — not that you've used it up. I hit this myself while testing from Pakistan.

That's exactly why this tutorial uses Groq instead. Make sure GROQ_API_KEY is in your .env and that generateAnswer in src/embeddings.js is pointing at api.groq.com.

To verify both keys work, run:

node test-keys.js

It tests the Gemini embedding endpoint and the Groq generation endpoint independently and reports whether each succeeds.

nodemon doesn't pick up changes to `.env`

nodemon only watches .js files — .env changes don't trigger a restart. Switch to the terminal running the server and type rs, then hit Enter. That forces a restart and picks up whatever you changed.

`curl` doesn't work in Windows PowerShell

curl : The term 'curl' is not recognized

curl : Cannot bind parameter because parameter 'Method' is specified more than once

PowerShell has a built-in curl alias that points to Invoke-WebRequest — completely different flags, completely different behaviour. Add .exe and you bypass the alias and hit the real binary.

So instead of curl, type curl.exe:

# Ingest
curl.exe -X POST http://localhost:3000/ingest -F "file=@your-document.pdf"

# Chat
curl.exe -X POST http://localhost:3000/chat -H "Content-Type: application/json" -d "{\"question\": \"How do I handle async errors?\"}"

That .exe is the whole fix.

Docker Desktop stopped running

Docker Desktop doesn't start automatically after a reboot on most setups. If your Docker commands suddenly fail with connection errors, that's probably why. Open Docker Desktop, wait until it says "Engine running", then try again.

How to Swap in OpenAI

If you want to use the OpenAI API instead of Gemini, it's three changes.

1. Install the OpenAI SDK:

npm install openai

2. Replace src/embeddings.js entirely:

const OpenAI = require('openai');

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function embedText(text) {
  const result = await client.embeddings.create({
    model: 'text-embedding-3-small',
    input: text,
  });
  return result.data[0].embedding;
}

async function generateAnswer(context, question) {
  const result = await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [
      { role: 'system', content: 'Answer only from the context provided. If the context is insufficient, say so.' },
      { role: 'user', content: `Context:\n${context}\n\nQuestion: ${question}` },
    ],
  });
  return result.choices[0].message.content;
}

module.exports = { embedText, generateAnswer };

3. Update the vector dimension in src/db.js:

Open db.js and swap VECTOR(3072) for VECTOR(1536) — that's the output size of text-embedding-3-small. Then kill the volume so the table gets recreated with the right dimensions:

docker compose down -v
docker compose up -d

Nothing else needs touching. The ingestion and query logic works the same regardless of which model you plugged in.

What to Build Next

What you've built works. But there are some gaps that come up quickly once you put it in front of real users.

The most noticeable one is streaming. Right now /chat holds the connection open until Groq finishes generating the full answer, then returns everything at once. On a short question that's fine. On a longer one, the user stares at nothing for a few seconds and wonders if the request hung.

The Groq API supports streaming — add stream: true to the request body and tokens start coming back as they're generated. Piping those through Express with res.write() is maybe 15 minutes of work and the difference in feel is immediate.

Metadata filtering is the second thing you'll want. Once you've loaded more than a few documents, queries bleed across everything: ask about the API spec and you'll get chunks from the onboarding guide too.

The fix is a metadata JSONB column where you store the document ID on ingest, then add WHERE metadata->>'doc_id' = $1 to the similarity query. Expose it as an optional body field on /chat: { "question": "...", "docId": "api-spec-v2" }. Users get scoped results, and you get much cleaner answers.

When your corpus grows into the hundreds of documents, look at re-ranking. Vector similarity retrieval is fast but approximate — it finds chunks that are semantically close to the question, not necessarily the ones that most directly answer it.

The pattern is: retrieve the top 20 by cosine distance, then run a cross-encoder over them to re-score by actual relevance, then take the best 5 from that second pass. LangChain.js has a cross-encoder wrapper if you don't want to implement it yourself.

The last thing most people forget until they actually need it is document management — the ability to list what's ingested, delete a specific file, and re-ingest an updated version.

A DELETE FROM documents WHERE source = $1 handles the delete case. Add a GET /documents endpoint that queries SELECT DISTINCT source FROM documents and you have a complete enough API for real use.

RAG isn't magic. It's a well-scoped retrieval problem combined with a language model that's been told to stay within its lane.

The quality of your answers depends on three things: how cleanly your PDFs parse, how well your chunk size fits the content type, and how clearly your system prompt instructs the model to say "I don't know" rather than guess. Get those right and you've built something genuinely useful: the kind of thing that saves a new engineer's first two weeks.

How to Build a Browser-Based PDF Image Extractor Using JavaScript

Bhavin Sheth — Mon, 13 Jul 2026 14:12:57 +0000

PDF files are widely used for sharing documents because they preserve formatting across different devices. Many PDFs contain valuable images such as logos, product photos, charts, diagrams, illustrations, and marketing graphics.

While these images are easy to view, extracting them individually isn't always simple. Many users rely on screenshots or manual cropping, which can reduce image quality and take unnecessary time.

In this tutorial, you'll build a browser-based PDF Image Extractor using JavaScript. The application lets users upload a PDF, preview its pages, extract embedded images, organize them by page, and download individual images or all extracted images at once.

Everything runs directly inside the browser, so uploaded documents never leave the user's device. This makes the tool fast, private, and easy to use without requiring a backend server.

By the end of this tutorial, you'll have a fully functional PDF Image Extractor capable of recovering embedded images while preserving their original quality.

Why Extract Images from PDFs?
How Images Are Stored Inside PDF Files
Understanding Embedded Images vs Rendered Pages
Project Setup
What Libraries Are We Using?
Creating the Upload Interface
Previewing Uploaded PDF Pages
Finding Embedded Images
Extracting Images from PDF Pages
Displaying Extracted Images
Downloading Individual Images
Downloading All Images from the PDF
Demo: How the PDF Image Extractor Works
Performance Optimization Tips
Important Notes from Real-World Use
Common Mistakes to Avoid
Conclusion

Why Extract Images from PDFs?

Although PDF documents are primarily designed for sharing text-based information, they often contain valuable visual assets. Product catalogs include product photographs, annual reports contain charts and graphs, presentations use icons and illustrations, brochures showcase marketing banners, and technical manuals include diagrams and engineering drawings.

Without a dedicated image extraction tool, users often take screenshots or manually crop pages to save these visuals. Unfortunately, screenshots usually reduce image quality, introduce unwanted page elements, and require significant manual effort when working with large documents.

A PDF Image Extractor automates this process by identifying every embedded image inside the document and separating it from the surrounding page content. Instead of copying an entire page, users receive individual image files that can be downloaded and reused immediately.

This capability is extremely useful across many industries.

Graphic designers frequently receive client brochures, advertisements, and presentation files that contain logos, icons, or promotional graphics. Instead of recreating those assets manually, they can extract the original images directly from the PDF and continue working with high-quality source files.

Marketing teams often work with catalogs, product flyers, promotional leaflets, and campaign reports. Extracting product photographs or promotional graphics saves considerable time when creating social media posts, advertisements, landing pages, or newsletters.

Publishers and content creators regularly receive PDF magazines, ebooks, newsletters, and educational material containing illustrations and infographics. Individual images can be extracted and reused without manually cropping every page.

Researchers frequently download scientific papers containing graphs, charts, microscopy images, satellite photographs, and experimental diagrams. Image extraction allows them to save those visuals separately for presentations, publications, or further analysis.

Educational institutions use image extraction when preparing teaching material. Teachers can reuse diagrams, mathematical figures, scientific illustrations, historical maps, or educational graphics from reference documents without recreating them from scratch.

Government departments often maintain scanned archives containing seals, stamps, signatures, photographs, maps, engineering plans, and official diagrams. Extracting these images individually simplifies document digitization and archival workflows.

E-commerce businesses can also benefit significantly from image extraction. For example, a seller may receive a supplier catalog in PDF format containing hundreds of product photographs. Instead of requesting every image separately, the seller can extract all embedded product images from the catalog within minutes and reuse them while preparing listings for platforms such as Amazon, Flipkart, Meesho, Shopify, or WooCommerce.

Businesses working with invoices and purchase documents can also recover company logos, QR codes, signatures, and barcode images for document verification or automation systems.

Because this application performs every operation locally inside the browser, sensitive business documents remain private while users quickly recover all embedded images from their PDFs.

How Images Are Stored Inside PDF Files

Many people assume that a PDF page is simply a picture of the document. In reality, PDF files are much more sophisticated.

Each page inside a PDF is built from multiple independent objects. Text is stored separately using fonts and character information. Lines and shapes are represented as vector drawing instructions. Images are embedded as independent image objects that are placed at specific positions on the page.

This separation is one of the reasons PDFs remain flexible and efficient. A document may contain dozens of pages while reusing the same company logo or icon multiple times without storing duplicate copies.

When an image is embedded inside a PDF, the file usually preserves information such as the image dimensions, color space, compression method, and image format. Depending on how the document was created, embedded images may use formats such as JPEG, PNG, JPEG2000, CCITT, or other PDF-supported image encodings.

A PDF Image Extractor scans the internal structure of the document to locate these embedded image objects. Instead of capturing the entire page as a screenshot, it retrieves each image individually whenever possible.

This approach preserves much higher quality because the original embedded image is recovered rather than recreating it from the rendered page.

Understanding how PDF files store images also explains why some documents contain dozens of extractable images while others contain none at all. If a PDF consists entirely of vector graphics or text, there may be no embedded raster images available for extraction.

Knowing the difference between these document structures helps developers build more accurate PDF processing tools while helping users understand the capabilities and limitations of image extraction.

Understanding Embedded Images vs Rendered Pages

One of the most common misconceptions about PDF image extraction is that every visible picture on a page can always be extracted as a separate image.

In reality, there is an important difference between embedded images and rendered page images.

An embedded image is an independent object stored inside the PDF document. These images usually retain their original quality and can often be extracted without any loss of resolution.

A rendered page, on the other hand, is simply a visual representation of everything that appears on the page. When PDF.js displays a page inside the browser, it combines text, vector graphics, images, backgrounds, and shapes into a single canvas. Although this rendered page looks identical to the original document, it's no longer separated into individual components.

For example, imagine a product catalog containing a company logo, five product photographs, several icons, and descriptive text.

The PDF page preview displays everything together as one complete page. However, the PDF Image Extractor scans the document internally and identifies the individual logo, each product photograph, and every embedded icon separately. This allows users to download each image individually instead of cropping screenshots from the page preview.

Another important point is that not every visible graphic is actually an image.

Some company logos are created entirely using vector drawing commands. Charts may also be generated using vector graphics rather than bitmap images. Since these objects are not stored as raster images, they can't always be extracted using an image extraction tool.

Understanding this distinction helps explain why image extraction results may differ between documents even when they appear visually similar.

For developers, learning how embedded resources differ from rendered pages provides a much deeper understanding of PDF internals and browser-based document processing.

Project Setup

We'll build the PDF Image Extractor using standard web technologies so that the entire application runs directly inside the browser without requiring a backend server.

The project consists of a simple HTML file for the interface, a CSS file for styling, and a JavaScript file that handles PDF loading, page rendering, image extraction, and downloading.

Create the following project structure:

pdf-image-extractor/

│── index.html

│── style.css

│── script.js

│── assets/

After creating the project, include the required JavaScript libraries inside your index.html file:

Once these files are ready, the browser will have everything required to read PDF files, render document pages, inspect PDF objects, locate embedded images, and generate downloadable image files.

Keeping the project lightweight also makes it easier to understand each stage of the image extraction workflow.

What Libraries Are We Using?

Extracting images from PDF documents requires more than simply displaying PDF pages inside the browser. The application needs to load the document, inspect its internal structure, render preview pages, and recover embedded image objects.

To accomplish this, we'll use two JavaScript libraries.

The first library is PDF.js.

PDF.js is Mozilla's open-source PDF rendering engine. It allows browsers to load PDF documents without additional plugins and provides APIs for reading document pages, rendering previews, accessing page objects, and inspecting document resources.

In this project, PDF.js is responsible for loading the uploaded PDF and generating the page preview shown to the user before image extraction begins.

The second library is PDF-lib.

PDF-lib provides low-level access to PDF objects and document resources. Although it's widely used for editing PDF files, it's also useful when working with embedded objects and document manipulation. It complements PDF.js by giving developers additional flexibility when extending the application with future PDF editing features.

Together, these libraries allow us to create a browser-based image extraction workflow that is fast, secure, and completely client-side.

The following code initializes PDF.js:

pdfjsLib.GlobalWorkerOptions.workerSrc =

"https://cdnjs.cloudflare.com/ajax/libs/pdf.js/4.4.168/pdf.worker.min.js";

Loading the worker separately keeps PDF rendering responsive while large documents are processed.

Creating the Upload Interface

Every document processing application begins with uploading a file.

The upload interface is responsible for accepting PDF documents, validating the selected file, and preparing it for processing. A clean upload experience is important because it becomes the entry point for the entire application.

In this project, users can either drag a PDF onto the upload area or browse for a document using the standard file picker.

Once the file has been selected, the browser immediately verifies that it's a valid PDF before attempting to load it.

Supporting both drag-and-drop uploads and manual file selection provides a familiar experience across desktop and mobile devices.

The upload section also displays clear instructions so first-time users understand exactly how to begin extracting images.

Create the upload area using the following HTML:



    

        ☁

    

    Drag & Drop PDF Here

    Or click to browse file

Next, validate the uploaded document:

const file = pdfFile.files[0];

if(!file){

    return;

}

if(file.type !== "application/pdf"){

    alert("Please upload a valid PDF.");

    return;

}

After validation succeeds, the browser reads the uploaded file:

const buffer =

await file.arrayBuffer();

loadPDF(buffer);

At this point, the PDF has been loaded into memory and is ready for preview generation.

Previewing Uploaded PDF Pages

Before extracting images, users should first verify that they uploaded the correct document.

Instead of immediately scanning the PDF, the application generates thumbnail previews for every page. These previews help users confirm page order, inspect the document contents, and estimate where embedded images are located.

Preview generation is particularly useful for large reports, product catalogs, presentations, magazines, brochures, ebooks, and technical documentation containing dozens of pages.

Each preview is rendered using PDF.js and displayed inside a responsive grid layout.

First, load the uploaded document:

const pdf = await pdfjsLib

.getDocument({

    data:buffer

})

.promise;

Next, loop through every page:

for(

let pageNumber = 1;

pageNumber <= pdf.numPages;

pageNumber++

){

    renderPage(pageNumber);

}

Render the page as a canvas:

const page =

await pdf.getPage(pageNumber);

const viewport =

page.getViewport({

    scale:0.35

});

const canvas =

document.createElement("canvas");

canvas.width = viewport.width;

canvas.height = viewport.height;

await page.render({

    canvasContext:

    canvas.getContext("2d"),

    viewport

}).promise;

Finally, add the preview to the page:

previewContainer

.appendChild(canvas);

Once rendering is complete, every page becomes visible inside the preview area.

Users can scroll through the thumbnails and verify that the correct document has been uploaded before starting the extraction process.

Although the preview displays complete page images, no extraction has occurred yet. The next stage scans the internal PDF structure to locate every embedded image separately.

Why Previewing the PDF Matters

Previewing the uploaded document may seem like a small feature, but it greatly improves the overall user experience.

Without a preview, users have no way to verify that they selected the correct file before extraction begins. This becomes especially important when working with multiple PDFs that have similar filenames.

Page previews also help users estimate where images appear throughout the document. For example, a product catalog may contain photographs only on certain pages, while a technical report might include diagrams only within specific chapters.

By reviewing the page thumbnails first, users gain confidence that the document is correct before the application begins scanning for embedded images.

This simple verification step reduces mistakes, avoids unnecessary processing, and makes the overall workflow feel much more intuitive.

Finding Embedded Images

Once the PDF pages have been rendered and displayed in the preview section, the application is ready to search for embedded images.

This stage is different from generating page previews. The preview simply renders each page as a complete visual image, while the extraction process examines the internal structure of the PDF to locate every embedded image object stored inside the document.

Each page is scanned individually. If embedded images are found, the application records their location, dimensions, image format, and page number before preparing them for extraction.

This page-by-page approach makes it easier to organize the extracted images later and allows users to understand exactly where each image originated within the document.

Scanning only begins after users click the Extract Images button, ensuring that unnecessary processing is avoided if they simply want to preview the document.

First, create the click event for the extraction button:

document

.getElementById(

"extractBtn"

)

.addEventListener(

"click",

extractImages

);

Next, loop through every page inside the uploaded PDF:

for(

let pageNumber = 1;

pageNumber <= pdf.numPages;

pageNumber++

){

    const page =

    await pdf.getPage(

    pageNumber

    );

}

Read the page operator list:

const operatorList =

await page.getOperatorList();

Now inspect every drawing operation to determine whether it contains an embedded image:

operatorList.fnArray

.forEach(operation=>{

    if(

    operation ===

    pdfjsLib.OPS.paintImageXObject

    ){

        console.log(

        "Image Found"

        );

    }

});

After every page has been scanned, the application creates a collection containing all discovered images grouped by page.

This collection becomes the foundation for the extraction process that follows.

Extracting Images from PDF Pages

Once embedded image objects have been identified, the application begins extracting them from the PDF.

Unlike taking screenshots of an entire page, this method retrieves each embedded image individually whenever possible. As a result, the extracted images preserve their original quality, dimensions, and compression rather than inheriting the resolution of the page preview.

Each image is assigned to the page where it was found. Organizing images this way makes it much easier for users to locate graphics inside large reports, magazines, brochures, presentations, catalogs, technical manuals, and research papers.

As each page finishes processing, its extracted images are stored inside a JavaScript array before being displayed inside the browser.

Create an array for storing extracted images:

const extractedImages = [];

Save every discovered image:

extractedImages.push({

    page:

    pageNumber,

    image:

    imageData,

    type:

    imageType

});

Each stored object contains useful information that will later be displayed to the user.

The extraction routine continues until every page inside the uploaded PDF has been inspected.

Once complete, the browser immediately displays the extracted images without requiring another processing step.

Displaying Extracted Images

After extraction finishes, the application presents every recovered image inside an organized gallery.

Instead of displaying one long collection of images, the results are grouped according to the page from which they were extracted. This organization makes it much easier to understand the original document structure.

For every extracted image, the application displays a preview together with useful technical information.

Users can immediately see the image dimensions, image format, and the page where the image originated. This additional information helps determine whether an image is suitable for reuse before downloading it.

For example, a high-resolution product photograph may be useful for marketing material, while a small company logo may only be appropriate for branding purposes.

Loop through every extracted image:

extractedImages.forEach(image=>{

    renderImageCard(

    image

    );

});

Create the preview card:

const card =

document.createElement(

"div"

);

card.className =

"image-card";

Insert the preview:

const img =

document.createElement(

"img"

);

img.src =

image.image;

Display the image information:

details.innerHTML =

`

Dims:

${image.width} × ${image.height}




Type:

${image.type}

`;

Once every card has been created, the gallery displays all extracted images grouped beneath their respective pages.

This layout provides a clean overview of every image contained inside the uploaded PDF while making individual downloads straightforward.

Downloading Individual Images

Many users don't need every image contained inside a PDF.

For example, a designer may only want the company logo from a brochure, while a researcher may only need one graph from a scientific paper.

To support these workflows, every extracted image includes its own download button.

When clicked, the browser downloads only the selected image without affecting any of the remaining extracted images.

This allows users to quickly save exactly the graphics they need.

Create a download button:

const button =

document.createElement(

"button"

);

button.innerText =

"Download";

Attach the download event:

button.onclick = ()=>{

    downloadImage(

    image

    );

};

Generate the download:

const link =

document.createElement(

"a"

);

link.href =

image.image;

link.download =

image.fileName;

link.click();

Providing separate download buttons makes the application much more flexible because users can save only the images they actually need instead of downloading every extracted asset.

Downloading All Images from the PDF

Large PDF documents often contain dozens or even hundreds of embedded images.

Downloading every image individually would be both slow and repetitive.

To simplify this workflow, the application also includes a Download All Images from PDF button.

After extraction has completed, clicking this button automatically downloads every extracted image from every page.

This feature is particularly useful when working with supplier catalogs, product brochures, magazines, annual reports, technical documentation, ebooks, educational material, and presentation files containing many graphics.

Loop through every extracted image:

extractedImages.forEach(image=>{

    downloadImage(

    image

    );

});

Attach the click event:

downloadAllButton

.addEventListener(

"click",

downloadAllImages

);

Finally, allow users to begin another extraction:

startOverButton

.addEventListener(

"click",

resetApplication

);

After the downloads have completed, users can click Start Over to upload another PDF and repeat the extraction process without refreshing the browser.

Demo: How the PDF Image Extractor Works

Step 1: Upload Your PDF Document

The image extraction workflow begins by uploading a PDF document using either the drag-and-drop area or the file picker.

Once a document has been selected, the browser validates that the uploaded file is a PDF before reading it into memory. Since the application performs all processing locally, the uploaded document never leaves the user's computer, making the tool suitable for confidential business reports, catalogs, presentations, contracts, technical manuals, research papers, and other sensitive documents.

After the PDF has been loaded successfully, the application prepares every page for preview generation before image extraction begins.

Step 2: Preview Uploaded PDF Pages

After the upload is complete, the application renders thumbnail previews for every page inside the document.

Instead of immediately scanning the PDF for images, users first receive a visual overview of the entire document. This allows them to verify that they selected the correct PDF and quickly identify which pages contain photographs, diagrams, illustrations, charts, or other graphics.

Page previews are especially useful when working with large product catalogs, magazines, annual reports, brochures, technical documentation, educational books, and research papers containing dozens or even hundreds of pages.

This verification step helps prevent unnecessary processing and improves the overall user experience.

Step 3: Extract Embedded Images

Once the document has been verified, users click the Extract Images button to begin scanning the PDF.

The application examines every page individually, searching for embedded image objects stored inside the document. Unlike screenshots or page rendering, the extractor retrieves the original image resources whenever possible, preserving their quality and dimensions.

As each page is processed, every discovered image is grouped according to the page where it originally appeared. This organization makes it much easier to browse the extracted results later.

Depending on the size of the PDF and the number of embedded images, extraction may take a few seconds for larger documents.

Step 4: Review the Extracted Images

After extraction is complete, the browser displays every recovered image inside an organized gallery.

Instead of showing one large collection of images, the application groups the results page by page. This allows users to understand exactly where each image came from within the original document.

Every image card displays a preview together with useful information such as the page number, image dimensions, and image format. This helps users quickly identify the graphics they need before downloading anything.

For example, a brochure may contain company logos, banners, icons, and product photographs spread across several pages. Grouping images by page makes navigating these documents much easier.

Step 5: Download Individual Images or Pagewise

Each extracted image includes its own Download Image button.

This feature is useful when users only need one or two graphics from a large document. Instead of downloading every extracted image, they can save only the specific illustrations, charts, product photographs, or logos that are relevant to their work.

For example, a designer may only need a company logo, while a marketing team may only want product images from a supplier catalog. Individual downloads eliminate unnecessary files and simplify the workflow.

After clicking the download button, the browser immediately saves the selected image without requiring any additional processing.

Step 6: Download Every Image

For users who need all graphics contained inside the document, the application also provides a Download All Images from PDF button.

After extraction has finished, clicking this button automatically downloads every recovered image from every page. This saves considerable time compared to downloading each image individually.

This feature is particularly useful when processing large product catalogs, marketing brochures, presentation decks, educational books, technical manuals, magazines, supplier catalogs, or company reports containing dozens of embedded images.

Once the downloads are complete, users can click Start Over to clear the current session and upload another PDF without refreshing the page.

Step 7: Start a New Extraction

After downloading the required images, users can begin working with another PDF document.

Clicking Start Over clears the uploaded document, removes every generated preview, resets the extracted image gallery, and restores the application to its initial state.

This allows users to process multiple PDF files during the same session without reloading the browser or reopening the application.

The reset process is completed instantly, making the workflow smooth and efficient when working with many PDF documents throughout the day.

Performance Optimization Tips

Image extraction is generally faster than OCR because the application recovers existing image objects instead of recognizing characters. But large PDF documents containing hundreds of pages or high-resolution graphics can still require significant processing time.

One simple optimization is to process pages sequentially instead of attempting to analyze every page simultaneously.

for(

let page = 1;

page <= pdf.numPages;

page++

){

    await extractPageImages(page);

}

Loading only the required page into memory reduces browser memory usage and improves stability when processing large documents.

If the application supports page selection, allowing users to extract images from only specific pages can greatly reduce processing time for large catalogs or reports.

const startPage = 10;

const endPage = 25;

After images have been downloaded, release any temporary browser resources:

URL.revokeObjectURL(

imageURL

);

Finally, clear the extracted image collection before processing another PDF:

extractedImages.length = 0;

These small optimizations help the application remain responsive even when working with documents containing hundreds of embedded graphics.

Important Notes from Real-World Use

Not every PDF contains embedded images.

Some documents consist entirely of text and vector graphics, while others may contain scanned pages that appear as a single full-page image. Understanding how the original PDF was created helps set realistic expectations before extraction begins.

Always validate uploaded files before processing.

if(

file.type !== "application/pdf"

){

    alert(

    "Please upload a valid PDF."

    );

}

Some PDF creators compress embedded images heavily to reduce file size. In those situations, the extracted images will match the quality stored inside the PDF, but they can't be improved beyond the original resolution.

Users should also verify extraction results before downloading every image, particularly when processing large reports or catalogs containing hundreds of graphics.

Because the application performs all operations locally inside the browser, confidential documents remain private throughout the extraction process. This makes browser-based image extraction suitable for business reports, engineering drawings, financial documents, legal records, educational resources, and other sensitive PDFs.

Common Mistakes to Avoid

One common mistake is assuming every visible object inside a PDF is an extractable image.

Many diagrams, logos, and charts are actually vector graphics rather than raster images. These elements are rendered by drawing commands and can't always be extracted as standalone image files.

Another mistake is relying on screenshots instead of extracting embedded images.

Screenshots capture only the rendered page displayed on the screen, which often reduces image quality and includes unnecessary page elements.

Always verify that embedded images have been detected before displaying the results.

if(

extractedImages.length === 0

){

    alert(

    "No embedded images found."

    );

}

Some users also forget to organize extracted images by page.

Grouping images according to their original page location makes it much easier to navigate large documents containing dozens or hundreds of graphics.

Finally, always review the extracted images before downloading them.

Checking the preview allows users to confirm image quality, dimensions, and page location before saving the files.

Conclusion

In this tutorial, you built a browser-based PDF Image Extractor using JavaScript.

You learned how to upload PDF files, preview document pages, locate embedded image objects, extract images while preserving their original quality, organize results page by page, download individual images, and download every extracted image directly from the browser.

More importantly, you learned the difference between embedded images and rendered page previews, giving you a better understanding of how PDF documents are structured internally.

Because the entire workflow runs locally inside the browser, users can safely recover graphics from confidential PDF documents without uploading them to external servers.

You can try the complete implementation here:

PDF Image Extractor: https://allinonetools.net/extract-images-from-pdf/

Once you understand this workflow, you can extend the project further by adding duplicate image detection, automatic image compression, AI-powered image tagging, background removal, image format conversion, OCR on extracted images, watermark detection, or bulk asset management features.

How to Implement Role-Based Access Control in a Node.js REST API with JWT

Zia Ullah — Thu, 09 Jul 2026 14:46:47 +0000

The first time I built an API without thinking about roles, I gave every logged-in user the same access. It worked fine until a regular user accidentally hit a delete endpoint and wiped test data. That was the day I actually sat down and learned RBAC properly.

Role-Based Access Control sounds fancy, but the idea is simple: what you can do depends on who you are, not just that you're logged in. An admin deletes users. An editor creates posts. A regular user just reads. Same app, completely different experience depending on who's asking.

That's what we're building here. A REST API with three roles: JWT to carry those roles on every request, and a pair of middleware functions that check permissions before your route handlers even run. There's no database hit per request, and no if/else soup in your business logic.

By the end, you'll have three working roles (admin, editor, user) each locked to their own endpoints. More importantly, the pattern is transferable: once it clicks, you'll wire it into your next project without needing a tutorial.

Full source code on GitHub: github.com/ziaongit/nodejs-rbac-jwt-api

What You'll Learn
Prerequisites
What We'll Build
Project Setup
Setting Up the In-Memory Data Store
Building the Auth Routes
Building the RBAC Middleware
Building the Protected Routes
Putting It All Together
Testing the API
Key Takeaways
Conclusion

What You'll Learn

What RBAC is and how it differs from basic authentication
How to embed roles in JWT payloads
How to write reusable Express middleware for token verification and role checking
How to protect API routes based on user roles

Prerequisites

Node.js (v18+) installed
Basic knowledge of Express.js
Familiarity with how JWTs work (we'll cover the relevant parts)
npm installed

What We'll Build

We'll build a REST API for a simple content management system with three user roles:

Role	Permissions
`user`	Read content
`editor`	Read + create content
`admin`	Full access — read, create, delete content, manage users

The API will expose these endpoints:

Method	Endpoint	Access
POST	/api/auth/register	Public
POST	/api/auth/login	Public
GET	/api/content	user, editor, admin
POST	/api/content	editor, admin
DELETE	/api/content/:id	admin only
GET	/api/admin/users	admin only

Project Setup

Create a new folder and initialize the project:

mkdir nodejs-rbac-jwt-api
cd nodejs-rbac-jwt-api
npm init -y

Install the dependencies:

npm install express jsonwebtoken bcryptjs dotenv
npm install --save-dev nodemon

Here's what each package does:

express: web framework for building the API
jsonwebtoken: creates and verifies JWTs
bcryptjs: securely hashes passwords
dotenv: reads your .env file so you're not hardcoding secrets in your source code

Update package.json to add start scripts:

"scripts": {
  "start": "node src/app.js",
  "dev": "nodemon src/app.js"
}

Create the project structure:

nodejs-rbac-jwt-api/
├── src/
│   ├── middleware/
│   │   └── auth.js
│   ├── routes/
│   │   ├── auth.js
│   │   ├── content.js
│   │   └── admin.js
│   ├── data/
│   │   └── users.js
│   └── app.js
├── .env
├── .env.example
└── package.json

Create your .env file:

JWT_SECRET=your_super_secret_key_change_this_in_production
PORT=3000

Important: Never commit your .env file to version control. Add it to .gitignore.

Setting Up the In-Memory Data Store

We don't have a database here, just an array in memory. The point was to keep the focus on RBAC, not spend half the tutorial on database config. In a real project, swap the array for whatever database you're already using.

Create src/data/users.js:

// In-memory users store
// In production, replace this with a real database (MongoDB, PostgreSQL, etc.)
const users = [];

const findUserByEmail = (email) => users.find((u) => u.email === email);
const findUserById = (id) => users.find((u) => u.id === id);
const createUser = (user) => {
  users.push(user);
  return user;
};
const getAllUsers = () => users.map(({ password, ...user }) => user);

module.exports = { findUserByEmail, findUserById, createUser, getAllUsers };

One thing worth noting: getAllUsers uses destructuring to drop the password before returning anything. Never send password fields in API responses, even hashed ones.

Building the Auth Routes

The auth routes handle registration and login. Login is where roles first enter the picture — we embed the user's role directly into the JWT payload.

Create src/routes/auth.js:

const express = require('express');
const bcrypt = require('bcryptjs');
const jwt = require('jsonwebtoken');
const { findUserByEmail, createUser } = require('../data/users');

const router = express.Router();

// POST /api/auth/register
router.post('/register', async (req, res) => {
  const { name, email, password, role } = req.body;

  if (!name || !email || !password) {
    return res.status(400).json({ message: 'Name, email, and password are required' });
  }

  if (findUserByEmail(email)) {
    return res.status(409).json({ message: 'Email already registered' });
  }

  // Only allow valid roles — default to 'user' if none provided
  const validRoles = ['user', 'editor', 'admin'];
  const assignedRole = validRoles.includes(role) ? role : 'user';

  const hashedPassword = await bcrypt.hash(password, 10);

  const newUser = {
    id: Date.now().toString(),
    name,
    email,
    password: hashedPassword,
    role: assignedRole,
  };

  createUser(newUser);

  res.status(201).json({
    message: 'User registered successfully',
    user: {
      id: newUser.id,
      name: newUser.name,
      email: newUser.email,
      role: newUser.role,
    },
  });
});

// POST /api/auth/login
router.post('/login', async (req, res) => {
  const { email, password } = req.body;

  if (!email || !password) {
    return res.status(400).json({ message: 'Email and password are required' });
  }

  const user = findUserByEmail(email);
  if (!user) {
    return res.status(401).json({ message: 'Invalid credentials' });
  }

  const isMatch = await bcrypt.compare(password, user.password);
  if (!isMatch) {
    return res.status(401).json({ message: 'Invalid credentials' });
  }

  // Issue JWT — embed role in the payload
  const token = jwt.sign(
    {
      id: user.id,
      email: user.email,
      role: user.role,   // ← This is the key part for RBAC
    },
    process.env.JWT_SECRET,
    { expiresIn: '24h' }
  );

  res.json({
    message: 'Login successful',
    token,
  });
});

module.exports = router;

The most important line is the JWT payload:

jwt.sign({ id, email, role }, process.env.JWT_SECRET, { expiresIn: '24h' })

By embedding role in the token, every subsequent request carries the user's permissions without requiring a database lookup. The server just verifies the token and reads the role from the payload.

Building the RBAC Middleware

This is the core of the system. We need two separate middleware functions:

verifyToken confirms the JWT is valid and attaches the decoded payload to req.user
checkRole confirms the user has the required role for a specific route

Keeping them separate gives you flexibility. Some routes only need authentication. Others need both authentication and a specific role.

Create src/middleware/auth.js:

const jwt = require('jsonwebtoken');

// Middleware 1: Verify the JWT token
const verifyToken = (req, res, next) => {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1]; // Expects: Bearer 

  if (!token) {
    return res.status(401).json({ message: 'Access denied. No token provided.' });
  }

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.user = decoded; // Attach decoded payload (including role) to request
    next();
  } catch (err) {
    return res.status(403).json({ message: 'Invalid or expired token.' });
  }
};

// Middleware 2: Check if user has one of the required roles
const checkRole = (...allowedRoles) => {
  return (req, res, next) => {
    if (!req.user) {
      return res.status(401).json({ message: 'Not authenticated.' });
    }

    if (!allowedRoles.includes(req.user.role)) {
      return res.status(403).json({
        message: `Access denied. Required role: ${allowedRoles.join(' or ')}. Your role: ${req.user.role}`,
      });
    }

    next();
  };
};

module.exports = { verifyToken, checkRole };

checkRole uses a rest parameter (...allowedRoles) so you can pass in one or multiple roles:

checkRole('admin')                  // only admin
checkRole('editor', 'admin')        // editor or admin
checkRole('user', 'editor', 'admin') // all roles

This makes route definitions clean and readable — the permissions are visible right at the route level.

Building the Protected Routes

Now let's wire up routes that use the middleware.

Create src/routes/content.js:

const express = require('express');
const { verifyToken, checkRole } = require('../middleware/auth');

const router = express.Router();

// In-memory content store
const content = [
  { id: '1', title: 'Getting Started with Node.js', author: 'admin' },
  { id: '2', title: 'Express Middleware Explained', author: 'editor' },
];

// GET /api/content — all authenticated users
router.get('/', verifyToken, checkRole('user', 'editor', 'admin'), (req, res) => {
  res.json({ content });
});

// POST /api/content — editors and admins only
router.post('/', verifyToken, checkRole('editor', 'admin'), (req, res) => {
  const { title } = req.body;

  if (!title) {
    return res.status(400).json({ message: 'Title is required' });
  }

  const newItem = {
    id: Date.now().toString(),
    title,
    author: req.user.email,
  };

  content.push(newItem);
  res.status(201).json({ message: 'Content created', item: newItem });
});

// DELETE /api/content/:id — admin only
router.delete('/:id', verifyToken, checkRole('admin'), (req, res) => {
  const index = content.findIndex((c) => c.id === req.params.id);

  if (index === -1) {
    return res.status(404).json({ message: 'Content not found' });
  }

  content.splice(index, 1);
  res.json({ message: 'Content deleted successfully' });
});

module.exports = router;

Notice how readable each route is:

router.delete('/:id', verifyToken, checkRole('admin'), handler)

You can understand the access control without reading the handler body. This is one of the key advantages of middleware-based RBAC: permissions live at the routing layer, not buried in business logic.

Create src/routes/admin.js:

const express = require('express');
const { verifyToken, checkRole } = require('../middleware/auth');
const { getAllUsers } = require('../data/users');

const router = express.Router();

// GET /api/admin/users — admin only
router.get('/users', verifyToken, checkRole('admin'), (req, res) => {
  res.json({ users: getAllUsers() });
});

module.exports = router;

Putting It All Together

Create src/app.js:

require('dotenv').config();
const express = require('express');

const authRoutes = require('./routes/auth');
const contentRoutes = require('./routes/content');
const adminRoutes = require('./routes/admin');

const app = express();

app.use(express.json());

// Routes
app.use('/api/auth', authRoutes);
app.use('/api/content', contentRoutes);
app.use('/api/admin', adminRoutes);

// Health check
app.get('/', (req, res) => {
  res.json({ message: 'RBAC API is running' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Testing the API

Start the server:

npm run dev

Step 1: Register Users with Different Roles

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Admin User", "email": "admin@example.com", "password": "password123", "role": "admin"}'

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Editor User", "email": "editor@example.com", "password": "password123", "role": "editor"}'

curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Regular User", "email": "user@example.com", "password": "password123"}'

Step 2: Log in and Get a Token

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

You'll get a response like:

{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Copy the token.

Step 3: Test Role-based Access

Read content as a regular user (should succeed):

curl http://localhost:3000/api/content \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Try creating content as a regular user (should fail — 403):

curl -X POST http://localhost:3000/api/content \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Article"}'

Response:

{
  "message": "Access denied. Required role: editor or admin. Your role: user"
}

Now log in as an editor and try the same POST request. It succeeds. Log in as admin and try the DELETE route. Only the admin token will work.

Step 4: Decode the JWT to See the Role

You can paste any token into jwt.io to inspect the payload. You'll see something like:

{
  "id": "1720300000000",
  "email": "admin@example.com",
  "role": "admin",
  "iat": 1720300000,
  "exp": 1720386400
}

The role field is exactly what checkRole reads on every protected request.

Key Takeaways

Roles live in the JWT payload. The role travels with the token — no extra DB call needed every time someone hits a protected route. It gets embedded at login and verified cryptographically on each request.

Middleware is composable. verifyToken and checkRole are separate, reusable functions. You can chain them on any route in any combination.

Permissions are visible at the route level. router.delete('/:id', verifyToken, checkRole('admin'), handler) tells you everything about access control before you even read the handler.

Before you ship this to production:

The in-memory array was just to keep this tutorial focused — replace it with a real database before anything goes near production. A server restart wipes all your users right now.
That 24h token expiry is too long. Cut it to 15 minutes and add refresh token rotation. A stolen token becomes useless fast.
Re-validate roles from the DB on sensitive operations. A role change won't reflect in an existing token until it expires
HTTPS, always
If your permission logic grows beyond "check a role", look at casl. It handles attribute-level rules cleanly

Conclusion

The core of it fits in two middleware functions and a JWT payload. I've used this same pattern across several projects. And once you've built it yourself, you'll start spotting it everywhere, because almost every multi-user app needs some version of it.

Full source code on GitHub: github.com/ziaongit/nodejs-rbac-jwt-api

How to Build a Browser-Based PDF OCR to Text Converter Using JavaScript

Bhavin Sheth — Tue, 07 Jul 2026 16:23:22 +0000

Not every PDF contains searchable or editable text. Many PDFs are simply scanned images of documents such as invoices, contracts, books, receipts, government forms, and handwritten notes.

While these documents are easy to read, copying, searching, or editing their content isn't possible without additional processing.

This is where Optical Character Recognition (OCR) comes in. OCR recognizes text inside scanned images and converts it into editable, searchable digital text.

In this tutorial, you'll build a browser-based PDF OCR to Text Converter using JavaScript. Users will be able to upload PDF files, preview pages, configure OCR settings, extract text, monitor processing progress, review OCR confidence scores, and export the results – all directly inside the browser.

Since everything runs locally, uploaded documents never leave the user's device, making the tool both fast and privacy-friendly.

By the end of this tutorial, you'll understand how browser-based OCR works and how to build your own PDF-to-text converter using JavaScript.

Why PDF OCR Is Useful
How PDF OCR Works
Project Setup
What Libraries Are We Using?
Creating the Upload Interface
Previewing Uploaded PDF Pages
Configuring OCR Settings
Extracting Text from the PDF
Tracking OCR Progress
Understanding OCR Confidence Scores
Reviewing the Extracted Text
Exporting the OCR Results
Demo: How the PDF OCR Tool Works
Performance Optimization Tips
Important Notes from Real-World Use
Common Mistakes to Avoid
Conclusion

Why PDF OCR Is Useful

Many PDF files are scanned documents rather than digital text. Although they look readable, the text is actually stored as images, making it impossible to search, copy, edit, or analyze the content.

OCR (Optical Character Recognition) solves this problem by recognizing characters from scanned pages and converting them into editable, searchable text. Once the text is extracted, it can be copied, translated, indexed, summarized, or imported into other applications.

OCR is widely used across many industries. Businesses use it to process invoices, purchase orders, receipts, contracts, bank statements, and tax documents without manually entering data. Legal professionals use OCR to search agreements, affidavits, and court documents for names, dates, or specific clauses. Government agencies digitize historical records, application forms, passports, and official documents to build searchable digital archives.

Educational institutions convert scanned books, research papers, lecture notes, and examination materials into searchable text, making learning resources easier to access. Healthcare organizations use OCR to digitize prescriptions, laboratory reports, insurance claims, and patient records, reducing paperwork and improving record management.

OCR is also valuable for e-commerce businesses. Sellers handling hundreds of invoices, shipping labels, and purchase orders from platforms such as Amazon, Flipkart, Meesho, or Shopify can quickly extract order numbers, customer details, addresses, and product information instead of typing everything manually.

Developers use OCR when building document management systems, enterprise search tools, AI assistants, and workflow automation platforms where scanned documents need to become searchable digital content.

Since this application performs OCR entirely inside the browser, users can process confidential documents without uploading them to external servers. This keeps document processing fast, private, and secure while making scanned PDFs much more useful.

How PDF OCR Works

A PDF OCR application converts scanned pages into editable text by combining PDF rendering with Optical Character Recognition.

When a user uploads a PDF, the browser first validates the document and loads it into memory. Each page is then rendered as an image using PDF.js. These rendered page images become the input for the OCR engine.

The OCR engine examines every image pixel by pixel. It identifies printed characters, recognizes words and sentences, and reconstructs the document as digital text. Depending on the selected language, the recognition engine applies language-specific dictionaries and character models to improve accuracy.

If the user enables image enhancement, the application can improve the scanned page before recognition. Converting the page to grayscale, increasing contrast, or sharpening the image often helps OCR detect characters more accurately, especially when working with old scans or low-quality photocopies.

As each page is processed, the application updates a progress indicator so users can monitor the extraction process in real time. The OCR engine also returns a confidence score for every page, allowing users to estimate how reliable the recognized text is.

After all selected pages have been processed, the application combines the extracted text into a single document. Users can review the output, copy it directly from the browser, or export it as a TXT or JSON file for further use.

Since every stage of the workflow runs locally, the uploaded PDF never leaves the user's device. This makes browser-based OCR an excellent solution for sensitive business documents, legal records, healthcare files, financial reports, and government paperwork.

Project Setup

We'll build the PDF OCR application using standard web technologies.

Create the following project structure.

pdf-ocr-tool/

│── index.html

│── style.css

│── script.js

Next, include the required JavaScript libraries inside index.html.

These libraries provide everything needed to render PDF pages, recognize text, and manage PDF-related operations directly inside the browser.

What Libraries Are We Using?

This project combines several JavaScript libraries because OCR involves multiple processing stages.

The primary library is PDF.js, which loads the uploaded PDF document and renders every page as an image inside the browser. Since OCR engines work with images rather than PDF files directly, rendering each page is the first step of the workflow.

The application uses Tesseract.js to perform Optical Character Recognition. Tesseract is one of the most popular open-source OCR engines and supports dozens of languages, making it possible to recognize printed text from scanned documents without relying on any external API or cloud service.

We also include PDF-lib, which helps manage PDF-related operations and provides additional flexibility if future features such as annotations, metadata editing, or document modifications are added.

Together, these libraries create a complete browser-based OCR solution capable of rendering PDF pages, recognizing printed text, tracking recognition progress, reporting confidence scores, and exporting the extracted text while keeping every document private on the user's device.

Creating the Upload Interface

Every OCR workflow begins with selecting a PDF document. Before the application can recognize any text, it must first load the PDF into the browser and verify that it's a supported file type.

A good upload interface should be simple, intuitive, and accessible for both desktop and mobile users. Supporting drag-and-drop uploads alongside the traditional file picker gives users multiple ways to import their documents.

In this project, the upload section serves as the starting point for the entire OCR workflow. After a PDF is selected, the browser validates the file, reads it into memory, and prepares it for page rendering. Since the application runs completely inside the browser, no document is uploaded to an external server. This ensures confidential PDFs remain private throughout the OCR process.

The upload interface also provides clear instructions so users immediately understand how to begin using the tool.

Here's the HTML for the upload area:



    

        
            ☁
        

        Drag & Drop PDF Here

        Or click to browse file

Next, validate the uploaded file before loading it.

const pdfInput = document.getElementById("pdfInput");

pdfInput.addEventListener("change", async (event)=>{

    const file = event.target.files[0];

    if(!file) return;

    if(file.type !== "application/pdf"){

        alert("Please upload a valid PDF file.");

        return;

    }

    loadPDF(file);

});

Once the validation succeeds, the PDF is loaded into memory and the application proceeds to generate preview thumbnails for each page.

Previewing Uploaded PDF Pages

After the PDF has been loaded successfully, the application generates page previews.

Instead of immediately starting OCR, users first see thumbnail images for every page in the uploaded document. This allows them to confirm that the correct file has been selected and inspect the document before extraction begins.

The preview stage is especially useful for large PDFs because users can quickly identify scanned pages, blank pages, rotated pages, or incorrect uploads without wasting time running OCR on the wrong document.

PDF.js renders every page as a canvas before displaying it inside the preview grid.

First, load the PDF document.

const pdf = await pdfjsLib.getDocument({

    data: await file.arrayBuffer()

}).promise;

Next, render every page.

for(let pageNumber = 1; pageNumber <= pdf.numPages; pageNumber++){

    const page = await pdf.getPage(pageNumber);

    const viewport = page.getViewport({

        scale:0.35

    });

    const canvas = document.createElement("canvas");

    const context = canvas.getContext("2d");

    canvas.width = viewport.width;

    canvas.height = viewport.height;

    await page.render({

        canvasContext:context,

        viewport

    }).promise;

    previewContainer.appendChild(canvas);

}

Each rendered page becomes a thumbnail, allowing users to scroll through the document before choosing the OCR settings.

This visual confirmation greatly reduces mistakes when processing long reports, contracts, invoices, books, or multi-page scanned documents.

Configuring OCR Settings

Different PDF documents require different OCR configurations. A clean digital scan usually processes very quickly, while old photocopies or low-quality scans often require additional image enhancement to improve recognition accuracy.

Before starting OCR, the application allows users to customize several options that affect how text is extracted.

Users can choose whether OCR should process every page or only a specific page range. This is particularly useful when working with large documents where only a few pages contain important information.

The OCR engine also supports multiple recognition languages. Selecting the correct language helps improve accuracy because Tesseract uses language-specific dictionaries and character models during recognition.

For users who prioritize speed, the Fast mode completes OCR quickly while still producing good results. When working with low-quality scans or official documents, High Accuracy mode performs additional processing to improve recognition quality.

The application also includes optional image enhancement settings. Converting pages to grayscale, increasing contrast, or sharpening the scanned image often improves OCR accuracy by making printed characters easier to recognize.

These configurable options allow the OCR engine to adapt to many different document types without overwhelming users with unnecessary complexity.

The page selection section allows users to process either the entire document or only selected pages.



All Pages



Specific Pages

Users can also choose the OCR language.

Next, configure the OCR accuracy mode.

const mode = document.querySelector(

'input[name="accuracy"]:checked'

).value;

console.log(mode);

Finally, enable optional image enhancement features before OCR begins.

const grayscale = grayscaleCheckbox.checked;

const contrast = contrastCheckbox.checked;

const sharpen = sharpenCheckbox.checked;

console.log(

grayscale,

contrast,

sharpen

);

These settings allow the application to balance processing speed and recognition quality depending on the type of PDF being analyzed.

Improving OCR Accuracy Before Processing

One advantage of browser-based OCR is that the document can be optimized before recognition begins. Small image enhancements often have a significant impact on the quality of the extracted text.

For example, grayscale conversion removes unnecessary color information, allowing the OCR engine to focus only on character shapes. Increasing contrast helps distinguish text from the page background, while sharpening makes blurred letters easier to recognize.

These enhancements are especially valuable when processing old books, photocopies, historical records, receipts, handwritten forms, government documents, engineering drawings, and low-resolution scans.

Choosing the correct OCR language is equally important. A scanned Gujarati document processed using the English language model will usually produce poor recognition results. Selecting the matching language significantly improves OCR accuracy.

Taking a few moments to configure these settings before processing often produces cleaner extracted text, fewer recognition errors, and higher confidence scores, particularly when working with challenging documents.

Extracting Text from the PDF

Once the document has been uploaded, previewed, and the OCR settings have been configured, the application is ready to extract text from the selected pages.

Unlike searchable PDFs that already contain digital text, scanned PDF documents consist entirely of images. OCR works by examining each rendered page image, recognizing every visible character, and converting those characters into editable text.

The extraction process begins by rendering each selected PDF page as an image using PDF.js. Each rendered page is then passed to Tesseract.js, which analyzes the image pixel by pixel and reconstructs words, sentences, paragraphs, and punctuation.

If the user selected a specific page range, only those pages are processed. Otherwise, every page in the document is analyzed.

Because OCR can be computationally intensive, especially for high-resolution scans, the application processes one page at a time. This approach keeps memory usage lower while providing continuous progress updates to the user.

The recognized text from each page is appended to a single output document that can later be reviewed, copied, or exported.

First, create the OCR worker.

const worker = await Tesseract.createWorker(

    selectedLanguage

);

Next, loop through the selected pages.

for(let page = startPage; page <= endPage; page++){

    await processPage(page);

}

Now perform OCR on the rendered page.

const result = await worker.recognize(

    canvas

);

const extractedText = result.data.text;

Append the extracted text to the final output.

finalText +=

`----- Page ${page} -----\n\n`;

finalText += extractedText;

finalText += "\n\n";

Once every page has been processed, terminate the OCR worker.

await worker.terminate();

Processing one page at a time allows users to monitor OCR progress while ensuring stable performance, even for large documents.

Tracking OCR Progress

OCR processing can take anywhere from a few seconds to several minutes depending on the size of the document, image quality, language, and selected accuracy mode.

Providing a progress indicator is important because users can immediately see that the application is actively processing the document instead of appearing frozen.

As each page finishes recognition, the progress bar updates automatically, displaying both the current page number and the overall completion percentage.

For example, a 42-page document may display messages such as "Processing Page 2 of 42" before eventually reaching the final page.

Showing real-time progress improves the overall user experience and makes it easier to estimate the remaining processing time.

The OCR engine reports its progress while recognizing each page.

logger: info => {

    console.log(info);

}

Update the progress bar.

progressBar.style.width =

`${percentage}%`;

progressLabel.innerText =

`${percentage}%`;

Display the currently processed page.

status.innerText =

`Processing Page ${currentPage}

of ${totalPages}`;

Once the final page has been processed, the progress bar reaches one hundred percent and the extracted text becomes available for review.

Understanding OCR Confidence Scores

One useful feature of Tesseract.js is that it reports a confidence score for every page that it processes.

The confidence score estimates how accurately the OCR engine recognized the characters contained on a page. Higher confidence generally indicates cleaner scans, sharper text, and fewer recognition errors.

For example, a professionally scanned document with clear printed text may produce confidence scores above ninety-five percent, while older photocopies or blurry mobile phone images may produce lower values.

Displaying confidence scores helps users quickly identify pages that may require manual review or reprocessing.

In this application, every processed page displays its individual OCR confidence score after recognition finishes.

The OCR engine returns the confidence value together with the extracted text.

const confidence =

result.data.confidence;

Store each page's score.

confidenceScores.push({

    page: currentPage,

    confidence

});

Display the results.

confidenceScores.forEach(score=>{

    console.log(

        score.page,

        score.confidence

    );

});

Pages with lower confidence scores may contain faded text, handwritten notes, poor lighting, skewed scans, or low image resolution. Reviewing these pages helps improve the overall quality of the extracted document.

Optimizing OCR Accuracy

Even with a powerful OCR engine, the quality of the original document has a significant impact on the extracted text.

Scanned PDFs with sharp, high-resolution pages usually produce excellent results without additional processing. But documents containing faded printing, uneven lighting, shadows, handwritten annotations, or compression artifacts may require image enhancement before OCR begins.

The application includes several preprocessing options that improve recognition quality.

Grayscale conversion removes unnecessary color information and simplifies the image for the OCR engine. Increasing contrast helps separate text from the background, while sharpening improves character edges that may appear blurry in low-quality scans.

Selecting the correct recognition language is equally important. OCR models are trained for specific languages, so choosing the matching language greatly improves character recognition and reduces spelling mistakes.

Users should also select the appropriate accuracy mode. Fast Mode works well for clean digital scans, while High Accuracy Mode performs additional analysis that produces better results for difficult documents, although it requires more processing time.

Taking a few extra seconds to configure these settings often produces significantly cleaner text, higher confidence scores, and fewer manual corrections after extraction.

Reviewing the Extracted Text

Once the OCR process finishes, the application combines the recognized text from every processed page into a single output area.

Instead of immediately downloading the results, users can first review the extracted text directly inside the browser. This provides an opportunity to verify the OCR output, check formatting, identify recognition errors, and ensure that the correct pages were processed.

The extracted text preserves the page sequence by separating the content from each page with a clear page heading. This makes it much easier to navigate large documents such as books, contracts, technical manuals, invoices, government records, and research papers.

For searchable PDFs, the extracted text is usually very accurate. For scanned documents, users can quickly compare the OCR output with the original page preview and decide whether additional image enhancement or a different OCR language would improve the results.

The application also includes a Copy button so users can instantly copy all extracted text to the clipboard without downloading a file.

First, display the extracted text.

document.getElementById(

"output"

).value = finalText;

Next, implement the copy feature.

async function copyText(){

    await navigator.clipboard.writeText(

        finalText

    );

    alert("Text copied successfully.");

}

Attach the event listener.

document.getElementById(

"copyButton"

).addEventListener(

"click",

copyText

);

Providing an in-browser preview allows users to verify OCR quality before exporting the results.

Exporting the OCR Results

After reviewing the extracted content, users can export it in different formats depending on how they intend to use the information.

Plain text files are ideal for editing inside any text editor, importing into word processors, or searching with desktop applications.

JSON exports are useful for developers building document management systems, AI applications, search engines, automation workflows, or APIs that consume structured OCR results.

Providing multiple export formats makes the OCR tool suitable for both everyday users and software developers.

Creating a downloadable TXT file is straightforward.

const blob = new Blob(

    [finalText],

    {

        type:"text/plain"

    }

);

Generate the download link.

const url = URL.createObjectURL(

blob

);

const link = document.createElement(

"a"

);

link.href = url;

link.download = "ocr-output.txt";

link.click();

JSON exports include additional information such as page numbers and confidence scores.

const report = {

    text: finalText,

    confidence: confidenceScores

};

downloadJSON(report);

These export options allow users to continue working with the extracted text in virtually any application.

Demo: How the PDF OCR Tool Works

Step 1: Upload Your PDF

The OCR workflow begins by uploading a PDF document using either the drag-and-drop area or the file picker.

Once a document has been selected, the browser validates the file format, loads the PDF into memory, and prepares it for page rendering. Since all processing occurs locally, the uploaded file never leaves the user's computer.

Step 2: Preview the Uploaded PDF

After the upload is complete, the application renders thumbnail previews of every page.

This allows users to verify that the correct document has been selected and inspect the page order before running OCR.

Previewing the document is particularly useful when processing large books, reports, legal documents, or scanned archives containing dozens of pages.

Step 3: Configure OCR Settings

Before text extraction begins, users configure the OCR options.

The application allows users to choose all pages or a specific page range, select the OCR language, switch between Fast and High Accuracy modes, and enable optional image enhancement features such as grayscale conversion, contrast improvement, and sharpening.

These settings help improve recognition quality depending on the condition of the scanned document.

Step 4: Start OCR Processing

After reviewing the settings, users click the Extract Text button.

The browser begins processing every selected page one by one. During this stage, each rendered page image is analyzed by the OCR engine, which recognizes printed characters and converts them into editable text.

Because OCR runs directly inside the browser, even confidential documents remain completely private throughout the process.

Step 5: Monitor Processing Progress

As OCR runs, the application displays a live progress indicator.

Users can monitor the current page being processed, overall completion percentage, and recognition progress in real time. For large documents, this provides useful feedback and reassures users that the application is actively processing the file.

Step 6: Review OCR Confidence Scores

Once recognition is complete, the application displays confidence scores for every processed page.

These values indicate how accurately the OCR engine recognized each page. Pages with lower confidence scores may contain faded text, skewed scans, or poor image quality and can be reviewed manually if necessary.

Confidence scores provide an additional layer of quality assurance before exporting the extracted text.

Step 7: Review the Extracted Text

After OCR finishes, the complete extracted text appears inside the browser.

Users can scroll through the recognized content, compare it with the original document, and copy the text directly to the clipboard using the built-in Copy button.

This makes it easy to reuse the extracted information immediately without downloading a separate file.

Step 8: Export the Results

Finally, users can export the OCR results.

The application supports downloading the extracted text as a TXT file for general editing or as a JSON file for software development and automation workflows.

After selecting the preferred format, the browser generates the file instantly without uploading any data to external servers.

Performance Optimization Tips

OCR is one of the most computationally intensive operations performed inside a browser. Although modern JavaScript engines and OCR libraries are highly optimized, a few simple techniques can significantly improve performance.

Before processing begins, render PDF pages at an appropriate resolution. Extremely high-resolution images increase processing time without always improving recognition accuracy.

const viewport = page.getViewport({

    scale:1.5

});

Processing pages sequentially instead of loading every page simultaneously reduces memory consumption for large documents.

for(let page = 1; page <= totalPages; page++){

    await processPage(page);

}

Users should enable OCR only when working with scanned PDFs. Searchable PDFs already contain digital text, so OCR simply increases processing time without improving the results.

If the document contains hundreds of pages, allowing users to analyze only a selected page range can significantly reduce processing time.

Using grayscale images instead of full-color pages also improves recognition speed while reducing memory usage.

Whenever possible, choose the OCR language that matches the document. Smaller language models generally process faster and produce more accurate results than attempting recognition with an incorrect language.

Finally, remember to terminate the OCR worker after processing completes to release browser resources.

await worker.terminate();

These small optimizations produce a smoother user experience while making browser-based OCR practical even for large documents.

Important Notes from Real-World Use

OCR accuracy depends heavily on the quality of the original document.

Clean scans with high resolution, good lighting, and sharp printed text usually produce excellent recognition results. Older photocopies, faded documents, handwritten notes, or skewed scans may require image enhancement before OCR begins.

Before processing, always verify that the uploaded file is a valid PDF.

if(file.type !== "application/pdf"){

    alert("Please upload a valid PDF.");

    return;

}

Selecting the correct OCR language is equally important. Processing a Gujarati document with the English language model will significantly reduce recognition accuracy.

console.log(

"Selected Language:",

selectedLanguage

);

Users should also review OCR confidence scores after processing. Pages with lower confidence values often benefit from rescanning or using image enhancement options.

Because the entire workflow runs locally, browser-based OCR is well suited for confidential business reports, contracts, financial documents, legal records, healthcare files, and government paperwork that should never be uploaded to third-party services.

Common Mistakes to Avoid

One common mistake is enabling OCR for documents that already contain selectable text.

Searchable PDFs can usually be processed much faster by extracting the embedded text directly.

if(pdfHasText){

    skipOCR();

}

Another mistake is choosing the wrong recognition language.

Always select the language that matches the document before starting OCR.

worker = await Tesseract.createWorker(

selectedLanguage

);

Some users also attempt OCR on extremely low-quality scans without enabling image enhancement.

Using grayscale conversion, contrast adjustment, or sharpening often improves recognition quality considerably.

Finally, always review the extracted text before exporting it.

Checking the OCR output and confidence scores helps identify pages that may require rescanning or additional processing before the results are used in business workflows.

Conclusion

In this tutorial, you built a browser-based PDF OCR to Text Converter using JavaScript.

You learned how to upload PDF documents, preview scanned pages, configure OCR settings, select recognition languages, improve image quality, extract text, monitor processing progress, review OCR confidence scores, and export the recognized text directly from the browser.

More importantly, you discovered how modern browsers can perform Optical Character Recognition locally without requiring a backend server or cloud-based OCR service.

This approach keeps document processing fast, private, and secure while giving users complete control over how scanned PDFs are converted into editable text.

You can try the complete implementation here:

PDF OCR to Text Converter

Once you understand this workflow, you can extend the project further by adding handwriting recognition, AI-powered document summarization, automatic translation, named entity extraction, keyword detection, document classification, searchable PDF generation, or intelligent document automation.

How to Build a Browser-Based PDF Analyzer Using JavaScript

Bhavin Sheth — Fri, 03 Jul 2026 15:37:58 +0000

PDF files are one of the most widely used document formats for sharing reports, invoices, contracts, books, research papers, manuals, forms, and business documents. Although viewing a PDF is simple, understanding what's inside the document is often much more difficult.

For example, you may need to know how many pages a PDF contains, whether it's password protected, who created it, what metadata it includes, how much text it contains, which fonts are used, or whether the document contains embedded images.

Manually inspecting all of this information can be time-consuming, especially when working with large collections of PDF files.

A PDF Analyzer solves this problem by automatically extracting detailed information from a document. Instead of opening the file in multiple applications, users can upload a PDF once and instantly view metadata, security settings, text statistics, image information, page details, fonts, and much more.

In this tutorial, you'll build a browser-based PDF Analyzer using JavaScript. The application allows users to upload a PDF, preview its pages, configure analysis options, perform different levels of document analysis, inspect the extracted information, and export a complete analysis report in multiple formats.

Everything runs directly inside the browser without requiring a backend server, making document analysis fast, private, and secure.

By the end of this tutorial, you'll have a fully functional PDF Analyzer capable of examining both simple and complex PDF documents.

Why PDF Analysis Is Useful
How PDF Analysis Works
Project Setup
What Library Are We Using?
Creating the Upload Interface
Previewing Uploaded PDF Pages
Configuring Analysis Settings
Analyzing the PDF
Displaying the Analysis Report
Exporting the Analysis Report
Demo: How the PDF Analyzer Works
Important Notes from Real-World Use
Common Mistakes to Avoid
Conclusion

Why PDF Analysis Is Useful

Most people think of a PDF as simply a document that can be viewed or printed, but every PDF contains much more information than what appears on the screen.

Behind every document is a collection of properties such as metadata, security settings, page information, fonts, embedded images, and document statistics. Accessing this information can help users better understand the document before editing, sharing, printing, or archiving it.

Businesses often receive hundreds of PDF files every day from clients, suppliers, government departments, and employees. Before these files are stored or distributed, they frequently need to be inspected to verify their contents. A PDF Analyzer makes this process much faster by automatically extracting important document information.

Legal professionals regularly review contracts and agreements where document properties such as creation dates, authorship, and security restrictions may be important. Instead of manually checking each document, an analyzer provides these details in seconds.

Educational institutions use PDF analysis when reviewing assignments, research papers, and digital course materials. Teachers and administrators can quickly inspect page counts, metadata, extracted text, and document properties before storing or distributing files.

Publishing companies analyze PDF files before printing books, manuals, catalogs, and magazines. Reviewing page sizes, fonts, metadata, and embedded resources helps identify formatting problems before production begins.

Government agencies and healthcare organizations also benefit from document analysis when processing applications, medical records, permits, forms, and official reports. Verifying document integrity before long-term storage helps reduce errors and maintain consistent records.

A PDF Analyzer is equally useful for developers. Before building editing tools such as watermarking, page rotation, cropping, metadata editing, or page extraction, developers often need to inspect the document structure to determine how it should be processed.

Because this application performs all analysis directly inside the browser, users can inspect sensitive documents without uploading them to external servers. This provides an additional layer of privacy while delivering instant results.

How PDF Analysis Works

A PDF Analyzer reads the uploaded document and extracts useful information from its internal structure.

Once the user selects a PDF file, the browser loads the document into memory. Instead of modifying the PDF, the application examines its contents and collects various types of information that can later be displayed in a structured report.

The analysis begins by reading the document itself. Basic properties such as the filename, total number of pages, and file size are identified immediately.

Next, the application extracts metadata including the document title, author, subject, keywords, creator, producer, creation date, modification date, and PDF version.

The analyzer can also inspect security-related properties to determine whether the document is password protected or contains restrictions on printing, copying, or editing.

After processing the document structure, the application examines each page individually. It can count words, characters, images, fonts, estimate reading time, calculate speaking time, and even perform sentiment analysis on extracted text when OCR is enabled.

If the uploaded document consists of scanned pages instead of selectable text, OCR can be used to recognize text before analysis begins.

Once all information has been collected, the application generates a complete report that can be viewed inside the browser or exported as a PDF, JSON, CSV, or text file.

Since the entire workflow runs locally, the original document remains on the user's device throughout the process.

Project Setup

We'll build this project using standard web technologies.

Create the following files:

pdf-analyzer/

│── index.html

│── style.css

│── script.js

Next, include the required libraries inside index.html.

These libraries provide everything needed for PDF loading, rendering, OCR processing, and report visualization.

What Library Are We Using?

This project combines several JavaScript libraries because no single library can perform every type of PDF analysis.

The primary library is PDF-lib, which allows the application to load PDF documents and access important document properties such as metadata and page information. It's lightweight, fast, and runs entirely inside modern browsers.

The project also uses PDF.js to render document pages for previews. This enables users to visually inspect uploaded PDFs before running the analysis.

For scanned documents that don't contain selectable text, Tesseract.js provides Optical Character Recognition (OCR). It recognizes text directly inside the browser, making it possible to analyze scanned PDFs without requiring any server-side processing.

To visualize analysis results, we'll use Chart.js for generating simple graphs and statistics such as word counts, sentiment distribution, and other document metrics.

Together, these libraries create a powerful browser-based PDF Analyzer capable of extracting metadata, rendering previews, recognizing scanned text, generating statistics, and exporting detailed analysis reports while keeping every document completely private.

Creating the Upload Interface

Every PDF workflow begins with selecting a document. Before any analysis can take place, users need a simple and reliable way to upload one or more PDF files into the browser.

A good upload interface should clearly indicate that only PDF documents are accepted while supporting both drag-and-drop uploads and the traditional file picker. This makes the tool easy to use regardless of whether users are working on a desktop or a mobile device.

In this project, the upload area acts as the entry point for the entire analysis process. When a user selects a PDF, the browser validates the file type, loads the document into memory, and prepares it for previewing and analysis. Since everything happens locally, the original PDF never leaves the user's device.

Our upload component displays a drag-and-drop area, a browse button, and helpful instructions that guide users through the first step of the workflow.

Here's the HTML for the upload area:



    

        
            ☁
        

        Drag & Drop PDF Here

        Or click to browse file

Next, register the file input and handle PDF selection.

const pdfInput = document.getElementById("pdfInput");

pdfInput.addEventListener("change", async (event) => {

    const file = event.target.files[0];

    if (!file) return;

    if (file.type !== "application/pdf") {

        alert("Please select a valid PDF file.");

        return;

    }

    loadPDF(file);

});

This validation prevents unsupported file types from being processed while ensuring the application only loads valid PDF documents.

After the upload interface is complete, users can immediately select a document and move to the preview stage.

Previewing Uploaded PDF Pages

Once a PDF has been uploaded, it's helpful to display a visual preview before starting the analysis. This allows users to verify that they selected the correct document and quickly inspect its pages.

Instead of showing only the file name, our application renders thumbnail previews of every page in the PDF. Users can scroll through the thumbnails to inspect the document and confirm that all pages loaded successfully.

Displaying previews also improves the user experience because it gives immediate visual feedback while the document is being prepared for analysis.

The browser uses PDF.js to render each page as a canvas before converting it into an image that can be displayed inside the page preview grid.

The following code loads the PDF document:

const pdf = await pdfjsLib.getDocument({

    data: await file.arrayBuffer()

}).promise;

Next, render each page:

for (let pageNumber = 1; pageNumber <= pdf.numPages; pageNumber++) {

    const page = await pdf.getPage(pageNumber);

    const viewport = page.getViewport({

        scale: 0.35

    });

    const canvas = document.createElement("canvas");

    const context = canvas.getContext("2d");

    canvas.width = viewport.width;

    canvas.height = viewport.height;

    await page.render({

        canvasContext: context,

        viewport

    }).promise;

    previewContainer.appendChild(canvas);

}

Each page is rendered independently, making it possible to preview documents containing dozens or even hundreds of pages.

The preview shown in this project displays all page thumbnails together, making it easy to verify page order before continuing.

Configuring Analysis Settings

Before analyzing the document, users can customize how the application should examine the PDF.

Different documents require different levels of analysis. Some users may only need basic information such as the page count and metadata, while others may want detailed statistics about extracted text, embedded images, fonts, security permissions, and OCR results.

To support these different scenarios, the PDF Analyzer provides several configurable options before processing begins.

The first option allows users to choose which pages should be analyzed. They can analyze every page in the document or specify a custom page range when only certain pages are relevant.

For scanned PDFs, OCR can be enabled to recognize text that's stored as images rather than selectable characters. Users can also select the OCR language before processing starts.

Finally, the application offers multiple analysis levels. Basic mode extracts essential document information such as metadata and security properties. Standard mode additionally collects text and image statistics. Advanced mode performs the most detailed inspection available, including fonts, page-level statistics, OCR processing, and sentiment analysis.

The analysis settings panel gives users complete control over how the document should be processed while keeping the interface simple and easy to understand.

Here's the HTML used for the settings panel:

Users can also enable OCR when analyzing scanned PDF documents:

const enableOCR = document.getElementById("enableOCR").checked;

const language = document.getElementById("ocrLanguage").value;

if (enableOCR) {

    console.log("OCR Enabled");

    console.log(language);

}

Finally, capture the selected analysis level:

const level = document.getElementById("analysisLevel").value;

switch (level) {

    case "basic":

        runBasicAnalysis();

        break;

    case "standard":

        runStandardAnalysis();

        break;

    case "advanced":

        runAdvancedAnalysis();

        break;

}

These settings allow the application to adapt to many different types of PDF documents, from simple text files to complex scanned reports containing images, metadata, and security restrictions.

Analyzing the PDF

Once the PDF has been uploaded, previewed, and the analysis options have been configured, the application is ready to examine the document.

Unlike editing tools that modify pages, a PDF Analyzer inspects the document and extracts useful information without changing the original file. The analyzer reads the PDF structure, examines each page, and collects information that can later be displayed in a detailed report.

The analysis begins by loading the uploaded document into memory. From there, the application extracts basic information such as the filename, file size, total number of pages, and document validity. It then reads metadata including the title, author, subject, creator, producer, creation date, modification date, and PDF version.

Depending on the selected analysis level, the application can also inspect security permissions, count words and characters, estimate reading time, identify embedded images, list fonts used throughout the document, and perform OCR on scanned PDFs. When OCR is enabled, the analyzer converts scanned images into searchable text before calculating document statistics.

Because the application processes everything inside the browser, users receive instant results while maintaining complete privacy.

The first step is loading the uploaded PDF:

async function analyzePDF(file){

    const bytes = await file.arrayBuffer();

    const pdf = await PDFLib.PDFDocument.load(bytes);

    return pdf;

}

Next, extract the document metadata:

const metadata = {

    title: pdf.getTitle(),

    author: pdf.getAuthor(),

    subject: pdf.getSubject(),

    creator: pdf.getCreator(),

    producer: pdf.getProducer(),

    keywords: pdf.getKeywords(),

    creationDate: pdf.getCreationDate(),

    modificationDate: pdf.getModificationDate()

};

Basic document information is also collected:

const fileInfo = {

    fileName: file.name,

    fileSize: file.size,

    totalPages: pdf.getPageCount(),

    valid: true

};

If the user selects Advanced Analysis, additional routines extract page statistics, fonts, images, OCR results, and text analysis:

if(selectedLevel === "advanced"){

    analyzeFonts();

    analyzeImages();

    analyzeText();

    performOCR();

}

Once every analysis step has finished, the application combines the collected information into a single report object that will be displayed in the next stage.

Displaying the Analysis Report

After processing is complete, the application presents the collected information inside a structured report.

Instead of showing raw JSON or technical output, the report organizes related information into separate cards. This layout makes it much easier for users to understand large amounts of document information.

The first section displays basic document information, including the filename, file size, total number of pages, and validation status.

The metadata section contains properties such as the document title, author, subject, keywords, creator, producer, PDF version, creation date, and modification date.

Security information indicates whether the document is password protected and whether printing, copying, or modification restrictions are present.

When text analysis is enabled, the report includes the total word count, character count, average words per page, estimated reading time, and estimated speaking time. If OCR has been performed, the extracted text is also analyzed to calculate sentiment statistics.

Additional cards display image information, embedded fonts, and page-by-page extracted text for users who need a deeper inspection of the document.

The following example creates a simple report section:

function renderBasicInfo(info){

    document.getElementById("fileName").textContent = info.fileName;

    document.getElementById("pageCount").textContent = info.totalPages;

    document.getElementById("fileSize").textContent = info.fileSize;

}

Rendering the metadata is straightforward:

function renderMetadata(metadata){

    title.innerText = metadata.title;

    author.innerText = metadata.author;

    creator.innerText = metadata.creator;

    producer.innerText = metadata.producer;

}

Page-wise extracted content can also be displayed:

pages.forEach((page,index)=>{

    createPageCard(

        index + 1,

        page.text

    );

});

Organizing the results into individual sections allows users to quickly locate the information they need without scrolling through large blocks of text.

Exporting the Analysis Report

After reviewing the analysis results, users often need to save the report for future reference or share it with colleagues.

To support different workflows, the PDF Analyzer allows the report to be exported in several formats. Depending on the user's needs, the report can be downloaded as a PDF document, JSON file, CSV spreadsheet, or plain text file.

PDF reports are useful for documentation and sharing with clients or team members. JSON exports are ideal for developers who want to process the analysis programmatically. CSV files can be opened in spreadsheet applications for further analysis, while text files provide a simple human-readable version of the report.

Providing multiple export formats makes the analyzer suitable for business users, developers, researchers, and system administrators alike.

The following example creates a JSON export:

const report = JSON.stringify(

    analysisResult,

    null,

    2

);

Create a downloadable file:

const blob = new Blob(

    [report],

    {

        type:"application/json"

    }

);

Generate the download link:

const url = URL.createObjectURL(blob);

const link = document.createElement("a");

link.href = url;

link.download = "analysis-report.json";

link.click();

The export menu allows users to choose the most appropriate output format before downloading the completed report.

Demo: How the PDF Analyzer Works

Step 1: Upload Your PDF File

The process begins by uploading a PDF document using either the drag-and-drop area or the file selection button.

Once a file is selected, the browser validates that it's a PDF before loading it into memory. Because the application runs entirely inside the browser, the uploaded document never leaves the user's device, making the tool suitable for confidential business reports, contracts, invoices, research papers, legal documents, and other sensitive files.

After the PDF is loaded successfully, the application prepares it for page preview generation and document analysis.

Step 2: Preview Uploaded PDF Pages

After the document has been loaded, the application generates page previews for the uploaded PDF.

Displaying page thumbnails allows users to confirm that the correct file has been selected before analysis begins. Users can quickly browse through the document, inspect page order, and verify that every page has loaded successfully.

This visual preview also helps identify scanned pages, blank pages, or unexpected formatting issues before processing.

Step 3: Configure Analysis Settings

Next, users configure how the PDF should be analyzed.

The tool allows users to choose whether every page or only a specific page range should be processed. For scanned PDFs, OCR can be enabled to recognize text stored as images, and users can select the appropriate recognition language.

The application also offers multiple analysis levels. Basic mode extracts essential document properties, Standard mode adds text and image statistics, and Advanced mode performs a more detailed inspection that includes fonts, OCR, page-level information, sentiment analysis, and additional document insights.

These settings allow users to customize the analysis based on the type of PDF they are working with.

Step 4: Analyze the PDF

Once the settings have been reviewed, users simply click the Analyze PDF button.

The browser reads the uploaded document and extracts the selected information. Depending on the chosen analysis level, the application examines metadata, security settings, page information, extracted text, fonts, embedded images, and OCR results.

Although large documents may require a few additional seconds, the entire analysis is completed locally without uploading the PDF to a remote server.

Step 5: Review the Analysis Report

After processing is complete, the application displays a comprehensive analysis report.

The report is divided into multiple sections that make it easy to inspect different aspects of the document. Users can review basic document information, metadata, security settings, extracted text statistics, page information, fonts, embedded images, OCR results, estimated reading time, speaking time, and sentiment analysis.

Each section is organized into individual cards so that important information can be located quickly.

Step 6: Review Page-Level Analysis

For users who need more detailed information, the application also displays page-by-page analysis.

Each page can include extracted text, OCR output, word count, image statistics, page dimensions, and additional information collected during processing.

This level of detail is especially useful when analyzing large reports, scanned books, research papers, contracts, technical documentation, and multi-page business documents.

Step 7: Export the Analysis Report

After reviewing the analysis, users can export the report for future reference.

The tool supports multiple export formats, including PDF, JSON, CSV, and plain text. This allows developers, researchers, businesses, and system administrators to choose the format that best fits their workflow.

Exported reports can be archived, shared with team members, imported into other systems, or used for additional processing.

Once the desired format is selected, the browser generates the report and downloads it instantly.

Important Notes from Real-World Use

A PDF Analyzer can process everything from a single-page document to large reports containing hundreds of pages. While modern browsers handle most documents efficiently, larger files containing high-resolution images or scanned pages may require additional processing time, especially when OCR is enabled.

Before starting the analysis, it's good practice to validate the uploaded file.

if (file.type !== "application/pdf") {

    alert("Please upload a valid PDF document.");

    return;

}

If OCR is enabled, remember that recognizing text from scanned pages takes longer than extracting text from a standard searchable PDF. Users should only enable OCR when it's actually needed.

if(enableOCR){

    console.log("Running OCR Analysis...");

}

When analyzing very large documents, processing pages individually helps reduce memory usage and keeps the browser responsive.

for(let page = 1; page <= pdf.numPages; page++){

    analyzePage(page);

}

Before exporting the report, review the extracted information to ensure metadata, text statistics, page information, and OCR results are accurate.

Common Mistakes to Avoid

One common mistake is running OCR on documents that already contain selectable text.

OCR is designed for scanned PDFs where text exists only as images. Running OCR on searchable PDFs increases processing time without improving the analysis.

if(pdfContainsText){

    enableOCR = false;

}

Another mistake is selecting the wrong analysis level.

For example, users who only need metadata and document properties can choose Basic Analysis instead of Advanced Analysis, which performs additional processing such as OCR, font inspection, sentiment analysis, and image detection.

const analysisLevel = "basic";

console.log(analysisLevel);

Some users also forget to verify the page selection before starting the analysis.

When working with large reports, analyzing only the required pages can significantly reduce processing time.

const pageRange = "1-20";

console.log(pageRange);

Finally, always review the generated report before exporting it.

A quick inspection helps verify that metadata, page statistics, OCR output, document properties, and extracted text are accurate before downloading the final report.

Taking a few extra moments to validate the results can save considerable time when working with large document collections.

Conclusion

In this tutorial, you built a browser-based PDF Analyzer using JavaScript.

You learned how to upload PDF files, preview document pages, configure analysis options, inspect metadata, analyze document structure, extract text, perform OCR, generate detailed reports, and export the analysis in multiple formats directly from the browser.

More importantly, you saw how modern browsers can inspect complex PDF documents without requiring a backend server or uploading files to third-party services.

This approach keeps document analysis fast, private, and secure while giving users valuable insights into the contents and structure of their PDF files.

You can try the complete implementation here:

PDF Analyzer: https://allinonetools.net/pdf-analyzer/

Once you understand this workflow, you can extend the project further by adding AI-powered document summarization, keyword extraction, duplicate document detection, document comparison, accessibility analysis, compliance checking, digital signature validation, or advanced reporting dashboards.

JavaScript - freeCodeCamp.org

A Guide to Modern React Form Architecture: TanStack Form + Zod + Shadcn

Table of Contents

The Problem with Traditional Forms

The Problem

The Uncontrolled "Ref" Workaround

The Ref Workaround

Why Not Just Use Native HTML Forms?

Introducing TanStack Form

Add New Speaker

Fine-Grained Reactivity

Validation with Zod

Headless TanStack Form with ShadCN UI

Handling Nested Dynamic Arrays with TanStack Form

TanStack Form's Granular Reactivity: useSelector vs form.Subscribe

With useSelector()

With form.Subscribe()

TanStack Form vs. React Hook Form

Dynamic Arrays

Deeply Nested Components

The Ecosystem Sync

Conclusion & Important Resources

If You've Read This Far...

How to Build a Browser-Based PDF Blur Tool Using JavaScript

Table of Contents

What This PDF Blur Tool Does and How It Works

Project Setup

Creating the HTML Layout

Selecting DOM Elements

Uploading and Previewing PDFs

Reading the PDF

Rendering the First Page

Creating Page Navigation

Preparing for Blur Editing

Showing the Editor

Creating Blur Regions

Creating the Blur Area Object

Storing Multiple Blur Regions

Starting a Blur Selection

Drawing the Blur Rectangle

Finishing the Selection

Drawing Existing Blur Areas

Displaying Blur Boxes

Blur Options

Adjusting Blur Intensity

Managing Multiple Blur Areas

Applying Blur to Pages

Applying the Blur Effect

Loading the Original PDF

Processing the Selected Pages

Rendering Each Page as an Image

Applying Blur to Selected Regions

Blurring the Canvas Region

Blurring an Entire Page

Converting the Canvas Back into a PDF Image

Showing the Processing State

Generating the Final PDF

Previewing the Result

Renaming and Downloading

Demo: How the PDF Blur Tool Works

Step 1: Upload the PDF

Step 2: Preview the Document

Step 3: Configure Blur Settings

Step 4: Draw Blur Areas

Step 5: Adjust Blur Intensity

Step 6: Manage Blur Regions

Step 7: Choose the Pages

Step 8: Apply the Blur

Step 9: Review the Final Document

Step 10: Rename and Download

Performance Tips

Common Mistakes

Conclusion

How to Build an AI Agent with Function Calling in Node.js Using Google Gemini

Table of Contents

How Function Calling Works

What We're Building

Prerequisites

Project Setup

Defining the Tools

TanStack Form's Granular Reactivity: `useSelector` vs `form.Subscribe`

With `useSelector()`

With `form.Subscribe()`

1. `[404 Not Found] models/gemini-1.5-flash is not found for API version v1beta`

2. `[429 Too Many Requests] You exceeded your current quota`

3. `Error: GEMINI_API_KEY is not set`

4. `GoogleGenerativeAIError: 400 INVALID_ARGUMENT`

6. `TypeError: fetch is not a function`

8. Exchange Rate Returns `No rate found`

What Is `contenteditable`?

How to Edit Links Inside `contenteditable`