In this tutorial, you'll build a data pipeline yourself. You'll create a Python ETL (Extract, Transform, Load) pipeline that pulls daily water-level readings from Hub'Eau, France's official open water-data API. Then, you'll clean that data and publish it as a public dataset, just like the live version does.

This tutorial is based on a real pipeline that runs once a week, on a schedule, and it keeps the Paris Flood Dataset updated automatically.

You won't just copy and paste code, though. The real goal is to understand why the pipeline works the way it does. You'll walk through the design decisions that separate a script meant to run once from a script that keeps working, unattended, for years.

You can code along with this notebook. For most of the tutorial, the pipeline runs on simulated (mock) API data. This lets you run every cell safely, without hammering a real server. A later section shows how to switch to the live API.

By the end, you'll be able to:

• Explain and implement the Extract, Transform, Load pattern

• Manage configuration with Python @dataclass instead of scattering constants everywhere

• Write API-fetching code that survives network failures and paginated responses

• Apply robust type-coercion so one bad row can't crash a whole pipeline run

• Deduplicate and merge incremental data safely

• Wire everything into a single, idempotent, schedulable main() entry point

Table of Contents:

• Prerequisites

• Part 1: The Design Logic

  • What is an ETL pipeline?

  • The architecture, at a glance

  • Two patterns that make it production-grade

• Part 2: Setup and Dependencies

• Part 3: Manage Configuration with Dataclasses

  • Why bother with a config layer at all?

  • Code-level walkthrough

• Part 4: The Extraction Step

  • Graceful file loading

  • Incremental update logic

  • Simulate the API

  • Fetch data for real

• Part 5: The Transform Step

  • Type parsing and graceful coercion

  • Schema translation with bidirectional mappings

  • Compute flood alerts

  • Column ordering

  • Deduplication

  • Put it all together inpostprocess()

• Part 6: The Load Step

  • Design logic

  • Code-level walkthrough

• Part 7: Assemble the Full Pipeline

  • The global rehearsal (mock mode)

  • main(): pipeline orchestration

  • Theif name == "main":guard

• Part 8: Go Live and Switch to the Real API

  • Post-run validation

• Summary

• References

Prerequisites

• Python 3.10+. The code uses type hints and dataclasses. These work from Python 3.7 onward, but 3.10+ is best.

• Knowledge of pandas DataFrames: read data, filter rows, and basic column operations.

• Comfort with functions and basic OOP (Object-Oriented programming) in Python. Don't worry, this guide explains every non-obvious piece as you go.

• Optional: a free Kaggle account and the Kaggle CLI, only if you want to run the final publishing step for real.

Install the dependencies:

pip install requests pandas numpy ipykernel

You'll do the work inside a Jupyter notebook. Download the .ipynb file from Kaggle, or click "Copy and Edit" to work directly on Kaggle. You'll need a Kaggle account for that.

Optional: If you plan to run the notebook locally, install the notebook package too:

pip install notebook

Part 1: The Design Logic

Before you touch a single line of code, we'll spend three minutes on why the pipeline is shaped this way.

This is the big-picture view. Every code-level decision later traces back to one of these ideas. Read this section even if you skim everything else.

What is an ETL Pipeline?

ETL stands for Extract, Transform, Load. It's the standard pattern for moving data from a source to a destination in a reliable, repeatable way.

• Extract: pull data from a source, like an API, a database, or files.

• Transform: clean, standardize, enrich, and validate the data.

• Load: write the result to a destination, like a warehouse, a CSV, or a public platform.

Here's how those three stages map onto this project:

The Architecture, at a Glance

Notice that "Extract" already touches two different sources: the existing dataset (what you already have) and the new data from the API. That distinction is the seed of the next idea.

Two Patterns that Make it Production-Grade

There two patterns that make this pipeline safe to run unattended, scheduled, for years.

1. Idempotency

Idempotence means when the same operation runs twice it gives the same result as if it runs once. Deduplication is what makes this pipeline idempotent. If the scheduler accidentally triggers twice, or a network retry fetches the same day again, the second run won't create duplicate rows. This matters a lot for anything that runs on a schedule with no one watching it.

2. Incremental loading

A naïve pipeline would re-download the entire history on every run. That's slow, it wastes your API quota, and it's fragile: the more data you transfer, the more chances something fails.

An incremental pipeline avoids this. Instead, it:

• Checks the most recent date already in the dataset

• Requests only the data from that date onward

• Merges the new records into the existing dataset

You'll find this logic built explicitly in determine_update_range.

Always ask yourself: "Do I actually need to do this?" That one habit separates a fragile script from a production pipeline. For example, every "expensive" or "external" step in this pipeline (network calls, disk writes, publishing) is guarded by a cheap, local check first.

Part 2: Setup and Dependencies

Here's the import block. It looks unremarkable, but how it's organized is itself a best practice worth calling out.

# Standard library imports
import json
import os
import random
import subprocess
from dataclasses import dataclass, field
from datetime import date, timedelta
from pathlib import Path
from typing import Dict, List, Optional, Set, Tuple

# Third-party libraries
import numpy as np
import pandas as pd
import requests

# Display config for notebooks
pd.set_option('display.max_columns', None)   # All columns will show
pd.set_option('display.max_colwidth', None)  # Prevents cutting long column text with ...

Code-level notes:

• Imports fall into three blocks: standard library, then third-party, then local, with blank lines between them. This follows PEP 8's import-ordering convention. Most auto-formatters (isort, ruff) enforce this same grouping.

• Nothing is imported with from module import *. That syntax pollutes the current namespace. It makes it hard to trace where a name came from when someone debugs the code six months later. Python style guides echo this advice, including Google's Python Style Guide.

• The pd.set_option(...) calls exist purely for notebook readability, so wide DataFrames don't get truncated with .... They have zero effect on the pipeline's logic. You'd typically remove or scope them differently in a .py script.

Part 3: Manage Configuration with Dataclasses

Why Bother with a Config Layer at All?

Every pipeline has knobs: which stations to monitor, what the flood threshold is, and where to publish. The bad approach sprinkles these values as literals throughout the code as you write it. You end up with an if level > 6000: buried three functions deep. Then changing any setting means hunting through the whole file, and it's easy to update one spot and miss another.

The fix: centralize all settings in one place. Python's @dataclass decorator is a natural fit for that.

Compare that to a configuration written as a plain dict:

config = {
    "stations": ["STN001", "STN002"],
    "flood_threshold": 6000,
    "publish_url": "https://example.com/alerts",
    "retry_count": 2,
    "timeout_seconds": 5,
}

A plain dict gives you none of that: no immutability, no type checking, and no autocomplete.

Code-Level Walkthrough

The pipeline defines three configuration classes. Each one has a single responsibility: API details, station rules, and publishing destination. Each class becomes one module-level singleton instance. Every other function in the pipeline reads from these singletons.

@dataclass
class APIConfig:
    """API configuration for HubEau data fetching.

    Think of this as the "address book" for the API.
    """
    use_mock: bool = True
    base_url: str = "https://hubeau.eaufrance.fr/api/v2/hydrometrie/obs_elab"
    metric: str = "HIXnJ"  # Daily max water level (elaborated observations)
    # Pagination: fetch 20k records per request (API Limit)
    max_per_page: int = 20000
    timeout_seconds: int = 60  # Network timeout

    def __post_init__(self):
        """Validate configuration after initialization."""
        if self.max_per_page <= 0:
            raise ValueError("max_per_page must be positive")
        if self.timeout_seconds <= 0:
            raise ValueError("timeout_seconds must be positive")

Notice the validation inside __post_init__. It runs right after the auto-generated __init__. A misconfigured APIConfig(max_per_page=-1) fails loudly and immediately at startup, instead of surfacing as a bug later during an actual pipeline run.

@dataclass
class StationConfig:
    """Station monitoring configuration.

    The 'what' of data collection: which stations, what's a flood?
    """
    station_codes: List[str] = field(default_factory=lambda: [
        "F700000109", "F700000110", "F700000111",
        "F700000102", "F700000103",
    ])
    flood_threshold_mm: int = 6000  # Flood alert threshold
    earliest_date: str = "1900-01-01"  # How far back to go

The mutable-default trap: Look closely at station_codes. It isn't written as station_codes: List[str] = [...]. That's deliberate, and it dodges one of the most common gotchas in Python. If you use a plain mutable object (a list, dict, or set) as a default argument or dataclass field, every instance shares the same underlying object. Mutate it on one instance, and you silently mutate it everywhere else too.

Stack Overflow covers this at length in its "least astonishment" mutable-default-argument discussion, as does Real Python's guide to optional arguments. The fix is field(default_factory=...). It calls a fresh factory function (here, a lambda) for every new instance, so each one gets its own independent list.

Explanation:

# Bad: shared mutable default
@dataclass
class BadConfig:
    station_codes: list[str] = []

a = BadConfig()
b = BadConfig()

a.station_codes.append("ALERT")
print(a.station_codes)  # ['ALERT']
print(b.station_codes)  # ['ALERT']  <-- same list!!


# Good: fresh list per instance
@dataclass
class GoodConfig:
    station_codes: list[str] = field(default_factory=list)

x = GoodConfig()
y = GoodConfig()

x.station_codes.append("ALERT")
print(x.station_codes)  # ['ALERT']
print(y.station_codes)  # []  <-- independent list

And the last Config singleton, the Kaggle settings:

@dataclass
class KaggleConfig:
    """Kaggle dataset publishing configuration."""
    dataset_slug: str = "grimespoint/paris-flood-dataset"
    input_csv: str = "kaggle/input/datasets/{slug}/paris_flood_dataset.csv"
    output_dir: Path = field(default_factory=lambda: Path("kaggle/working/kaggle_dataset"))
    mock_output_dir: Path = field(default_factory=lambda: Path("mock_output"))
    output_filename: str = "paris_flood_dataset.csv"
    mock_output_filename: str = "mock_flood_dataset.csv"
    metadata_filename: str = "dataset-metadata.json"

    # Metadata
    title: str = "Paris flood dataset"
    keywords: list = field(default_factory=lambda: [
        "tabular", "weather and climate", "environment", "europe", "time series analysis"
    ])
    geospatial_coverage: str = "Paris, France"
    update_frequency: str = "Weekly"
    license_name: str = "CC0-1.0"

    # Computed fields (set in __post_init__)
    output_csv_path: Path = field(init=False)
    metadata_path: Path = field(init=False)

    def __post_init__(self):
        """Compute derived paths after initialization."""
        self.input_csv = self.input_csv.format(slug=self.dataset_slug)
        self.output_csv_path = self.output_dir / self.output_filename
        self.metadata_path = self.output_dir / self.metadata_filename
        self.mock_output_filename = self.mock_output_dir / self.mock_output_filename

# Initialize configs - module-level singletons
API_CONFIG = APIConfig()
STATION_CONFIG = StationConfig()
KAGGLE_CONFIG = KaggleConfig()

This is the most common use of __post_init__. output_csv_path and metadata_path are marked field(init=False), so you can't set them directly through the constructor. Instead, __post_init__ computes them from other fields (output_dir and output_filename).

Use this pattern for derived, computed values: compute them once, in one place, instead of recomputing output_dir / output_filename every time you need the path elsewhere in the codebase.

See Real Python's data classes guide or the data classes chapter of O'Reilly's Fluent Python for more on this pattern.

Tip: the auto-generated __repr__ gives you a readable printout for free. Call print(API_CONFIG): it shows every field and value without a single line of formatting code. It's handy for quick sanity checks when you're debugging a pipeline run.

print(APIConfig)
# prints APIConfig(use_mock=True, base_url='https://hubeau.eaufrance.fr/api/v2/hydrometrie/obs_elab', ...)

Part 4: The Extraction Step

The Extract phase pulls data from source systems and reads it into memory. Here, you genuinely have two sources to extract from: the existing dataset (what you already published last time) and the new (recent) data from the Hub'Eau API.

Graceful File Loading

Design logic

What should happen the very first time this pipeline runs (and there's no existing dataset yet)? A naïve implementation would crash with a FileNotFoundError.

Here's the trick: load_csv() follows the Null Object pattern. Instead of raising an error, it returns an empty DataFrame. Every downstream function can then treat "no existing data" and "some existing data" the same way, with no special-casing needed.

Code-level walkthrough

This function loads a CSV file into a DataFrame. If the file doesn't exist, it returns an empty DataFrame instead of crashing.

low_memory=False tells pandas to read the file carefully, so it avoids mixed-type guesses. parse_dates=True tries to automatically convert date-like columns into dates. delimiter="," tells pandas the file is comma-separated.

def load_csv(path: str) -> pd.DataFrame:
    """Load CSV file or return empty DataFrame if file does not exist.

    Args:
        path (str): Full path to the CSV file.

    Returns:
        pd.DataFrame: Loaded data, or empty DataFrame if file not found.

    Raises:
        pd.errors.ParserError: If the CSV is malformed.
    """
    if os.path.exists(path):
        return pd.read_csv(path, low_memory=False, parse_dates=True, delimiter=",")
    return pd.DataFrame()   # Null Object: consistent return type

To test, try it against a path that doesn't exist:

df_missing = load_csv("/tmp/does_not_exist.csv")
print(df_missing.empty)  # True: no crash

# Callers can always do this, instead of an `is None` check:
if df_missing.empty:
    print("No existing data. Will run a full fetch from earliest date.")

Best practice: return a consistent type from every code path in a function. A function that sometimes returns a DataFrame and sometimes None forces every caller to add a None check before using the result.

Return a DataFrame, empty or not, which keeps things simpler. You never have to ask "did I get a real result, or None?" before using it.

Incremental Update Logic

Design logic

This is the "incremental loading" pattern from Part 1 in action. Before you fetch anything, ask: "What's the most recent record I already have, and do I actually need more?"

Strategy: check whether the existing data already covers yesterday.

• Yes: skip the update entirely. Nothing to do, the dataset is current.

• No: fetch starting from the day after the last known date.

Existing data: Jan. 1 – Jan. 15
Yesterday: Jan. 19

Decision: fetch from Jan. 16 onwards (not from Jan. 1)

Why yesterday and not today? Today's measurement might not be finalized on the source system yet. Hub'Eau's "elaborated observations" are a processed daily aggregate, so the safest check is against the last fully completed day.

Code-level walkthrough

determine_update_range() checks the newest saved date. It tells you either "you're already up to date" or "start downloading from this next date."

Step by step:

1. The function starts with existing data

   • existing is a pandas DataFrame that already has some rows of data.

2. If there is no data at all

   • if existing.empty:

   • If the DataFrame has zero rows, it says: "Nothing is saved yet, so fetch everything."

   • It returns:

     • True = update needed

     • STATION_CONFIG.earliest_date = start from the earliest allowed date

3. Find the date column

   • The code checks which column contains dates:

     • first tries "date_obs_elab"

     • then "record_date"

   • If neither exists, it raises an error because it doesn’t know which column to use.

4. Convert the date column into real dates

   • pd.to_datetime(...) turns the column into date objects pandas can work with.

   • errors="coerce" means bad date values become missing values instead of crashing.

5. Find the latest date in the data

   • last_day = s.max().date()

   • This gets the newest date already in the dataset.

6. Compare it with yesterday

   • yesterday = date.today() - timedelta(days=1)

   • The function checks whether data already includes yesterday.

7. If data is already up to date

   • If last_day >= yesterday, it returns:

     • False = no update needed

     • None = no start date needed

8. If data is behind

   • It sets next_day to the day after the last saved date.

   • Then it returns:

     • True = update needed

     • that next day as a string like "2026-07-12"

def determine_update_range(existing: pd.DataFrame) -> Tuple[bool, Optional[str]]:
    """Determine whether an update is needed and from what date.

    Logic:
    1. Check if existing data covers yesterday's date
    2. If yes → no update needed
    3. If no → start fetching from day after last data

    Returns:
        Tuple[should_update, start_date]
    """
    # Case 1: nothing on disk yet
    if existing.empty:
        print("No existing data found. Will fetch all data from earliest date.")
        return True, STATION_CONFIG.earliest_date

    if "date_obs_elab" in existing.columns:
        record_colname = "date_obs_elab"
    elif "record_date" in existing.columns:
        record_colname = "record_date"
    else:
        raise KeyError("Missing date column: expected 'date_obs_elab' or 'record_date'")

    s = pd.to_datetime(existing[record_colname], errors="coerce")
    last_day = s.max().date()
    yesterday = date.today() - timedelta(days=1)

    # Case 2: already current
    if last_day >= yesterday:
        print("\nDataset already covers yesterday or later. No update needed.")
        return False, None

    # Case 3: fetch the gap
    next_day = (last_day + pd.Timedelta(days=1))
    print(f"\nWill retrieve data starting from: {next_day}")
    return True, next_day.isoformat()

A few things worth a note here.

First, the function checks for two possible column names: date_obs_elab, the raw API name, or the already-renamed English name record_date. It doesn't assume just one. This makes the function work whether you call it on freshly-fetched raw data or an already-processed CSV loaded from disk.

errors="coerce" shows up here, and it'll show up again (we'll dig into this in Part 5). Any date pandas can't parse becomes NaT (Not a Time) instead of raising an exception.

The return type is Tuple[bool, Optional[str]]. This tuple bundles two related results: should I update, and from when? That beats returning two separate values, or worse, one ambiguous value that means different things depending on context.

Best practice: use Tuple return types (or, for more fields, a small dataclass or NamedTuple) to bundle related results together. Document clearly what each position means. If you return different types from different code paths without documentation, you'll hit a common source of confusion and bugs: "why is this None sometimes and a string other times?".

Run a quick check against three scenarios:

# Test 1: No existing data
should_update, start_date = determine_update_range(pd.DataFrame())
# → True, "1900-01-01"

# Test 2: Old existing data (covers only Jan 10-15)
# → True, "2026-01-16"  (the day after the last known date)

# Test 3: Recent data that already covers yesterday
# → False, None

Simulate the API

Design logic

In production, fetching means a real HTTP call:

requests.get(
    "https://hubeau.eaufrance.fr/api/v2/hydrometrie/obs_elab",
    params={"code_entite": "F700000109", "size": 20000, ...}
)

Real API calls bring real challenges. Rather than fight those on your first read-through, this tutorial first builds and tests everything against a mock generator. It returns data shaped exactly like the real API. Only once the logic works does it swap in the real endpoint.

This technique is useful well beyond this project. Build and test your transform logic against fixtures or mocks first. That way, you're not into "is my parsing wrong?" and "is the network flaky right now?" at the same time.

Code-level walkthrough

generate_mock_api_data() generates fake sample data for a station, one record per day, starting from start_date.

How it works:

• It converts start_date into a real date.

• It loops for num_days.

• For each day, it creates a mock observation dictionary.

• It adds a small random variation to the water level so the data looks realistic.

• It randomly picks status, quality, and method labels.

• It returns a list of these dictionaries.

def generate_mock_api_data(station_code: str, start_date: str, num_days: int = 10) -> List[Dict]:
    """Generate realistic mock API data for demonstration.

    Simulates what HubEau API would return: list of observation dicts.
    """
    start = pd.to_datetime(start_date).date()
    records = []

    validation_statuses = ["Donnée validée", "Donnée brute", "Donnée pré-validée"]
    qualities = ["Bonne", "Non qualifiée", "Douteuse"]
    methods = ["Mesurée", "Calculée", "Expertisée"]

    for i in range(num_days):
        obs_date = start + timedelta(days=i)
        base_level = 5500 + int(station_code[-2:])  # Varies by station
        noise = random.randint(-200, 200)
        water_level = base_level + noise

        record = {
            "code_site": "mock_" + station_code[1:],
            "code_station": "mock_" + station_code,
            "date_obs_elab": obs_date.isoformat(),
            "resultat_obs_elab": water_level,
            "date_prod": (obs_date + timedelta(days=1)).isoformat(),
            "code_statut": "1",
            "libelle_statut": random.choice(validation_statuses),
            "code_methode": "1",
            "libelle_methode": random.choice(methods),
            "code_qualification": "1",
            "libelle_qualification": random.choice(qualities),
            "longitude": 2.3522 + random.uniform(-0.01, 0.01),
            "latitude": 48.8566 + random.uniform(-0.01, 0.01),
            "grandeur_hydro_elab": "mock_HIXnJ",
        }
        records.append(record)

    return records

Fetch Data for Real

Design logic

Two functions handle extraction. They're deliberately split according to the Single Responsibility Principle (SRP): each function should have one reason to change.

fetch_all_data() (orchestrator)
    ├── fetch_single_station_data(station_1) ← handles all complexity
    ├── fetch_single_station_data(station_2) ← handles all complexity
    └── fetch_single_station_data(station_n) ← handles all complexity

• fetch_single_station_data() owns all the messy per-station complexity: pagination, cursor advancement, stop conditions, and network error handling.

• fetch_all_data() owns none of that. It just loops over stations and delegates.

This split has two payoffs. First, you can debug or swap out the pagination strategy for one station without touching the orchestration code at all. Second, if you ever want to parallelize fetching (with concurrent.futures or asyncio, for example), the orchestrator is the only place you'd need to touch.

Code-level walkthrough

fetch_single_station_data() fetches station data either from mock test data or from the real API, page by page, until it has everything it needs.

• If use_mock=True, it uses fake data instead of calling the real API.

  1. It calls generate_mock_api_data()

  2. Turns the result into a DataFrame

  3. Converts the date column into real pandas dates

  4. Returns that DataFrame

• If use_mock=False, it does the real API request:

  1. Creates a reusable HTTP session

  2. Starts from start_date

  3. Repeatedly asks the API for a page of data

  4. Stops when:

     • the API returns no data

     • the latest date reaches yesterday

     • the page is smaller than expected

     • a network error happens

  5. Combines all pages into one DataFrame

  6. Returns an empty DataFrame if nothing was fetched

def fetch_single_station_data(station_code: str, start_date: str, use_mock: bool = True) -> pd.DataFrame:
    """Fetch all hydrometric data for a single station from mock API (default) or from the real endpoint.

    In production (cursor based pagination strategy):
    - Fetches max_per_page records per request
    - Continues until no new data or yesterday's date reached
    - Stop when: no data returned | last date >= yesterday | page was not full
    - Handles network errors gracefully
    """
    if use_mock:
        data = generate_mock_api_data(station_code, start_date, num_days=7)
        page_df = pd.DataFrame(data)
        page_df["date_obs_elab"] = pd.to_datetime(
            page_df["date_obs_elab"], errors="coerce").dt.normalize()
        return page_df

    # Real implementation
    else:
        session = requests.Session()  # Reuse TCP connection across pages
        frames = []
        cursor = start_date

        while True:
            params = {
                "code_entite": station_code,
                "grandeur_hydro_elab": API_CONFIG.metric,
                "date_debut_obs_elab": cursor,
                "size": API_CONFIG.max_per_page,
            }

            try:
                response = session.get(
                    API_CONFIG.base_url,
                    params=params,
                    timeout=API_CONFIG.timeout_seconds  # Best practice, always set
                )
                response.raise_for_status()
            except requests.RequestException as e:  # Don't let one station kill the whole pipeline
                print(f"Error fetching data for station {station_code}: {e}")
                break

            data = response.json().get("data", [])
            if not data:  # Empty response: we've exhausted this station
                break

            page_df = pd.DataFrame(data)
            page_df["date_obs_elab"] = pd.to_datetime(
                page_df["date_obs_elab"], errors="coerce").dt.normalize()
            frames.append(page_df)

            last_page_date = page_df["date_obs_elab"].max()
            yesterday = date.today() - timedelta(days=1)

            # Prevent infinite loops
            if pd.isna(last_page_date) or last_page_date.date() >= yesterday:
                break

            cursor = (last_page_date + pd.Timedelta(days=1)).strftime("%Y-%m-%d")

            if len(data) < API_CONFIG.max_per_page:
                break

    if frames:
        return pd.concat(frames, ignore_index=True)
    return pd.DataFrame()

How does the pagination loop actually work?

Let's walk through it step by step. This is the densest bit of logic in the whole notebook.

1. Send a request with date_debut_obs_elab=cursor: "give me records from this date on."

2. If the request fails outright (requests.RequestException), log it and break. break stops the loop right away and moves on. One station's network hiccup shouldn't kill the pipeline for every other station.

3. If the response has no data at all, you've caught up: break.

4. Otherwise, note the latest date seen on this page (last_page_date).

5. If that latest date is already >= yesterday, you've caught up: break.

6. Otherwise, advance the cursor to last_page_date + 1 day and loop again for the next page.

7. As a safety net: if the page returned fewer records than max_per_page, that also means you've reached the end. The API wouldn't return a partial page unless it ran out of data, so: break.

That last check (step 7) is a classic pagination termination heuristic. You don't always need a next_page token from the API. If a full page is size=20000 and you get back only 4213 records, there's nothing left to fetch.

Three specific, deliberate choices, called out:

session = requests.Session()

A Session object reuses the underlying TCP connection across multiple requests to the same host. That avoids a fresh TCP/TLS handshake on every single page request. In short, it's faster for you and more polite to Hub'Eau's servers.

Best practice: any time you call requests.get() more than once against the same host in a loop, reach for a Session.

except requests.RequestException as e:

RequestException is the base class for every exception requests can raise: timeouts, connection errors, HTTP errors from raise_for_status() and more. Catching the base class here means any network hiccup gets handled the same forgiving way: log it, stop fetching this station, move on.

timeout=API_CONFIG.timeout_seconds

By default, requests calls never time out. Without an explicit timeout, a hung server can freeze your entire pipeline indefinitely. The requests advanced usage docs states that requests to external servers should have a timeout attached.

Best practice: wrap every external I/O call in try/except. Always fail gracefully. Log the error and let the pipeline recover or move on. This avoids one flaky request taking down an unattended weekly job.

Now the orchestrator, fetch_all_data(), is deliberately much simpler:

1. Loop through all station codes.

   • Fetch each station's data.

   • Keep the non-empty results.

2. Combine them into one big DataFrame.

def fetch_all_data(start_date: str, use_mock: bool = True) -> pd.DataFrame:
    """Orchestrator: Fetch data for all configured stations."""
    frames = []

    for station_code in STATION_CONFIG.station_codes:
        print(f"Fetching data for station {station_code}...")
        df_station = fetch_single_station_data(station_code, start_date, use_mock=use_mock)

        if not df_station.empty:
            print(f"  Got {len(df_station)} records")
            frames.append(df_station)
        else:
            print(f"  (no data)")

    if frames:
        return pd.concat(frames, ignore_index=True)
    return pd.DataFrame()

That's it. A loop and a pd.concat. All the hard-won complexity lives one layer down, exactly where SRP says it should.

Part 5: The Transform Step

This is where raw, freshly-fetched data becomes something you can publish. Here's the design philosophy for this whole section: compose many small, pure functions. Each one takes a DataFrame in and returns a new DataFrame out without side effects. Avoid the one giant do-everything function trap.

    (EXTRACT)
    Raw API Data
    ↓
    (TRANSFORM)
1. Type parsing (datetime, numeric)
2. Column renaming (French → English)
3. Categorical mapping (validation status, quality)
4. Derived columns computation (flood alert flags)
5. Column reordering (logical grouping)
6. Sorting & index reset
    ↓
    (LOAD)
    Publication-ready dataset

Why split this into six tiny steps instead of one big function? Each piece is testable and replaceable on its own. When something breaks at 3am on a scheduled run, every function is debuggable in isolation. You can pinpoint exactly which stage produced bad output. No need to pick apart one 200-line function.

Type Parsing and Graceful Coercion

Design logic

Data from a CSV or a JSON API starts out, by default, as strings. Pandas needs real types to sort dates chronologically, do date arithmetic (last_date + timedelta(days=1)), or compare numeric values (water_level > 6000). Type mismatches are a common error that break batch pipelines. One malformed row, like "N/A", a truncated date, misaligned values, or stray characters and a strict parser throws an exception that kills the whole run.

Best practice: both conversion functions below use errors="coerce", so values pandas can't parse become NaT (Not a Time) or NaN (Not a Number) instead of raising an error. This is called graceful coercion.

Code-level walkthrough

convert_to_date() and convert_to_numeric() are small helper functions that make sure certain columns have the right type.

• Both start with df.copy() so they don’t change the original DataFrame.

• errors="coerce" means bad values become missing values instead of causing a crash.

For convert_to_date():

1. df.copy() makes a separate copy, so the original table stays unchanged

2. The loop goes through each column name in columns

   • if col in df.columns checks that the column actually exists before trying to convert it

   • pd.to_datetime(...) turns text like "2026-07-12" into real pandas date/time values

   • errors="coerce" means invalid values become NaT (missing date) instead of raising an error

   • .dt.normalize() removes the time part and keeps only the date at midnight

For convert_to_numeric():

1. df.copy() is used here as well.

2. The loop goes through each column name in columns

   • if col in df.columns checks that the column actually exists before trying to convert it

   • The loop calls pd.to_numeric() turns text like "12.5" into numbers

   • errors="coerce" turns bad values into NaN instead of crashing

def convert_to_date(df: pd.DataFrame, columns: List[str]) -> pd.DataFrame:
    """Convert specified columns to pandas datetime type."""
    df = df.copy()  # Never modify the original!
    for col in columns:
        if col in df.columns:
            df[col] = pd.to_datetime(df[col], errors="coerce").dt.normalize()
    return df


def convert_to_numeric(df: pd.DataFrame, columns: List[str]) -> pd.DataFrame:
    """Convert specified columns to numeric (float) type."""
    df = df.copy()
    for col in columns:
        if col in df.columns:
            df[col] = pd.to_numeric(df[col], errors="coerce")
    return df

Why is this useful?

• You can aggregate the data: group it, summarize it and so on...

• Dates become sortable and filterable as real dates.

• Numbers work correctly in calculations like averages, sums, or comparisons.

• It prevents bugs caused by mixed types, like "12" and 12.

Both pd.to_datetime and pd.to_numeric are official pandas functions with an errors parameter. By default, that parameter is set to "raise", which throws on bad input. The other options are "coerce" (replace with null) or "ignore" (leave untouched). See the pandas to_datetime docs and to_numeric docs for the full parameter list.

Test it against an example of messy input:

messy_df = pd.DataFrame({
    "date_obs_elab": ["2026-01-15", "2026-01-16", "not a date", None],
    "resultat_obs_elab": [5800.0, "5900", "N/A", None],
})

type_safe_df = convert_to_date(messy_df, ["date_obs_elab"])
type_safe_df = convert_to_numeric(type_safe_df, ["resultat_obs_elab"])

# "not a date"  → NaT
# "N/A"         → NaN
# Pipeline continues safely — nothing crashed.

Best practice: don't let one bad row kill an entire run. Coerce bad data to nulls rather than raising exceptions. Flag or log nulls separately if you need to investigate data quality later.

This is a deliberate trade-off. A choice between availability (the pipeline keeps running) over strictness (catching every bad row immediately). That's usually the right call for a scheduled, unattended job.

df.copy(): immutability by convention

Look again at the top of both functions above: df = df.copy(). This single line appears at the start of every transform function in the pipeline, and that's not an accident.

Python DataFrames are mutable objects, passed by reference. If a function modifies df in place without copying first, the caller's original DataFrame changes too. That's a classic side effect and it can produce genuinely confusing bugs. Call .copy() first means each function's output is a brand-new object. The input the caller passed in stays guaranteed untouched.

Best practice: treat DataFrames as immutable inputs. Return a new DataFrame rather than modify it one in place. Even if it costs a small amount of memory or CPU, the debugging win is almost always worth it for a pipeline that isn't operating at extreme scale.

Finally, one auto-detecting convenience function wraps these two low-level functions. It scans text columns, guesses whether they contain dates or numbers, and calls the matching parsing function above.

auto_convert_columns() tries to guess which columns are dates or numbers and then fixes these types automatically.

How it works:

It starts with two empty lists:

• datetime_cols for date columns

• numeric_cols for number columns

It goes through each column in the DataFrame. If a column is already a real datetime or numeric type, it skips it. If the column is text-like (object or string), it looks at up to 10 non-empty sample values.

It first tries to read those values as dates:

• if that works, the column is added to datetime_cols

If not, it tries to read them as numbers:

• if that works, the column is added to numeric_cols

At the end, it converts all date columns with convert_to_date(). Then it converts all numeric columns with convert_to_numeric()

def auto_convert_columns(df: pd.DataFrame) -> pd.DataFrame:
    """Auto-detect and convert datetime and numeric columns to the correct type."""
    datetime_cols = []
    numeric_cols = []

    for col in df.columns:
        if pd.api.types.is_datetime64_any_dtype(df[col]):
            continue
        if pd.api.types.is_numeric_dtype(df[col]):
            continue

        if pd.api.types.is_object_dtype(df[col]) or pd.api.types.is_string_dtype(df[col]):
            sample = df[col].dropna().head(10)
            if len(sample) == 0:
                continue

            try:
                pd.to_datetime(sample, errors='raise', format='mixed')
                datetime_cols.append(col)
                continue
            except (ValueError, TypeError):
                pass

            try:
                pd.to_numeric(sample, errors='raise')
                numeric_cols.append(col)
                continue
            except (ValueError, TypeError):
                pass

    df = convert_to_date(df, datetime_cols)
    df = convert_to_numeric(df, numeric_cols)
    return df

Notice the inner try/except blocks here use errors='raise'. That's the opposite of the coercion strategy above, but it only runs against a small .head(10) sample of each column.

This is a type-sniffing step, not the final conversion. It tests "does this column look like dates, or numbers, or neither?" on a cheap sample. Then, it hands off the actual, forgiving conversion of the whole column to convert_to_date() or convert_to_numeric(). Two different errors strategies, two different jobs.

Schema Translation with Bidirectional mappings

Design logic

The Hub'Eau API returns French column names and French categorical values, like code_station or "Donnée validée". A dataset meant for an international audience should ship in English. If you rename columns inline, wherever it's convenient, the mapping between French and English ends up scattered across the codebase. Then you'd have no way to reverse it if you ever needed to.

The fix: define one authoritative mapping at the top of the module, and derive everything else from it.

Code-level walkthrough

API_TO_EN maps API field names to English translations.

# Primary mapping: French API columns to English column names
API_TO_EN = {
    "code_site": "location_code",
    "code_station": "station_code",
    "date_obs_elab": "record_date",
    "resultat_obs_elab": "water_level_mm",
    "date_prod": "data_production_date",
    "code_statut": "validation_status_code",
    "libelle_statut": "validation_status",
    "code_methode": "production_method_code",
    "libelle_methode": "production_method",
    "code_qualification": "quality_code",
    "libelle_qualification": "quality_assessment",
    "longitude": "longitude",
    "latitude": "latitude",
    "grandeur_hydro_elab": "hubeau_elab_code",
}

# Reverse mapping: English to French (computed automatically)
EN_TO_API = {v: k for k, v in API_TO_EN.items()}

The second line (EN_TO_API) is just a shortcut: it swaps each key and value from API_TO_EN. A dict comprehension builds it. Here's the important design point: EN_TO_API isn't hand-maintained, it's derived. If you add, remove, or rename an entry in API_TO_EN, EN_TO_API updates automatically the next time the module runs.

There's exactly one place in the entire codebase where a schema change needs to happen.

Categorical values (not just column names) get the same treatment:

CATEGORICAL_MAPPINGS = {
    "validation_status": {
        "Donnée validée": "validated",
        "Donnée brute": "raw",
        "Donnée pré-validée": "pre-validated",
    },
    "quality_assessment": {
        "Bonne": "good",
        "Non qualifiée": "unqualified",
        "Douteuse": "dubious",
    },
    "production_method": {
        "Calculée": "calculated",
        "Mesurée": "measured",
        "Expertisée": "expert-reviewed",
    },
}

The functions below apply these mappings, in order, to standardize column names and category values.

rename_to_english():

1. If the DataFrame is empty, it returns a copy right away.

2. It builds a list of columns that are renamed from API names to English names.

   • It only renames a column if:

     • the old name exists, and

     • the new name does not already exist

3. Then it returns the renamed DataFrame.

rename_to_api_schema():

1. Also returns a copy for empty data.

2. Does the reverse: English names back to API names.

3. Returns the DataFrame.

(Useful if you need to send data back in the API’s original format).

apply_categorical_mappings():

1. Makes a copy so the original DataFrame is not changed.

2. For each column in CATEGORICAL_MAPPINGS, it replaces values using the mapping.

   • Example: "Donnée validée" becomes "validated".

   • .fillna(df[col_name]) keeps the original value if a value isn’t found in the mapping.

3. Returns the DataFrame.

def rename_to_english(df: pd.DataFrame) -> pd.DataFrame:
    """Rename API column names to English schema names."""
    if df.empty:
        return df.copy()

    columns_to_rename = {}
    for src, dst in API_TO_EN.items():
        if src in df.columns and dst not in df.columns:
            columns_to_rename[src] = dst

    return df.rename(columns=columns_to_rename)

def rename_to_api_schema(df: pd.DataFrame) -> pd.DataFrame:
    """Rename English column names back to API schema names (defensive/reverse operation)."""
    if df.empty:
        return df.copy()

    columns_to_rename = {k: v for k, v in EN_TO_API.items() if k in df.columns}
    return df.rename(columns=columns_to_rename)

def apply_categorical_mappings(df: pd.DataFrame) -> pd.DataFrame:
    df = df.copy()
    for col_name, mapping in CATEGORICAL_MAPPINGS.items():
        if col_name in df.columns:
            df[col_name] = df[col_name].map(mapping).fillna(df[col_name])
    return df

Two defensive habits are worth a note here:

Robustness to partial inputs: Both rename functions only rename columns that actually exist in the input (if src in df.columns).

A rename function that assumes every mapped column is always present will crash the moment it's called on a partial or differently-shaped DataFrame.

.map(mapping).fillna(df[col_name]). Series.map replaces every value it finds in the mapping dict and turns any value not found in the dict into NaN. Chain .fillna(df[col_name]) right after restores the original value wherever the mapping didn't apply. That way, unexpected categorical values pass through unchanged instead of silently becoming null. It's a subtle but important robustness choice.

See this exact .map()-then-.fillna() idiom discussed on Stack Overflow: pandas map vs apply performance.

A quick round-trip test proves the bidirectional mapping actually works:

sample_api_df = pd.DataFrame({"code_station": ["F700000109"], ...})
renamed_df = rename_to_english(sample_api_df)          # French → English
reversed_df = rename_to_api_schema(renamed_df)          # English → French
# reversed_df.columns.tolist() == sample_api_df.columns.tolist()  → True

Compute Flood Alerts

add_derived_columns() is a one-liner. It just computes flood_alert. If the water level is greater than the flood threshold set in the Config, the result is True. Otherwise, the result is False.

def add_derived_columns(df: pd.DataFrame) -> pd.DataFrame:
    """Add a computed columns based on raw data.
    """
    df = df.copy()

    if "water_level_mm" in df.columns:
        df["flood_alert"] = df["water_level_mm"] > STATION_CONFIG.flood_threshold_mm

    return df

Column Ordering

Here's a small but user-facing detail: define a preferred column order once, as data, and reuse it everywhere. COLUMN_ORDER holds that preferred column sequence.

order_columns() rearranges a DataFrame so those columns come first, while any extra columns stay at the end.

COLUMN_ORDER = [
    # Primary identifiers & measurements
    "station_code", "record_date", "water_level_mm", "flood_alert",
    # Metadata about the observation
    "hubeau_elab_code", "data_production_date",
    "validation_status_code", "validation_status",
    "production_method_code", "production_method",
    "quality_code", "quality_assessment",
    # Geographic info (less important)
    "location_code", "longitude", "latitude",
]

def order_columns(df: pd.DataFrame) -> pd.DataFrame:
    """Reorder columns to preferred order."""
    present_cols = [c for c in COLUMN_ORDER if c in df.columns]
    other_cols = [c for c in df.columns if c not in present_cols]
    return df[present_cols + other_cols]

other_cols acts as a safety net: any column not explicitly listed in COLUMN_ORDER still gets included at the end. They're not silently dropped.

Rules, in order of priority:

• Keep identifiers and key fields up front.

• Put the most important, most frequently used, and most stable columns first.

• Group related fields together, so the table reads naturally.

• Push optional or rarely-used fields to the end.

Deduplication

Design logic

Remove duplicates as you go. In an incremental pipeline, date ranges and records can overlap:

• The same day might get re-fetched, because API data arrives late or gets finalized later.

• The same observation might appear on two different pages of a paginated response.

Without deduplication, these scenarios let duplicate rows pile up in the dataset over time. This is also, recall from Part 1, exactly what makes the pipeline idempotent: run it once or run it five times and the resulting dataset stays identical.

The fix requires defining what makes a record unique. Define a composite key:

key = (station_code, observation_date, water_level_value)

Why this specific combination? Physically, one sensor (station_code) reports one day's (observation_date) daily-maximum reading (water_level_mm), and that reading should be unique.

• Records from different stations obviously aren't duplicates of each other.

• Two readings on different days aren't duplicates.

• A subtler point: if the same station reports the same day but with a different value, that counts as a distinct observation, for example a corrected or revised measurement, not a duplicate to silently discard.

Code-level walkthrough

create_dedup_key() builds a unique text ID for each row by joining three pieces together with an underscore:

• station code

• date, as YYYY-MM-DD

• water level value

Example key:

"F700000109_2024-01-15_5800.0"

def create_dedup_key(df: pd.DataFrame) -> pd.Series:
    """Create unique deduplication key from station, day, and water level value.

    Key format: "station_code_YYYY-MM-DD_value"
    Example: "F700000109_2024-01-15_5800.0"
    """
    parts = []

    if "code_station" in df.columns:
        parts.append(df["code_station"].astype(str))

    if "date_obs_elab" in df.columns:
        parts.append(df["date_obs_elab"].dt.strftime("%Y-%m-%d"))

    if "resultat_obs_elab" in df.columns:
        parts.append(df["resultat_obs_elab"].astype(str))

    if not parts:
        return pd.Series(index=df.index, dtype="object")

    return pd.Series(
        ["_".join(row) for row in zip(*parts)],
        index=df.index
    )

How the key-building works: parts ends up as a list of Series, one per key component (station, date, value), each the same length as the DataFrame.

Read the last line from the inside out:

    return pd.Series(["_".join(row) for row in zip(*parts)], index=df.index)

zip(*parts) transposes that list of columns into row-wise tuples. It yields (station_1, date_1, value_1), then (station_2, date_2, value_2), and so on. The list comprehension then joins each row-tuple with underscores into one string key per row.

This "list of columns → zip → row tuples" idiom is a common and efficient way to combine several Series into one derived Series, without writing .apply(lambda row: ..., axis=1). Row-wise .apply is notoriously slow in pandas compared to vectorized string operations.

The actual deduplication happens in remove_duplicates(). It removes rows from "new" (freshly fetched data) that already exist in "existing" (historic data).

Step by step:

1. If one table is empty, it just returns new.

2. It enforces types in both DataFrames with auto_convert_columns() first, so dates and numbers compare correctly.

3. It creates a deduplication key for each row in both tables with create_dedup_key().

4. It checks which keys from the fetched data don't appear in the existing historic dataset, and keeps only truly new rows.

5. It returns the filtered result, keeping the original columns from new.

def remove_duplicates(existing: pd.DataFrame, new: pd.DataFrame) -> pd.DataFrame:
    """Remove rows from 'new' that already exist in 'existing'."""
    # Short-circuit: if either is empty, no work to do
    if existing.empty or new.empty:
        return new.copy()

    # Parse types on both sides for a fair comparison
    existing_std = auto_convert_columns(existing)
    new_std = auto_convert_columns(new)

    # Build the keys
    existing_keys = set(create_dedup_key(existing_std).dropna())
    new_keys = create_dedup_key(new_std)

    # Boolean mask: True where the new row is genuinely new
    mask = ~new_keys.isin(existing_keys)

    # Index back into the ORIGINAL (non-standardized) 'new' to preserve all columns
    result = new.iloc[new_keys[mask].index].copy()
    return result

Two performance and robustness details are worth to note:

First, existing_keys is a set, not a list. Testing membership (in / .isin()) against a Python set is O(1) on average, because it uses a fast hash lookup to answer is this item already here? directly. Testing against a list is O(n): it has to scan item by item and it gets slower as the existing dataset grows.

For a dataset with tens of thousands of rows, checked on every single pipeline run, that difference matters and that's a textbook example of choosing the right data structure for the job. See the general discussion of list vs. set lookup performance in Python and this guidance on .isin() performance for filtering.

Simple rule: use a set when you care about fast membership checks. Use a list when you care about order or duplicates.

Second, new.iloc[new_keys[mask].index] indexes back into the original, non-validated new DataFrame, not new_std.

Why? auto_convert_columns() only ran to get consistent types for comparison. The caller still wants the original raw values and schema back for everything that survives deduplication.

Don't let a side-computation accidentally become your source of truth. Always modify a copy only to decide what to keep or remove. Once you've made that decision, apply it to the original data. That way you preserve the real source values for later steps.

In short:

1. First modifications are only for comparison.

2. Use that comparison to filter the original data.

3. Return the original rows unchanged, so later stages can process them.

Best practice: keep your deduplication key simple and stable (immutable) and always short-circuit (with if existing.empty or new.empty: return new.copy()) before doing any heavier work. This cheap guard clause skips the expensive deduplication logic when there's no data to process.

Put it All Together in postprocess()

All the pieces above are small and testable on their own. The last step of Transform glues them together, in order, into the single pipeline function below:

def postprocess(df: pd.DataFrame) -> pd.DataFrame:
    """Apply all post-processing transformations."""
    if df.empty:
        return df

    df = df.copy()

    print("  1. Converting types...")
    df = auto_convert_columns(df)

    print("  2. Renaming columns (French → English)...")
    df = rename_to_english(df)

    print("  3. Mapping categorical values...")
    df = apply_categorical_mappings(df)

    print("  4. Adding derived columns...")
    df = add_derived_columns(df)

    print("  5. Reordering columns...")
    df = order_columns(df)

    print("  6. Sorting and resetting index...")
    df = df.sort_values(["record_date", "station_code"]).reset_index(drop=True)

    return df

Notice the shape of this function: it's basically a linear script with six numbered, printed steps. Each one calls a previously-defined pure function. There's no new logic here, only sequencing. That's intentional.

Best practice: log progress clearly at each stage. When a scheduled job fails at 3am, a clear step-by-step log is the difference between a two-minute diagnosis and an hour of guessing. A good option is to use a logger. Here, this tutorial sticks with classic console printing (print(f" 1. Converting types...")).

Part 6: The Load Step

Design Logic

Load is the final stage: take the processed data and move it to its destination. Typical destinations include data warehouses, data lakes, and databases.

Before publishing, the pipeline prepares two things: the output folder itself, and a metadata file that describes the dataset.

Code-level walkthrough

create_output_dir() makes sure an output folder exists, and creates one if it doesn't:

• If use_mock is True, it uses KAGGLE_CONFIG.mock_output_dir, the directory for fake data.

• Otherwise, it uses the real output directory set in KAGGLE_CONFIG.output_dir.

def create_output_dir(use_mock: bool = False) -> None:
    """Create output directory (and parents) if it does not already exist."""
    output_dir = KAGGLE_CONFIG.mock_output_dir if use_mock else KAGGLE_CONFIG.output_dir
    output_dir.mkdir(parents=True, exist_ok=True)
    # exist_ok=True: idempotent, safe to call multiple times

exist_ok=True is a small but important detail. Without it, Path.mkdir() raises FileExistsError if the directory already exists, which it will on every run after the first.

Setting exist_ok=True makes directory creation idempotent: calling it 100 times has the same effect as calling it once. On the filesystem, this is the "safe to re-run" idea behind the deduplication logic from Part 5.

The Kaggle API follows the Data Package specification. It requires a descriptive dataset-metadata.json file alongside the CSV. This matters for the search and discoverability of the Paris flood dataset:

def create_metadata(df: pd.DataFrame, config: KaggleConfig) -> Dict:
    """Generate Kaggle dataset metadata from DataFrame and config."""
    if df.empty or "record_date" not in df.columns:
        first_date = "unknown"
        last_date = "unknown"
    else:
        first_date = df["record_date"].min().strftime("%Y-%m-%d")
        last_date = df["record_date"].max().strftime("%Y-%m-%d")

    return {
        "title": config.title,
        "id": config.dataset_slug,
        "licenses": [{"name": config.license_name}],
        "keywords": config.keywords,
        "temporalCoverage": {"startDate": first_date, "endDate": last_date},
        "geospatialCoverage": config.geospatial_coverage,
        "updateFrequency": config.update_frequency,
    }

Metadata comes from the KaggleConfig dataclass. Note that temporalCoverage is computed from the data itself (df["record_date"].min()/.max()) rather than hardcoded. Every time the pipeline runs, the metadata's date range automatically reflects reality, with zero manual bookkeeping.

Finally, publish_to_kaggle() uploads the updated dataset to Kaggle. It calls out to the Kaggle CLI as an external command.

What it does:

1. Gets the current time and turns it into a text label like Weekly update: 2026-07-13 14:30:00

2. Builds a Kaggle command that says:

   • publish a new dataset version

   • use files from KAGGLE_CONFIG.output_dir

   • attach the message

   • zip the directory contents

3. Prints the command so you can see what will run

4. Runs the command with subprocess.run(...)

If the upload works:

• it prints Successfully published to Kaggle.

If it fails:

• it prints the error and then raises the error again so the failure isn't hidden.

def publish_to_kaggle() -> None:
    """Publish the updated dataset to Kaggle using the Kaggle CLI."""
    timestamp = pd.Timestamp.now().strftime("%Y-%m-%d %H:%M:%S")
    message = f"Weekly update: {timestamp}"

    cmd = [
        "kaggle", "datasets", "version",
        "-p", str(KAGGLE_CONFIG.output_dir),
        "-m", message,
        "--dir-mode", "zip",
    ]

    print("Publishing to Kaggle...")
    print("Command:", " ".join(cmd))

    try:
        subprocess.run(cmd, check=True)
        print("Successfully published to Kaggle.")
    except subprocess.CalledProcessError as e:
        print(f"Error publishing to Kaggle: {e}")
        raise

publish_to_kaggle calls the Kaggle CLI (Command Line Interface) through Python's subprocess module. This is the standard way to run an external command-line tool from a Python pipeline.

Two choices here are worth adopting as general habits, not just for Kaggle:

• cmd is built as a list, never as a concatenated string. Pass a list of arguments to subprocess.run skips invoking a shell entirely. That sidesteps shell-injection risks and correctly handles arguments containing spaces or special characters. See the official subprocess security considerations.

• check=True means that if the Kaggle CLI fails, by exiting with a non-zero status, subprocess.run raises CalledProcessError instead of silently returning. Without check=True, a failed publish would look exactly like a successful one to the rest of the code.

Part 7: Assemble the Full Pipeline

The Global Rehearsal (Mock Mode)

The whole pipeline is built and tested in isolation. It's time to wire the blocks into one linear function. First, run it entirely against mock data. Nothing gets published this way. For Demonstration purposes, a CSV filled with artificial data will land in a local mock_output folder.

def run_etl_pipeline(use_mock: bool = True) -> pd.DataFrame:
    """Run the complete ETL pipeline: Extract → Transform → Load to CSV."""

    # STEP 1: LOAD EXISTING DATA
    if use_mock:
        loaded_df = pd.DataFrame(mock_api_response)
        loaded_df['date_obs_elab'] = pd.to_datetime(loaded_df['date_obs_elab'])
        loaded_df = rename_to_english(loaded_df)
    else:
        loaded_df = load_csv(KAGGLE_CONFIG.input_csv)

    # STEP 2: DETERMINE UPDATE RANGE
    should_update, start_date = determine_update_range(loaded_df)
    if not should_update:
        return loaded_df   # already current: nothing more to do

    # STEP 3: EXTRACT (FETCH DATA)
    fetched_data = fetch_all_data(start_date, use_mock=use_mock)

    # STEP 4: TRANSFORM I - DEDUPLICATE
    deduped_fetched_data = remove_duplicates(loaded_df, fetched_data)

    # STEP 5: TRANSFORM II - COMBINE (MERGE WITH EXISTING)
    new_df_english = rename_to_english(deduped_fetched_data)
    merged_historical_and_new = pd.concat([loaded_df, new_df_english], ignore_index=True)

    # STEP 6: TRANSFORM III - POST-PROCESS
    processed_records = postprocess(merged_historical_and_new)

    # STEP 7: EXPORT (LOAD TO CSV)
    create_output_dir(use_mock=use_mock)
    output_path = KAGGLE_CONFIG.mock_output_filename if use_mock else KAGGLE_CONFIG.output_csv_path
    processed_records.to_csv(output_path, index=False, sep=",")

    return processed_records

Every one of the seven steps above corresponds to a function you already built, and tested earlier in this tutorial. To Assemble them is almost mechanical. That's always the payoff of composing small, single-responsibility functions:

loaded_df                 = load_csv(...)                          # 1. load existing data
should_update, start_date = determine_update_range(...)            # 2. check what's needed
fetched_data               = fetch_all_data(start_date)             # 3. fetch new records
deduped_fetched_data       = remove_duplicates(existing, new_raw)   # 4. deduplicate
merged_historical_and_new  = pd.concat([existing, new_clean])       # 5. merge
processed_records          = postprocess(merged_historical_and_new) # 6. postprocess
processed_records.to_csv(...)                                       # 7. save
write_metadata() + publish_to_kaggle()                               # 8. publish

Each line's intent is obvious just from reading it left to right. That is exactly the point of good decomposition.

main(): Pipeline Orchestration

main() is the conductor. It wires every previously-built component together in the right order, just like postprocess() did one level down.

def main() -> None:
    """Execute the full Paris Flood Monitoring ETL pipeline.

    EXTRACT
    1. Load the existing dataset from the Kaggle input mount
    2. Determine whether an update is needed (and from what date)
    3. Fetch new data from the Hub'Eau API

    TRANSFORM
    4. Deduplicate against the existing dataset
    5. Combine and post-process (type parsing, translation, derived cols...)

    LOAD
    6. Write the updated CSV and metadata file
    7. Publish the new dataset version to Kaggle

    Exits early if the dataset is already up to date.
    """
    final_dataset = run_etl_pipeline(use_mock=False)
    final_dataset.to_csv(KAGGLE_CONFIG.output_csv_path, index=False)
    write_metadata(final_dataset)

    print("\n[FINAL STEP] Publishing to Kaggle...")
    publish_to_kaggle()

    print("Running post-run validation")
    validate_and_analyze(final_dataset)


if __name__ == "__main__":
    main()

The if __name__ == "__main__": Guard

if __name__ == "__main__":
    main()

This is one of the most common idioms in Python, and it's worth understanding exactly what it does. Per the official Python documentation on __main__:

• Run the file directly (python script.py)

  • → the special variable __name__ is set to "__main__"

  • → the condition is True

  • → main() executes.

• Import the file as a module elsewhere (import script)

  • → __name__ is set to the module's name instead

  • → the condition is False

  • → main() does not run automatically.

Best practice: always guard your entry point this way. It makes the module safely importable for testing individual functions, or for reuse in another script, without triggering the full pipeline (including a real publish to Kaggle!) just by importing it.

Part 8: Go Live and Switch to the Real API

Everything above runs safely against mock data. To point the pipeline at the real Hub'Eau API instead:

1. Note the use_mock=False setting above. It threads through APIConfig.use_mock, and the calls to run_etl_pipeline(use_mock=False) and main().

2. Make sure KAGGLE_CONFIG.dataset_slug and input_csv point at your own Kaggle dataset copy before you use it. You can only publish new versions of a dataset you own. Fork both the notebook and the dataset, then update the slug in the KaggleConfig section.

3. Install and authenticate the Kaggle CLI if you plan to call publish_to_kaggle() outside of a Google Colab or Kaggle notebook.

Everything else needs zero changes.

Post-Run Validation

validate_and_analyze() closes the loop, and it's more than just a nice-to-have. It's a welcome sanity check that runs after the pipeline finishes. The output is a human-readable report covering shape, data types, null counts, summary statistics on water_level_mm, how many flood-alert records turned up, the temporal coverage and per-station record counts.

It doesn't change any data. It exists so that whoever, or whatever monitoring system, reads the run's log output can immediately see whether this week's numbers look sane. No need to analyze the CSV by hand. Try it!

Summary

You've just built a complete ETL pipeline that you can run again and again without breaking anything. The skeleton is here, and that same pattern repeats for almost any scheduled data job: swap out the API, the field mapping, and the destination.

For more tutorials like this one, check out my GitHub or Kaggle profile.

Thanks for reading!

References

• Hub'Eau API: France's official open water-data platform

• The updater .py script runs live once a week and updates the original dataset.

• The source dataset generator is available on GitHub.

• The complete Jupyter notebook to follow this tutorial and code all along (backup available).

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.

Table of Contents

• 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.

<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/4.4.168/pdf.min.js"></script>

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

<script src="script.js"></script>

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:

<div id="uploadSection"></div>

<div id="editorSection" hidden>

    <div id="pdfPreview"></div>

    <aside id="blurSettings"></aside>

</div>

<div id="resultSection" hidden></div>

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.

Creating Page Navigation

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.

<canvas
    id="overlayCanvas">
</canvas>

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.

<input

type="text"

id="outputFilename"

value="blurred-document.pdf">

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.

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.

Table of Contents

• 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}` +
    `&current=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.

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.

1. The Draw option provides a canvas where the user can write a signature using a mouse, trackpad, stylus, or touch input.

2. 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.

3. 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:

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

    <meta charset="UTF-8">

    <meta
        name="viewport"
        content="width=device-width, initial-scale=1.0">

    <title>PDF Signature Tool</title>

    <link
        rel="stylesheet"
        href="style.css">

</head>

<body>

    <main class="pdf-signature-tool">

        <section id="uploadSection">

            <h1>PDF Signature Tool</h1>

            <p>
                Upload your PDF to add your
                electronic signature.
            </p>

            <div id="dropZone">

                <p>Drag & Drop PDF Here</p>

                <p>Or click to browse file</p>

                <button id="selectPdfButton">
                    Select PDF
                </button>

                <input
                    type="file"
                    id="pdfInput"
                    accept="application/pdf"
                    hidden>

            </div>

        </section>

        <section
            id="editorSection"
            hidden>

            <div class="pdf-preview">

                <div id="previewContainer">

                    <canvas id="pdfCanvas"></canvas>

                    <div id="elementLayer"></div>

                </div>

                <div class="page-navigation">

                    <button id="previousPage">
                        &lt;
                    </button>

                    <span id="pageInfo">
                        Page 1 of 1
                    </span>

                    <button id="nextPage">
                        &gt;
                    </button>

                </div>

            </div>

            <aside id="editorControls">

                <!-- Signature and text controls
                     will be added here -->

            </aside>

        </section>

        <section
            id="resultSection"
            hidden>

            <!-- Final preview and download
                 controls will be added here -->

        </section>

    </main>

    <script src="script.js"></script>

</body>
</html>

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.

<script
    src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js">
</script>

<script
    src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js">
</script>

<script src="script.js"></script>

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.

Adding PDF Page Navigation

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:

<div class="element-selector">

    <h3>1. Choose Element</h3>

    <label>
        <input
            type="radio"
            name="elementType"
            value="signature"
            checked>
        Signature
    </label>

    <label>
        <input
            type="radio"
            name="elementType"
            value="text">
        Text/Stamp
    </label>

</div>

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:

<div id="signatureControls">

    <h3>2. Create Signature</h3>

    <div class="signature-tabs">

        <button
            data-method="draw"
            class="active">
            Draw
        </button>

        <button
            data-method="type">
            Type
        </button>

        <button
            data-method="upload">
            Upload
        </button>

    </div>

    <div id="drawPanel"></div>

    <div
        id="typePanel"
        hidden>
    </div>

    <div
        id="uploadPanel"
        hidden>
    </div>

</div>

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:

<div id="drawPanel">

    <canvas
        id="signatureCanvas"
        width="500"
        height="180">
    </canvas>

    <button id="clearSignature">
        Clear
    </button>

</div>

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:

<div id="typePanel" hidden>

    <input
        type="text"
        id="typedSignature"
        placeholder="Type your name">

    <label for="signatureFontSize">
        Font Size
    </label>

    <input
        type="number"
        id="signatureFontSize"
        value="45"
        min="12"
        max="120">

    <div id="signatureStyles">
    </div>

</div>

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:

<div id="uploadPanel" hidden>

    <input
        type="file"
        id="signatureUpload"
        accept="image/png,image/jpeg">

    <p id="selectedSignatureFile">
        No file chosen
    </p>

</div>

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:

<div id="textControls" hidden>

    <h3>2. Add Text or Stamp</h3>

    <input
        type="text"
        id="customText"
        placeholder="Enter text">

    <div class="stamp-options">

        <button data-stamp="APPROVED">
            APPROVED
        </button>

        <button data-stamp="CONFIDENTIAL">
            CONFIDENTIAL
        </button>

        <button data-stamp="DRAFT">
            DRAFT
        </button>

        <button data-stamp="PAID">
            PAID
        </button>

    </div>

    <label>
        Size

        <input
            type="number"
            id="textSize"
            value="16"
            min="8"
            max="120">
    </label>

    <label>
        Color

        <input
            type="color"
            id="textColor"
            value="#000000">
    </label>

</div>

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:

<div id="placementControls">

    <h3>3. Placement & Style</h3>

    <label>
        Rotation (°)

        <input
            type="number"
            id="rotationInput"
            value="0">
    </label>

    <label>
        Opacity

        <input
            type="range"
            id="opacityInput"
            min="0"
            max="100"
            value="100">
    </label>

    <label>
        X Position

        <input
            type="number"
            id="xPosition"
            value="100">
    </label>

    <label>
        Y Position

        <input
            type="number"
            id="yPosition"
            value="100">
    </label>

</div>

For signature elements, add a scale control:

<label>
    Scale (<span id="scaleValue">100%</span>)

    <input
        type="range"
        id="scaleInput"
        min="25"
        max="250"
        value="100">
</label>

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:

<div id="pageApplication">

    <h3>4. Apply to Pages</h3>

    <label>
        <input
            type="radio"
            name="applyMode"
            value="current"
            checked>
        Current page only
    </label>

    <label>
        <input
            type="radio"
            name="applyMode"
            value="all">
        All pages
    </label>

    <label>
        <input
            type="radio"
            name="applyMode"
            value="specific">
        Specific pages
    </label>

    <input
        type="text"
        id="specificPages"
        placeholder="e.g., 1, 3-5, 10">

</div>

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:

[
    1,
    3,
    4,
    5,
    10
]

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:

<div class="editor-actions">

    <button id="applyButton">
        Apply & Finalize
    </button>

    <button id="startOverButton">
        Start Over
    </button>

</div>

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:

<input
    type="text"
    id="outputFilename"
    value="document_signed.pdf">

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.

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.

Table of Contents

• 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:

1. Pull the raw text out of the PDF

2. Break it into chunks of 400 to 600 characters each, with a bit of overlap so nothing important gets cut at a boundary

3. Run each chunk through an embedding model, which turns it into a vector (a long list of numbers that captures what the text means)

4. Store each chunk and its vector in Postgres

Query phase — runs every time someone asks a question:

1. Embed the user's question using the same model

2. Search the database for chunks whose vectors are closest to the question vector

3. Take the top 5 matching chunks and assemble them into a context block

4. 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

1. Go to aistudio.google.com/app/apikey and sign in with a Google account

2. Click "Create API key"

3. Select "Create API key in new project"

4. Copy the key — it starts with AIzaSy...

No credit card or billing required.

How to Get Your Free Groq API Key

1. Go to console.groq.com and sign up with Google

2. Click "API Keys" in the left sidebar

3. 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

or

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.

Maybe it's a different Node version, maybe an environment variable is missing, or maybe a system dependency doesn't match. You spend an hour debugging something that was never actually a code problem.

Docker fixes this at the root. With Docker, you stop shipping just code. The Node version, dependencies, and config all travel inside the container. Your laptop, a CI server, a production VM — it behaves the same on all of them. No more environment surprises.

In this tutorial, we'll go through all this step by step: a multi-stage Dockerfile, using Docker Compose with PostgreSQL for local development, and a GitHub Actions workflow that pushes a fresh image to Docker Hub on every merge to main.

The complete code for this tutorial is available on GitHub.

Table of Contents

1. Prerequisites

2. The Sample Application

3. Writing the Dockerfile

4. The .dockerignore File

5. The .gitignore File

6. Build and Test the Image Locally

7. Docker Compose for Local Development

8. Automate the Build with GitHub Actions

9. Deploying the Image

10. Wrapping Up

Prerequisites

• Node.js 18+

• Docker Desktop, which you can download at docs.docker.com/get-docker. Windows users need WSL 2 before Docker starts. Open PowerShell as Administrator and run wsl --install. After the restart, Docker Desktop will install without issues.

• A GitHub account

• A Docker Hub account (free at hub.docker.com)

• Some Express.js experience helps, but isn't required

The Sample Application

We're building a task management API with Express and PostgreSQL. Keep in mind the app is just a vehicle to teach you how this works. The Dockerfile and pipeline we set up here work the same way for any Node.js project.

Create the project:

mkdir nodejs-docker-cicd && cd nodejs-docker-cicd
npm init -y
npm install express pg dotenv
npm install --save-dev nodemon

Create src/index.js:

const express = require('express');
const { Pool } = require('pg');
require('dotenv').config();

const app = express();
app.use(express.json());

const pool = new Pool({
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
});

// Create table on startup
pool.query(`
  CREATE TABLE IF NOT EXISTS tasks (
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    completed BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT NOW()
  )
`).catch(console.error);

// Health check — required for Docker HEALTHCHECK and load balancers
app.get('/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

app.get('/tasks', async (req, res) => {
  try {
    const result = await pool.query('SELECT * FROM tasks ORDER BY created_at DESC');
    res.json(result.rows);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.post('/tasks', async (req, res) => {
  const { title } = req.body;
  if (!title) return res.status(400).json({ error: 'Title is required' });
  try {
    const result = await pool.query(
      'INSERT INTO tasks (title) VALUES ($1) RETURNING *',
      [title]
    );
    res.status(201).json(result.rows[0]);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.patch('/tasks/:id', async (req, res) => {
  const { id } = req.params;
  const { completed } = req.body;
  try {
    const result = await pool.query(
      'UPDATE tasks SET completed = $1 WHERE id = $2 RETURNING *',
      [completed, id]
    );
    if (result.rows.length === 0) return res.status(404).json({ error: 'Task not found' });
    res.json(result.rows[0]);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

Open package.json and update the "scripts" section:

"scripts": {
  "start": "node src/index.js",
  "dev": "nodemon src/index.js"
}

npm start runs the app directly with Node. npm run dev uses nodemon so the server restarts automatically when you edit a file.

For running without Docker, create a .env file:

DB_HOST=localhost
DB_PORT=5432
DB_NAME=tasksdb
DB_USER=postgres
DB_PASSWORD=yourpassword
PORT=3000

Notice that all database credentials come from environment variables rather than being hardcoded. Swap the variables, and the same image runs against your local database or a production one — no code changes needed. The /health endpoint is what Docker pings to know the app is actually handling requests.

Writing the Dockerfile

Before touching the Dockerfile, there are two terms you'll keep seeing. An image is a packaged, immutable version of your app — Node runtime, code, dependencies, everything together in one artifact. A container is a running instance of that image. One image, many containers, any machine.

Here's the Dockerfile we'll use:

# ── Stage 1: Install dependencies ──────────────────────────────────────────
FROM node:18-alpine AS builder

WORKDIR /app

# Copy package files first — Docker caches this layer separately.
# If you only change src code (not package.json), Docker skips npm ci on rebuild.
COPY package*.json ./
RUN npm ci

COPY . .


# ── Stage 2: Production image ───────────────────────────────────────────────
FROM node:18-alpine AS production

# Create a non-root user — running as root inside a container is a security risk
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodeuser -u 1001

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

# Copy only the source code from the builder stage (not node_modules or dev files)
COPY --from=builder /app/src ./src

RUN chown -R nodeuser:nodejs /app
USER nodeuser

EXPOSE 3000

# Docker will ping /health every 30s. If it fails 3 times, the container is marked unhealthy.
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["node", "src/index.js"]

This is a multi-stage build. The first stage (builder) installs everything, including dev dependencies. The second stage (production) starts fresh and only copies what the app needs to run. Nodemon, test frameworks, and anything else dev-only never make it into the final image.

The size difference is real. A node:18 Debian image is over 950MB. Switch to node:18-alpine and cut out the dev dependencies, and the final image lands around 150–200MB instead. A smaller image means faster pushes and faster deploys.

npm ci instead of npm install is a deliberate choice for CI/CD. It reads exact versions from package-lock.json and fails hard if the lockfile doesn't match package.json. Every build on every machine installs the exact same versions — no surprises from a dependency that quietly updated overnight.

The nodeuser account exists because containers run as root by default. That's fine until something goes wrong. A non-root user means that an attacker who gets inside the container can't just do whatever they want.

The .dockerignore File

Create .dockerignore before building:

node_modules
npm-debug.log
.env
.git
.gitignore
README.md
Dockerfile
.dockerignore

The node_modules exclusion is the critical one. Your local modules were compiled for your operating system — macOS or Windows binaries won't work inside a Linux container. Excluding them means Docker installs fresh modules during the build, compiled for the correct platform. Without this exclusion, you'd either copy broken binaries into the image or waste time uploading hundreds of megabytes to the build context.

Never put .env in an image. Passwords, API keys, anything sensitive — those go in at runtime as environment variables, never inside the image itself.

The .gitignore File

One more thing before the first commit: a .gitignore. You don't want node_modules or .env tracked:

node_modules/
.env
.env.local
npm-debug.log*
logs/
.DS_Store
Thumbs.db
.vscode/
.idea/
dist/
build/

Build and Test the Image Locally

Open Docker Desktop first and give it a moment. On Windows, you'll see a whale icon in the taskbar that animates while the engine is starting up. Once it goes still, you're good to run Docker commands. If you try to run Docker before the engine is up, you'll hit this:

ERROR: Error response from daemon: Docker Desktop is unable to start

If that happens, quit Docker Desktop. Open PowerShell as Administrator, run wsl --update, and restart. Then go to Control Panel → Programs → Turn Windows features on or off. Both Hyper-V and Virtual Machine Platform need to be checked. After the restart, Docker Desktop should come up fine.

It's worth knowing about this error too:

docker : The term 'docker' is not recognized as the name of a cmdlet, function,
script file, or operable program.

This means that Docker Desktop isn't running or isn't installed. Open it from the Start menu and wait.

Run the build:

docker build -t nodejs-docker-cicd:latest .

The first time takes roughly 30 seconds since Docker has to pull node:18-alpine from the internet. Once that's cached, subsequent builds are much quicker. Both stages will scroll by:

[+] Building 33.1s (17/17) FINISHED
 => [builder 1/5] FROM docker.io/library/node:18-alpine       20.9s
 => [builder 4/5] RUN npm ci                                   3.5s
 => [production 5/7] RUN npm ci --only=production              3.2s
 => [production 7/7] RUN chown -R nodeuser:nodejs /app         3.2s
 => exporting to image                                         1.5s
 => => naming to docker.io/library/nodejs-docker-cicd:latest     0.0s

When you see (17/17) FINISHED the image is built. Check the size:

docker images nodejs-docker-cicd

IMAGE                     ID             DISK USAGE   CONTENT SIZE
nodejs-docker-cicd:latest   c9eed311d999        198MB         47.5MB

CONTENT SIZE (47.5MB) is the compressed size that gets pushed to Docker Hub. DISK USAGE (198MB) is what it takes up on disk locally. Compare that to a node:18 Debian image at 950MB+, and you can see why the Alpine base and multi-stage approach matter.

On subsequent builds, Docker reuses cached layers. Edit only your source files without touching package.json and the npm ci step gets skipped completely. That 33-second first build becomes 3 seconds.

Docker Compose for Local Development

The app needs a database. Setting up PostgreSQL locally means every developer who clones the repo has to do it, too. Docker Compose handles this: one file defines both services, and one command starts them.

Create docker-compose.yml:

services:
  app:
    build:
      context: .
      target: production
    ports:
      - '3000:3000'
    environment:
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: tasksdb
      DB_USER: postgres
      DB_PASSWORD: postgres
      PORT: 3000
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: tasksdb
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - '5432:5432'
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

A few things worth pointing out. DB_HOST is set to postgres. That's the service name, not localhost. Containers on the same Docker network reach each other by service name. Put localhost there and the app tries to connect to itself.

depends_on with condition: service_healthy holds the app back until Postgres actually passes its health check. Skip this and the app starts, tries to connect to a database that isn't ready yet, and crashes. The health check pings pg_isready every 5 seconds. Once it gets a green response, the app container starts.

The named volume postgres_data keeps your data alive between restarts. Run docker compose down and the data is still there next time. Add --volumes to wipe it clean.

Start both services:

docker compose up --build

You'll see PostgreSQL initialize and then the app start. Once you see Server running on port 3000 in the logs, the stack is up.

Open a second terminal to test — leave the compose logs running in the first one.

Linux/macOS:

curl -X POST http://localhost:3000/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Learn Docker"}'

curl http://localhost:3000/tasks

curl http://localhost:3000/health

Windows PowerShell: Typing curl in PowerShell runs Invoke-WebRequest, not actual curl. Run curl.exe instead. For JSON bodies, write to a file first:

'{"title": "Learn Docker"}' | Set-Content body.json
curl.exe -X POST http://localhost:3000/tasks -H "Content-Type: application/json" --data `@body.json

curl.exe http://localhost:3000/tasks

curl.exe http://localhost:3000/health

The backtick before @body.json is necessary. PowerShell would otherwise try to interpret @ as a splatting operator rather than passing it to curl as a filename prefix.

You should see responses like these:

# POST /tasks
{"id":1,"title":"Learn Docker","completed":false,"created_at":"2026-07-09T22:21:17.073Z"}

# GET /tasks
[{"id":1,"title":"Learn Docker","completed":false,"created_at":"2026-07-09T22:21:17.073Z"}]

# GET /health
{"status":"ok","timestamp":"2026-07-09T22:11:44.700Z"}

The task hit PostgreSQL in one container and came back through the app. Ctrl+C in the compose terminal stops both.

Automate the Build with GitHub Actions

The image works locally, so it's time to stop doing this by hand.

Step 1: Create a Docker Hub Access Token

Go to hub.docker.com and then Account Settings → Security → New Access Token. Set permission to Read & Write, as read-only breaks the push. The token appears once, so copy it before closing the page.

Security warning: Don't paste this token into a chat, email, or commit. If you expose it by accident, delete it immediately, then make a new one.

Step 2: Add Secrets to Your GitHub Repository

Head to Settings → Secrets and variables → Actions in your repo and add:

• DOCKERHUB_USERNAME — your Docker Hub username

• DOCKERHUB_TOKEN — paste the token here, nowhere else

If you ran into Error: Username and password required, the secrets either aren't saved yet or the names are typed wrong. Both are case-sensitive.

A Node 20 deprecation warning in the logs is normal. It comes from the Docker actions internally, not your code.

Step 3: Create the Workflow File

Create .github/workflows/docker-publish.yml:

name: Build and Push Docker Image

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  IMAGE_NAME: ${{ secrets.DOCKERHUB_USERNAME }}/nodejs-docker-cicd

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Docker Hub
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE_NAME }}
          tags: |
            type=sha,prefix=sha-
            type=raw,value=latest,enable={{is_default_branch}}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          target: production
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

The login step has if: github.event_name != 'pull_request'. This skips authentication on pull requests. PRs from forks don't have access to your secrets, so trying to log in would just fail. The build still runs on PRs to validate your Dockerfile, but the image isn't pushed.

The metadata action generates two tags on every merge to main: latest and a short commit SHA like sha-a1b2c3d. The SHA tag is what makes rollbacks practical. If latest breaks in production, you can pull any previous sha- tag and you're back to a known-good state in seconds.

The cache-from/cache-to: type=gha lines store Docker's layer cache in GitHub Actions' built-in cache. The first run builds everything from scratch. After that, unchanged layers are pulled from cache rather than rebuilt. On a typical Node.js app this brings build time from 2–3 minutes down to under 30 seconds.

Push and Watch it Run

git add .
git commit -m "Add Docker configuration and GitHub Actions workflow"
git push origin main

Go to your repo's Actions tab. You'll see the workflow running in real time. Each step turns green as it completes:

✅ Checkout code
✅ Set up Docker Buildx
✅ Log in to Docker Hub
✅ Extract metadata
✅ Build and push

Green across the board means your image is live on Docker Hub — two tags, latest and a commit SHA like sha-a1b2c3d. Every push to main from here builds and ships automatically.

Deploying the Image

With your image on Docker Hub, you can deploy it to any infrastructure:

Any VPS or server:

docker pull yourusername/nodejs-docker-cicd:latest
docker run -d -p 3000:3000 \
  -e DB_HOST=your-db-host \
  -e DB_NAME=tasksdb \
  -e DB_USER=postgres \
  -e DB_PASSWORD=yourpassword \
  yourusername/nodejs-docker-cicd:latest

Railway — Connect your Docker Hub image in the Railway dashboard and it deploys on the next push.

Fly.io — Run fly launch pointing at your Dockerfile and Fly handles the rest.

Render — Paste your Docker Hub image URL into the Render service settings.

Each push to main runs the workflow. New image goes to Docker Hub, platform picks it up — that's your deployment handled.

Wrapping Up

What started as a local Node.js app now runs in a container. You get the same behavior on any machine, real PostgreSQL in development, and a pipeline that builds and ships to Docker Hub without you doing anything after the push.

The multi-stage build keeps the image lean — dev tools stay out, non-root user, health check baked in. Compose gets the full stack up with one command for anyone who clones the repo. The SHA tag on every GitHub Actions build means rolling back is just a matter of pulling an older tag.

These same patterns (multi-stage builds, Compose for local development, automated image publishing) are used across the industry for production Node.js deployments. Pick up these patterns once and they follow you to every project.

From here, you can extend the pipeline: drop a test step in before the build, or add multi-platform support if you're targeting ARM. Once Docker Compose starts feeling limiting in production, that's usually when Kubernetes enters the picture.

In this tutorial, you’ll build a healthcare AI assistant that runs entirely on your own machine using three open-source tools:

• MedGemma, Google’s open medical AI model for understanding medical text and images

• Ollama, the easiest way to download and run AI models locally

• Open WebUI, a ChatGPT-style web interface for interacting with local models

By the end, you’ll be able to chat with a medically tuned AI model, upload medical images such as chest X-rays for analysis, and do it all locally, without sending your data to the cloud.

Important disclaimer before we start: MedGemma is a developer model, not a medical device. Its outputs are not intended to directly inform clinical diagnosis, patient management, or treatment decisions.

Everything you build in this tutorial is for learning, prototyping, and research. Always consult qualified healthcare professionals for real medical questions.

What We'll Cover:

• Who is This Tutorial For?

• What is MedGemma?

• Why Run Models Locally?

• Prerequisites

• Architecture Diagram

• Step 1: Install Ollama

• Step 2: Pull MedGemma

• Step 3: Test MedGemma from the Terminal

• Step 4: Install Open WebUI

  • Option A: Docker (recommended)

  • Option B: pip (no Docker)

• Step 5: Connect Open WebUI to Ollama

• Step 6: Start Chatting with MedGemma

• Step 7: Upload Medical Images

• Example Prompts to Try

• Running Larger Models

• Troubleshooting Guide

  • Error: registry.ollama.ai/library/medgemma:latest does not support tools

  • Open WebUI shows no models in the dropdown

  • ollama pull medgemma says model not found

  • Responses are extremely slow

  • Image upload doesn't work or the model ignores the image

  • Port 3000 is already in use

  • "Out of memory" errors when loading the 27B model

• Conclusion

Who is This Tutorial For?

This tutorial is ideal if you’re:

• learning healthcare AI

• building medical RAG systems

• experimenting with radiology assistants

• developing medical education tools

• researching multimodal models

What is MedGemma?

MedGemma is a collection of open models from Google, built on the Gemma 3 architecture and specifically trained for medical text and image comprehension. Think of it as Gemma after four years of medical school and a radiology residency.

Why MedGemma?

Unlike general-purpose models such as Llama or Mistral, MedGemma is designed specifically for healthcare applications.

• Medical image understanding: Its multimodal models are trained on de-identified medical images, including chest X-rays, dermatology, ophthalmology, and pathology images.

• Medical language expertise: It has been trained on medical literature and clinical question-answer datasets, enabling it to better understand medical terminology and radiology reports.

• Multiple model sizes: MedGemma is available in 4B and 27B variants, both supporting text and image inputs with a 128K context window.

• Open weights: You can download, run, fine-tune, and build applications with the model locally under the Health AI Developer Foundation's terms of use.

MedGemma is intended as a foundation model for developers building healthcare applications, medical education tools, research assistants, report summarizers, and other AI-powered medical workflows.

Why Run Models Locally?

You could call a hosted medical model through an API. So why go local? In healthcare, the case is stronger than almost anywhere else.

First, there's the principle of privacy by architecture. When the model runs on your machine, medical text and images never leave your device. There's no API log, no third-party data processor, no data processing agreement to negotiate.

For anyone working near PHI (Protected Health Information), "the data never left the laptop" is the simplest compliance story that exists.

Next, you have zero per-token cost. Experimentation is free once the model is downloaded. You can iterate on prompts hundreds of times without watching a billing dashboard.

You also get offline access. Hospitals, labs, and field clinics often have restricted or air-gapped networks. A local model works without internet after the initial download.

And you have full control over the setup: you choose the model version, you pin it, and it never changes underneath you. No deprecation notices, no silent behavior changes.

Finally, it's a great way to learn. Running models locally demystifies them. You'll develop intuition for context windows, quantization, and memory constraints that you simply don't get from calling an API.

Prerequisites

Here's what you need before starting:

Hardware:

• 8 GB RAM minimum (16 GB recommended) for the MedGemma 4B model. The download is about 3.3 GB.

• 32 GB RAM or a 24 GB+ GPU if you want to run the 27B model (a roughly 17 GB download).

• Around 15 GB of free disk space to be comfortable (model + Docker images + working room).

• Apple Silicon Macs (M1 through M4) are excellent for this. Ollama uses Metal acceleration automatically. On Windows and Linux, an NVIDIA GPU helps a lot but isn't required. A CPU-only inference works, just slower.

Software:

• macOS, Linux, or Windows 10/11

• Docker Desktop (for the recommended Open WebUI installation), or Python 3.11 if you prefer installing Open WebUI with pip

• Basic comfort with the terminal

That's it. No API keys, no accounts, and no GPU cloud credits.

Architecture Diagram

Step 1: Install Ollama

Ollama is a lightweight runtime that handles downloading, quantizing, and serving open models through a simple CLI and a local REST API.

On macOS:

Download the app from ollama.com/download and drag it to Applications, or install via Homebrew:

brew install ollama

On Linux:

curl -fsSL https://ollama.com/install.sh | sh

On Windows:

Download the native Windows installer from ollama.com/download and run it. (Ollama now supports Windows natively, no WSL required.)

Once installed, verify it works:

ollama --version

You should see a version number printed. Ollama also starts a background service that listens on http://localhost:11434. This is the API that Open WebUI will talk to later. You can confirm the server is up with:

curl http://localhost:11434

which should return Ollama is running.

Step 2: Pull MedGemma

MedGemma is available directly in the official Ollama model library, so downloading it is one command:

ollama pull medgemma

This pulls the default 4B multimodal variant, about a 3.3 GB download.

If you want to be explicit about the size (useful when you later experiment with the 27B model):

ollama pull medgemma:4b     # 3.3 GB — multimodal, runs on most laptops
ollama pull medgemma:27b    # 17 GB — multimodal, needs serious hardware

When the download finishes, confirm the model is installed:

ollama list

You should see medgemma in the output along with its size.

Step 3: Test MedGemma from the Terminal

Before adding a UI, let's make sure the model actually works. Start an interactive session:

ollama run medgemma

You'll get a >>> prompt. Try a medical question:

>>> What are the classic radiographic signs of pneumonia on a chest X-ray?

MedGemma should respond with a structured answer covering findings like consolidation, air bronchograms, and silhouette signs — the kind of answer that shows its radiology training.

Try one more to see the clinical reasoning:

>>> Explain the difference between Type 1 and Type 2 diabetes to a first-year medical student.

A few useful commands inside the session:

• /bye — exit the session

• /clear — clear the conversation context

• /show info — display model details (parameters, quantization, context length)

You can also test image input directly from the terminal by passing a file path directly in the prompt:

>>> Describe the key findings in this image. ./chest_xray_sample.png

While this works, uploading images through Open WebUI is much more convenient.

Step 4: Install Open WebUI

Open WebUI gives you a clean, ChatGPT-style interface on top of Ollama: conversation history, model switching, image uploads, and multi-user support, all self-hosted.

Option A: Docker (recommended)

Start by installing Docker.

Make sure Docker Desktop is running, then launch Open WebUI with:

docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Let's break down what this command does:

• -d runs the container in the background

• -p 3000:8080 maps port 3000 on your machine to the WebUI's internal port 8080

• --add-host=host.docker.internal:host-gateway lets the container reach the Ollama server running on your host machine

• -v open-webui:/app/backend/data creates a Docker volume so your chats and settings survive container restarts

• --restart always brings the UI back up automatically after reboots

Option B: pip (no Docker)

If you'd rather skip Docker, you can instead install Open WebUI as a Python package (Python 3.11 is the supported version):

pip install open-webui
open-webui serve

This starts the interface at http://localhost:8080 instead of port 3000.

Step 5: Connect Open WebUI to Ollama

Open your browser and go to http://localhost:3000 (or :8080 if you used pip).

On first launch, you'll be asked to create an admin account. This account is stored locally on your machine (it's not a cloud signup).

In most setups, Open WebUI auto-detects Ollama at http://localhost:11434 and you're done.

If your models don't appear, wire up the connection manually:

1. Click your profile icon and go to Admin Panel then Settings then Connections.

2. Under Ollama API, set the URL:

   • Docker install: http://host.docker.internal:11434

   • pip install: http://localhost:11434

3. Click the refresh icon to verify the connection, then save.

Head back to the main chat screen, and medgemma should now appear in the model dropdown at the top.

You can check the troubleshooting section below if you face any errors.

Step 6: Start Chatting with MedGemma

Select medgemma from the model selector and start a conversation. A good first test might look like this:

Summarize this radiology report in plain language a patient could understand:

"Impression: Mild cardiomegaly. Small right pleural effusion.
No focal consolidation. Degenerative changes of the thoracic spine."

You should get a clear, patient-friendly explanation of each finding. This "clinical language to plain language" translation is one of MedGemma's genuine strengths.

There are a few Open WebUI features worth knowing about:

• System prompts: Click the model name and set a system prompt like "You are a medical education assistant. Always explain your reasoning and cite the relevant physiology." This shapes every response in the conversation.

• Conversation history: Every chat is saved locally and searchable from the sidebar.

• Multiple models: You can add llama3.2, gemma3, or any other Ollama model and compare their answers to the same medical question side by side. This is a great way to see the difference domain training makes.

Step 7: Upload Medical Images

This is where MedGemma really separates itself from general-purpose models. Because its vision encoder was pre-trained on medical imaging, it can meaningfully describe radiographs, skin lesions, fundus photos, and histopathology patches.

To try it:

1. Start a new chat with medgemma selected.

2. Click the + (or image) icon in the message box, or simply drag and drop an image file.

3. Add a prompt alongside the image and hit send.

For sample images you can test with (without touching any real patient data), try public teaching datasets like the NIH ChestX-ray14 dataset, MedPix, or Radiopaedia's teaching cases.

Example workflow with a chest X-ray:

[Upload: chest_xray.png]

You are an expert radiology assistant. Describe this chest X-ray
systematically: technical quality, lungs, heart, mediastinum, bones,
and soft tissues. Then summarize the key findings.

MedGemma will typically walk through the image in the systematic order you asked for, which mirrors how radiologists are trained to read films.

Two important caveats:

• Ollama and Open WebUI work with standard image formats (PNG, JPEG). Clinical DICOM files need to be converted to PNG/JPEG first — a one-liner with Python libraries like pydicom + Pillow.

• Never upload images containing patient-identifying information (names, MRNs, dates burned into the image) unless the data has been properly de-identified. Even on a local machine, good data hygiene is a habit worth building.

Example Prompts to Try

Here are prompts that showcase different capabilities. Use them as starting points:

Medical education:

Create a comparison table of ACE inhibitors vs ARBs: mechanism, common examples, key side effects, and contraindications.

Clinical documentation:

Convert these shorthand clinic notes into a structured SOAP note:"45F, 3d cough + fever 101F, no SOB, lungs clear, likely viral URI, supportive care, return if worse"

Report translation for patients:

Explain this MRI impression to a worried patient in a reassuring but honest tone: "Small disc protrusion at L4-L5 without significant canal stenosis or nerve root compression."

Image analysis (with an uploaded dermatology photo):

Describe this skin lesion using the ABCDE criteria
(Asymmetry, Border, Color, Diameter, Evolution cannot be assessed from a single image — note that explicitly).

Differential reasoning:

A 60-year-old presents with sudden painless vision loss in one eye. List the top 5 differential diagnoses and the key distinguishing feature of each.

Notice a pattern: the best results come from prompts that give MedGemma a role, a structure to follow, and explicit constraints. That's true of all LLMs, but it matters even more in a domain where precision counts.

Running Larger Models

The 4B model is impressive for its size, but the 27B variant is noticeably stronger at complex clinical reasoning, longer differential diagnoses, and nuanced report interpretation.

The trade-off is hardware:

To try the 27B model:

ollama pull medgemma:27b
ollama run medgemma:27b

Practical tips for larger models:

• Watch your memory: Run ollama ps to see how much RAM/VRAM a loaded model is using and whether it's running on GPU, CPU, or split across both. A model that spills from GPU to CPU gets dramatically slower.

• On Apple Silicon, a 32 GB M-series Mac runs the 27B model comfortably.

• Free memory between models: Ollama keeps models loaded for a few minutes after use. Unload immediately with ollama stop medgemma:27b if you need the RAM back.

• Sanity-check the speed trade-off: If the 27B model generates at 2–3 tokens per second on your machine, the 4B model at 30+ tokens/second may be the better.

You can keep both installed and switch between them in the Open WebUI dropdown — 4B for fast iteration, 27B when you need the deeper reasoning.

Troubleshooting Guide

Error: registry.ollama.ai/library/medgemma:latest does not support tools

This is the most common MedGemma-specific error, and it means Open WebUI is sending native tool/function definitions with your request. MedGemma (like base Gemma 3) doesn't support Ollama's tools API, so the request is rejected before the model even sees your message.

Hunt down whatever is attaching tools, in this order:

1. Model capabilities (most likely culprit): Go to the Admin Panel, then Settings, then Models, then medgemma, then uncheck Builtin Tools, Web Search, Code Interpreter, and Terminal under Capabilities, and make sure every item in the Builtin Tools checklist is unticked. Keep Vision, File Upload, and File Context checked. Newer Open WebUI versions enable builtin tools by default, so a fresh install will hit this immediately.

2. Task model: Go to Admin Panel, then Settings, then Interface, and make sure neither the local nor external Task Model is set to medgemma. Background jobs like title and follow-up generation use tool calls — route them to llama3.2 or similar.

3. Function Calling mode: Set to Default (not Native) in the model's Advanced Params and in your user Settings, General, Advanced Parameters.

4. Global functions/filters: Go to Admin Panel, then Functions, and disable the Global toggle on any active function, since global functions attach to every model.

5. Per-chat toggles: In the message box, make sure web search and code interpreter toggles are off, and no Tools are attached via the + menu.

Then start a new chat (old chats can carry stale settings) and test. To confirm the model itself is fine, run ollama run medgemma "hello" in your terminal. If that works, the issue is purely Open WebUI configuration.

Open WebUI shows no models in the dropdown

The container can't reach Ollama. Check that:

• Ollama is actually running: curl http://localhost:11434 should return Ollama is running.

• The connection URL in Admin Panel, Settings, Connections is http://host.docker.internal:11434 (Docker) — localhost won't work from inside a container because it refers to the container itself.

• On Linux, if host.docker.internal doesn't resolve, add --network=host to your docker run command instead and use http://localhost:11434.

ollama pull medgemma says model not found

Update Ollama, as MedGemma requires a recent version. Re-run the installer or, on macOS, click the menu bar icon and then Update. Then retry the pull.

Responses are extremely slow

• Check ollama ps — if the model shows a large CPU percentage, it doesn't fit in your GPU/unified memory. Switch to the 4B model.

• Close memory-hungry apps (browsers with 40 tabs are the usual suspect).

• On first message, models take several seconds to load into memory, subsequent messages are much faster.

Image upload doesn't work or the model ignores the image

• Make sure you selected medgemma (multimodal) and not a text-only model in the dropdown.

• Use PNG or JPEG. DICOM files must be converted first.

• Very high-resolution images can cause issues — resize to something reasonable (e.g., 1024px on the long edge) before uploading.

Port 3000 is already in use

Map a different host port: change -p 3000:8080 to -p 3001:8080 and access the UI at http://localhost:3001.

"Out of memory" errors when loading the 27B model

Your machine doesn't have enough free RAM/VRAM. Stick with medgemma:4b, or free memory and try again. There is no shame in the 4B model — it punches well above its weight.

Conclusion

In this tutorial, you built a complete, private healthcare AI assistant from scratch — and it took three tools and a handful of terminal commands.

Let's recap what you accomplished:

• Installed Ollama and pulled MedGemma, a medically-tuned multimodal model, onto your own machine

• Verified the model from the terminal, then put a full chat interface on top of it with Open WebUI

• Configured the model's capabilities correctly so tool-calling features don't break a model that doesn't support them

• Chatted with a model that understands radiology reports, clinical terminology, and medical images — and uploaded images for analysis

• Learned how to scale up to the 27B model and how to diagnose the most common errors along the way.

You now have a fully private AI assistant running entirely on your own machine. From here, you can extend it with retrieval-augmented generation (RAG), integrate it with medical imaging pipelines, or connect it to de-identified clinical datasets to build more advanced healthcare AI applications.

Happy building!

Further reading:

• MedGemma on the Ollama library

• MedGemma model documentation (Google Health AI Developer Foundations)

• Ollama documentation

• Open WebUI documentation

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.

Table of Contents

• 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.

<script src="https://unpkg.com/pdf-lib"></script>

<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/4.4.168/pdf.min.js"></script>

<script src="https://cdn.jsdelivr.net/npm/tesseract.js@5/dist/tesseract.min.js"></script>

<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>

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:

<div class="upload-container">

    <div id="dropZone" class="drop-zone">

        <div class="upload-icon">
            ☁
        </div>

        <h2>Drag & Drop PDF Here</h2>

        <p>Or click to browse file</p>

        <button id="selectPDF">
            Select PDF
        </button>

        <input
            type="file"
            id="pdfInput"
            accept="application/pdf"
            hidden>

    </div>

</div>

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:

<select id="analysisLevel">

    <option value="basic">
        Basic (Info, Metadata, Security)
    </option>

    <option value="standard">
        Standard (Basic + Text & Image Stats)
    </option>

    <option value="advanced">
        Advanced (All Features)
    </option>

</select>

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.

In this tutorial, you'll learn how to build a browser-based PDF Add Margins Tool using JavaScript. The application allows users to upload a PDF, preview its pages, configure custom margin values, choose measurement units, apply preset margin sizes, select specific pages, and generate an updated PDF directly inside the browser.

Everything runs locally on the user's device using JavaScript, which means documents remain private and no backend server is required. This approach provides fast processing while giving users complete control over how margins are applied.

By the end of this guide, you'll understand how to work with PDF pages, create new page dimensions, reposition existing content, and export a new PDF with the desired margins.

Table of Contents

• Why PDF Margins Are Useful

• How PDF Margin Editing Works

• Project Setup

• What Library Are We Using?

• Creating the Upload Interface

• Previewing Uploaded PDF Pages

• Configuring Margin Settings

• Applying the Margins

• Generating the Updated PDF

• Demo: How the Add Margins Tool Works

• Important Notes from Real-World Use

• Common Mistakes to Avoid

• Conclusion

Why PDF Margins Are Useful

PDF documents are designed to preserve their appearance across different devices and printers, but that doesn't always mean they're ready for every use case. Many PDFs are created with very little white space around the content, making them difficult to print, bind, annotate, or archive.

Adding margins creates extra space around the page without changing the document's content. This additional white space improves readability, prevents content from being clipped during printing, and provides room for notes, signatures, stamps, or hole punching.

One of the most common uses for PDF margins is printing. Most home and office printers can't print all the way to the edge of the paper, so documents with little or no margin may lose important text or images. Adding margins ensures the entire page fits safely within the printer's printable area.

Margins are also essential when preparing books, manuals, reports, and training materials for binding. Without enough inner spacing, text can disappear into the binding, making the document difficult to read. Publishers often use larger inner margins or mirror margins to create professional-looking printed books.

Businesses regularly add margins before printing invoices, quotations, purchase orders, financial reports, contracts, and presentations. The extra space makes documents easier to file and leaves room for handwritten notes, approval stamps, signatures, or comments.

Students, teachers, and researchers also benefit from margin editing. Universities and educational institutions often require assignments, dissertations, and research papers to follow specific formatting guidelines, including minimum page margins. Instead of recreating the document, users can simply add the required spacing before submission.

Government offices, legal firms, and healthcare organizations frequently work with PDFs that must meet strict printing or filing standards. Adding consistent margins helps ensure forms, applications, agreements, medical records, and official documents are easier to print, review, and archive.

Another practical example comes from e-commerce businesses. Sellers who process hundreds of orders from platforms such as Amazon, Flipkart, or Meesho often print invoices, packing slips, shipping labels, and courier documents in bulk. If the content is positioned too close to the paper edges, some printers may crop important information. Adding consistent margins before printing helps prevent this issue and ensures every document prints correctly.

Because this tool works entirely inside the browser, users can add margins to sensitive PDF documents without uploading them to external servers. This keeps document processing fast, private, and secure while producing professional-looking PDFs that are ready for printing, sharing, binding, or long-term storage.

How PDF Margin Editing Works

Unlike editing text inside a PDF, adding margins doesn't modify the original content. Instead, the application creates a larger page and places the existing page content inside it with the specified spacing around each edge.

When a user uploads a document, the browser first reads every page in the PDF. The application calculates the current page dimensions and determines how much additional space should be added to the top, bottom, left, and right sides.

Depending on the selected settings, the tool can either expand the overall page size while preserving the original content dimensions or keep the existing page size and reposition the content within the available area.

Users can also choose whether the margin changes should be applied to every page or only selected page ranges. Mirror margins are available for printed books where the inner margin alternates between left and right pages to leave room for binding.

After processing every selected page, the browser generates a brand-new PDF containing the updated page dimensions and revised content positioning. Because everything happens locally, no files leave the user's computer during the process.

Project Setup

Before writing any JavaScript, create a simple project structure for the application.

Create a new project folder and add the following files:

pdf-add-margins/
│
├── index.html
├── style.css
├── script.js
└── assets/

The HTML file contains the upload area, preview section, margin settings, and download interface.

The CSS file styles the application and creates the responsive layout used throughout the project.

The JavaScript file handles file uploads, PDF processing, page rendering, margin calculations, and generation of the updated document.

Because everything runs inside the browser, there's no need to configure a backend server or install server-side frameworks.

What Library Are We Using?

This project uses PDF-lib, one of the most popular JavaScript libraries for creating and editing PDF files directly in the browser.

PDF-lib allows developers to load existing PDF documents, create new pages, copy pages between documents, edit document metadata, rotate pages, resize pages, crop pages, add page numbers, insert images, draw text, and export completely new PDF files without relying on external software.

Install PDF-lib using npm:

npm install pdf-lib

Or include it directly from a CDN inside your HTML page:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

Once the library is loaded, you can import the required objects:

const {
  PDFDocument
} = PDFLib;

Throughout this tutorial, PDF-lib will be responsible for loading uploaded documents, creating new page dimensions, repositioning page content according to the selected margins, and exporting the finished PDF.

Creating the Upload Interface

The first feature users interact with is the upload interface. A simple and intuitive upload area makes it easy to select a PDF file using either drag-and-drop or the traditional file picker.

In this project, the upload section accepts only PDF documents. Once a valid file is selected, the browser immediately begins loading the document and prepares it for previewing and margin editing.

The upload component also acts as the starting point for the entire workflow. Every action that follows (page preview, margin configuration, page selection, and PDF generation) depends on the uploaded file.

Because the application runs entirely inside the browser, the uploaded PDF never leaves the user's computer. This improves privacy while reducing processing time.

Here's a simple upload field:

<div class="upload-box">
    <input
        type="file"
        id="pdfFile"
        accept=".pdf,application/pdf"
        hidden
    >

    <button id="selectPDF">
        Select PDF
    </button>
</div>

Connect the upload button with JavaScript:

const input = document.getElementById("pdfFile");
const button = document.getElementById("selectPDF");

button.addEventListener("click", () => {
    input.click();
});

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

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

    if (!file) return;

    const bytes = await file.arrayBuffer();

    console.log("PDF Loaded", bytes);

});

The uploaded PDF is now available for rendering page previews and applying margin settings.

Upload Interface Demo

Previewing Uploaded PDF Pages

Once the PDF has been uploaded successfully, the next step is displaying its pages.

Showing page previews gives users confidence that the correct document has been selected before any changes are made. It also allows them to inspect each page and decide whether margins should be applied to the entire document or only to specific pages.

In this project, every page is rendered as a thumbnail. Users can quickly scroll through the document and verify page order before adjusting any settings.

For large documents, thumbnail previews make navigation much easier than displaying one full-size page at a time.

The browser renders each page directly from the uploaded PDF without sending the document to a server.

After loading the document, each page can be rendered individually.

const pdfDoc = await PDFDocument.load(pdfBytes);

const pages = pdfDoc.getPages();

console.log("Total Pages:", pages.length);

Each page is then displayed inside the preview gallery.

pages.forEach((page, index) => {

    console.log(`Rendering page ${index + 1}`);

});

After the previews are generated, users can move on to configuring the margin settings.

Preview Demo

Configuring Margin Settings

After verifying the uploaded document, users can configure exactly how the margins should be added.

Rather than applying one fixed margin to every document, the tool provides several options that make it suitable for different printing, publishing, and business workflows.

Users can enter custom values for the top, bottom, left, and right margins. These values can be measured in millimeters, pixels, or inches depending on the intended use.

For users who don't want to calculate measurements manually, the application also includes preset margin sizes such as None, Narrow, Normal, and Wide.

The tool supports applying margins to every page or only to a specific page range. This is especially useful when only certain pages require additional spacing.

For printed books and manuals, mirror margins can be enabled so that left and right pages automatically receive opposite inner margins for binding.

Users can also decide how the margin should be applied. Expanding the page size preserves the original content dimensions while increasing the overall page size. Alternatively, the existing page size can be maintained and the content repositioned within the available space.

All of these settings are configured before any processing begins, allowing users to preview and adjust everything in advance.

Example margin configuration:

const marginSettings = {

    top: 25.4,

    bottom: 25.4,

    left: 25.4,

    right: 25.4,

    unit: "mm",

    applyTo: "all",

    mirrorMargins: false,

    preset: "Normal",

    resizeMode: "Expand Page Size"

};

The selected values are then used while generating the updated PDF pages.

Margin Settings Demo

Applying the Margins

Once the margin settings have been configured, the application can begin processing the PDF.

Instead of modifying the original document directly, the tool creates a new page layout based on the selected margin values. The existing page content is then repositioned inside the newly calculated page dimensions.

This approach preserves the original document while generating a new PDF with additional white space around the content.

Depending on the selected resize mode, the application can either expand the page size to accommodate the new margins or keep the existing page size and reposition the content within the available printable area.

For documents containing multiple pages, the same settings can be applied to every page or only to a selected page range.

A simplified example looks like this:

const pages = pdfDoc.getPages();

pages.forEach((page) => {

    const { width, height } = page.getSize();

    const newWidth = width + leftMargin + rightMargin;

    const newHeight = height + topMargin + bottomMargin;

    page.setSize(newWidth, newHeight);

});

The application then adjusts the page content so it remains correctly positioned inside the new page dimensions.

page.translateContent(
    leftMargin,
    bottomMargin
);

This ensures the document content shifts into the correct position while leaving the requested space around the page edges.

Applying Margins Demo

Generating the Updated PDF

After every selected page has been processed, the browser creates a brand-new PDF containing the updated page sizes and margin layout.

The original PDF remains unchanged while the modified document is prepared for download.

Because everything happens locally, the generation process is usually very fast, even for multi-page documents.

Once processing is complete, the updated PDF is converted into downloadable bytes.

const pdfBytes = await pdfDoc.save();

A Blob object can then be created for downloading.

const blob = new Blob(
    [pdfBytes],
    {
        type: "application/pdf"
    }
);

const url = URL.createObjectURL(blob);

Finally, the browser starts the download.

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

link.href = url;

link.download = "updated-document.pdf";

link.click();

The generated PDF can also be previewed before downloading.

Users are able to review the updated document, rename the output file, view the total number of pages, check the final file size, and download the completed PDF when they are satisfied with the results.

Updated PDF Preview

Demo: How the Add Margins Tool 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 picker.

Once a file is selected, the browser validates that it's a PDF and loads it locally. Since all processing happens inside the browser, the document never leaves the user's device, making the tool suitable for confidential reports, contracts, invoices, and other sensitive documents.

After the file is loaded successfully, the application prepares the document for preview generation and margin editing.

Step 2: Preview Uploaded PDF Pages

After uploading the document, the application generates page previews directly inside the browser.

Displaying page thumbnails allows users to verify that the correct document has been selected before making any changes. For larger PDFs, the preview section also makes it easier to navigate through the document and inspect individual pages.

This step helps prevent mistakes before the margin settings are applied.

Step 3: Configure Margin Settings

Next, users configure how margins should be added to the document.

The tool allows custom values for the top, bottom, left, and right margins while also supporting predefined presets such as None, Narrow, Normal, and Wide.

Users can choose whether the margins should be applied to every page or only to selected page ranges. Mirror margins are available for printed books and documents that require binding.

Another useful option lets users decide whether the application should expand the overall page size or reposition the existing content while keeping the original page dimensions.

These settings provide complete control over how the final document will appear.

Step 4: Apply the Margins

After reviewing the selected settings, users simply click the Add Margins button.

The browser processes every selected page, calculates the new page dimensions, repositions the original content, and generates an updated PDF with the requested spacing around each page.

If users want to work with another document, the Start Over button clears the current session without requiring a page refresh.

Step 5: Preview the Updated PDF

Once processing has finished, the updated document is displayed inside the browser.

Users can review every page before downloading to ensure the margins have been applied correctly.

The preview section also includes page navigation controls, making it easy to browse through multi-page documents and confirm that every selected page has been processed successfully.

Reviewing the document before downloading helps catch formatting issues early and reduces the need for additional edits later.

Step 6: Download the Final PDF

After verifying the updated document, users can download the finished PDF.

The final output section displays useful information including the output filename, total number of pages, and file size. Users can rename the generated document before downloading it, making file organization much easier.

Once everything looks correct, the updated PDF can be downloaded and immediately used for printing, sharing, binding, archiving, or submitting to organizations that require specific page margins.

Important Notes from Real-World Use

Adding margins is generally a lightweight operation, but large PDF files containing hundreds of pages or high-resolution images may require additional processing time.

Before processing begins, it's a good idea to validate the uploaded file.

if (file.type !== "application/pdf") {
    alert("Please upload a valid PDF file.");
    return;
}

When working with large documents, verify the selected margin values before generating the final PDF.

console.log(`Top: ${topMargin}`);
console.log(`Bottom: ${bottomMargin}`);
console.log(`Left: ${leftMargin}`);
console.log(`Right: ${rightMargin}`);

If the document is intended for printing, preview the generated PDF to ensure that text, tables, images, and page numbers remain correctly positioned.

Because all processing happens locally, documents remain on the user's device throughout the entire workflow, making browser-based margin editing suitable for contracts, invoices, financial reports, legal documents, educational records, healthcare forms, and other confidential PDFs.

Common Mistakes to Avoid

One common mistake is using excessively large margin values that reduce the printable area more than necessary.

Always verify the selected measurements before generating the updated document.

if (leftMargin < 0 || rightMargin < 0) {
    alert("Margin values cannot be negative.");
}

Another mistake is forgetting to choose the correct page selection mode.

Sometimes only the first page or a specific page range requires additional margins, while the rest of the document should remain unchanged.

const applyTo = "all";

console.log(`Apply margins to: ${applyTo}`);

Users should also verify whether Expand Page Size or Keep Original Page Size is the correct option for their workflow. Choosing the wrong mode can affect the final layout when printing or sharing the document.

Finally, always review the generated PDF before downloading it.

Taking a few moments to inspect the updated pages helps confirm that the spacing is correct, page content remains properly aligned, and the document is ready for printing, binding, archiving, or distribution.

Conclusion

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

You learned how to upload PDF files, preview document pages, configure custom margin settings, apply margins to selected pages, and generate updated PDF files directly inside the browser.

More importantly, you saw how modern browsers can perform PDF page layout modifications without requiring a backend server.

This approach keeps document processing fast, private, and easy to use while giving users complete control over page spacing.

You can try the live implementation here: AllInOneTools - Add Margin to PDF.

Once you understand this workflow, you can extend it further by adding features such as page cropping, resizing, page numbering, watermarking, document organization, metadata editing, and other advanced PDF editing capabilities.

In this tutorial, you'll build your very own browser-based Text Compare Tool. It will take an original piece of text, compare it against a changed version, and instantly highlight exactly what was added or removed.

Building this project will help you level up your JavaScript skills. You'll also create a tool that's highly secure, because everything happens locally in the user's browser. No sensitive data is ever sent to a server.

Let’s get started.

Prerequisites

To follow along easily, you should know:

• Basic HTML and CSS knowledge: How to structure a page and use Flexbox to put items side-by-side.

• Basic JavaScript knowledge: How to write functions, use arrays, and listen for button clicks.

• Your Setup: A code editor (like VS Code) and a web browser to view your work.

Table of Contents

• Step 1: Set Up Your Project Files

• Step 2: Build the HTML Structure

• Step 3: Style the Tool with CSS

• Step 4: Write the JavaScript Engine

• Step 5: Test Your Application

• Conclusion

Step 1: Set Up Your Project Files

First, you need a place to store your code. Create a new folder on your computer and name it text-compare-tool.

Inside that folder, create three empty files:

• index.html (This holds the structure of your app)

• style.css (This makes your app look good)

• script.js (This makes your app actually work)

Step 2: Build the HTML Structure

Open your index.html file. You need to create a simple layout with two large text boxes: one for the original text, and one for the updated text.

Copy and paste this code into your HTML file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Text Compare Tool</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>

    <h1>Text Compare Tool</h1>
    <p class="description">
        Quickly find every addition and deletion between two versions of your text. Just paste them into our tool, and we’ll show you exactly what’s been changed.
    </p>

    <div class="container">
        
        <div class="panels-wrapper">
            <!-- Left Side: Original Text -->
            <div class="panel">
                <textarea id="text1" placeholder="Paste your original text here..."></textarea>
                <div id="result1" class="result-box"></div>
            </div>
            
            <!-- Right Side: Changed Text -->
            <div class="panel">
                <textarea id="text2" placeholder="Paste your changed text here..."></textarea>
                <div id="result2" class="result-box"></div>
            </div>
        </div>

        <!-- Action Buttons -->
        <div class="controls">
            <button class="btn-compare" onclick="compareText()">Compare</button>
            <button class="btn-clear" onclick="clearText()">Clear</button>
        </div>

    </div>

    <script src="script.js"></script>
</body>
</html>

Understanding the HTML:

• The two panels: Inside the .panels-wrapper, you have a left side and a right side.

• Textareas vs results: Each side has a <textarea> where the user can type. Right below the text area is a <div> with the class .result-box. Right now, those result boxes are invisible. Later, JavaScript will hide the text areas and show the result boxes instead.

• The buttons: The "Compare" and "Clear" buttons are hooked up to JavaScript functions using onclick.

Step 3: Style the Tool with CSS

A good utility tool should be easy on the eyes. You'll use a clean white and blue design, and apply soft red and green colors to highlight the text changes.

Open your style.css file and add this code:

:root {
    --primary-blue: #007bff;
    --background-color: #f8f9fa;
    --text-color: #202124;
    --border-color: #dadce0;
    
    /* Highlight Colors */
    --red-bg: #fce8e6;
    --red-text: #c5221f;
    --green-bg: #e6f4ea;
    --green-text: #137333;
}

body {
    font-family: Arial, sans-serif;
    background-color: var(--background-color);
    color: var(--text-color);
    display: flex;
    flex-direction: column;
    align-items: center;
    padding: 40px 20px;
    margin: 0;
}

h1 {
    margin-bottom: 10px;
}

.description {
    text-align: center;
    max-width: 600px;
    color: #5f6368;
    margin-bottom: 30px;
    line-height: 1.5;
}

.container {
    background: white;
    padding: 20px;
    border-radius: 8px;
    border: 1px solid var(--border-color);
    width: 100%;
    max-width: 1000px;
    box-shadow: 0 4px 10px rgba(0,0,0,0.05);
}

.panels-wrapper {
    display: flex;
    gap: 20px;
    margin-bottom: 20px;
}

.panel {
    flex: 1;
    display: flex;
    flex-direction: column;
}

textarea, .result-box {
    width: 100%;
    height: 300px;
    padding: 15px;
    border: 1px solid var(--border-color);
    border-radius: 6px;
    font-size: 16px;
    line-height: 1.5;
    box-sizing: border-box;
    resize: vertical;
}

textarea:focus {
    outline: none;
    border-color: var(--primary-blue);
}

/* Hidden by default */
.result-box {
    display: none; 
    background-color: #fafafa;
    overflow-y: auto;
    white-space: pre-wrap; 
}

.controls {
    display: flex;
    justify-content: center;
    gap: 15px;
}

button {
    padding: 10px 25px;
    font-size: 16px;
    font-weight: bold;
    border: none;
    border-radius: 5px;
    cursor: pointer;
}

.btn-compare {
    background-color: var(--primary-blue);
    color: white;
}

.btn-clear {
    background-color: white;
    color: var(--primary-blue);
    border: 1px solid var(--border-color);
}

/* How the differences will look */
.deleted {
    background-color: var(--red-bg);
    color: var(--red-text);
    padding: 2px 4px;
    border-radius: 3px;
}

.added {
    background-color: var(--green-bg);
    color: var(--green-text);
    padding: 2px 4px;
    border-radius: 3px;
}

Understanding the CSS:

• Flexbox layout: display: flex; inside .panels-wrapper is what places your two text boxes neatly side-by-side.

• The highlighters: The .deleted and .added classes are the most important part of the visual design. When a user deletes a word, we give it a soft red background. When they add a word, it gets a soft green background.

This is what your tool will look like once it's finished:

Step 4: Write the JavaScript Engine

Now you need to make the tool actually work. How does your computer know if a word has changed?

We have to write logic that breaks paragraphs down into individual words. The code will look at the original list of words and compare it to the new list. If a word from the original text is missing, it gets marked as "deleted." If a brand new word appears, it gets marked as "added."

Open your script.js file and paste in this complete, working code:

function compareText() {
    // 1. Grab the text from the text boxes
    const text1 = document.getElementById('text1').value;
    const text2 = document.getElementById('text2').value;

    // 2. Chop the text up into an array of words (and keep the spaces)
    const words1 = text1.split(/(\s+)/);
    const words2 = text2.split(/(\s+)/);

    // 3. Find the differences
    const { diff1, diff2 } = calculateDifferences(words1, words2);

    const resultBox1 = document.getElementById('result1');
    const resultBox2 = document.getElementById('result2');
    
    // 4. Turn those differences into HTML with colors
    resultBox1.innerHTML = createColoredHTML(diff1, 'deleted');
    resultBox2.innerHTML = createColoredHTML(diff2, 'added');

    // 5. Hide the text boxes and show the final results
    document.getElementById('text1').style.display = 'none';
    document.getElementById('text2').style.display = 'none';
    resultBox1.style.display = 'block';
    resultBox2.style.display = 'block';
}

// The engine that compares the two lists of words
function calculateDifferences(arr1, arr2) {
    const n = arr1.length;
    const m = arr2.length;
    
    // Create a grid to keep track of matching words
    const grid = Array.from({ length: n + 1 }, () => Array(m + 1).fill(0));

    for (let i = 1; i <= n; i++) {
        for (let j = 1; j <= m; j++) {
            if (arr1[i - 1] === arr2[j - 1]) {
                grid[i][j] = grid[i - 1][j - 1] + 1;
            } else {
                grid[i][j] = Math.max(grid[i - 1][j], grid[i][j - 1]);
            }
        }
    }

    let i = n, j = m;
    const diff1 = [];
    const diff2 = [];

    // Walk backwards through the grid to mark what changed
    while (i > 0 || j > 0) {
        if (i > 0 && j > 0 && arr1[i - 1] === arr2[j - 1]) {
            diff1.unshift({ value: arr1[i - 1], type: 'equal' });
            diff2.unshift({ value: arr2[j - 1], type: 'equal' });
            i--;
            j--;
        } else if (j > 0 && (i === 0 || grid[i][j - 1] >= grid[i - 1][j])) {
            diff2.unshift({ value: arr2[j - 1], type: 'changed' });
            j--;
        } else if (i > 0 && (j === 0 || grid[i][j - 1] < grid[i - 1][j])) {
            diff1.unshift({ value: arr1[i - 1], type: 'changed' });
            i--;
        }
    }

    return { diff1, diff2 };
}

// Packages the text safely into HTML span elements
function createColoredHTML(diffArray, colorClass) {
    return diffArray.map(wordItem => {
        // Replace dangerous characters so the browser doesn't crash
        const safeText = wordItem.value.replace(/</g, "&lt;").replace(/>/g, "&gt;");
        
        // If the word was changed (and isn't just a blank space), wrap it in color
        if (wordItem.type === 'changed' && !/^\s+$/.test(wordItem.value)) {
            return `<span class="${colorClass}">${safeText}</span>`;
        }
        return safeText;
    }).join('');
}

// Puts the tool back to its default state
function clearText() {
    document.getElementById('text1').value = '';
    document.getElementById('text2').value = '';
    
    document.getElementById('text1').style.display = 'block';
    document.getElementById('text2').style.display = 'block';
    
    document.getElementById('result1').style.display = 'none';
    document.getElementById('result2').style.display = 'none';
}

Understanding the JavaScript:

1. Keeping the formatting: In the first function, you see .split(/(\s+)/). This splits the text up by spaces, but keeps the spaces and line-breaks. If you don't do this, all of the user's paragraphs will mash into one giant block of text!

2. The grid system: The calculateDifferences function creates an invisible grid. It compares every word in the first box with every word in the second box. If it sees the same word in the same order, it leaves it alone. If it hits a snag, it marks the word as a change.

3. Safety first: The createColoredHTML function wraps our changed words in <span class="added"> or <span class="deleted"> so CSS can color them. But before it does that, it removes any < or > symbols using .replace(). This stops hackers from pasting malicious code into your app.

Step 5: Test Your Application

You're completely done coding! Now it’s time to see it in action.

1. Open your text-compare-tool folder.

2. Double-click the index.html file. It will open in your default web browser.

3. Type a sentence into the left box: "The quick brown fox jumps over the lazy dog."

4. Type a slightly different sentence into the right box: "The fast brown fox jumps over the sleepy dog."

5. Click Compare.

You will instantly see the word "quick" highlight in red on the left, and the word "fast" highlight in green on the right. If you want to start over, just click Clear.

Conclusion

Great job! You just built a highly practical, browser-based text comparison utility using nothing but pure HTML, CSS, and JavaScript.

You learned how to break text into arrays, compare them using a grid-based algorithm, and manipulate the DOM to show those differences to the user safely. Because this tool relies on local browser processing, it's incredibly fast and 100% private.

If you want to see this exact logic running in a live production environment, or if you need to bookmark a fast tool for your own writing tasks, check out the live Text Compare Tool. Keep experimenting with the code, and happy building!

A PDF resizing tool solves this problem by allowing users to change the page dimensions of an existing PDF without recreating the document from scratch.

Whether you're preparing business reports, invoices, scanned documents, eBooks, presentations, or government forms, resizing pages helps ensure documents fit the required paper size while maintaining a professional appearance.

In this tutorial, you'll build a browser-based PDF Resizer using JavaScript. Users will be able to upload PDF files, preview document pages, choose preset or custom page sizes, configure scaling behavior, add page margins, and generate a resized PDF directly inside the browser.

Everything happens locally using JavaScript, so uploaded documents never leave the user's device. This improves privacy, eliminates server-side processing, and provides a faster experience.

By the end of this guide, you'll understand how browser-based PDF resizing works and how to build a practical tool that can be extended with additional document editing features.

Table of Contents

• Why PDF Resizing Is Useful

• How PDF Resizing Works

• Project Setup

• What Library Are We Using?

• Creating the Upload Interface

• Previewing Uploaded PDF Pages

• Configuring Resize Settings

• Applying the Resize

• Generating the Resized PDF

• Demo: How the PDF Resize Tool Works

• Important Notes from Real-World Use

• Common Mistakes to Avoid

• Conclusion

Why PDF Resizing Is Useful

PDF files are created for many different purposes, and not every document uses the same page dimensions. A presentation might be designed for widescreen viewing, an invoice could use Letter size, a government application may require A4 paper, and engineering drawings often use Legal or Tabloid formats.

When documents don't match the required page size, they can be difficult to print correctly. Content may appear cut off, excessive white space may be introduced, or the document may scale incorrectly during printing.

A PDF resizing tool helps solve these problems by allowing users to convert pages into standardized sizes without rebuilding the document.

This is especially useful in everyday situations. Businesses often receive invoices and contracts from different organizations that use different paper standards. Before storing or printing these documents, employees frequently resize them to a consistent format.

Students regularly download lecture notes, assignments, research papers, and ebooks from different sources. Converting these files to a common page size makes printing and reading much easier.

Graphic designers and publishers also resize PDFs before sending artwork for commercial printing, ensuring that documents match the required dimensions of the printing service.

One practical example comes from e-commerce businesses. Imagine a seller who receives hundreds of shipping labels every day from platforms like Amazon, Flipkart, or Meesho. Different marketplaces may generate labels using different paper sizes. Before printing them in bulk, the seller can resize every PDF to A4 so all labels print consistently without manual adjustments.

Government offices, banks, educational institutions, and legal firms also work with PDFs from multiple sources. Standardizing page sizes simplifies document management, digital archiving, scanning, and future editing.

Instead of recreating an entire document, resizing allows users to adapt existing PDFs quickly while preserving their original content.

How PDF Resizing Works

A PDF resizing tool changes the dimensions of one or more pages inside an existing PDF document while preserving the page content.

When a user uploads a PDF, the browser first reads the document and extracts information such as page count, page dimensions, and page objects. Instead of editing the original file directly, a new PDF is created with the selected page size, and each page is copied into the new document using the chosen scaling method.

Depending on the resize settings, the page content can be scaled to fill the page, stretched to match the new dimensions, centered without scaling, or cropped to fit the selected paper size.

Users can also choose whether the resize operation should apply to every page or only a specific page range. This is useful when only part of a document needs to be converted to another paper size.

Because all processing happens inside the browser, uploaded files remain on the user's device throughout the entire workflow. No documents are sent to external servers, making the tool suitable for confidential reports, contracts, invoices, educational documents, business records, and other sensitive files.

Project Setup

Create a new project folder for the PDF resizer.

A simple project structure looks like this:

pdf-resizer/
│── index.html
│── style.css
│── script.js
│── assets/

The HTML file contains the upload area, page preview, resize settings, and download section.

The CSS file handles the overall layout and responsive design.

The JavaScript file manages PDF loading, page previews, resize operations, and exporting the updated document.

Keeping the project organized makes it easier to add new features later, such as cropping, page rotation, watermarking, metadata editing, or PDF merging.

What Library Are We Using?

This project uses pdf-lib, one of the most popular JavaScript libraries for creating and editing PDF documents directly in the browser.

It allows developers to:

• Read existing PDF files.

• Create new PDF documents.

• Copy pages between PDFs.

• Resize pages.

• Rotate pages.

• Add text, images, and shapes.

• Modify document metadata.

• Export updated PDFs.

Unlike many online PDF services, pdf-lib works entirely in the browser and doesn't require a backend server.

Install the library using npm:

npm install pdf-lib

Or include it directly from a CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

Once loaded, the library exposes the PDFDocument object that is used throughout the application.

Example:

const { PDFDocument } = PDFLib;

Creating the Upload Interface

The first step is allowing users to upload a PDF document.

The interface includes a drag-and-drop area together with a traditional file picker so users can choose whichever method they prefer.

When a file is selected, JavaScript validates that it is a PDF before loading it into memory.

Here's a simple upload input:

<input
    type="file"
    id="pdfUpload"
    accept="application/pdf"
/>

Next, listen for file selection:

const upload = document.getElementById("pdfUpload");

upload.addEventListener("change", async (event) => {
    const file = event.target.files[0];

    if (!file) return;

    console.log(file.name);
});

Read the uploaded file:

const bytes = await file.arrayBuffer();

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

At this point, the uploaded PDF is loaded into memory and is ready for preview generation and resizing.

Previewing Uploaded PDF Pages

After the document has been uploaded, the next step is generating page previews.

Displaying page thumbnails helps users confirm that the correct file has been selected before changing its size.

For multi-page PDFs, previewing every page also makes it easier to understand how the resize operation will affect the document.

Your tool displays thumbnails for every page, allowing users to visually inspect the PDF before making any modifications.

Developers can retrieve the total number of pages using pdf-lib:

const totalPages = pdfDoc.getPageCount();

console.log(totalPages);

Retrieve individual pages:

const pages = pdfDoc.getPages();

pages.forEach((page, index) => {
    console.log(`Page ${index + 1}`);
});

Once the pages are available, the application can generate preview thumbnails and display them inside the browser.

Users can then decide whether to resize the entire document or only selected pages.

Configuring Resize Settings

Once the PDF pages have been loaded, users need to configure how the document should be resized.

A flexible PDF resizing tool should support both standard paper sizes and custom dimensions while allowing users to control how the existing content fits inside the new page.

In this project, users can choose whether the resize operation should be applied to every page or only a specific page range.

For page dimensions, the tool supports popular paper formats such as A4, A5, Letter, Legal, Tabloid, and Square. If none of these meet the user's requirements, custom width and height values can also be entered.

Another important setting is content scaling. Depending on the document, users may want to fit the existing content inside the page, stretch it to fill the available space, keep the original size centered on the page, or crop the content to match the selected paper size.

The resize panel also includes margin controls so users can add additional spacing around the document if required.

Together, these settings provide complete control over the final page layout before generating the resized PDF.

Choosing Preset Paper Sizes

Many users simply want to convert documents into common paper formats.

Instead of entering page dimensions manually, the tool provides several predefined page sizes that can be selected with a single click.

These presets are especially useful when preparing PDFs for printing, business reports, contracts, government forms, books, or educational documents.

Using Custom Page Sizes

If a standard paper size isn't suitable, users can enter custom page dimensions.

The width and height can be specified using supported measurement units, allowing documents to match exact printing or publishing requirements.

The Lock Aspect Ratio option ensures that the document maintains its original proportions while resizing.

Selecting Content Scaling

Different documents require different scaling behavior.

The tool offers several scaling modes so users can choose the most appropriate layout for their document.

For example, Fit to Page scales content while preserving proportions, Stretch to Fit expands the content to fill the page completely, Keep Original Size (Center) places the original page in the center without scaling, and Crop to Fit trims overflowing content to match the selected page dimensions.

Example Resize Settings

Here's a simplified configuration object that stores the selected resize options.

const resizeOptions = {
    width: 210,
    height: 297,
    unit: "mm",
    scaleMode: "fit",
    applyTo: "all"
};

The selected values are then used while generating the resized PDF.

Applying the Resize

After the resize settings have been configured, the application creates a new PDF document and copies each page into it using the selected dimensions.

Each page is resized according to the chosen paper size and scaling mode before being added to the new document.

A simplified example looks like this:

const newPdf = await PDFLib.PDFDocument.create();

const copiedPages = await newPdf.copyPages(
    pdfDoc,
    pdfDoc.getPageIndices()
);

copiedPages.forEach(page => {
    page.setSize(595, 842);

    newPdf.addPage(page);
});

The dimensions shown above represent an A4 page measured in PDF points.

Developers can replace these values with custom dimensions depending on the selected paper size.

After every page has been resized, the new document is ready for export.

Generating the Resized PDF

Once all pages have been processed, the updated document is converted into a downloadable PDF.

The browser creates a binary PDF file and generates a temporary download link without sending the document to a server.

Saving the resized document is straightforward.

const pdfBytes = await newPdf.save();

const blob = new Blob([pdfBytes], {
    type: "application/pdf"
});

const url = URL.createObjectURL(blob);

The generated URL can then be attached to a download button.

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

link.href = url;
link.download = "resized-document.pdf";

link.click();

The user immediately receives the updated document with the newly selected page dimensions.

Demo: How the PDF Resize Tool Works

Step 1: Upload Your PDF File

The process begins by uploading a PDF document into the browser.

Users can either drag and drop a file into the upload area or choose a document using the file picker.

Once selected, the browser validates the file type and loads the document locally without uploading it to a server. This keeps the entire resizing process private and ensures sensitive documents remain on the user's device.

Step 2: Preview Uploaded PDF Pages

After the PDF has been loaded, the tool generates page previews for the entire document.

Displaying thumbnails allows users to verify that the correct document has been selected before making any modifications.

Users can also select individual pages if they only want to resize certain parts of the document.

This preview step helps avoid mistakes before generating the final PDF.

Step 3: Configure Resize Settings

Next, users configure how the document should be resized.

The tool supports standard paper sizes such as A4, A5, Letter, Legal, Tabloid, and Square, while also allowing completely custom dimensions.

Users can specify whether the resize operation should apply to all pages or only selected page ranges.

Additional options include locking the aspect ratio, choosing page orientation, selecting a content scaling mode, and adding page margins when necessary.

These settings provide complete control over the final document layout before processing begins.

Step 4: Generate the Resized PDF

After reviewing the selected options, users simply click the Resize PDF button.

The browser processes every selected page according to the configured paper size and scaling method.

Because the entire operation runs locally, even large documents can usually be processed within a few seconds depending on the number of pages.

If users want to process another document, the Start Over button clears the current session and returns the tool to its initial state.

Step 5: Preview the Resized PDF

Once processing is complete, the newly generated PDF is displayed inside the browser.

Users can review the resized pages before downloading the document.

The preview section includes page navigation controls, making it easy to move through multi-page PDFs and confirm that every page has been resized correctly.

Reviewing the output before download helps catch formatting issues and ensures the selected page size and scaling options produced the expected results.

Step 6: Download the Final PDF

After confirming the resized document, users can download the updated PDF.

The final output section displays useful information such as the output filename, total number of pages, and file size.

Users may also rename the document before downloading it, making it easier to organize files after processing.

The Download PDF button saves the resized document, while the Start Over button allows users to upload another PDF without refreshing the page.

Important Notes from Real-World Use

Resizing PDF pages can significantly improve document compatibility, but it's important to validate uploaded files before processing.

For example:

if (file.type !== "application/pdf") {
    alert("Please upload a valid PDF file.");
    return;
}

Very large PDF files may require additional processing time depending on the number of pages and embedded images.

When resizing documents containing hundreds of pages, processing them page by page can help reduce memory usage.

Before generating the final PDF, it's also a good idea to verify the selected page size.

For example:

console.log(`Selected Size: ${pageSize}`);
console.log(`Scale Mode: ${scaleMode}`);

Previewing the resized document before downloading helps ensure that text, images, and page layouts appear correctly.

Because everything happens inside the browser, uploaded documents remain on the user's device throughout the entire resizing process.

Common Mistakes to Avoid

One common mistake is selecting a page size that doesn't match the intended output.

For example, resizing a wide presentation directly to A4 portrait may cause content to become too small or appear compressed.

Always verify the selected paper size before processing.

if (pageWidth <= 0 || pageHeight <= 0) {
    alert("Invalid page dimensions.");
}

Another common mistake is choosing the wrong content scaling mode.

Stretching content may distort images and text, while cropping may remove important information from the page.

Users should preview different scaling modes before generating the final PDF.

It's also important to check whether the resize operation should apply to every page or only selected pages.

const applyMode = "all";

console.log(`Resize Mode: ${applyMode}`);

Finally, always review the generated PDF before downloading it.

Taking a few seconds to inspect page layouts, margins, and scaling can prevent unnecessary reprocessing later.

Conclusion

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

You learned how to upload PDF files, preview document pages, configure page sizes, adjust scaling behavior, resize pages, and generate downloadable PDF files directly inside the browser.

More importantly, you saw how modern browsers can perform PDF page resizing locally without requiring a backend server.

This approach keeps document processing fast, private, and easy to use while giving users complete control over the final document layout.

If you'd like to see a working example, try the PDF Resize Tool and explore how PDF pages can be resized directly in your browser.

Once you understand this workflow, you can extend it further with features like page cropping, rotation, watermarking, metadata editing, page numbering, document organization, and other advanced PDF editing capabilities.

Cropping allows users to remove these unwanted areas and focus only on the important content.

In this tutorial, you'll build a browser-based PDF Crop Tool using JavaScript.

Users will be able to upload a PDF, preview pages, select a crop area visually, apply crop settings to specific pages, generate a cropped PDF, preview the final result, and download the updated document directly from the browser.

Everything runs locally without requiring a backend server.

Table of Contents

• Why PDF Cropping Is Useful

• How PDF Cropping Works

• Project Setup

• What Library Are We Using?

• Creating the Upload Interface

• Previewing Uploaded PDF Pages

• Configuring Crop Settings

• Applying the Crop

• Generating the Cropped PDF

• Why PDF Cropping Is Useful in Real-World Documents

• Demo: Cropping PDF Files in the Browser

• Important Notes from Real-World Use

• Common Mistakes to Avoid

• Conclusion

Why PDF Cropping Is Useful

PDF cropping is commonly used when working with scanned documents, invoices, reports, contracts, forms, ebooks, manuals, presentations, and academic documents.

Many PDFs contain unnecessary whitespace or scanning artifacts around the edges of the page. Cropping helps remove distractions and makes documents easier to read.

Businesses often crop invoices and reports before sharing them with clients. Students crop lecture notes and scanned study materials to focus on the important content. And designers frequently crop exported PDFs to remove unwanted margins before printing or publishing.

Cropping also reduces visual clutter and creates a cleaner, more professional document.

How PDF Cropping Works

A PDF crop tool loads document pages inside the browser and allows users to define a rectangular crop area.

Once selected, the crop coordinates are applied to the chosen pages. The browser then generates a new PDF using only the selected content area.

Everything happens locally inside the browser. This means uploaded documents never leave the user's device, improving privacy and security.

Project Setup

This project is intentionally simple: you'll only need an HTML file, a JavaScript file, and a PDF processing library.

No backend server or database is required, as everything runs directly inside the browser.

What Library Are We Using?

We'll use PDF-lib for PDF processing.

PDF-lib allows us to load PDF documents, modify page boundaries, and export updated PDF files directly in JavaScript.

Add the library using a CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

Once loaded, JavaScript can process PDF pages directly inside the browser.

Creating the Upload Interface

Users first upload a PDF document into the browser.

A simple file input works well:

<input type="file" id="pdfInput" accept=".pdf">

JavaScript can detect when a file is selected:

document.getElementById("pdfInput").addEventListener("change", (event) => {
  const file = event.target.files[0];
  console.log(file.name);
});

Here's what the upload section looks like:

Previewing Uploaded PDF Pages

After uploading a document, users can preview PDF pages directly inside the browser.

The preview area includes page navigation controls that allow users to move between pages before cropping.

A default crop selection area is displayed on the preview page to help users begin selecting content immediately. This makes it easier to verify the document before applying crop settings.

Here's what the preview section looks like:

Configuring Crop Settings

After users select a crop area on the PDF preview, they often need more precise control over how the crop should be applied.

A practical PDF crop tool should allow users to manually adjust crop coordinates, choose predefined page ratios, and decide which pages should receive the crop operation.

This flexibility is especially useful when working with scanned documents, forms, reports, ebooks, presentations, and multi-page PDFs where different pages may require different crop settings.

In this project, users can adjust the crop position, control the crop dimensions, choose predefined crop ratios, and decide whether the crop should be applied to the current page, all pages, or a specific page range.

The crop settings panel provides complete control before generating the final PDF.

Here's what the crop settings section looks like:

Reading Crop Coordinates

When users drag a selection area on the preview page, the application records the crop dimensions.

A crop object typically contains:

const cropArea = {
  x: 173,
  y: 141,
  width: 452,
  height: 309
};

These values determine which portion of the page will remain visible after cropping.

Applying Custom Coordinates

Users can manually modify crop coordinates for more accurate results.

For example:

const left = parseInt(document.getElementById("cropX").value);
const top = parseInt(document.getElementById("cropY").value);
const width = parseInt(document.getElementById("cropWidth").value);
const height = parseInt(document.getElementById("cropHeight").value);

These values are later used when applying the crop to the PDF page.

Supporting Predefined Crop Ratios

Many users don't want to manually enter crop coordinates every time they crop a document.

In real-world situations, documents often need to follow standard page dimensions. Instead of adjusting the crop area manually, users can quickly choose a predefined ratio and let the tool apply the appropriate crop settings automatically.

For example, a user preparing documents for printing may choose an A4 layout, while someone working with presentation slides may prefer a landscape format. Other users may simply want to remove margins while keeping the original page proportions intact.

A simple example looks like this:

function applyA4Portrait() {
  cropArea = {
    x: 0,
    y: 0,
    width: 595,
    height: 842
  };
}

This allows users to instantly apply a standard page size.

Selecting Pages to Crop

Not every page requires cropping. Some users may only want to crop a single page while leaving the rest of the document unchanged.

The tool supports three page selection modes:

Current page only:

const applyMode = "current";

All pages:

const applyMode = "all";

Specific page ranges:

const applyMode = "specific";
const pageRange = "1,3-5,10";

This gives users full control over where the crop should be applied.

Applying Crop Settings to PDF Pages

Once the crop values are finalized, the selected pages can be updated using PDF-lib.

A simplified example looks like this:

const pages = pdfDoc.getPages();

pages.forEach((page) => {
  page.setCropBox(
    cropArea.x,
    cropArea.y,
    cropArea.width,
    cropArea.height
  );
});

The crop box defines the visible area that will remain in the generated PDF.

Validating Crop Values

Before applying the crop, it's important to verify that users entered valid dimensions.

For example:

if (
  cropArea.width <= 0 ||
  cropArea.height <= 0
) {
  alert("Invalid crop size");
  return;
}

Validation helps prevent errors and ensures the final PDF is generated correctly.

After the crop settings are configured, users can proceed to generate the updated PDF and review the results before downloading the final document.

Applying the Crop

Once the crop settings are configured, users can apply the crop operation.

For example:

page.setCropBox(x, y, width, height);

The selected crop area is applied to the chosen pages before generating the updated document.

Here's what the crop action section looks like:

Generating the Cropped PDF

After cropping is complete, the browser generates a new PDF document containing only the selected page areas.

For example:

const pdfBytes = await pdfDoc.save();

The updated file can then be previewed and downloaded.

Why PDF Cropping Is Useful in Real-World Documents

PDF cropping is one of those features that seems simple at first, but it becomes incredibly useful once you start working with real-world documents.

Many PDFs contain content that users don't actually need. Scanned documents often include large white borders created by scanners. Screenshots converted into PDFs may contain unnecessary background areas. Reports and presentations frequently have oversized margins that waste space and make documents harder to read.

By cropping unwanted areas, users can focus attention on the content that actually matters. The final document becomes cleaner, easier to read, more professional, and often more suitable for printing.

PDF cropping is especially valuable in business environments where documents are processed in large quantities.

For example, many e-commerce sellers on platforms such as Flipkart, Amazon, Meesho, and other marketplaces regularly download shipping labels, invoices, and packing slips in PDF format.

Imagine receiving a PDF containing 100 shipping labels for customer orders. The downloaded file may include unnecessary margins, extra whitespace, instructions, or content outside the area that needs to be printed.

Instead of manually editing every page, users can define a crop area once and apply the same crop settings to all pages in the document. This automatically removes unwanted content from all 100 labels in a single operation.

The result is a cleaner PDF that contains only the information required for printing and packaging.

The same workflow is useful for:

• E-commerce packing slips

• Warehouse barcode sheets

• Courier documentation

• Invoices and billing documents

• Scanned contracts and agreements

• Academic research papers

• Government forms

• Business reports and presentations

• Construction drawings and engineering documents

• Training manuals and internal company documentation

Cropping can also significantly improve printing efficiency. When unnecessary margins are removed, the important content occupies more of the printable area, making labels, invoices, diagrams, and reports easier to read.

Another common use case involves scanned paperwork. Many scanner applications automatically capture extra background around a document. Cropping removes these unwanted edges and produces a cleaner digital copy without requiring image-editing software.

Because the crop area can be applied to the current page, all pages, or specific page ranges, users can process large PDF documents in seconds rather than manually editing pages one by one.

For businesses that handle hundreds of PDF files every week, this can save a significant amount of time while producing cleaner, more professional documents ready for sharing, printing, or archiving.

Demo: How the PDF Crop Tool Works

Step 1: Upload a PDF File

Users begin by uploading a PDF document into the browser.

The upload area supports drag-and-drop functionality and manual file selection.

Step 2: Preview the Uploaded PDF

After uploading the document, the browser displays a page preview.

Users can move between pages using the navigation controls.

A default crop selection area is displayed to simplify the cropping process.

Step 3: Configure Crop Settings

Users can fine-tune crop coordinates, choose predefined ratios, and select which pages should receive the crop.

The crop can be applied to a single page, all pages, or specific page ranges.

Step 4: Apply the Crop

Once everything is configured, users click the Crop PDF button.

The browser processes the selected pages and applies the crop settings.

Step 5: Preview the Cropped PDF

After processing is complete, users can preview the cropped document.

Page navigation controls allow users to review every cropped page before downloading.

Step 6: Download the Cropped PDF

The final section displays the generated file.

Users can rename the document, review file details such as total pages and file size, and download the cropped PDF.

A Start Over button is also available for processing another file.

Important Notes from Real-World Use

When working with large PDF files, processing may take longer depending on the number of pages.

Always validate uploaded files before loading them.

For example:

if (!file.name.endsWith(".pdf")) {
  alert("Please upload a PDF file");
  return;
}

Previewing pages before downloading helps catch cropping mistakes early.

Common Mistakes to Avoid

One common mistake is selecting crop coordinates that remove important document content.

Another mistake is applying a crop to all pages when only specific pages should be modified.

For example:

if (!cropArea) {
  alert("Select a crop area first");
  return;
}

Always review the cropped preview before downloading the final document.

Conclusion

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

You learned how to upload PDF files, preview pages, define crop areas, configure crop settings, apply cropping operations, generate updated PDFs, and download the final document directly from the browser.

More importantly, you saw how modern browsers can handle PDF editing tasks locally without requiring a backend server. This approach keeps document processing fast, private, and easy to use.

If you'd like to see a working example, try the AllinoneTools- PDF Crop Tool and explore how PDF pages can be cropped directly in the browser.

Once you understand this workflow, you can extend it further with features like PDF rotation, page organization, watermarking, metadata editing, annotations, and advanced PDF editing tools.

Modern browsers make this much easier than before.

Instead of uploading documents to a server, we can process PDF files directly inside the browser using JavaScript. This keeps the tool fast, private, and easy to use.

In this tutorial, you’ll build a browser-based PDF to image converter using JavaScript.

The tool will support uploading PDF files, previewing pages, selecting image formats like JPG or PNG, adjusting image quality, and downloading converted images directly from the browser.

Everything runs entirely client-side without any backend.

Table of Contents

1. How PDF to Image Conversion Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading the PDF File

6. Rendering PDF Pages as Images

7. Selecting Image Format and Quality

8. Generating and Downloading Images

9. Demo: How the PDF to Image Tool Works

10. Important Notes from Real-World Use

11. Common Mistakes to Avoid

12. Conclusion

How PDF to Image Conversion Works

A browser can't directly convert PDF files into images on its own.

Instead, JavaScript libraries render PDF pages onto an HTML canvas, which can then be exported as image files like JPG or PNG.

The process starts when users upload a PDF document into the browser. JavaScript then reads the file, renders each PDF page visually onto a canvas, converts those rendered pages into image files, and finally makes them available for download.

Everything happens locally inside the browser.

This means users don't need to upload private documents to external servers, making the process faster and more privacy-friendly.

Project Setup

This project is intentionally simple. Everything runs directly inside the browser using JavaScript, so no backend or server setup is required.

You only need:

• an HTML file

• a JavaScript file

• the PDF.js library

What Library Are We Using?

We’ll use Mozilla’s PDF.js library to render PDF pages inside the browser.

Add it using a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script>

Once loaded, the browser can read and render PDF pages directly using JavaScript.

Creating the Upload Interface

Start with a simple upload area:

<input type="file" id="pdfUpload" accept="application/pdf">

<select id="format">
  <option>JPG</option>
  <option>PNG</option>
  <option>WEBP</option>
</select>

<input type="range" id="quality" min="10" max="100" value="90">

<button onclick="convertPDF()">
  Convert to Images
</button>

This allows users to upload PDF files directly into the browser.

Here’s what the upload section looks like inside the tool:

Reading the PDF File

After the file is uploaded, we need to read it using JavaScript.

For example:

const file = document.getElementById("pdfUpload").files[0];

const reader = new FileReader();

reader.onload = async function () {
  const typedArray = new Uint8Array(reader.result);

  const pdf = await pdfjsLib.getDocument(typedArray).promise;

  console.log(pdf.numPages);
};

reader.readAsArrayBuffer(file);

This loads the PDF document directly inside the browser.

You can then access each page individually.

Rendering PDF Pages as Images

Once the PDF is loaded, pages can be rendered onto a canvas.

For example:

const page = await pdf.getPage(1);

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

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

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

canvas.width = viewport.width;
canvas.height = viewport.height;

await page.render({
  canvasContext: context,
  viewport: viewport
}).promise;

This renders the selected PDF page visually inside the browser.

After rendering, the canvas can be converted into an image.

For example:

const imageData = canvas.toDataURL("image/jpeg", 0.9);

This creates a downloadable image version of the PDF page.

Selecting Image Format and Quality

Before generating the final images, users may want to customize output settings.

Different image formats work better for different situations.

For example:

• JPG works well for smaller file sizes

• PNG preserves better quality

• WEBP offers modern compression

Users can also control image quality using a slider.

For example:

canvas.toDataURL("image/jpeg", 0.8);

The value 0.8 controls compression quality.

Here’s an example of image format and quality settings inside the tool:

Generating and Downloading Images

Once pages are rendered, images can be downloaded directly from the browser.

For example:

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

link.href = imageData;

link.download = `page-${pageNumber}.jpg`;

link.click();

This downloads the generated image instantly.

When working with multi-page PDFs, the same process can run for every page automatically.

This allows users to export complete PDF documents as separate image files.

Demo: How the PDF to Image Tool Works

For this example, we’ll convert PDF pages into downloadable image files directly inside the browser.

Step 1: Upload PDF Files

Users upload one or more PDF files into the converter.

Step 2: Preview Uploaded Pages

The tool generates page previews before conversion.

This helps users verify the uploaded document visually.

Step 3: Configure Output Settings

Users can choose image format and quality settings before generating images.

This allows better control over output size and image clarity.

Step 4: Convert PDF Pages into Images

Once settings are configured, users click the convert button.

The browser processes the PDF locally and generates image files instantly.

Step 5: Download Generated Images

After conversion, every PDF page becomes a downloadable image.

Important Notes from Real-World Use

When working with large PDFs, performance and memory usage become important.

Documents with many pages can slow down rendering if everything is processed at once.

One practical optimization is processing pages step-by-step instead of rendering the entire document immediately.

For example:

for (let i = 1; i <= pdf.numPages; i++) {
  const page = await pdf.getPage(i);

  // render page
}

This keeps browser memory usage more stable.

Another useful optimization is reducing render scale for large documents.

For example:

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

Lower scale values generate smaller image files and improve performance.

You can also resize generated images before export.

For example:

canvas.width = viewport.width;
canvas.height = viewport.height;

This helps reduce unnecessary file size growth.

Since everything runs locally inside the browser, uploaded PDF files never leave the user’s device, which improves privacy and security.

Common Mistakes to Avoid

One common mistake is not validating uploaded files before processing them.

For example:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file.");
  return;
}

This prevents unsupported files from breaking the tool.

Another issue is rendering extremely large pages at very high scale values.

Large canvas rendering can consume a lot of memory and slow down conversion significantly.

Using smaller scale values usually improves performance.

Another common mistake is forgetting to wait for page rendering before exporting the image.

For example:

await page.render({
  canvasContext: context,
  viewport: viewport
}).promise;

Without await, the image may export before rendering finishes.

Incorrect file naming can also confuse users when multiple pages are generated.

Adding page numbers to filenames improves organization:

link.download = `page-${pageNumber}.jpg`;

Conclusion

In this tutorial, you built a browser-based PDF to image converter using JavaScript.

You learned how to upload PDF files, render pages inside the browser, generate images, and download them directly without using a backend server.

More importantly, you saw how modern browsers can handle document processing tasks locally while keeping user files private.

This approach keeps the tool fast, lightweight, and easy to use.

Once you understand this workflow, you can extend it further with features like ZIP downloads, batch exports, page selection, watermarking, or image compression.

You can also try a real working version here:

https://allinonetools.net/pdf-to-image-converter/

And that’s where things start getting really interesting.

Most developers either rely on external tools or assume this requires backend processing. That’s usually where things get slower, more complex, and harder to maintain.

But modern browsers have quietly become powerful enough to handle this entirely on their own.

In this tutorial, you’ll build a barcode generator that runs completely in the browser. It won’t upload data anywhere, and it won’t require any server logic. Everything happens instantly on the client side.

Along the way, you’ll also learn how barcode formats work, how to validate inputs properly, and how to create a real-time preview experience that feels responsive and practical.

Table of Contents

1. How Barcode Generation Works

2. Project Setup

3. What Library Are We Using?

4. Creating the HTML Structure

5. Adding JavaScript for Barcode Generation

6. How the Barcode Is Generated

7. Types of Barcodes You Can Generate

8. Adding Real-Time Preview

9. How to Validate Input Properly

10. How to Download the Barcode

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Demo: How the Barcode Generator Works

14. Conclusion

How Barcode Generation Works

A barcode is simply a visual encoding of data. Instead of displaying text directly, it represents that data using a pattern of lines and spaces.

Different barcode formats use different encoding rules. Some support only numbers, while others allow full text input. When you generate a barcode in the browser, you’re essentially converting user input into a structured visual pattern.

The key idea here is that we don’t draw these lines manually. A library takes care of encoding the data and rendering it as an SVG element, which the browser can display instantly.

Project Setup

We’ll keep this project intentionally simple so the focus stays on understanding how it works.

All you need is a basic HTML file, a small JavaScript file, and a barcode library. There’s no backend involved, and nothing gets stored or uploaded.

This makes the tool fast, private, and easy to integrate into other projects.

What Library Are We Using?

In this project, we use the JsBarcode library.

It’s a lightweight JavaScript library that can generate barcodes directly inside the browser using SVG. It supports multiple formats and works without any external dependencies.

You can include it using a CDN:

<script src="https://cdn.jsdelivr.net/npm/jsbarcode@3.11.5/dist/JsBarcode.all.min.js"></script>

Creating the HTML Structure

The interface is simple but practical. It includes an input field where users can enter data, a dropdown to choose the barcode format, and a preview area where the barcode is rendered.

<input type="text" id="text" placeholder="Enter text or number">

<select id="format">
  <option value="CODE128">Code128</option>
  <option value="EAN13">EAN13</option>
</select>

<button onclick="generateBarcode()">Generate</button>

<svg id="barcode"></svg>

This structure is enough to handle input, display output, and connect everything through JavaScript.

Adding JavaScript for Barcode Generation

Now we'll connect the user input to barcode generation.

function generateBarcode() {
  const text = document.getElementById("text").value;
  const format = document.getElementById("format").value;

  if (!text) {
    alert("Please enter a value");
    return;
  }

  JsBarcode("#barcode", text, {
    format: format,
    width: 2,
    height: 100,
    displayValue: true
  });
}

This function reads the input, checks if it exists, and then generates the barcode using the selected format.

How the Barcode Is Generated

When you call the JsBarcode function, the library handles everything behind the scenes.

It encodes the input into a barcode standard, converts that into a pattern of lines, and renders it as an SVG element. Because SVG is vector-based, the barcode remains sharp even when resized.

All of this happens instantly in the browser, which is why the experience feels fast.

Types of Barcodes You Can Generate

Different barcode formats are used in different industries, and understanding them helps you build more practical tools.

1. Code128 is the most flexible format. It supports letters, numbers, and special characters, which makes it ideal for general-purpose use.

2. EAN-13 is commonly used in retail products. It works only with 13-digit numbers, so it requires strict validation.

3. UPC is similar to EAN and is widely used in billing systems, especially in the US. It also expects numeric input with a fixed length.

4. Code39 is simpler and supports uppercase letters and numbers, but it’s less compact compared to Code128.

5. ITF-14 is mostly used in logistics and packaging. It’s designed for numeric data and is common in shipping environments.

In most cases, starting with Code128 is the safest option unless you have a specific requirement.

Adding Real-Time Preview

One of the biggest improvements you can make to a tool like this is real-time feedback.

Instead of requiring users to click a button every time, you can generate the barcode as they type.

document.getElementById("text").addEventListener("input", generateBarcode);
document.getElementById("format").addEventListener("change", generateBarcode);

This small change makes the tool feel much more responsive.

As soon as the user types or changes the format, the barcode updates automatically. This is the same kind of interaction you see in polished production tools.

How to Validate Input Properly

Validation is where many simple tools break.

Since different barcode formats have different rules, if you don’t validate input correctly, the barcode may fail silently or produce incorrect output.

Here’s a simple example:

function isValidInput(text, format) {
  if (format === "EAN13") {
    return /^\d{13}$/.test(text);
  }

  if (format === "UPC") {
    return /^\d{12}$/.test(text);
  }

  return text.length > 0;
}

Then use it inside your generator:

if (!isValidInput(text, format)) {
  alert("Invalid input for selected format");
  return;
}

This ensures users get immediate feedback instead of confusion.

How to Download the Barcode

Once the barcode is generated, you can allow users to download it.

function downloadBarcode() {
  const svg = document.getElementById("barcode");
  const serializer = new XMLSerializer();
  const source = serializer.serializeToString(svg);

  const blob = new Blob([source], { type: "image/svg+xml" });
  const url = URL.createObjectURL(blob);

  const link = document.createElement("a");
  link.href = url;
  link.download = "barcode.svg";
  link.click();
}

This converts the SVG into a file that can be downloaded directly from the browser.

Important Notes from Real-World Use

When building tools like this in production, small details matter.

Large input values can sometimes affect readability, so it’s important to test how dense the barcode becomes. Choosing the right format also makes a difference depending on whether you need flexibility or strict standards.

Another important detail is rendering quality. Using SVG instead of raster formats ensures that the barcode remains sharp even when printed.

Common Mistakes to Avoid

One common issue is skipping validation. This leads to broken or unreadable barcodes, especially with strict formats like EAN or UPC.

Another mistake is relying too much on button-based interactions. Real-time updates create a much better user experience.

Finally, developers sometimes forget to include the library correctly, which leads to silent failures. Always verify that your CDN is loaded.

Demo: How the Barcode Generator Works

To better understand how everything comes together, here’s a quick walkthrough of how the tool works in the browser.

Step 1: Select a Barcode Type

Start by choosing the barcode format. In most cases, Code128 is a good default since it supports both text and numbers.

Step 2: Enter Your Data

Next, enter the value you want to encode. This could be a product ID, URL, or any text depending on the selected format.

Step 3: Customize the Design

You can adjust things like bar width, height, and colors. These settings help control how the barcode looks and how readable it is in different use cases.

Step 4: Generate and Preview

As you type or change settings, the barcode updates instantly. This real-time preview makes it easier to experiment and see results immediately.

Step 5: Download the Barcode

Once you're satisfied with the result, you can download the barcode in formats like PNG, JPG, or SVG.

This entire process happens in the browser, without uploading any data to a server.

Conclusion

In this tutorial, you built a browser-based barcode generator using JavaScript.

More importantly, you learned how to think about building tools that run entirely on the client side. This approach reduces complexity, improves performance, and gives users a faster experience.

Once you understand this pattern, you can apply it to many other tools like QR generators, image converters, and file processors.

And that’s where things start to get interesting.

Most developers use online tools for this. But there’s a problem: many of those tools upload your image to a server. That can be slow, and sometimes you don’t want to upload private files at all.

The good news is that modern browsers are powerful enough to handle image conversion locally using JavaScript.

In this tutorial, you’ll learn how to build a browser-based image converter that runs entirely in the browser. The tool converts images using JavaScript without uploading files to a server, and allows users to download the converted file instantly.

By the end, you’ll understand how browser-based file processing works and how to use it in your own projects.

Table of Contents

1. How Browser-Based Image Conversion Works

2. Project Setup

3. How to Read the Image File in JavaScript

4. How the Canvas Converts the Image

5. How the Download Works

6. Why This Approach Is Powerful

7. Important Notes from Real-World Use

8. Common Mistakes to Avoid

9. How You Can Extend This Project

10. Why Browser-Based Tools Are Becoming More Popular

11. Demo: How the Image Converter Works

12. Conclusion

How Browser-Based Image Conversion Works

Before writing code, you should understand what’s happening behind the scenes.

Modern browsers provide several APIs that make this possible. JavaScript can read local files from a user’s device, draw images on a canvas element, and export the processed image in a different format.

The key pieces we’ll use are:

• File input – to select an image

• FileReader – to read the file

• Canvas API – to redraw and convert

• toDataURL or toBlob – to export the converted image

The important thing is that everything happens locally in the user’s browser. Nothing gets uploaded anywhere.

Project Setup

We’ll keep this simple with just HTML and JavaScript.

Create an index.html file:

<!DOCTYPE html>
<html>
<head>
  <title>Image Converter</title>
</head>
<body>

<h2>Browser Image Converter</h2>

<input type="file" id="upload" accept="image/*">

<select id="format">
  <option value="image/png">PNG</option>
  <option value="image/jpeg">JPEG</option>
  <option value="image/webp">WebP</option>
</select>

<button onclick="convertImage()">Convert</button>

<br><br>

<a id="download" style="display:none;">Download Converted Image</a>

<script src="script.js"></script>

</body>
</html>

This simple interface includes a file upload input for selecting the image, a format selector for choosing the output format, a convert button to start the process, and a download link that appears once the image has been converted.

Now let’s add the logic.

How to Read the Image File in JavaScript

Create a script.js file:

function convertImage() {

  const fileInput = document.getElementById("upload");
  const format = document.getElementById("format").value;

  if (!fileInput.files.length) {
    alert("Please select an image");
    return;
  }

  const file = fileInput.files[0];
  const reader = new FileReader();

  reader.onload = function(event) {

    const img = new Image();

    img.onload = function() {

      const canvas = document.createElement("canvas");
      const ctx = canvas.getContext("2d");

      canvas.width = img.width;
      canvas.height = img.height;

      ctx.drawImage(img, 0, 0);

      const converted = canvas.toDataURL(format);

      const link = document.getElementById("download");

      link.href = converted;
      link.download = "converted-image";
      link.style.display = "inline";
      link.innerText = "Download Converted Image";

    };

    img.src = event.target.result;

  };

  reader.readAsDataURL(file);

}

This is the core of the image converter. Let’s break down what’s happening.

How the Canvas Converts the Image

This line draws the image:

ctx.drawImage(img, 0, 0);

Now the image exists inside the canvas.

This line converts it:

canvas.toDataURL(format);

This exports the image in the selected format.

For example:

• PNG → image/png

• JPEG → image/jpeg

• WebP → image/webp

This is where the conversion actually happens.

How the Download Works

This part creates the download:

link.href = converted;
link.download = "converted-image";

The browser treats it as a downloadable file. No server needed.

Why This Approach Is Powerful

This technique has several advantages.

• It’s fast: There is no upload time, and everything runs locally.

• It’s private: Files never leave the user’s device. This matters for sensitive images.

• It reduces server costs: You don’t need backend processing. No storage, and no processing servers.

Important Notes from Real-World Use

If you plan to build tools like this, here are a few practical things I’ve learned.

Large Images Use More Memory

Very large images can slow down the browser. If needed, you can resize images using Canvas.

JPEG Supports Quality Settings

You can control quality:

canvas.toDataURL("image/jpeg", 0.8);

This reduces file size.

WebP Usually Gives the Best Compression

WebP often produces smaller files than PNG or JPEG. It’s a good default option.

How to Resize an Image Using Canvas

If you need to reduce the size of large images, you can resize them before exporting.

After loading the image, you can set a smaller width and height on the canvas:

const canvas = document.createElement("canvas");
const ctx = canvas.getContext("2d");

const maxWidth = 800;
const scale = maxWidth / img.width;

canvas.width = maxWidth;
canvas.height = img.height * scale;

ctx.drawImage(img, 0, 0, canvas.width, canvas.height);

Common Mistakes to Avoid

Trying to Upload Files Unnecessarily

If processing can happen in the browser, do it there. It’s faster and simpler.

Forgetting Browser Compatibility

Most modern browsers support Canvas and FileReader. But always test.

Not Validating File Input Properly

Before processing the image, it’s important to validate the input file.

For example, you can check if a file is selected and ensure it is an image:

const file = fileInput.files[0];

if (!file) {
  alert("Please select a file.");
  return;
}

if (!file.type.startsWith("image/")) {
  alert("Please upload a valid image file.");
  return;
}

How You Can Extend This Project

Once this basic converter works, you can expand it with additional features. For example, you could add image resizing so users can adjust dimensions before downloading the converted file. Another useful improvement is implementing drag-and-drop uploads, which makes the interface more user-friendly.

You might also support multiple file uploads so users can convert several images at once. Adding compression controls would allow users to balance image quality and file size. Finally, you could include an image preview before download so users can confirm the result before saving the file.

All of these improvements rely on the same browser APIs used in this tutorial, so once you understand the core logic, extending the project becomes much easier.

Why Browser-Based Tools Are Becoming More Popular

Browsers today are far more capable than they used to be. Modern browser APIs allow developers to handle tasks that previously required server-side processing.

For example, browsers can now perform image processing, generate PDFs, convert files into different formats, and even handle some types of video processing directly on the client side.

Because of these capabilities, developers can build tools that run entirely inside the browser without relying on a backend server. This approach improves performance since users don’t have to upload files and wait for a server to process them.

It also improves privacy because files stay on the user’s device instead of being sent to a remote server. At the same time, it simplifies system architecture and makes applications easier to scale since there is no server infrastructure needed for file processing.

Demo: How the Image Converter Works

After building the project, here is what the tool looks like in the browser.

Upload an Image

First, the user uploads an image using the file upload area.

Select the Output Format

After uploading the image, the tool displays a preview along with details such as the image name, format, and file size. This helps users confirm that they uploaded the correct file before converting it.

Next, the user can choose the desired output format from the dropdown menu. The tool supports formats such as PNG, JPEG, WebP, GIF, and BMP, allowing the image to be converted into the format that best fits the user's needs.

Convert the Image

Once the format is selected, clicking the Convert All Images button processes the image directly in the browser.

Download the Converted Image

After conversion is complete, the tool generates a downloadable file.

Conversion Results

The tool can also display useful information such as original size, converted size, and space saved after compression.

Because everything happens in the browser using JavaScript and the Canvas API, the image never leaves the user's device.

Conclusion

In this tutorial, you built a browser-based image converter using JavaScript.

In this tutorial, you learned how to read local image files using JavaScript, process images using the Canvas API, convert them into different formats, and allow users to download the result directly from the browser.

This pattern is useful far beyond image conversion.

You can use the same approach for many browser-based tools.

Understanding how to use browser APIs like this opens up a lot of possibilities for building fast, efficient web applications.