A storyboard provides a more organized way to review this information. Instead of opening every page individually, users can arrange selected PDF pages into a single sheet containing multiple panels. Each panel can include a page number, a caption, and a visual preview of the original page.

In this tutorial, we'll explore how to build a browser-based PDF Storyboard Generator using JavaScript, PDF.js, and PDF-lib.

The application takes pages from an existing PDF and arranges them into printable storyboard sheets. Users can choose different layouts, select the pages they want to include, add captions, customize the appearance, preview the result, and download the finished storyboard.

The application runs directly in the browser. The uploaded PDF is processed locally rather than uploaded to the website's server.

We'll examine the implementation step by step, including PDF rendering, page selection, caption handling, layout calculations, preview generation, and file export.

What We'll Cover:

• What Is a PDF Storyboard Generator?
• Main Features of the Application
• Understanding the Browser-Based Workflow
• Project Setup
• Libraries Used
• Preparing the HTML Workspace
• Selecting the Main DOM Elements
• Defining Important Configuration Values
• Understanding the Application State
• Uploading a PDF
• Loading the PDF with PDF.js
• Measuring PDF Pages
• Rendering PDF Pages on Canvas
• Reusing Rendered Page Previews
• Reading Text from PDF Pages
• Filling Empty Captions Automatically
• Updating the Preview
• Choosing the Storyboard Layout
• Controlling Rows, Columns, and Paper Size
• Selecting PDF Pages and Their Order
• Adding Panel Labels
• Drawing the Storyboard Sheet
• Updating the Live Preview
• Adjusting Caption Appearance
• Navigating Between Storyboard Sheets
• Reading Scanned Pages with OCR
• Generating the Final Storyboard PDF
• Downloading PNG Storyboard Sheets
• Downloading Individual Page Pictures
• Performance and Important Considerations
• Demo: PDF Storyboard Generator
• Conclusion

What Is a PDF Storyboard Generator?

A PDF Storyboard Generator converts selected pages from an existing PDF into a structured visual sheet.

For example, imagine that you have a PDF containing 20 presentation slides. Instead of sharing all 20 slides separately, you can arrange them into a storyboard containing three columns and two rows per sheet.

Each panel displays a scaled version of its original PDF page. You can also add a number or label and write a short description underneath.

The same approach can be useful for:

• Reviewing presentation slides.
• Organizing comic pages.
• Planning video scenes.
• Preparing visual scripts.
• Reviewing scanned documents.
• Creating printable teaching materials.
• Organizing page sequences for creative projects.

The application doesn't create new scenes or draw illustrations. It arranges existing PDF pages into a storyboard layout.

Main Features of the Application

Before writing the code, let's understand the features we're going to implement.

1. PDF Upload

Users can select a PDF from their device or drag and drop it into the upload area.

2. Multiple Storyboard Layouts

The application supports three layouts:

• Grid: Arranges pages in rows and columns.
• Panels with notes: Provides space for written notes alongside the page panels.
• Film strip: Arranges pages in a film-strip style.

3. Page Selection and Ordering

Users can choose which PDF pages should appear in the storyboard. They can also specify a custom order rather than following the original PDF sequence.

4. Captions

Users can type captions manually, fill empty captions using extracted PDF page text, or use OCR to read text from scanned pages.

5. Customization

Users can customize the paper size, orientation, number of columns and rows, panel labels, sheet colors, caption font, text size, spacing, and panel frames.

6. Live Preview

The application generates a preview of the storyboard sheets. Users can review the arrangement before downloading the final output.

7. Multiple Export Formats

Users can export their work as:

• A PDF storyboard.
• PNG storyboard sheets.
• A ZIP file containing individual page pictures.

The PDF export preserves original page content as vectors when possible, helping maintain sharp text and graphics.

Understanding the Browser-Based Workflow

The application follows a straightforward process.

1. The user selects or drops a PDF file into the upload area.
2. PDF.js loads the document and renders its pages.
3. The application displays page previews and caption fields.
4. The user selects pages, changes their order, and enters captions.
5. The user configures the storyboard layout and appearance.
6. JavaScript calculates the position and dimensions of every panel.
7. The preview is updated to reflect the selected settings.
8. PDF-lib and browser canvas functionality are used to generate the requested output.
9. The browser downloads the finished file.

PDF Upload Workspace

Panels and Captions

Board Settings and Preview

Final Storyboard Preview

Downloaded PDF

Project Setup

Before writing the JavaScript functionality, we need to understand how the application is organized.

The PDF Storyboard Generator combines HTML, CSS, and JavaScript. HTML provides the interface, CSS controls the appearance of the workspace and storyboard sheets, and JavaScript handles PDF processing, page previews, captions, layout calculations, and downloads.

For a standalone development project, we can organize the files like this:

pdf-storyboard-generator/
├── index.html
├── style.css
├── script.js
└── assets/

The index.html file contains the application structure, including the upload area, page panels, caption fields, board settings, and preview.

The style.css file controls the appearance of the application. It defines the workspace, panel grid, form controls, buttons, preview area, and responsive layout.

The script.js file contains the main application logic. It loads PDF documents, renders their pages, manages captions, processes OCR requests, calculates storyboard layouts, and generates downloadable files.

The assets directory can hold any additional local resources required by the project.

In the existing AllInOneTools implementation, these components are integrated into the website's tool page rather than being deployed as four separate files. The same separation of responsibilities still applies.

Libraries Used

The application uses three main JavaScript libraries or browser technologies for its PDF and image-processing workflow.

1. PDF.js

We'll use PDF.js to open PDF documents and render their pages inside the browser.

It allows JavaScript to access individual pages, retrieve their dimensions, create viewports, and draw page content onto an HTML canvas.

For this project, PDF.js is responsible for the original PDF page previews.

The application uses the PDF.js document API to retrieve pages and render them at the required dimensions. This is important because the storyboard must display a visual representation of each selected page before the user downloads the finished sheet.

2. PDF-lib

We'll use PDF-lib used when generating the final PDF document.

PDF.js and PDF-lib have different responsibilities. PDF.js reads and renders the source document, while PDF-lib creates the new storyboard PDF.

The application uses PDF-lib to create output pages, embed the original PDF pages when possible, and place the finished storyboard elements onto those pages.

Keeping the original PDF pages as vector content helps preserve text and line quality when users zoom in or print the exported document. The implementation also uses a raster-based fallback for password-protected PDFs that can't be loaded through the regular PDF embedding path.

3. Tesseract.js

This library provides optional Optical Character Recognition (OCR).

Not every PDF contains selectable text. A scanned document, for example, may contain photographs of printed pages instead of actual text data.

When the user selects the OCR option, the application loads Tesseract.js and its English language data. It then processes eligible scanned pages and attempts to extract their text for captions.

OCR is optional, so users don't need to load the OCR engine when they only want to arrange PDF pages and write captions manually.

The following example illustrates how a standalone project could include the libraries through CDN scripts:

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

For a production application, use library versions that you've tested and configure the matching PDF.js worker file as required by your chosen PDF.js build.

Why These Libraries Work Together

Each library has a separate responsibility.

PDF.js reads the source PDF and renders its pages. Tesseract.js optionally extracts text from scanned pages. PDF-lib creates the final storyboard PDF.

JavaScript connects these operations and manages the user interface.

This separation makes the application easier to understand and maintain. It also avoids using one library for tasks that are better handled by another.

Preparing the HTML Workspace

The interface needs several areas to support the complete storyboard workflow.

The upload area accepts the source PDF. The panel area displays rendered pages and caption fields. The board settings area contains layout and appearance controls. Finally, the preview area displays the generated storyboard sheets.

A simplified HTML structure looks like this:

<section id="aiot-sb">
    <div id="aiot-sb-drop">
        <input
            type="file"
            id="aiot-sb-file-input"
            accept="application/pdf,.pdf"
        >
        <button type="button" data-act="browse">
            Select a PDF
        </button>
    </div>
    <div id="aiot-sb-grid"></div>
    <div id="aiot-sb-settings"></div>
    <div id="aiot-sb-preview"></div>
</section>

This is an illustrative structure showing the main interface areas. The actual application contains additional controls, accessibility attributes, and elements for its different operations.

The aiot-sb container provides a common root for the application. JavaScript can use this root to find the relevant interface elements without searching the entire website.

Selecting the Main DOM Elements

JavaScript needs references to the interface elements before it can respond to user actions.

The application starts by finding its root container and checking whether initialization has already taken place:

var root = document.getElementById("aiot-sb");
if (!root || root.getAttribute("data-aiot-sb-ready")) {
    return;
}
root.setAttribute("data-aiot-sb-ready", "1");

This prevents the application from initializing again if the script is executed more than once.

The implementation uses a small helper to find elements inside the application:

function q(selector) {
    return root.querySelector(selector);
}

For example, q('[data-act="browse"]') finds the button used to open the PDF file picker.

Using a root-specific helper also helps keep the application code organized when the website contains other tools or interface components.

Defining Important Configuration Values

The application needs a few shared configuration values for its layouts and output settings.

For example, it defines supported paper dimensions and font families:

var MM = 72 / 25.4;
var PAPERS = {
    a4: [595.28, 841.89],
    letter: [612, 792],
    a3: [841.89, 1190.55],
    slide: [405, 720]
};
var PAPER_NAMES = {
    a4: "A4",
    letter: "Letter",
    a3: "A3",
    slide: "16:9 slide"
};

PDF page dimensions are commonly expressed in points, while some of the storyboard spacing settings are easier to understand in millimeters. The MM conversion value helps translate between these units.

The PAPERS object stores the available page dimensions. The application can use these values when calculating the size of each storyboard sheet.

The PAPER_NAMES object provides readable labels for the corresponding settings.

The application also defines font families for captions and other text:

var FONTS = {
    sans: "Arial, 'Helvetica Neue', Helvetica, sans-serif",
    serif: "Georgia, 'Times New Roman', serif",
    mono: "'Courier New', Courier, monospace",
    hand: "'Segoe Print', 'Bradley Hand', cursive"
};

These values allow the storyboard renderer to use different text styles without repeating font definitions throughout the code.

Understanding the Application State

The application needs to remember information about the currently loaded PDF, its pages, captions, selected layout, and export process.

Instead of relying on individual variables scattered throughout the application, the implementation groups related information into a shared state object.

For example, the application tracks information such as:

• The loaded PDF document.
• The original PDF bytes.
• The current filename.
• Page captions.
• Page preview data.
• Loading and export status.
• The OCR worker when OCR is active.
• Cancellation and loading tokens.

The actual implementation manages these values within its application state and uses them throughout the rendering and export functions.

This becomes especially important when the user changes a caption or layout setting. The application needs to know which values have changed so it can update the storyboard preview without unnecessarily reopening the source document.

Uploading a PDF

The first step is allowing users to select a PDF from their device. The PDF Storyboard Generator supports two methods: selecting a file through the file picker or dragging and dropping it into the upload area.

The file input uses the following HTML:

<input
    type="file"
    id="aiot-sb-file-input"
    accept="application/pdf,.pdf"
>

Let's understand the accept attribute:

• application/pdf is the MIME type for PDF files.
• .pdf is the file extension.

A MIME type (Multipurpose Internet Mail Extensions type) identifies the format of a file. Browsers use MIME types to describe the kind of content a file contains. For example, application/pdf identifies a PDF document.

The application checks both the MIME type and the filename extension. This is useful because some browsers or operating systems may provide an empty or incorrect MIME type for a selected file.

The actual application uses this helper:

function isPdf(file) {
    return file.type === 'application/pdf' ||
        /\.pdf$/i.test(file.name || '');
}

The first condition checks the file's MIME type. The second checks whether its filename ends with .pdf. The i flag makes the extension check case-insensitive, so filenames such as document.PDF are also accepted.

After validation, both upload methods use the same handleFiles() function. Its initial steps are:

function handleFiles(list, password) {
    var all = Array.prototype.slice.call(list || []);
    ui.input.value = '';

    if (!all.length) {
        return Promise.resolve();
    }

    var file = all.filter(isPdf)[0];

    if (!file) {
        toast("That isn't a PDF. Choose a PDF file.", 'error');
        return Promise.resolve();
    }

    var note = all.length > 1
        ? ' Only ' + file.name + ' was opened; a storyboard uses one PDF.'
        : '';

    var token = ++state.loadToken;
    var hadDoc = !!state.doc;
    var task, bytes;

    if (hadDoc) {
        ui.fileMeta.textContent = 'Opening ' + file.name + '…';
    }

    setStatus('Opening ' + file.name + '…', true);

    // The remaining function loads and processes the selected PDF.
}

The function converts the supplied file list into an array and selects the first valid PDF. If no valid PDF is found, it displays an error message and stops.

The loadToken value helps the application distinguish the current loading operation from an older one. This matters when a user selects another document while a previous document is still being processed.

Next, the application waits for the PDF libraries to become available and reads the selected file:

return engine().then(function () {
    return file.arrayBuffer();
}).then(function (buf) {
    bytes = buf;

    var opts = {
        data: new Uint8Array(buf.slice(0))
    };

    if (password) {
        opts.password = password;
    }

    task = window.pdfjsLib.getDocument(pdfjsOptions(opts));
    return task.promise;
});

The file.arrayBuffer() method reads the PDF into browser memory. The application converts the data into a Uint8Array and passes it to PDF.js through getDocument().

If a password was supplied, it's added to the PDF.js options before the document is opened.

The complete function continues by measuring the PDF pages, checking whether the original pages can be embedded as vectors, updating the application state, and displaying the workspace.

This means the selected PDF is processed in the browser. It isn't uploaded to the website's server.

Loading the PDF with PDF.js

Once a file has been selected, the application reads its contents and passes the data to PDF.js.

The PDF.js loading process returns a document object. This object provides access to the document's pages and metadata.

In the actual application, PDF.js is initialized inside the file-loading process. The application first waits for the PDF libraries to load, reads the selected file, and then passes its data to PDF.js.

return engine().then(function () {
    return file.arrayBuffer();
}).then(function (buf) {
    bytes = buf;

    var opts = {
        data: new Uint8Array(buf.slice(0))
    };

    if (password) {
        opts.password = password;
    }

    task = window.pdfjsLib.getDocument(pdfjsOptions(opts));
    return task.promise;
});

The engine() function ensures that the required PDF libraries are available before processing begins. The application then uses file.arrayBuffer() to read the selected PDF into browser memory.

The Uint8Array constructor converts the file data into a format that PDF.js can process. If the user has supplied a password, it's added to the PDF.js options before the document is opened.

The getDocument() method starts the PDF loading process, and task.promise resolves when PDF.js has successfully opened the document.

The resulting document object provides access to the PDF's pages and metadata. The application stores this document for later operations, including measuring pages, extracting text, rendering previews, and generating the storyboard.

Measuring PDF Pages

Before arranging pages into storyboard panels, the application needs to know their dimensions.

PDF documents can contain pages with different sizes and orientations. Measuring each page helps the layout engine fit it correctly inside its panel.

The actual application uses the pageFacts() function to measure every page and periodically update the interface while processing large PDFs.

async function pageFacts(doc, token) {
    var sizes = [];

    for (var n = 1; n <= doc.numPages; n++) {
        if (token !== state.loadToken) {
            return null;
        }

        if (n % 25 === 0) {
            setStatus(
                'Measuring pages: ' + n + ' of ' + doc.numPages + '…',
                true
            );
            await nextFrame();
        }

        var p = await doc.getPage(n);
        var vp = p.getViewport({ scale: 1 });

        sizes.push([vp.width, vp.height]);
    }

    return sizes;
}

The function starts by creating an empty sizes array. It then loops through all pages using doc.numPages and retrieves each page with doc.getPage(n).

The getViewport({ scale: 1 }) method measures the page at its original scale. The function stores the resulting width and height in the sizes array.

The token parameter helps prevent an outdated loading operation from continuing. If the current token no longer matches state.loadToken, the function stops and returns null.

For larger PDFs, the application updates the loading status after every 25 pages and calls nextFrame() to give the browser an opportunity to update the interface.

Finally, the function returns the array containing the dimensions of all measured pages. These measurements are used later by the storyboard layout calculations.

Rendering PDF Pages on Canvas

The next task is displaying the PDF pages in the workspace.

PDF.js can render an individual page onto an HTML canvas. The canvas provides a visual representation that can be used in the page cards and storyboard preview.

The core rendering function looks like this:

async function renderPage(n, w, h) {
    var page = await state.doc.getPage(n);
    var b = page.getViewport({ scale: 1 });

    var vp = page.getViewport({
        scale: Math.min(w / b.width, h / b.height)
    });

    var c = document.createElement('canvas');
    c.width = Math.max(1, Math.round(vp.width));
    c.height = Math.max(1, Math.round(vp.height));

    var g = c.getContext('2d');
    g.fillStyle = '#FFFFFF';
    g.fillRect(0, 0, c.width, c.height);

    await page.render({
        canvas: c,
        canvasContext: g,
        viewport: vp
    }).promise;

    return c;
}

The function accepts three parameters: n is the PDF page number, while w and h define the available width and height for the preview.

First, state.doc.getPage(n) retrieves the requested PDF page. The function then creates a viewport at scale 1 to obtain the page's original dimensions.

Next, Math.min(w / b.width, h / b.height) calculates a scale that fits the page inside the available space without changing its proportions.

The function creates an HTML canvas and sets its width and height using the calculated viewport dimensions. It fills the canvas with white before rendering the PDF page.

Finally, page.render() draws the page onto the canvas. The function waits for rendering to finish and returns the completed canvas for use in the page previews and storyboard.

Reusing Rendered Page Previews

Rendering the same PDF page repeatedly can consume unnecessary processing time. For example, a page might be rendered once for its card preview and again when the storyboard preview is updated.

The application uses a page-picture cache to reuse previously rendered canvases.

var picCache = new Map();

// For the preview: reuse a page picture when one at least as big is already made.
async function cachedPic(n, w, h) {
    var got = picCache.get(n);

    if (got && got.w >= w * 0.92) {
        picCache.delete(n);
        picCache.set(n, got);
        return got.c;
    }

    var c = await renderPage(
        n,
        Math.ceil(w * 1.15),
        Math.ceil(h * 1.15)
    );

    picCache.set(n, { c: c, w: c.width });

    while (picCache.size > 60) {
        var old = picCache.keys().next().value;
        picCache.get(old).c.width = 1;
        picCache.delete(old);
    }

    return c;
}

The application stores rendered page previews in a JavaScript Map called picCache. Each entry contains the rendered canvas and its width.

When cachedPic() is called, it first checks whether a cached image exists for the requested page. If the cached image is at least 92% of the requested width, the application reuses it instead of rendering the page again.

The function moves a reused entry to the end of the Map. This helps the application keep recently used previews available.

If a suitable cached image isn't available, the function calls renderPage() to create a new canvas. It renders the page at 1.15 times the requested width and height, providing some extra resolution for the preview.

To control memory usage, the cache is limited to 60 entries. When that limit is exceeded, the oldest entry is removed, and its canvas width is reduced to 1 to release its drawing resources.

This caching approach avoids unnecessary PDF rendering while keeping memory usage under control, especially when users work with longer documents.

Reading Text from PDF Pages

The storyboard generator can create captions in three ways:

1. The user writes captions manually.
2. The application extracts text from the PDF.
3. OCR reads text from scanned pages.

For PDFs containing selectable text, PDF.js provides the getTextContent() method.

The actual application uses the readTexts() function to extract and store text from every page in the loaded PDF.

async function readTexts(token) {
    var doc = state.doc, out = [];

    for (var n = 1; n <= doc.numPages; n++) {
        if (token !== state.loadToken) {
            return;
        }

        try {
            var tc = await (await doc.getPage(n)).getTextContent();

            out.push(tc.items.map(function (it) {
                return (it.str || '') + (it.hasEOL ? '\n' : '');
            }).join(''));
        } catch (e) {
            out.push('');
        }

        if (n % 20 === 0) {
            await nextFrame();
        }
    }

    if (token !== state.loadToken) {
        return;
    }

    state.texts = out;
    refreshTags(board());
}

The function starts by accessing the loaded PDF document through state.doc and creating an empty array called out to store the extracted text.

It then loops through every page and calls getTextContent() to retrieve its text items. The map() method combines each item's text into a single string. It also adds a newline when the PDF.js item indicates the end of a line through hasEOL.

If text extraction fails for a page, the function adds an empty string to the results instead of stopping the entire process.

The token check prevents an older PDF-loading operation from updating the current application state. The function also calls nextFrame() after every 20 pages to give the browser an opportunity to update the interface.

After processing all pages, the extracted text is stored in state.texts. The application then calls refreshTags(board()) to update the page information displayed in the workspace.

This stored text is used later when users choose to fill empty captions automatically.

Filling Empty Captions Automatically

Once the application has extracted text from the PDF pages, it can use that text to create captions.

The important behaviour is that the application fills only empty caption fields. It doesn't overwrite captions that users have already entered.

The application uses the captionFromText() helper to clean and shorten the extracted text:

function captionFromText(t) {
    var s = String(t || '')
        .replace(/\s+/g, ' ')
        .trim();

    if (letters(s) < 3) {
        return '';
    }

    if (s.length <= 200) {
        return s;
    }

    var cut = s.slice(0, 200);
    var end = Math.max(
        cut.lastIndexOf('. '),
        cut.lastIndexOf('? '),
        cut.lastIndexOf('! '),
        cut.lastIndexOf('। ')
    );

    return end > 60
        ? cut.slice(0, end + 1)
        : cut.replace(/\s+\S*$/, '') + '…';
}

Here's what this function does:

1. Converts the supplied value into a string.
2. Replaces repeated whitespace with single spaces and removes whitespace from the beginning and end.
3. Checks whether the text contains enough letters to be useful as a caption.
4. Returns the complete text if it contains no more than 200 characters.
5. For longer text, tries to end the caption at a sentence boundary. If there isn't a suitable boundary, it removes the incomplete final word and adds an ellipsis.

The application then uses fillFromText() to apply the generated captions to the selected storyboard pages.

function fillFromText() {
    var bd = board(), list = bd.error ? [] : unique(bd.list), filled = 0, scans = 0;

    list.forEach(function (n) {
        if (captionFor(n)) { return; }

        var c = captionFromText(state.texts[n - 1]);

        if (c) {
            state.captions[n] = c;
            filled++;

            var ta = ui.grid.querySelector('[data-cap="' + n + '"]');
            if (ta) { ta.value = c; }
        } else if (isScan(n)) {
            scans++;
        }
    });

    if (!state.opts.captions && filled) {
        state.opts.captions = true;
        savePrefs();
    }

    redrawSoon(0);

    if (!list.length) {
        toast(bd.error || 'No pages on the board.', 'error');
        return;
    }

    toast(
        filled
            ? plural(filled, 'caption', 'captions') +
              ' filled from the page text. Edit them in the cards below.' +
              (scans
                  ? ' ' + plural(scans, 'scanned page has', 'scanned pages have') +
                    ' no text; use OCR for ' + (scans === 1 ? 'it' : 'them') + '.'
                  : '')
            : scans
                ? 'The empty pages are scans with no text. Use Read with OCR.'
                : 'Every panel already has a caption.'
    );
}

The fillFromText() function starts by calling board() to get the currently selected storyboard pages. It uses unique() to avoid processing the same page more than once.

For each selected page, captionFor(n) checks whether a caption already exists. If one is present, the function skips that page so the user's existing caption isn't overwritten.

If the caption is empty, the function retrieves the extracted text from state.texts and passes it to captionFromText(). When useful text is available, it saves the generated caption in state.captions and updates the corresponding textarea in the page card.

If a page has no extractable text and is identified as a scan, the function increases the scanned-page counter. Users can process these pages separately using OCR.

Finally, the application enables captions if necessary, saves the updated preferences, and schedules a preview refresh. It also displays a message showing how many captions were filled or whether OCR is needed.

This allows users to generate starting captions automatically while keeping their manually written descriptions intact.

Updating the Preview

Whenever a caption or relevant setting changes, the storyboard preview needs to be refreshed.

The application uses a small scheduling function to avoid redrawing the preview immediately after every individual change:

function redrawSoon(ms) {
    clearTimeout(drawTimer);
    drawTimer = setTimeout(
        drawPreview,
        ms === undefined ? 120 : ms
    );
}

The redrawSoon() function first cancels any previously scheduled preview update using clearTimeout(). It then schedules drawPreview() using setTimeout().

By default, the application waits 120 milliseconds before refreshing the preview. If another change happens during that time, the previous scheduled redraw is cancelled and a new one is scheduled.

This helps prevent unnecessary repeated rendering when users are typing captions or adjusting settings.

Drawing the Updated Preview

Once the redraw is scheduled, the drawPreview() function calculates the current storyboard configuration and updates the visible preview canvas.

The following is the actual implementation from the application:

async function drawPreview() {
    if (!state.doc) { return; }

    var my = ++drawToken, bd = board();
    refreshTags(bd);
    syncPanel();

    if (bd.error) {
        ui.boardMsg.textContent = bd.error;
        ui.sheetPos.textContent = 'No sheets';
        ui.sheetCount.textContent = '';
        root.querySelectorAll('[data-needs-board]').forEach(function (b) {
            b.disabled = true;
        });
        return;
    }

    root.querySelectorAll('[data-needs-board]').forEach(function (b) {
        b.disabled = state.busy;
    });

    var L = bd.L, o = state.opts;
    state.sheet = clamp(state.sheet, 0, L.sheets - 1);

    ui.boardMsg.textContent = L.tight
        ? 'Captions leave little room for the pages. Use fewer caption lines, fewer rows or a smaller text size.'
        : '';

    ui.sheetPos.textContent = 'Sheet ' + (state.sheet + 1) + ' of ' + L.sheets;
    ui.sheetCount.textContent =
        plural(bd.list.length, 'panel', 'panels') + ' on ' +
        plural(L.sheets, 'sheet', 'sheets') + ', ' +
        PAPER_NAMES[o.paper] + ' ' + o.orient;

    q('[data-act="sheet-prev"]').disabled = state.sheet <= 0;
    q('[data-act="sheet-next"]').disabled = state.sheet >= L.sheets - 1;

    ui.sheetWrap.style.aspectRatio = L.W + ' / ' + L.H;

    var cssW = ui.sheetWrap.clientWidth || 600;
    var dpr = Math.min(window.devicePixelRatio || 1, 2);
    var k = cssW * dpr / L.W;

    var off = document.createElement('canvas');
    off.width = Math.round(L.W * k);
    off.height = Math.round(L.H * k);

    var done = await drawSheet(
        off.getContext('2d'),
        o,
        bd.list,
        L,
        state.sheet,
        k,
        'full',
        function (n, w, h) {
            return my === drawToken
                ? cachedPic(n, w, h)
                : Promise.resolve(null);
        }
    );

    if (!done || my !== drawToken) { return; }

    ui.sheet.width = off.width;
    ui.sheet.height = off.height;
    ui.sheet.getContext('2d').drawImage(off, 0, 0);

    off.width = 1;

    var start = state.sheet * L.per;
    var on = bd.list.slice(start, start + L.per);

    ui.sheet.setAttribute(
        'aria-label',
        'Sheet ' + (state.sheet + 1) + ' of ' + L.sheets + ': ' +
        (on.length === 1 ? 'page ' + on[0] : 'pages ' + on.join(', '))
    );

    ui.sheet.setAttribute('data-drawn', String(state.sheet + 1));
}

The function first checks whether a PDF document is loaded. It then calls board() to retrieve the selected pages and calculate the storyboard layout.

The drawToken value helps prevent an older preview-rendering operation from replacing a newer one. The function also calls refreshTags() and syncPanel() to update the page information and settings panel.

Next, it checks whether the selected board has any errors. If the selection is valid, it calculates the current sheet position and updates the sheet counter, panel count, paper information, and Previous and Next buttons.

The function then calculates the canvas scale using the available preview width and the device pixel ratio. The device pixel ratio is capped at 2 to limit the amount of rendering work.

The drawSheet() function draws the selected storyboard sheet onto a temporary canvas. It receives cachedPic() as a callback so previously rendered PDF page previews can be reused.

After drawing finishes, the function checks whether the operation is still current. If it is, the completed temporary canvas is copied onto the visible preview canvas.

Finally, the temporary canvas is released by reducing its width to 1. The application also updates the preview's accessibility label and records which sheet has been drawn.

This process allows users to see their storyboard changes without downloading a new PDF every time they adjust a caption or setting.

Choosing the Storyboard Layout

The tool supports three layout styles: Grid, Panels with notes, and Film strip. Each layout is designed for a different type of project.

Grid layout arranges PDF pages in rows and columns. It works well for reviewing presentation slides, comic pages, and documents.

Panels with notes provides additional writing space below each page. It's useful for lecture notes, planning, and reviewing visual material.

Film strip arranges pages as a sequence of frames. It's useful for planning videos, reels, and scenes.

The selected layout is stored in the application's state. When users choose a different layout, the application updates the number of columns and rows to provide suitable default settings.

The following excerpt from the actual onField() function handles layout changes:

if (f === 'layout' && e.type === 'change') {
    // sensible panel counts for each layout
    if (o.layout === 'notes') {
        o.cols = o.orient === 'landscape' ? 2 : 1;
        o.rows = o.orient === 'landscape' ? 3 : 4;
    }

    if (o.layout === 'strip') {
        o.cols = 4;
        o.rows = o.orient === 'landscape' ? 2 : 4;
    }

    if (o.layout === 'grid') {
        o.cols = o.orient === 'landscape' ? 3 : 2;
        o.rows = o.orient === 'landscape' ? 2 : 3;
    }
}

savePrefs();

if (f === 'cols' || f === 'rows' || f === 'layout') {
    state.sheet = 0;
}

redrawSoon(f === 'gap' ? 60 : 0);

This code checks which layout the user has selected and adjusts the default column and row counts according to the layout and paper orientation.

For example:

• Panels with notes: Uses 2 columns and 3 rows in landscape orientation, or 1 column and 4 rows in portrait orientation.
• Film strip: Uses 4 columns, with 2 rows in landscape orientation or 4 rows in portrait orientation.
• Grid: Uses 3 columns and 2 rows in landscape orientation, or 2 columns and 3 rows in portrait orientation.

After updating these values, savePrefs() saves the settings. The application resets the current sheet to the first sheet when the layout changes and calls redrawSoon() to refresh the preview.

Users can still adjust the number of rows and columns manually using the board settings.

Controlling Rows, Columns, and Paper Size

Users can choose between 1 and 6 columns and rows per sheet. This gives them control over how many PDF pages appear together.

The application also supports different paper sizes, including A4, Letter, A3, and a 16:9 slide format. Each format can be displayed in portrait or landscape orientation.

For example, a 3-column and 2-row layout can display six PDF pages on one sheet. A 4-column and 3-row layout can display twelve pages.

The application calculates the number of panels that fit on each sheet by multiplying the selected columns by the selected rows. It then determines how many sheets are needed for all selected pages.

The following function from the actual application calculates the sheet dimensions based on the selected paper size and orientation:

function sheetSize(o) {
    var p = PAPERS[o.paper] || PAPERS.a4;
    var a = Math.min(p[0], p[1]);
    var b = Math.max(p[0], p[1]);

    return o.orient === 'portrait' ? [a, b] : [b, a];
}

The PAPERS object contains the dimensions for each supported paper format. The function retrieves the selected dimensions and arranges them according to the chosen orientation.

For portrait orientation, the shorter dimension becomes the width and the longer dimension becomes the height. For landscape orientation, these dimensions are reversed.

The layout calculation then uses the selected rows and columns to determine the number of panels per sheet:

var per = o.cols * o.rows;
var sheets = Math.max(1, Math.ceil(list.length / per));

Here, per represents the number of panels on one sheet. The Math.ceil() function rounds up the total number of required sheets so that any remaining pages are placed on an additional sheet.

The layout engine also calculates the available space and positions each panel so that the pages fit within the selected sheet dimensions.

When more pages are selected than can fit on one sheet, the remaining panels are placed on additional sheets.

Selecting PDF Pages and Their Order

Users don't always need every page in the original PDF.

The tool supports using all pages, selecting a page range, or entering a custom page sequence.

For example, a user could enter:

1-4, 9, 6

This creates a storyboard using pages 1, 2, 3, 4, 9, and 6 in that exact order.

The application uses the parseList() function to process the custom page selection and check whether the requested page numbers are valid.

Here is the actual implementation from the application:

function parseList(text) {
    var t = String(text || '').trim();

    if (!t) {
        return { error: 'Type the pages, for example 1-4, 7, 5.' };
    }

    var out = [], parts = t.split(/[,;\s]+/).filter(Boolean);

    for (var i = 0; i < parts.length; i++) {
        var part = parts[i],
            m = /^(\d+)(?:\s*[-–]\s*(\d*))?$/.exec(part);

        if (!m) {
            return { error: '"' + part + '" isn\'t a page number or range.' };
        }

        var a = parseInt(m[1], 10),
            b = m[2] === undefined
                ? a
                : (m[2] === '' ? state.count : parseInt(m[2], 10));

        if (a < 1) {
            return { error: 'Pages start at 1, so "' + part + '" doesn\'t work.' };
        }

        if (b < a) {
            return { error: '"' + part + '" is backwards. Did you mean ' + b + '-' + a + '?' };
        }

        if (a > state.count) {
            return {
                error: 'Page ' + a + ' is past the end; this PDF has ' +
                    plural(state.count, 'page', 'pages') + '.'
            };
        }

        if (b > state.count) {
            return {
                error: 'Page ' + b + ' is past the end. Type ' + a +
                    '- to go to the last page.'
            };
        }

        for (var n = a; n <= b; n++) {
            out.push(n);
        }
    }

    if (out.length > 500) {
        return { error: 'That\'s ' + out.length + ' panels. Use 500 or fewer.' };
    }

    return { pages: out };
}

The function first converts the input into a trimmed string. It then splits the selection using commas, semicolons, or spaces.

The regular expression checks whether each entry is a single page number or a page range. For example, 3 represents page 3, while 2-5 represents pages 2 through 5.

The function also supports an open-ended range such as 4-. In this case, the application uses state.count as the final page number.

Before adding pages to the result, it checks that page numbers start at 1, ranges are in ascending order, and no requested page exceeds the total number of pages in the PDF.

The application also limits custom selections to 500 panels. If the input is valid, the function returns an array of page numbers in the exact order entered by the user.

The panels() function then uses this result when building the storyboard. If the user selects all pages instead of entering a custom list, it returns every page in the original order.

This feature is helpful when creating a storyboard from selected scenes or important slides without including the entire PDF.

Adding Panel Labels

Panel labels help users identify individual pages when reviewing or discussing a storyboard.

The application supports different label styles, including numbers, scene labels, original PDF page numbers, and no labels.

For example, a storyboard could display:

• 1, 2, 3, 4
• Scene 1, Scene 2, Scene 3
• Page 5, Page 6, Page 7

Users can select their preferred label style from the Panel label setting.

The application uses the labelFor() function to generate the appropriate label for each panel:

function labelFor(o, idx, n) {
    if (o.label === 'panel') {
        return String(idx + 1);
    }

    if (o.label === 'page') {
        return 'Page ' + n;
    }

    if (o.label === 'scene') {
        return 'Scene ' + (idx + 1);
    }

    return '';
}

The function accepts three parameters:

• o contains the storyboard settings, including the selected label style.
• idx represents the panel's position in the selected storyboard sequence. It starts at 0.
• n represents the original PDF page number.

When the user selects the panel number option, idx + 1 generates labels such as 1, 2, and 3.

When the user selects the page number option, the function uses n to display the original PDF page number. This is useful when the storyboard contains selected pages in a custom order.

For the scene label option, the function generates labels such as Scene 1, Scene 2, and Scene 3. If the user selects No label, it returns an empty string.

The drawing function uses this result when rendering each panel on the storyboard sheet. This helps users identify individual panels without changing the original PDF pages.

Drawing the Storyboard Sheet

Once the layout has been calculated, the application draws the storyboard sheet on an HTML canvas.

The drawing process places each selected PDF page inside its calculated panel area. It then adds panel labels and captions according to the user's settings.

The actual application uses the asynchronous drawSheet() function for this process. The following excerpt shows how it prepares the sheet and selects the pages that belong on it:

async function drawSheet(ctx, o, list, L, sheetIdx, k, mode, getPic) {
    var C = COLORS[o.colors] || COLORS.paper;
    var W = L.W * k;
    var H = L.H * k;
    var token = state.loadToken;
    var drawn = [];

    ctx.save();
    ctx.fillStyle = C.bg;
    ctx.fillRect(0, 0, W, H);
    ctx.textBaseline = 'alphabetic';

    var start = sheetIdx * L.per;
    var items = list.slice(start, start + L.per);

The function receives the canvas context, storyboard settings, selected page list, calculated layout, sheet index, and rendering scale.

It first selects the sheet colors and paints the background. The start variable determines the first panel on the current sheet, while items contains the PDF pages assigned to that sheet.

The following excerpt shows how the application fits each PDF page inside its panel and retrieves its rendered image:

for (var i = 0; i < items.length; i++) {
    var cell = L.cells[i], n = items[i], idx = start + i;
    var area = cell.img;
    var strip = o.layout === 'strip';

    if (strip) {
        ctx.fillStyle = C.bandMat;
        ctx.fillRect(
            area.x * k, area.y * k,
            area.w * k, area.h * k
        );
    } else if (o.frame) {
        ctx.fillStyle = C.mat;
        ctx.fillRect(
            area.x * k, area.y * k,
            area.w * k, area.h * k
        );
    }

    var inset = strip ? 0 :
        o.frame ? Math.min(area.w, area.h) * 0.04 : 0;

    var pr = fitPage(n, area, inset);

    var px = {
        x: Math.round(pr.x * k),
        y: Math.round(pr.y * k),
        w: Math.max(1, Math.round(pr.w * k)),
        h: Math.max(1, Math.round(pr.h * k))
    };

    drawn.push({ n: n, rect: pr });

    if (mode === 'overlay') {
        ctx.clearRect(px.x, px.y, px.w, px.h);
    } else {
        ctx.fillStyle = '#FFFFFF';
        ctx.fillRect(px.x, px.y, px.w, px.h);

        var pic = getPic ? await getPic(n, px.w, px.h) : null;

        if (token !== state.loadToken) {
            ctx.restore();
            return null;
        }

        if (pic) {
            ctx.drawImage(pic, px.x, px.y, px.w, px.h);
        }
    }
}

The fitPage() function calculates the position and dimensions needed to fit the original PDF page inside the panel without changing its proportions.

The application then uses getPic() to retrieve the rendered page image. If the image is available, drawImage() places it on the storyboard canvas.

The function also supports an overlay mode, which leaves the page picture areas transparent. This is useful when exporting PDFs while preserving the original PDF page content.

Drawing Panel Labels and Captions

After positioning the page previews, the application draws the panel labels and captions.

The following excerpt from the actual drawSheet() function shows how panel labels and captions are drawn on the canvas:

var t = cell.text;
var fs = cell.fs * k;
var lh = cell.lh * k;
var y = t.y * k + fs;

var label = labelFor(o, idx, n);
ctx.textAlign = 'left';

if (label) {
    ctx.font = '700 ' + fs + 'px ' + FONTS.mono;
    ctx.fillStyle = C.ink;
    ctx.fillText(label, t.x * k, y);
    y += lh * 1.05;
}

var lines = [];

if (o.captions && captionFor(n)) {
    ctx.font = '400 ' + fs + 'px ' + FONTS[o.font];
    ctx.fillStyle = C.ink;

    var maxL = cell.notes
        ? Math.max(1, Math.floor(
            (t.y * k + t.h * k - y + lh - fs) / lh
        ))
        : o.lines;

    lines = wrap(
        ctx,
        captionFor(n),
        t.w * k,
        Math.min(maxL, cell.notes ? 40 : o.lines)
    );

    lines.forEach(function (ln, j) {
        ctx.fillText(ln, t.x * k, y + j * lh);
    });
}

The labelFor() function generates the selected panel label. The application then uses fillText() to draw it on the canvas.

If captions are enabled and a caption exists, the application uses captionFor() to retrieve it. The wrap() function breaks the caption into lines that fit within the available panel space.

For the Panels with notes layout, the application also draws ruled lines below the caption area. This provides additional writing space for users.

The drawing process combines the original PDF page previews with the labels, captions, frames, and other selected settings to create the completed storyboard sheet.

Updating the Live Preview

One of the most useful features is the live preview. Users can change the layout, paper size, orientation, captions, font, spacing, and other settings without creating a new PDF every time.

The application uses the board() function to calculate the current storyboard configuration before drawing the preview.

Here's the actual implementation:

function board() {
    var sel = panels();

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

    var L = layout(state.opts, sel.pages);

    return {
        list: sel.pages,
        L: L
    };
}

The function first calls panels() to retrieve the selected PDF pages. If the selection contains an error, it returns that error instead of continuing.

Next, it calls layout() with the current storyboard settings and selected pages. The layout function calculates how the pages should be arranged on the storyboard sheets.

Finally, board() returns an object containing the selected page list and the calculated layout. The drawPreview() function uses this information to render the selected sheet onto a temporary canvas.

Once drawing is complete, the result is copied to the visible preview canvas. The application also updates the sheet counter, such as Sheet 1 of 3, and enables or disables the Previous and Next buttons depending on the current position.

This allows users to move between storyboard sheets and review their changes before downloading the result.

Adjusting Caption Appearance

Captions help explain what's happening on each page.

The application provides options for enabling captions, selecting a font, changing text size, and controlling the number of caption lines.

Users can also choose whether to display panel frames and sheet numbers.

These settings are stored in state.opts. The syncPanel() function updates the settings controls to match the current application state.

Here's the actual implementation:

function syncPanel() {
    var o = state.opts;

    ['layout', 'cols', 'rows', 'paper', 'orient', 'label',
     'lines', 'tsize', 'font', 'colors'].forEach(function (f) {
        q('[data-field="' + f + '"]').value = String(o[f]);
    });

    q('[data-field="captions"]').checked = o.captions;
    q('[data-field="frame"]').checked = o.frame;
    q('[data-field="numbers"]').checked = o.numbers;

    q('[data-field="gap"]').value = String(o.gap);
    q('[data-out="gap-val"]').textContent = o.gap + ' mm';

    q('[data-field="pages"]').value = state.pages;

    if (document.activeElement !== q('[data-field="title"]')) {
        q('[data-field="title"]').value = state.title;
    }

    var strip = o.layout === 'strip';

    q('[data-out="cols-label"]').textContent =
        strip ? 'Frames per strip' : 'Columns';

    q('[data-out="rows-label"]').textContent =
        strip ? 'Strips per sheet' : 'Rows';

    q('[data-field="lines"]').disabled =
        !o.captions || o.layout === 'notes';

    q('[data-field="frame"]').disabled = strip;

    ui.listWrap.hidden = state.pages !== 'list';
}

The function reads the current options from state.opts and updates the corresponding controls. For example, it sets the selected font, text size, caption line count, and paper settings.

It also handles layout-specific controls. In Film strip mode, the columns and rows labels change to Frames per strip and Strips per sheet. The caption-line control is disabled when captions are turned off or when the Panels with notes layout is selected.

Fitting Captions Inside Panels

Long captions need to fit inside the available panel space. The application uses a wrap() helper to divide text into lines based on the available canvas width.

Here's how the actual drawing code uses that helper:

if (o.captions && captionFor(n)) {
    ctx.font = '400 ' + fs + 'px ' + FONTS[o.font];
    ctx.fillStyle = C.ink;

    var maxL = cell.notes
        ? Math.max(1, Math.floor(
            (t.y * k + t.h * k - y + lh - fs) / lh
        ))
        : o.lines;

    lines = wrap(
        ctx,
        captionFor(n),
        t.w * k,
        Math.min(maxL, cell.notes ? 40 : o.lines)
    );

    lines.forEach(function (ln, j) {
        ctx.fillText(ln, t.x * k, y + j * lh);
    });
}

The application selects the font using FONTS[o.font] and calculates the available number of caption lines based on the panel layout.

For regular layouts, the selected o.lines setting controls the maximum number of lines. For Panels with notes, the available space determines how many lines can be displayed.

The wrap() function breaks the caption into lines that fit the available width. The fillText() method then draws each line onto the canvas.

When there isn't enough space for the selected caption settings, the preview displays a warning suggesting fewer caption lines, fewer rows, or a smaller text size.

The application also supports panel frames and sheet numbers. These options are stored in the application state and applied when the storyboard is drawn.

This gives users control over the appearance and readability of their storyboard captions without changing the original PDF.

Navigating Between Storyboard Sheets

A large PDF may require several storyboard sheets.

The application provides Previous and Next controls so users can review each sheet individually. It also displays the current sheet number and the total number of sheets.

The selected sheet is stored in state.sheet. The application uses this value to determine which storyboard sheet should be displayed.

Handling the Previous and Next Buttons

The application handles sheet navigation inside its main click event listener. Here's the actual implementation:

case 'sheet-prev':
    if (state.sheet > 0) {
        state.sheet--;
        drawPreview();
    }
    break;

case 'sheet-next':
    state.sheet++;
    drawPreview();
    break;

When the user clicks Previous, the application checks whether the current sheet number is greater than zero. If it is, state.sheet is decreased by one and drawPreview() refreshes the displayed sheet.

When the user clicks Next, the sheet number is increased and the preview is refreshed.

The application also prevents users from moving beyond the available sheets. Inside drawPreview(), it checks the current sheet position and disables the navigation buttons when necessary:

state.sheet = clamp(state.sheet, 0, L.sheets - 1);

ui.sheetPos.textContent =
    'Sheet ' + (state.sheet + 1) + ' of ' + L.sheets;

q('[data-act="sheet-prev"]').disabled = state.sheet <= 0;
q('[data-act="sheet-next"]').disabled =
    state.sheet >= L.sheets - 1;

The clamp() function keeps the selected sheet within the valid range. The sheet counter displays the current position, starting from 1, and the total number of sheets.

The Previous button is disabled on the first sheet, while the Next button is disabled on the last sheet. This makes it easier to review large documents without displaying every storyboard sheet at once.

Reading Scanned Pages with OCR

Some PDF documents contain selectable text, while others contain scanned images of printed pages.

PDF.js can extract text from pages containing actual text data. But it can't directly extract words from a scanned page that contains only an image.

To handle these pages, the application provides an optional OCR feature using Tesseract.js.

When users select Read scanned pages with OCR, the application identifies scanned pages that don't already have captions and processes them using the OCR engine.

Loading Tesseract.js When Needed

The application loads Tesseract.js only when the user requests OCR. It first checks whether the library is already available and reuses an existing loading promise if the script is still being loaded.

Here's the actual loadTesseract() implementation:

var tessPromise = null;

function loadTesseract() {
    if (window.Tesseract) {
        return Promise.resolve(window.Tesseract);
    }

    if (tessPromise) {
        return tessPromise;
    }

    tessPromise = new Promise(function (resolve, reject) {
        var s = document.createElement('script');
        s.src = TESS + 'tesseract.min.js';
        s.async = true;

        s.onload = function () {
            if (window.Tesseract) {
                resolve(window.Tesseract);
            } else {
                tessPromise = null;
                reject(new Error('engine'));
            }
        };

        s.onerror = function () {
            tessPromise = null;
            reject(new Error('engine'));
        };

        document.head.appendChild(s);

        setTimeout(function () {
            reject(new Error('engine'));
        }, 45000);
    });

    return tessPromise;
}

The function checks window.Tesseract to see whether the OCR library is already available. If it is, the function returns it immediately.

If the library is still loading, the existing tessPromise is returned instead of creating another script request.

Otherwise, the application creates a script element, sets its source to the Tesseract.js library, and adds it to the document. The onload and onerror handlers detect whether loading succeeds or fails.

Creating the OCR Worker

After the library loads, the application creates a Tesseract worker configured for English text recognition.

The following excerpt comes from the actual runOcr() function:

var T = await loadTesseract();
checkCancel();

var w = await T.createWorker('eng', 1, {
    workerPath: TESS + 'worker.min.js',
    corePath: TESS_CORE,
    logger: function (m) {
        if (!m || token !== state.loadToken || !state.busy) {
            return;
        }

        if (/loading language/i.test(m.status)) {
            setProgress(
                m.progress || 0,
                'Getting the English language data (first time only)…'
            );
        } else if (/recogniz/i.test(m.status)) {
            setProgress(
                (done + (m.progress || 0)) / list.length,
                'Reading page ' + list[done] +
                ' (' + (done + 1) + ' of ' + list.length + ')…'
            );
        }
    }
});

state.worker = w;
checkCancel();

await w.setParameters({ debug_file: '/dev/null' });

The createWorker() method initializes the OCR engine with the English language data. The worker and core paths tell Tesseract.js where to load its supporting files.

The logger reports language-loading and text-recognition progress. The application uses this information to update its progress indicator while OCR is running.

Recognizing Text from Scanned Pages

The application processes each eligible scanned page individually. It renders the page at a higher resolution before sending it to Tesseract.js.

Here's the actual page-processing excerpt from runOcr():

for (; done < list.length; done++) {
    checkCancel();

    var n = list[done],
        page = await state.doc.getPage(n),
        b = page.getViewport({ scale: 1 });

    var c = await renderPage(
        n,
        Math.min(b.width * 300 / 72, 2600),
        Math.min(b.height * 300 / 72, 2600)
    );

    checkCancel();

    var png = await pngBytes(c);
    c.width = 1;

    var res = await w.recognize(png);

    checkCancel();

    if (token !== state.loadToken) {
        return;
    }

    var cap = captionFromText(res.data && res.data.text);

    if (cap && !captionFor(n)) {
        state.captions[n] = cap;

        var ta = ui.grid.querySelector('[data-cap="' + n + '"]');

        if (ta) {
            ta.value = cap;
        }
    }
}

The function retrieves each scanned PDF page and calculates its original dimensions. It then renders the page at approximately 300 DPI, with a maximum dimension of 2,600 pixels.

The pngBytes() helper converts the rendered canvas into PNG image data. Tesseract.js receives this data through w.recognize(png) and returns the recognized text.

The application passes the recognized text to captionFromText() to clean and shorten it. If the result is useful and the page still has no caption, the application saves it in state.captions and updates the corresponding caption field.

The application also checks for cancellation and verifies that the PDF-loading operation is still current before updating the results.

After processing, the application displays a message asking users to review the generated captions. OCR isn't guaranteed to recognize every word correctly. Image quality, handwriting, unusual fonts, and page orientation can affect the result.

Users should review generated captions before downloading the storyboard.

Generating the Final Storyboard PDF

Once the user is satisfied with the layout and captions, the application can generate the final PDF.

This process uses PDF-lib to create a new PDF document. The application creates one output page for each storyboard sheet. It then places the original PDF pages inside their calculated panel positions and adds the storyboard's titles, labels, and captions.

Creating the PDF Document

The actual application uses the exportPdf() function to generate the storyboard. It first creates a new PDF document and checks whether the original PDF pages can be embedded as vector content.

Here's the first part of the actual implementation:

async function exportPdf(snap, token) {
    await engine();

    var PL = window.PDFLib,
        L = snap.L,
        o = snap.o,
        list = snap.list;

    var out = await PL.PDFDocument.create(),
        src = null,
        embedded = {};

    if (state.vector) {
        try {
            src = await PL.PDFDocument.load(
                state.bytes.slice(0),
                { updateMetadata: false }
            );
        } catch (e) {
            src = null;
        }
    }

    var k = exportScale(L, 300, 14e6);

    for (var s = 0; s < L.sheets; s++) {
        checkCancel();

        if (token !== state.loadToken) {
            return;
        }

        setProgress(
            s / L.sheets,
            'Making sheet ' + (s + 1) + ' of ' + L.sheets + '…'
        );

        var page = out.addPage([L.W, L.H]);
        var c = document.createElement('canvas');

        c.width = Math.round(L.W * k);
        c.height = Math.round(L.H * k);

        var drawn = await drawSheet(
            c.getContext('2d'),
            o,
            list,
            L,
            s,
            k,
            'overlay',
            null
        );

        if (!drawn) {
            return;
        }

The function first waits for the required PDF libraries using engine(). It then creates a new PDF document with PDFDocument.create().

The snap parameter contains a snapshot of the selected layout, options, and page list. The application uses these values so the export follows the settings selected by the user.

The state.vector check determines whether the original PDF can be loaded through PDF-lib for vector embedding. The application also calculates a rendering scale targeting 300 DPI, subject to a maximum pixel limit.

The loop creates one output PDF page for every storyboard sheet. It also calls drawSheet() in overlay mode to prepare the titles, panel labels, and captions that will be placed over the original PDF pages.

Preserving Original PDF Pages

When vector embedding is available, the application embeds the original PDF pages rather than converting them into ordinary images.

The following excerpt shows how it handles each selected panel:

for (var i = 0; i < drawn.length; i++) {
    checkCancel();

    var d = drawn[i],
        r = d.rect,
        yb = L.H - r.y - r.h;

    page.drawRectangle({
        x: r.x,
        y: yb,
        width: r.w,
        height: r.h,
        color: PL.rgb(1, 1, 1)
    });

    if (src) {
        var sp = src.getPage(d.n - 1);

        if (!embedded[d.n]) {
            var cb = sp.getCropBox();

            embedded[d.n] = await out.embedPage(sp, {
                left: cb.x,
                bottom: cb.y,
                right: cb.x + cb.width,
                top: cb.y + cb.height
            });
        }

        var em = embedded[d.n],
            rot = ((sp.getRotation().angle % 360) + 360) % 360;

        var turned = rot === 90 || rot === 270,
            sx = r.w / (turned ? em.height : em.width);

        var ew = em.width * sx,
            eh = em.height * sx,
            at = { x: r.x, y: yb };

        if (rot === 90) {
            at = { x: r.x, y: yb + ew };
        } else if (rot === 180) {
            at = { x: r.x + ew, y: yb + eh };
        } else if (rot === 270) {
            at = { x: r.x + eh, y: yb };
        }

        page.drawPage(em, {
            x: at.x,
            y: at.y,
            width: ew,
            height: eh,
            rotate: PL.degrees(-rot)
        });
    }

The application retrieves the original PDF page using its page number. It then uses embedPage() to embed that page into the new PDF document.

The embedded object caches embedded pages so the same original page doesn't need to be embedded repeatedly.

The code also checks the original page rotation and adjusts its position and dimensions before drawing it. This helps preserve the correct orientation when placing pages inside storyboard panels.

Handling Protected PDFs

If the original PDF can't be embedded as vector content, the application uses a raster fallback.

Here's the actual fallback code:

else {
    var pic = await renderPage(
        d.n,
        r.w * k,
        r.h * k
    );

    var jpg = await new Promise(function (res) {
        pic.toBlob(function (b) {
            b.arrayBuffer().then(function (a) {
                res(new Uint8Array(a));
            });
        }, 'image/jpeg', 0.92);
    });

    pic.width = 1;

    page.drawImage(
        await out.embedJpg(jpg),
        {
            x: r.x,
            y: yb,
            width: r.w,
            height: r.h
        }
    );
}

In this case, the application renders the original PDF page onto a canvas and converts it into JPEG image data. PDF-lib then embeds the image inside the corresponding storyboard panel.

This fallback is used when vector embedding is unavailable, including protected PDFs that can't follow the normal vector workflow.

Adding Captions and Saving the PDF

After the original page images or vector content have been placed, the application adds the storyboard's titles, labels, captions, and other drawing elements as an overlay.

The following excerpt shows how the overlay is added and the final PDF is saved:

var over = await out.embedPng(await pngBytes(c));
c.width = 1;

page.drawImage(over, {
    x: 0,
    y: 0,
    width: L.W,
    height: L.H
});

await nextFrame();

After all sheets have been processed, the application checks for cancellation and prepares the final PDF:

checkCancel();

setProgress(1, 'Saving the PDF…');

out.setTitle(state.title || state.base + ' storyboard');
out.setCreator('AllInOneTools PDF Storyboard');
out.setProducer('AllInOneTools (pdf-lib)');

var bytes = await out.save();

if (token !== state.loadToken) {
    return;
}

save(
    new Blob([bytes], { type: 'application/pdf' }),
    state.base + '-storyboard.pdf'
);

toast(
    'Saved ' + plural(L.sheets, 'sheet', 'sheets') +
    ' as ' + state.base + '-storyboard.pdf.'
);

The embedPng() method adds the storyboard overlay to the PDF page. This overlay contains the titles, panel labels, captions, and other visual elements.

The application then sets the PDF metadata, saves the document as bytes, and creates a downloadable PDF file.

Progress updates and cancellation checks are used throughout the export process, which is particularly helpful when generating storyboards with multiple sheets.

The final PDF combines the original PDF pages with the storyboard layout and captions, ready to download, share, or print.

Downloading PNG Storyboard Sheets

Users who don't need a PDF can choose PNG sheets.

The application renders each complete storyboard sheet as a PNG image at 200 DPI. If the storyboard contains only one sheet, the browser downloads a single PNG file. If it contains multiple sheets, the application packages them into a ZIP archive.

Exporting the Storyboard as PNG

The application handles PNG exports inside the exportJob() function. It first calculates the rendering scale and then processes each storyboard sheet.

The following excerpt shows the actual PNG export implementation:

var k = exportScale(L, 200, 16e6),
    files = [];

for (var s = 0; s < L.sheets; s++) {
    checkCancel();

    setProgress(
        s / L.sheets,
        'Drawing sheet ' + (s + 1) + ' of ' + L.sheets + '…'
    );

    var c = document.createElement('canvas');

    c.width = Math.round(L.W * k);
    c.height = Math.round(L.H * k);

    var ok = await drawSheet(
        c.getContext('2d'),
        o,
        list,
        L,
        s,
        k,
        'full',
        function (n, w, h) {
            checkCancel();
            return renderPage(n, w, h);
        }
    );

    if (!ok) { return; }

    files.push({
        name: state.base + '-storyboard-sheet-' +
            pad2(s + 1) + '.png',
        data: await pngBytes(c)
    });

    c.width = 1;
}

if (files.length === 1) {
    save(
        new Blob([files[0].data], { type: 'image/png' }),
        state.base + '-storyboard.png'
    );
} else {
    save(makeZip(files), state.base + '-storyboard-sheets.zip');
}

toast(
    files.length === 1
        ? 'Saved the storyboard as a PNG.'
        : 'Saved ' + files.length + ' sheets as PNG files in a ZIP.'
);

The application uses exportScale() to calculate a suitable rendering scale for 200 DPI while keeping the canvas within a maximum pixel limit of 16 million pixels.

For every sheet, it creates a canvas and calls drawSheet() in full mode. This draws the PDF page previews together with the storyboard titles, labels, captions, and other selected settings.

The pngBytes() helper converts the completed canvas into PNG data. Each image is added to the files array with a filename containing its sheet number.

After processing all sheets, the application checks how many PNG files were generated. A single sheet is downloaded directly as a PNG. Multiple sheets are packaged into a ZIP archive using makeZip().

This format is useful for sharing storyboard previews in presentations, messages, and other applications.

Downloading Individual Page Pictures

The third export option is Page pictures (ZIP).

Unlike the PNG sheets option, this export contains individual pictures of the PDF pages selected for the storyboard.

The application renders each selected page separately and places the resulting PNG files into a ZIP archive.

Exporting Individual PDF Pages

The actual application handles this option inside the exportJob() function. It first creates a unique list of selected pages and then renders each page individually.

Here's the actual implementation:

var pages = unique(list),
    out = [];

for (var i = 0; i < pages.length; i++) {
    checkCancel();

    setProgress(
        i / pages.length,
        'Saving page ' + pages[i] +
        ' (' + (i + 1) + ' of ' + pages.length + ')…'
    );

    var pg = await state.doc.getPage(pages[i]),
        vb = pg.getViewport({ scale: 1 }),
        sc = Math.min(
            2,
            Math.sqrt(12e6 / (vb.width * vb.height))
        );

    var pc = await renderPage(
        pages[i],
        vb.width * sc,
        vb.height * sc
    );

    out.push({
        name: 'panel-' +
            pad2(list.indexOf(pages[i]) + 1) +
            '-page-' + pad2(pages[i]) + '.png',
        data: await pngBytes(pc)
    });

    pc.width = 1;
}

save(makeZip(out), state.base + '-panels.zip');

toast(
    'Saved ' +
    plural(out.length, 'page picture', 'page pictures') +
    ' in a ZIP.'
);

The function first calls unique() to remove duplicate page numbers from the selected list.

It then processes each page individually. The getPage() method retrieves the original PDF page, and getViewport() obtains its dimensions.

The scale calculation limits the rendering scale to 2 while keeping the rendered page within approximately 12 million pixels. This helps control memory usage when processing large pages.

The renderPage() function creates the page image, while pngBytes() converts the canvas into PNG data.

Each image is added to the out array with a filename containing both its panel position and original PDF page number. This makes it easier to identify the pictures and maintain their storyboard order.

Finally, makeZip() packages all the generated PNG images into a ZIP archive, which the browser downloads.

This option is useful when users want to work with individual PDF page pictures rather than complete storyboard sheets.

Performance and Important Considerations

Rendering large PDFs and generating high-resolution images can consume significant browser memory.

The application uses page-preview caching, temporary canvases, progress reporting, and cancellation controls to manage this work.

For better results, use fewer panels per sheet when working with large documents. A3 paper can also provide more room when a storyboard contains many panels.

Remember that layout preferences are remembered on the device, but the PDF and captions remain in the current browser tab. Download your work before closing the tab.

Demo: PDF Storyboard Generator

You can try the finished application here:

PDF Storyboard Generator – AllInOneTools

Upload a PDF, arrange its pages, add captions, customize the storyboard, and download the finished result.

Conclusion

Building a PDF Storyboard Generator combines several useful browser technologies into one application.

PDF.js handles PDF loading and page rendering. Tesseract.js provides optional text recognition for scanned pages. PDF-lib creates the final storyboard PDF, while HTML canvas handles previews and image exports.

By connecting these components with JavaScript, we can create a practical tool for organizing presentation slides, comic pages, scripts, and other PDF documents.

The project also demonstrates how browser-based applications can process documents locally without requiring users to upload their files to a server.

With the complete workflow in place, users can turn ordinary PDF pages into organized storyboard sheets that are easier to review, print, and share.

We just published a comprehensive 10-hour course on the freeCodeCamp.org YouTube channel that will teach you how to build a complete top-down action roguelite in Godot 4.7.2, from an empty project to an exported game. This course is taught by Omar Zaki, creator of Coding Quests, and most lessons include a Your Turn section where you build the next piece yourself before you see the solution.

Here is what the course covers:

• Dash Combat & I-Frames
  Build weighty movement, aiming, and a dodge with invincibility frames so combat feels fair instead of cheap.
• Enemies, Telegraphs & a Boss Tell
  Create five enemy types from a shared base, then add a boss with a clear warning before the hard hit lands.
• Procedural Connected Rooms
  Generate random floors of linked rooms in code, track where you are, and lock a fight until the room is clear.
• Items, Corruption & Shops
  Stack items into builds, take corruption that trades power for fragility, and risk gold at shops and a gambling altar.
• Run Loop, Unlocks & Export
  Wire death, permanent unlocks, a title screen, sound, and an export so a stranger can download and play your game.

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

The setup works at first, but after a few design changes, even a small update can mean checking several files across the project.

Here's what a typical color file looks like after a while:

export const colors = {
  primary: '#6e4836',
  primaryPressed: '#5a3a2b',
  textPrimary: '#261d16',
  textSecondary: '#72665e',
  // and forty more
};

And here's what a typical Button looks like after a few redesigns:

<Button
  variant="primary"
  size="md"
  fullWidth
  loading={busy}
  containerStyle={styles.checkoutButton}
  labelStyle={styles.checkoutLabel}
/>

These are simplified examples, but you get the idea. The color object keeps growing, and the Button collects more props to handle every new design request.

Each change seems reasonable when you make it. But the annoying part comes later, when changing one design decision means checking several files to see that nothing else has changed unexpectedly.

Part of the problem is how many component libraries are distributed. Their code lives in node_modules, so you usually customize them through the props and options they expose. When the library doesn't cover your exact use case, you add another prop or override. Keep doing that and the component can become harder to maintain than the original problem you were trying to solve.

This is one reason I like shadcn/ui's approach. You don't install a traditional component package and treat its components as fixed. The CLI copies the source code into your project, where you can change it whenever you need to. For React Native, there's a project built around the same idea called React Native Reusables.

To make this practical, I'll use React Native Reusables, Expo, and Uniwind to build a cart and checkout screen for a coffee shop's pickup orders. It includes order items with quantity controls, a pickup-time dropdown, a name field, an "own cup" toggle, a bill summary, a checkout bar that stays at the bottom, and an order-confirmation dialog. If you want to see how reusable sections come together in complete interfaces, you can also browse shadcn templates.

I'll also point out a few things that are easy to miss when working with these components, including:

• How shadcn/ui and its CLI work, and why you own the component code
• How design tokens (named colors) replace a colors.ts file
• How to use components such as Card, Select, Switch, and AlertDialog in React Native
• How to handle mobile-specific issues, such as safe areas, keyboards, and tap targets
• How to switch between light and dark mode, and how to change the whole theme from one file

Table of Contents

• Prerequisites
• Tools You Will Use
• How shadcn/ui Works
• What React Native Reusables Gives You
• What You're Building
• Step 1: Create the App
  • Answer the CLI's Questions
  • Look at the Project Structure
  • Run the App
• Step 2: Understand the Theme File
  • The Palette Also Exists inlib/theme.ts
  • Try It: Change One Color
• Step 3: Read Three Core Components
  • The Text Component
  • The Button Component
  • The Icon Component
• Step 4: Add the Components You Need
• Step 5: Set Up the Data and the Screen
  • The Screen Layout
• Step 6: Build the Order Rows
• Step 7: Build the Pickup Options
  • Problem 1: Portals and the PortalHost
  • Problem 2: Safe Area Insets
  • Problem 3: The Select Value Is an Object
  • Making the Label Tappable
  • Keyboard Props for the Name Field
• Step 8: Build the Bill Component
• Step 9: Build the Fixed Checkout Bar
  • Handling the Home Indicator
  • A Note on Thin Borders
• Step 10: Add the Confirmation and Put the Screen Together
  • 1. It Also Needs thePortalHost
  • 2. The Footer Reverses its Order on Phones
  • Haptics
  • The Full Screen
• Step 11: Add Dark Mode
  • 1. The Navigation Header
  • 2. The Status Bar
  • 3. Saving the Choice
• Step 12: Create Your Own Theme
  • Update the Tokens
  • Update lib/theme.ts
• Common Mistakes and How to Fix Them
• Conclusion
  • Resources

Prerequisites

To follow along, you should have:

• Node.js 20 or newer. You can use pnpm, npm, yarn, or bun. The commands in this tutorial use pnpm, so swap the prefix if you use something else.
• Basic knowledge of React and TypeScript, especially hooks such as useState.
• Some familiarity with React Native, such as View, Text, and ScrollView. You don't need to know Tailwind, but it helps.
• Optional: Xcode or Android Studio if you want to run the app in a simulator. Everything also runs in a web browser through React Native Web, and that's how the screenshots in this tutorial were taken.

You don't need any accounts or API keys, and nothing here costs money.

Tools You Will Use

Before creating the app, let's look at the tools in this project. Each one has a specific job, and knowing that will make the setup easier to follow.

shadcn/ui is a collection of UI components for the web. It's not installed as a package. Instead, a command-line tool (CLI) copies the source code of each component into your project, and from then on the code is yours to edit.

React Native Reusables is the React Native version of shadcn/ui. It gives you components such as Button, Card, Select, and Dialog that are written for React Native and styled with Tailwind-style class names. It uses the same CLI idea as shadcn/ui.

RN Primitives is a React Native port of Radix UI, which is the library that shadcn/ui uses for behavior on the web. A "primitive" is a component that handles the behavior but has no styling. For example, the select primitive knows how a dropdown opens and closes and how it's announced to screen readers, but it has no colors or borders. React Native Reusables adds the looks on top.

Uniwind is a tool that lets you style React Native components with Tailwind CSS class names, such as className="bg-primary p-4". It converts those classes into regular React Native styles while the app is being bundled, so there's no extra work at runtime. Nativewind does a similar job, and React Native Reusables supports both. This tutorial uses Uniwind.

Expo and Expo Router provide the project setup, the development server, and file-based navigation. If you have used Next.js, Expo Router works in a similar way.

How shadcn/ui Works

The React Native Reusables documentation opens with a quote from shadcn:

This is not a component library. It is how you build your component library.

You won't add shadcn/ui as a regular dependency in package.json. It uses a registry instead. A registry is a collection of JSON files hosted on a server. Each file describes a component and includes the information the CLI needs to add it to your project. When you run the CLI, it reads the relevant file and copies the component's source code into your project.

To see what this looks like, here's the registry entry for the Badge component. A Badge is a small label, such as the "Medium" tag next to a coffee in the cart you will build later. This is a shortened version of the real file:

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "badge",
  "type": "registry:ui",
  "title": "Badge",
  "author": "@mrzachnugent",
  "description": "Displays a badge or a component that looks like a badge.",
  "dependencies": ["@rn-primitives/slot"],
  "registryDependencies": ["https://reactnativereusables.com/r/uniwind/text.json"],
  "files": [
    {
      "path": "./node_modules/@rnr/registry/src/uniwind/components/ui/badge.tsx",
      "content": "import { TextClassContext } from '@/components/ui/text';\nimport ...",
      "type": "registry:ui"
    }
  ]
}

The file is public, so you can look at it yourself:

curl https://reactnativereusables.com/r/uniwind/badge.json

Here's what the important fields mean:

• content holds the full source code of the component, stored as a string.
• dependencies lists npm packages that the component needs. The CLI installs these first.
• registryDependencies lists other registry entries that the component needs. In this case, Badge needs the Text component, which is a small wrapper around React Native's Text that you will read about in Step 3. When you run the CLI to add Badge, it also adds Text for you because of this field.

That's how a component gets from the registry into your app. The registry stores the component information, and the CLI uses it to create the files in your repository. React Native Reusables uses the shadcn CLI behind the scenes, so you can follow the same workflow when adding React Native components.

There are a few reasons this approach is useful when you're building an app:

1. You own the file: A component such as components/ui/button.tsx sits in your repository and shows up in your Git diffs. If you want a darker pressed state, you edit that line. You don't need to invent a new prop, maintain a fork, or open an issue.
2. Design lives in named colors instead of props: Colors are declared once as named roles, such as primary, muted, border, and destructive. You then use them in class names, like className="bg-primary". This replaces the colors.ts file from the introduction, because there's one place that defines your colors, and every component reads from it. You'll set this up in Step 2.
3. Behavior comes from a separate package: Things such as focus handling, open and close state, and screen reader support live in RN Primitives. You only write the styling.

There's one trade-off to keep in mind. Since the component code is copied into your project, updates from the registry aren't applied automatically. If a bug is fixed upstream, you'll need to run the CLI again with --overwrite. If you have customized that component, you may also need to reapply your changes. This is worth considering before you make large changes to several components.

What React Native Reusables Gives You

At the time of writing, React Native Reusables includes thirty components: accordion, alert, alert-dialog, aspect-ratio, avatar, badge, button, card, checkbox, collapsible, context-menu, dialog, dropdown-menu, hover-card, input, label, menubar, popover, progress, radio-group, select, separator, skeleton, switch, tabs, text, textarea, toggle, toggle-group, and tooltip. The available components cover many of the building blocks you need for a typical app interface.

React Native is different from the web in several ways, so the components can't be an exact copy of the web version. The documentation lists the main differences, and you'll run into each of them in this tutorial. If you're also building web interfaces with shadcn/ui, shadcn components can be useful when you need more ready-made examples to work from.

What You're Building

We'll build a cart and checkout screen for a coffee shop where customers place an order and pick it up at the counter. The screen uses twelve components from the registry. While putting it together, I'll also explain a few React Native details that are easy to miss, including how dropdowns are rendered, how safe areas affect the layout, and how to keep the checkout bar visible while the rest of the page scrolls:

Here's the finished screen:

The complete code is available in the GitHub repository if you want to compare your work with the final result.

Step 1: Create the App

We can let the React Native Reusables CLI create the initial project for us. It sets up Expo Router, the styling configuration, the theme file, and a few starter components. Run the following command to get started:

pnpm dlx @react-native-reusables/cli@latest init

Answer the CLI's Questions

The CLI asks four questions.

What is the name of your project? The name you type becomes the folder name. It suggests my-app.

Select a template. There are three options, and the one you need isn't the one selected by default:

❯ Minimal (Nativewind)
  Minimal (Uniwind)
  Clerk auth (Nativewind)

Press the down arrow once and choose Minimal (Uniwind). This is the one choice that's tricky to change later. Nativewind and Uniwind are two different ways to use Tailwind in React Native, and the CLI keeps a separate registry for each one. The components it writes for Uniwind are different from the ones it writes for Nativewind, so the code in this tutorial won't match if you pick Nativewind.

Would you like to install dependencies? Choose yes, and select the package manager you use.

Would you like to initialize a Git repository? Choose yes. You're about to replace the starter screen, and having a commit to compare against is helpful.

Look at the Project Structure

The CLI creates the following files:

shadcn-react-native-app/
├── app/
│   ├── _layout.tsx        # ThemeProvider, Stack, and the PortalHost
│   ├── +html.tsx          # web only, the root HTML shell
│   ├── +not-found.tsx
│   └── index.tsx          # the starter screen
├── components/ui/
│   ├── button.tsx
│   ├── icon.tsx
│   └── text.tsx
├── lib/
│   ├── theme.ts           # the same palette again, in JavaScript
│   └── utils.ts           # cn()
├── global.css             # the theme tokens
├── components.json        # the shadcn config, same as on the web
├── metro.config.js        # withUniwindConfig
└── uniwind-types.d.ts     # generated, do not edit

Before moving on, let's take a look at a few files in this structure. You'll use them throughout the tutorial:

• components.json is the same shadcn configuration file used on the web. It tells the CLI where to put components (@/components/ui) and where the cn() helper lives (@/lib/utils).
• global.css holds your theme tokens, which you'll learn about in Step 2.
• lib/utils.ts exports cn(), a helper that combines class names and resolves conflicts between them.
• app/_layout.tsx contains a PortalHost component. It looks like leftover scaffolding, but you must not delete it. Step 7 explains why.

Uniwind reads global.css while Metro bundles the app and turns your class strings into React Native style objects. This happens at build time, so a long className string doesn't slow down your app.

Run the App

Start the development server:

pnpm dev

Press w to open it in the browser, i for the iOS simulator, or a for Android. The starter screen has a theme toggle in the header, which shows that the theme setup is working.

You can also run a diagnostic command at any point if something seems wrong:

pnpm dlx @react-native-reusables/cli@latest doctor

It checks your setup and reports which styling library it detects. For this project, the output should be:

ℹ Styling Library: Uniwind
✔ All checks passed.

If it says Nativewind, fix that before you add any components.

Once the setup is working, you should see the starter screen. Try the theme toggle in the header to make sure light and dark mode both work, and check that the console is free of errors:

Step 2: Understand the Theme File

Now that the app is running, let's look at its theme setup. The global.css file is where we'll define the colors used by the components. If you've previously kept these values in a colors.ts or theme.ts file, this is the setup that replaces it.

@import "tailwindcss";
@import "uniwind";

@import "tw-animate-css";

@theme {
  --radius: 10px;
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);

  --spacing-hairline: hairlineWidth();
}

@layer theme {
  :root {
    @variant light {
      --color-background: oklch(1 0 0);
      --color-foreground: oklch(0.145 0 0);
      --color-card: oklch(1 0 0);
      --color-primary: oklch(0.205 0 0);
      --color-muted-foreground: oklch(0.556 0 0);
      --color-border: oklch(0.922 0 0);
      /* the rest of the list */
    }

    @variant dark {
      --color-background: oklch(0.145 0 0);
      --color-foreground: oklch(0.985 0 0);
      --color-card: oklch(0.205 0 0);
      --color-primary: oklch(0.922 0 0);
      --color-muted-foreground: oklch(0.708 0 0);
      --color-border: oklch(1 0 0 / 10%);
      /* the rest of the list */
    }
  }
}

There are two conventions in this file that you need to know.

First, the --color- prefix creates the class names. When you declare --color-primary, Tailwind automatically creates bg-primary, text-primary, and border-primary. If you declare --primary instead, you only get a CSS variable that nothing uses.

This is important because most shadcn theme generators produce the web format, where the variables are named --primary. If you paste that output without renaming the variables, nothing breaks, but nothing changes either. Step 12 shows you how to convert them.

Second, @variant light and @variant dark replace :root and .dark. On the web, dark mode works by adding a .dark class to the page. A phone has no page to add a class to, so Uniwind manages the switch. When you call Uniwind.setTheme, it swaps the active values. You'll use this in Step 11.

You may also notice that the file uses oklch() colors. Phones don't have a browser to read that format, but Uniwind converts the colors to a format React Native understands while bundling, so you can use modern color syntax anyway.

The Palette Also Exists in lib/theme.ts

If you open lib/theme.ts, you'll find the same colors again as a JavaScript object. This duplication is needed because React Navigation, which draws the header and screen background, reads colors from a plain JavaScript object and can't read CSS variables. As a result, you have to keep two copies of your palette in sync. Step 12 shows what happens when they differ.

Try It: Change One Color

Let's change one of the tokens to see how the theme works. Update the primary color in the light theme to a value that's easy to notice:

--color-primary: oklch(0.6 0.24 25);

Save the file and look at the starter screen. The Browse the Docs button is now red, even though you didn't edit button.tsx:

Notice that every component using bg-primary picks up the new color. You only changed one token, but the button updated without touching its component file. Change the value back before continuing.

Step 3: Read Three Core Components

The starter project already gives us three components: Text, Button, and Icon. I'd take a few minutes to look through them before building the screen. They introduce patterns you'll see again in the other registry components.

The Text Component

In React Native, styles don't cascade the way they do in CSS. If you set a text color on a View, the text inside it doesn't inherit that color. This is a problem for a component such as <Button variant="destructive">, which needs its label to be white. The label is a Text component that the Button doesn't control, because it comes in through children. On the web, the Button would simply set a color and let it flow down to the label.

React Native Reusables solves this with React context. This is the code in components/ui/text.tsx:

const TextClassContext = React.createContext<string | undefined>(undefined);

function Text({ className, asChild = false, variant = 'default', ...props }) {
  const textClass = React.useContext(TextClassContext);
  const Component = asChild ? Slot : RNText;
  return (
    <Component
      className={cn(textVariants({ variant }), textClass, className)}
      role={variant ? ROLE[variant] : undefined}
      aria-level={variant ? ARIA_LEVEL[variant] : undefined}
      {...props}
    />
  );
}

A parent component, such as Button, puts a class string into the context. Every Text inside it reads that string and applies it. Your own className still wins because it comes last in the cn() call.

The Text component also has a variant prop with options like h1 to h4, p, code, lead, large, small, and muted. For example, <Text variant="muted"> gives you the mobile version of text-muted-foreground text-sm. The variants also set the role and aria-level props, so screen readers announce headings correctly without any extra work.

The Button Component

The Button in components/ui/button.tsx uses cva (class-variance-authority) the same way the web version does. Here's a shortened version:

const buttonVariants = cva(
  cn(
    'group shrink-0 flex-row items-center justify-center gap-2 rounded-md shadow-none',
    Platform.select({
      web: "focus-visible:border-ring focus-visible:ring-ring/50 ... transition-all",
    })
  ),
  {
    variants: {
      variant: {
        default: cn(
          'bg-primary active:bg-primary/90 shadow-sm shadow-black/5',
          Platform.select({ web: 'hover:bg-primary/90' })
        ),
        /* ... */
      },
    },
  }
);

There are four differences from the web version:

• flex-row is written out: React Native lays out children in a column by default, which is the opposite of CSS. Every horizontal layout in this tutorial includes flex-row for that reason.
• active: replaces hover:: A finger can't really hover, so active: is the pressed state on a phone.
• Web-only classes are wrapped in Platform.select: Classes such as focus-visible:ring-[3px] mean nothing in React Native, so they're only included in the web build.
• A TextClassContext.Provider wraps the Pressable: This uses the context from the previous section, and it's why <Button variant="destructive"><Text>Delete</Text></Button> has white text automatically.

The Icon Component

Icons from lucide-react-native take color and size as props, not as class names. The Icon component in components/ui/icon.tsx teaches Uniwind how to convert one into the other:

const StyledIcon = withUniwind(IconImpl, {
  size: { fromClassName: 'className', styleProperty: 'width' },
  color: { fromClassName: 'className', styleProperty: 'color' },
});

This code reads the width from the class string and passes it as size, and it reads the color and passes it as color. That's why <Icon as={PlusIcon} className="size-4 text-muted-foreground" /> works the way you would expect. withUniwind is useful any time you use a third-party component that takes props where you want to use classes.

You don't need to run anything for this step. The important part is understanding what TextClassContext is doing. Once that clicks, the other components in the registry are much easier to follow.

Step 4: Add the Components You Need

We already have three components from the template. For the checkout screen, we need a few more. The CLI can add all of them in one go:

pnpm dlx @react-native-reusables/cli@latest add card separator input label select switch badge alert-dialog avatar

The CLI detects that you're using Uniwind and writes the matching versions. It also installs any required @rn-primitives packages and adds a file called native-only-animated-view.tsx, which Select and AlertDialog use for their animations.

The output looks like this:

ℹ Styling Library: Uniwind
✔ Created 10 files:
  - components/ui/separator.tsx
  - components/ui/input.tsx
  - components/ui/label.tsx
  - components/ui/switch.tsx
  - components/ui/avatar.tsx
  - components/ui/native-only-animated-view.tsx
  - components/ui/card.tsx
  - components/ui/badge.tsx
  - components/ui/select.tsx
  - components/ui/alert-dialog.tsx
ℹ Skipped 3 files: (files might be identical, use --overwrite to overwrite)
  - components/ui/text.tsx
  - components/ui/icon.tsx
  - components/ui/button.tsx

The CLI created ten files, which is more than the nine you asked for, because native-only-animated-view.tsx is a dependency of Select and AlertDialog. It skipped the three files that the template already gave you, so it does not overwrite your copies. This is the "you own the file" idea at work.

Run pnpm dev again to make sure the app still starts. The components/ui/ folder should now contain thirteen files.

Step 5: Set Up the Data and the Screen

Before we start building the UI, let's add the sample menu data and decide where the screen state will live. I'm going to store prices in cents rather than floating-point numbers. This avoids calculation results such as $4.7499999.

We'll also keep the state in the main screen component and pass the relevant values down as props. That way, changing an item quantity or selecting the own-cup option automatically updates the bill.

Create lib/menu.ts:

export type CartItem = {
  id: string;
  name: string;
  detail: string;
  size?: 'Small' | 'Medium' | 'Large';
  emoji: string;
  /** Cents. Money in floats is how you end up charging someone $4.7499999. */
  unitPrice: number;
  qty: number;
};

export const INITIAL_CART: CartItem[] = [
  {
    id: 'flat-white',
    name: 'Flat white',
    detail: 'Oat milk, extra shot',
    size: 'Medium',
    emoji: '☕️',
    unitPrice: 475,
    qty: 2,
  },
  {
    id: 'cold-brew',
    name: 'Cold brew',
    detail: 'Hold the ice',
    size: 'Large',
    emoji: '🧋',
    unitPrice: 525,
    qty: 1,
  },
  {
    id: 'croissant',
    name: 'Almond croissant',
    detail: 'Warmed',
    emoji: '🥐',
    unitPrice: 390,
    qty: 1,
  },
];

export const PICKUP_TIMES = [
  { value: 'asap', label: 'As soon as it is ready' },
  { value: '15', label: 'In 15 minutes' },
  { value: '30', label: 'In 30 minutes' },
  { value: '60', label: 'In an hour' },
];

export const CUP_DISCOUNT = 25;
export const TAX_RATE = 0.0825;

export function money(cents: number) {
  const sign = cents < 0 ? '-' : '';
  return `${sign}$${(Math.abs(cents) / 100).toFixed(2)}`;
}

export function billFor(items: CartItem[], ownCup: boolean) {
  const subtotal = items.reduce((sum, item) => sum + item.unitPrice * item.qty, 0);
  const discount = ownCup && subtotal > 0 ? CUP_DISCOUNT : 0;
  const tax = Math.round((subtotal - discount) * TAX_RATE);

  return { subtotal, discount, tax, total: subtotal - discount + tax };
}

The PICKUP_TIMES list is in this file instead of inside a component because two different components need it. You'll see why in Step 7.

The Screen Layout

This is basically how app/index.tsx looks. The parts that don't exist yet are left as comments, and you'll write the full file later in Step 10.

<View className="bg-background flex-1">
  <ScrollView
    className="flex-1"
    contentContainerClassName="gap-4 p-4 pb-8"
    keyboardShouldPersistTaps="handled"
    automaticallyAdjustKeyboardInsets>
    {/* the three cards */}
  </ScrollView>

  <CheckoutBar {...} />
</View>

There are three details in this layout that you should examine more closely:

• First, className on a ScrollView styles the scroll container, not its content. This is the class name version of the style and contentContainerStyle split in React Native. If you put padding in className, it gets clipped, and gap has no effect. Use contentContainerClassName for anything that should apply to the content. Uniwind adds this prop to ScrollView.
• There's no space-y-4. In CSS, space-y-* works by selecting siblings, and React Native has no selectors. Use gap-4 on the parent instead, which React Native supports on iOS, Android, and the web.
• keyboardShouldPersistTaps="handled" keeps taps working while the keyboard is open. Without it, the first tap after the keyboard appears only closes the keyboard, so the user has to tap twice. automaticallyAdjustKeyboardInsets is an iOS feature that scrolls the content so the focused input isn't hidden behind the keyboard.

At this stage, you should see only a header with the new title and an empty page below it:

Step 6: Build the Order Rows

The order row has quite a bit going on in a small space: an avatar, product name, size badge, price, and quantity controls. Long names make this especially tricky on a phone, so we'll handle the layout carefully.

Create components/cart/order-row.tsx:

import { Avatar, AvatarFallback } from '@/components/ui/avatar';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
import { Icon } from '@/components/ui/icon';
import { Text } from '@/components/ui/text';
import { money, type CartItem } from '@/lib/menu';
import { MinusIcon, PlusIcon, Trash2Icon } from 'lucide-react-native';
import { View } from 'react-native';

type OrderRowProps = {
  item: CartItem;
  onChangeQty: (id: string, qty: number) => void;
};

export function OrderRow({ item, onChangeQty }: OrderRowProps) {
  const lastOne = item.qty <= 1;

  return (
    <View className="flex-row gap-3">
      <Avatar alt={item.name} className="size-14 rounded-2xl">
        <AvatarFallback className="bg-muted rounded-2xl">
          <Text className="text-2xl">{item.emoji}</Text>
        </AvatarFallback>
      </Avatar>

      <View className="flex-1 gap-2">
        <View className="flex-row items-start gap-3">
          <View className="flex-1 gap-1">
            <View className="flex-row items-center gap-2">
              <Text numberOfLines={1} className="shrink font-medium">
                {item.name}
              </Text>
              {item.size ? (
                <Badge variant="secondary">
                  <Text>{item.size}</Text>
                </Badge>
              ) : null}
            </View>
            <Text numberOfLines={1} variant="muted">
              {item.detail}
            </Text>
          </View>
          <Text className="text-sm font-medium tabular-nums">
            {money(item.unitPrice * item.qty)}
          </Text>
        </View>

        <View className="border-border flex-row items-center gap-1 self-start rounded-full border p-0.5">
          <Button
            size="icon"
            variant="ghost"
            hitSlop={8}
            className="size-7 rounded-full"
            accessibilityLabel={lastOne ? `Remove ${item.name}` : `One fewer ${item.name}`}
            onPress={() => onChangeQty(item.id, item.qty - 1)}>
            <Icon as={lastOne ? Trash2Icon : MinusIcon} className="size-4" />
          </Button>
          <Text className="w-5 text-center text-sm font-medium tabular-nums">{item.qty}</Text>
          <Button
            size="icon"
            variant="ghost"
            hitSlop={8}
            className="size-7 rounded-full"
            accessibilityLabel={`One more ${item.name}`}
            onPress={() => onChangeQty(item.id, item.qty + 1)}>
            <Icon as={PlusIcon} className="size-4" />
          </Button>
        </View>
      </View>
    </View>
  );
}

A few details in this component deserve a closer look.

First, Avatar requires the alt prop. TypeScript won't compile without it. The value becomes the accessibility label, so a screen reader says "Flat white" instead of just "image".

The radius is repeated on the avatar fallback. Avatar and AvatarFallback are each rounded-full by default. If you only set rounded-2xl on Avatar, the emoji background stays a circle and pokes out of the rounded square.

You should also use numberOfLines={1} instead of truncate. Tailwind's truncate relies on text-overflow: ellipsis, which React Native doesn't support, and Uniwind doesn't convert it. The class compiles to nothing, so a long product name pushes the price off the screen. The numberOfLines prop is the React Native way to do this, and it also works in the web build.

The name has shrink and its column has flex-1. Without shrink, a long name won't get smaller and will push the badge out of the row. This is regular Flexbox behavior, but it shows up more on a phone because there's less width to work with.

hitSlop={8} makes small buttons easier to tap. Apple recommends touch targets of at least 44 points and Android recommends 48dp, but a size-7 button is only 28 points wide. The hitSlop prop makes the touchable area larger without changing how the button looks. There's no CSS equivalent.

Finally, tabular-nums keeps digits the same width. In most fonts, the digit 1 is narrower than 8, so prices would shift sideways every time the quantity changes. Uniwind converts tabular-nums to React Native's fontVariant, so it works on iOS, Android, and the web.

After adding this component and rendering it inside a Card (which you'll do in Step 10), you should see three rows:

Tapping plus on the flat white should change its price from $9.50 to $14.25. Tapping the trash icon on an item with a quantity of one should remove the row. The minus button turns into a trash icon whenever the quantity is one.

Step 7: Build the Pickup Options

The pickup card brings together three controls: a Select, an Input, and a Switch. The input and switch are fairly straightforward. The Select needs a little more attention because it has three platform-related quirks, and two of them can fail silently.

Create components/cart/pickup-card.tsx:

import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@/components/ui/select';
import { Switch } from '@/components/ui/switch';
import { Text } from '@/components/ui/text';
import { PICKUP_TIMES } from '@/lib/menu';
import { View } from 'react-native';
import { useSafeAreaInsets } from 'react-native-safe-area-context';

type PickupCardProps = {
  pickupValue: string;
  onPickupValueChange: (value: string) => void;
  name: string;
  onNameChange: (value: string) => void;
  ownCup: boolean;
  onOwnCupChange: (value: boolean) => void;
};

export function PickupCard({
  pickupValue,
  onPickupValueChange,
  name,
  onNameChange,
  ownCup,
  onOwnCupChange,
}: PickupCardProps) {
  const insets = useSafeAreaInsets();
  // Look the label up from our own data. The Option handed back by onValueChange
  // does not carry a usable label on web. See the note below.
  const selected = PICKUP_TIMES.find((time) => time.value === pickupValue);
  const contentInsets = {
    top: insets.top,
    bottom: insets.bottom,
    left: 16,
    right: 16,
  };

  return (
    <View className="gap-5">
      <View className="gap-2">
        <Label nativeID="pickup-time">Pickup time</Label>
        <Select
          value={selected}
          onValueChange={(option) => {
            if (option) {
              onPickupValueChange(option.value);
            }
          }}>
          <SelectTrigger className="w-full" aria-labelledby="pickup-time">
            <SelectValue placeholder="Pick a time" />
          </SelectTrigger>
          <SelectContent insets={contentInsets} className="w-full">
            {PICKUP_TIMES.map((time) => (
              <SelectItem key={time.value} value={time.value} label={time.label} />
            ))}
          </SelectContent>
        </Select>
      </View>

      <View className="gap-2">
        <Label nativeID="order-name">Name for the order</Label>
        <Input
          aria-labelledby="order-name"
          value={name}
          onChangeText={onNameChange}
          placeholder="Who is picking it up?"
          autoCapitalize="words"
          autoComplete="name"
          returnKeyType="done"
        />
      </View>

      <View className="flex-row items-center justify-between gap-4">
        <View className="flex-1 gap-1">
          <Label nativeID="own-cup" onPress={() => onOwnCupChange(!ownCup)}>
            Bringing my own cup
          </Label>
          <Text variant="muted">Takes 25¢ off and saves a lid.</Text>
        </View>
        <Switch nativeID="own-cup" checked={ownCup} onCheckedChange={onOwnCupChange} />
      </View>
    </View>
  );
}

Problem 1: Portals and the PortalHost

When a dropdown opens, it needs to appear above the other content on the screen. For that reason, SelectContent isn't rendered in the same place where you declare it in the component tree. It uses @rn-primitives/portal to render the content in another part of the app. This technique is called a portal.

On the web, a portal renders into document.body, and every page has one. React Native has nothing like that. So the portal package keeps a list of portal contents in memory, and a component called PortalHost reads that list and displays it. This is a simplified version of that code from node_modules/@rn-primitives/portal/dist/index.js:

var DEFAULT_PORTAL_HOST = "INTERNAL_PRIMITIVE_DEFAULT_HOST_NAME";
var updatePortal = (hostName, name, children) => { /* writes into the map */ };
function PortalHost({ name = DEFAULT_PORTAL_HOST }) { /* reads the map */ }

If no PortalHost is mounted, the content is saved but never displayed. The dropdown opens into nothing, and you get no error or warning.

The template already includes a PortalHost at the bottom of the root layout:

<ThemeProvider value={NAV_THEME[theme ?? 'light']}>
  <StatusBar style={theme === 'dark' ? 'light' : 'dark'} />
  <Stack />
  <PortalHost />
</ThemeProvider>

It looks like unnecessary code, but you need to keep it. The AlertDialog in Step 10 uses it too.

Problem 2: Safe Area Insets

There's another issue to consider when showing a dropdown on a phone. Parts of the screen are reserved for the operating system, such as the area around the notch and the home indicator. If a dropdown opens near the bottom of the screen, one of its options could appear underneath the home indicator. In that area, a tap may be handled by the operating system instead of your app.

To avoid this, pass the safe area insets to the content:

const insets = useSafeAreaInsets();
const contentInsets = { top: insets.top, bottom: insets.bottom, left: 16, right: 16 };

<SelectContent insets={contentInsets} className="w-full">

The insets prop is part of PositionedContentProps in @rn-primitives/types, so every positioned component in the registry accepts it, including Popover, DropdownMenu, HoverCard, Tooltip, and Select. It's a good habit to pass it every time.

Problem 3: The Select Value Is an Object

One more thing to watch out for is the value returned by onValueChange. It may look like you're selecting a string, but the callback returns an Option object:

type Option = { value: string; label: string } | undefined;

This causes a bug that only appears on one platform. If you store the whole Option in state and show option.label later, such as in a confirmation dialog, it displays correctly on a phone ("In 30 minutes") but incorrectly in the browser ("30").

The reason is in the primitive's source code. This is the native version, from select.js:

onValueChange({ value: itemValue, label });

And this is the web version, from select.web.js. It uses Radix, which only returns a value:

onValueChange({ value: val, label: val });

So the label is correct on native, but on the web it's a copy of the value. If you only test in a simulator, you won't notice this problem.

The fix is to keep only the value in state and look up the label from your own list:

const selected = PICKUP_TIMES.find((time) => time.value === pickupValue);

This is why PICKUP_TIMES is in lib/menu.ts. The pickup card needs it to build the options, and the main screen needs it to write the confirmation message.

Making the Label Tappable

The switch itself is quite small, so users may tap the label next to it instead. It makes sense to let that label toggle the switch as well. You can do that by adding an onPress handler to the Label:

<Label nativeID="own-cup" onPress={() => onOwnCupChange(!ownCup)}>
  Bringing my own cup
</Label>
<Switch nativeID="own-cup" checked={ownCup} onCheckedChange={onOwnCupChange} />

Giving both elements the same nativeID connects them for screen readers. The onPress on the Label is what makes the text toggle the switch, because React Native has no automatic <label for> behavior.

While you're here, open components/ui/switch.tsx. On the web, shadcn colors a switch with data-[state=checked]:bg-primary, which reads an attribute set in the DOM. React Native has no data-* attributes, so the component checks the prop in JavaScript:

props.checked ? 'bg-primary' : 'bg-input dark:bg-input/80',

The result is the same. Keep this in mind if you copy a data-[state=...] selector from a web example and it has no effect.

Keyboard Props for the Name Field

Input is a TextInput with your border and radius applied. You should set these four props on every text input:

• autoCapitalize="words" capitalizes each word, which suits a name.
• autoComplete="name" lets the operating system offer to fill in the name.
• returnKeyType="done" changes the return key label to "Done".
• keyboardType="number-pad" shows a numeric keyboard when you need digits.

Together with automaticallyAdjustKeyboardInsets on the ScrollView from Step 5, this keeps the field visible while the keyboard is open. If you need more control, react-native-keyboard-controller is already a dependency of the template, and it provides KeyboardAwareScrollView and KeyboardProvider.

When you open the dropdown, it should appear right under the trigger at the same width, with a check mark next to the current value:

Try picking a time and check that the trigger updates. Tap the words "Bringing my own cup" and confirm the switch flips. Type in the name field and confirm the keyboard doesn't cover it. If the dropdown opens and shows nothing, check your PortalHost.

Step 8: Build the Bill Component

The bill component is pretty small, but there are two details you should pay particular attention to here, especially when the values change while someone is editing their order.

Create components/cart/bill.tsx:

import { Separator } from '@/components/ui/separator';
import { Text } from '@/components/ui/text';
import { cn } from '@/lib/utils';
import { money } from '@/lib/menu';
import { View } from 'react-native';

type BillProps = {
  subtotal: number;
  discount: number;
  tax: number;
  total: number;
};

function Line({ label, value, tone }: { label: string; value: number; tone?: 'muted' | 'credit' }) {
  return (
    <View className="flex-row items-center justify-between">
      <Text className={cn('text-sm', tone === 'muted' && 'text-muted-foreground')}>{label}</Text>
      <Text
        className={cn(
          'text-sm tabular-nums',
          tone === 'muted' && 'text-muted-foreground',
          tone === 'credit' && 'text-foreground'
        )}>
        {money(value)}
      </Text>
    </View>
  );
}

export function Bill({ subtotal, discount, tax, total }: BillProps) {
  return (
    <View className="gap-2">
      <Line label="Subtotal" value={subtotal} tone="muted" />
      {discount > 0 ? <Line label="Own cup" value={-discount} tone="credit" /> : null}
      <Line label="Tax" value={tax} tone="muted" />
      <Separator className="my-1" />
      <View className="flex-row items-center justify-between">
        <Text className="font-medium">Total</Text>
        <Text className="text-lg font-semibold tabular-nums">{money(total)}</Text>
      </View>
    </View>
  );
}

First, use tabular-nums on every number. Right-aligned prices in a proportional font don't line up at the decimal point, and using tabular-nums fixes that, as in the order rows.

Second, only show the discount row when it applies. The code uses {discount > 0 ? <Line /> : null} instead of {discount && <Line />}. In JSX, if the left side of && is the number 0, React renders the 0. In React Native, a bare number outside a Text component throws the error Text strings must be rendered within a <Text> component. Using a boolean check and returning null avoids this whole category of bugs.

To test it, turn on the own cup switch and scroll down. An Own cup line should appear with -$0.25, and the tax should change from $1.54 to $1.52, because tax is calculated on the discounted subtotal:

The total changes from $20.19 to $19.92, which is 27 cents lower instead of 25. The extra two cents come from the lower tax.

Step 9: Build the Fixed Checkout Bar

I want the total and checkout button to remain visible while the user scrolls through the cart. On the web, you might reach for position: sticky and bottom: 0. React Native doesn't work that way, but we can get the same result with a simple flex layout.

You can get the same result with Flexbox. This is the layout from Step 5 again:

<View className="bg-background flex-1">
  <ScrollView className="flex-1" ...>{/* content */}</ScrollView>
  <CheckoutBar ... />
</View>

The outer View is a column. The ScrollView has flex-1, so it takes all the leftover height. The checkout bar is a sibling placed after it, so it sits at the bottom and doesn't scroll. You don't need any positioning or z-index.

Handling the Home Indicator

On phones without a home button, the bottom 34 points or so belong to the system. A button drawn there is hard or impossible to press. To avoid this, add the bottom safe area inset as padding.

const insets = useSafeAreaInsets();

<View
  className="border-border bg-background flex-row items-center gap-4 border-t px-4 pt-3"
  style={{ paddingBottom: insets.bottom + 12 }}>

The bottom padding is an inline style instead of a class because its value depends on the device and is only known when the app runs. Using className and style on the same element is fine, and this is the case it's meant for.

On devices with no gesture bar, and in a browser tab, insets.bottom is 0, so the extra 12 keeps the bar from looking cramped.

Create the full component in components/cart/checkout-bar.tsx. It includes the confirmation dialog, which Step 10 explains.

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from '@/components/ui/alert-dialog';
import { Button } from '@/components/ui/button';
import { Icon } from '@/components/ui/icon';
import { Text } from '@/components/ui/text';
import { money } from '@/lib/menu';
import * as Haptics from 'expo-haptics';
import { ArrowRightIcon } from 'lucide-react-native';
import { View } from 'react-native';
import { useSafeAreaInsets } from 'react-native-safe-area-context';

type CheckoutBarProps = {
  total: number;
  itemCount: number;
  pickupLabel: string;
  name: string;
  onConfirm: () => void;
};

export function CheckoutBar({ total, itemCount, pickupLabel, name, onConfirm }: CheckoutBarProps) {
  const insets = useSafeAreaInsets();
  const empty = itemCount === 0;

  function confirm() {
    // expo-haptics ships a web implementation that falls back to navigator.vibrate,
    // so this needs no platform guard.
    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
    onConfirm();
  }

  return (
    <View
      className="border-border bg-background flex-row items-center gap-4 border-t px-4 pt-3"
      style={{ paddingBottom: insets.bottom + 12 }}>
      <View className="flex-1">
        <Text variant="muted" className="text-xs">
          {empty ? 'Nothing in the cart' : `${itemCount} ${itemCount === 1 ? 'item' : 'items'}`}
        </Text>
        <Text className="text-xl font-semibold tabular-nums">{money(total)}</Text>
      </View>

      <AlertDialog>
        <AlertDialogTrigger asChild>
          <Button size="lg" disabled={empty}>
            <Text>Place order</Text>
            <Icon as={ArrowRightIcon} />
          </Button>
        </AlertDialogTrigger>
        <AlertDialogContent>
          <AlertDialogHeader>
            <AlertDialogTitle>Send this to the counter?</AlertDialogTitle>
            <AlertDialogDescription>
              {`${money(total)} for ${name.trim() || 'pickup'}, ${pickupLabel.toLowerCase()}. We start making it right away, so it cannot be cancelled after this.`}
            </AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel>
              <Text>Not yet</Text>
            </AlertDialogCancel>
            <AlertDialogAction onPress={confirm}>
              <Text>Send it</Text>
            </AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </View>
  );
}

A Note on Thin Borders

border-t draws a line that's one logical point thick, which is two or three physical pixels on most modern screens. Next to a true one-pixel line, it looks heavy. React Native's StyleSheet.hairlineWidth gives you the thinnest line the screen can draw, and the template connects it to Tailwind with this line in global.css:

--spacing-hairline: hairlineWidth();

This adds hairline to Tailwind's spacing scale, so h-hairline gives you a divider that's one physical pixel tall. The Common Mistakes section later explains one catch when you try to use it as an override.

That's the checkout bar in place. Scroll to the bottom of the screen and check that it stays below the bill:

Scroll back to the top and the bar stays in the same place:

On a phone with a notch, the button should be above the gesture bar. If you remove all items with the trash buttons, the button should be disabled and the label should say "Nothing in the cart".

Step 10: Add the Confirmation and Put the Screen Together

The checkout bar already contains the confirmation dialog. Before putting the full screen together, there are two differences between the React Native implementation and the web version that are worth looking at.

1. It Also Needs the PortalHost

On iOS, it also wraps itself in FullWindowOverlay from react-native-screens, so it draws above the native navigation header instead of under it. This is handled inside alert-dialog.tsx, which is why that file imports something that looks unrelated.

2. The Footer Reverses its Order on Phones

AlertDialogFooter uses flex-col-reverse and only becomes a row at the sm: breakpoint. On a phone, the button you write last is shown on top. Writing Cancel first and Action second puts the confirm button where the thumb is and the cancel button below it.

Haptics

When the customer confirms the order, the confirm function calls Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success). This gives a short success vibration on supported devices.

You might expect to wrap this call in a platform check because browsers don't have the same haptics support as native apps. In this case, expo-haptics already includes a web implementation that uses navigator.vibrate, with a fallback for iOS Safari. If the browser can't provide haptics, the call simply does nothing, so we don't need an extra platform check.

notificationAsync is meant for outcomes such as success or failure. impactAsync is for physical collisions, and selectionAsync is for moving through a list of options. Using the wrong one won't cause an error, but it feels slightly off.

The Full Screen

Now we can bring everything together in the main screen. This is where we'll keep the state, calculate the bill using billFor, and pass the required values and callbacks to each component.

When an order is placed, it sets orderNumber, and the screen shows a confirmation instead. Inside that confirmation, <Stack.Screen options> changes the header title to "Order sent" without navigating anywhere, so the whole flow stays in one file and one route.

Replace app/index.tsx with:

import { Bill } from '@/components/cart/bill';
import { CheckoutBar } from '@/components/cart/checkout-bar';
import { OrderRow } from '@/components/cart/order-row';
import { PickupCard } from '@/components/cart/pickup-card';
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
import { Icon } from '@/components/ui/icon';
import { Separator } from '@/components/ui/separator';
import { Text } from '@/components/ui/text';
import { billFor, INITIAL_CART, PICKUP_TIMES, type CartItem } from '@/lib/menu';
import { Stack } from 'expo-router';
import { CircleCheckIcon, MoonStarIcon, SunIcon } from 'lucide-react-native';
import * as React from 'react';
import { ScrollView, View } from 'react-native';
import { Uniwind, useUniwind } from 'uniwind';

const SCREEN_OPTIONS = {
  title: 'Your order',
  headerRight: () => <ThemeToggle />,
};

export default function CartScreen() {
  const [items, setItems] = React.useState<CartItem[]>(INITIAL_CART);
  const [pickupValue, setPickupValue] = React.useState(PICKUP_TIMES[0].value);
  const [name, setName] = React.useState('');
  const [ownCup, setOwnCup] = React.useState(false);
  const [orderNumber, setOrderNumber] = React.useState<string | null>(null);

  const bill = billFor(items, ownCup);
  const itemCount = items.reduce((count, item) => count + item.qty, 0);
  const pickupLabel =
    PICKUP_TIMES.find((time) => time.value === pickupValue)?.label ?? PICKUP_TIMES[0].label;

  function changeQty(id: string, qty: number) {
    setItems((current) =>
      qty <= 0
        ? current.filter((item) => item.id !== id)
        : current.map((item) => (item.id === id ? { ...item, qty } : item))
    );
  }

  function placeOrder() {
    setOrderNumber(`A-${Math.floor(Math.random() * 90 + 10)}`);
  }

  function startOver() {
    setItems(INITIAL_CART);
    setOwnCup(false);
    setName('');
    setPickupValue(PICKUP_TIMES[0].value);
    setOrderNumber(null);
  }

  if (orderNumber) {
    return (
      <>
        <Stack.Screen options={{ ...SCREEN_OPTIONS, title: 'Order sent' }} />
        <View className="bg-background flex-1 items-center justify-center gap-6 p-8">
          <Icon as={CircleCheckIcon} className="text-primary size-16" />
          <View className="gap-2">
            <Text variant="h3" className="text-center">
              We are on it
            </Text>
            <Text variant="muted" className="text-center">
              {`Order ${orderNumber} for ${name.trim() || 'pickup'}. Come to the far end of the counter and look for your name on the cup.`}
            </Text>
          </View>
          <Button variant="outline" onPress={startOver}>
            <Text>Start another order</Text>
          </Button>
        </View>
      </>
    );
  }

  return (
    <>
      <Stack.Screen options={SCREEN_OPTIONS} />
      <View className="bg-background flex-1">
        <ScrollView
          className="flex-1"
          contentContainerClassName="gap-4 p-4 pb-8"
          keyboardShouldPersistTaps="handled"
          automaticallyAdjustKeyboardInsets>
          <Card className="gap-3 py-4">
            <CardHeader className="px-4">
              <CardTitle>Fernwood Coffee</CardTitle>
              <CardDescription>112 Marine Drive, counter pickup</CardDescription>
            </CardHeader>
            <CardContent className="gap-4 px-4">
              {items.length === 0 ? (
                <Text variant="muted">Your cart is empty. Add something warm.</Text>
              ) : null}
              {items.map((item, index) => (
                <React.Fragment key={item.id}>
                  {index > 0 ? <Separator /> : null}
                  <OrderRow item={item} onChangeQty={changeQty} />
                </React.Fragment>
              ))}
            </CardContent>
          </Card>

          <Card className="gap-3 py-4">
            <CardHeader className="px-4">
              <CardTitle>Pickup</CardTitle>
            </CardHeader>
            <CardContent className="px-4">
              <PickupCard
                pickupValue={pickupValue}
                onPickupValueChange={setPickupValue}
                name={name}
                onNameChange={setName}
                ownCup={ownCup}
                onOwnCupChange={setOwnCup}
              />
            </CardContent>
          </Card>

          <Card className="gap-3 py-4">
            <CardHeader className="px-4">
              <CardTitle>Bill</CardTitle>
            </CardHeader>
            <CardContent className="px-4">
              <Bill {...bill} />
            </CardContent>
          </Card>
        </ScrollView>

        <CheckoutBar
          total={bill.total}
          itemCount={itemCount}
          pickupLabel={pickupLabel}
          name={name}
          onConfirm={placeOrder}
        />
      </View>
    </>
  );
}

const THEME_ICONS = {
  light: SunIcon,
  dark: MoonStarIcon,
};

function ThemeToggle() {
  const { theme } = useUniwind();

  return (
    <Button
      onPressIn={() => Uniwind.setTheme(theme === 'dark' ? 'light' : 'dark')}
      size="icon"
      variant="ghost"
      className="ios:size-9 web:mx-4 rounded-full"
      accessibilityLabel="Switch theme">
      <Icon as={THEME_ICONS[theme ?? 'light']} className="size-5" />
    </Button>
  );
}

Notice that pickupLabel is the fix from Step 7 in use. The screen looks up the label from PICKUP_TIMES and passes a plain string to CheckoutBar, so CheckoutBar never touches an Option object or the incorrect web label.

To test it, place an order. The dialog should show your name and the pickup time you chose (such as "in 30 minutes"), not the raw value 30. Confirm the order, and you should see the confirmation screen:

Tap "Start another order" and the cart returns to its original state.

The checkout screen is now working, and each part is kept in its own component. You can use the same approach when you build other screens: keep the component focused, pass the data it needs through props, and let the shared theme handle the styling.

Step 11: Add Dark Mode

We already added the theme toggle in Step 10. Here's the component again so we can look at how it switches between light and dark mode:

import { Uniwind, useUniwind } from 'uniwind';

function ThemeToggle() {
  const { theme } = useUniwind();

  return (
    <Button
      onPressIn={() => Uniwind.setTheme(theme === 'dark' ? 'light' : 'dark')}
      size="icon"
      variant="ghost"
      className="ios:size-9 web:mx-4 rounded-full"
      accessibilityLabel="Switch theme">
      <Icon as={THEME_ICONS[theme ?? 'light']} className="size-5" />
    </Button>
  );
}

Uniwind.setTheme changes the values behind every token, so everything that uses bg-card, text-muted-foreground, and similar classes updates at once. useUniwind subscribes the component to the current theme, so the icon changes too.

This code also uses the ios: and web: prefixes. Uniwind supports platform variants, so web:mx-4 only adds margin in the browser, and ios:size-9 only applies on iOS. It's similar to Platform.select, but it stays inside the class string.

Three things aren't handled by setTheme, and if you forget them, you end up with a screen that's only partly dark. The template already sets up the first two.

1. The Navigation Header

React Navigation takes its colors from a plain object, so the root layout needs to pass it the right one:

const { theme } = useUniwind();

<ThemeProvider value={NAV_THEME[theme ?? 'light']}>

2. The Status Bar

The clock and battery icons are drawn by the operating system, so you need to tell it which style to use. Without this, you can get dark text on a dark bar.

<StatusBar style={theme === 'dark' ? 'light' : 'dark'} />

3. Saving the Choice

Uniwind.setTheme only applies to the current session. The next time the app starts, it follows the system setting again. To keep the user's choice, save it with expo-secure-store or AsyncStorage and call setTheme when the app starts. You can call setTheme('system') to go back to following the operating system.

When you tap the header icon, the cards, borders, inputs, switch, header, and status bar should all change together. You can explore more ready-made shadcn blocks if you want examples of how these components are used in larger interfaces:

Look for anything that stays light while the rest goes dark. A light header usually means the ThemeProvider is not receiving the new NAV_THEME.

Step 12: Create Your Own Theme

The screen is currently using the default gray theme. Let's change it to a coffee-inspired palette with warm cream backgrounds and brown accents. This will also help us see why the palette needs to be updated in both global.css and lib/theme.ts.

Update the Tokens

Replace the @layer theme block in global.css with this coffee palette:

@layer theme {
  :root {
    @variant light {
      --color-background: oklch(0.98 0.008 75);
      --color-foreground: oklch(0.24 0.02 60);
      --color-card: oklch(1 0.003 90);
      --color-card-foreground: oklch(0.24 0.02 60);
      --color-popover: oklch(1 0.003 90);
      --color-popover-foreground: oklch(0.24 0.02 60);
      --color-primary: oklch(0.44 0.06 45);
      --color-primary-foreground: oklch(0.99 0.01 85);
      --color-secondary: oklch(0.93 0.03 80);
      --color-secondary-foreground: oklch(0.35 0.05 45);
      --color-muted: oklch(0.95 0.012 80);
      --color-muted-foreground: oklch(0.52 0.02 60);
      --color-accent: oklch(0.92 0.04 78);
      --color-accent-foreground: oklch(0.32 0.05 45);
      --color-destructive: oklch(0.577 0.245 27.325);
      --color-border: oklch(0.89 0.02 75);
      --color-input: oklch(0.89 0.02 75);
      --color-ring: oklch(0.44 0.06 45);
    }

    @variant dark {
      --color-background: oklch(0.17 0.012 60);
      --color-foreground: oklch(0.96 0.008 85);
      --color-card: oklch(0.22 0.016 62);
      --color-card-foreground: oklch(0.96 0.008 85);
      --color-popover: oklch(0.22 0.016 62);
      --color-popover-foreground: oklch(0.96 0.008 85);
      --color-primary: oklch(0.85 0.09 75);
      --color-primary-foreground: oklch(0.22 0.03 55);
      --color-secondary: oklch(0.29 0.022 62);
      --color-secondary-foreground: oklch(0.94 0.01 85);
      --color-muted: oklch(0.27 0.018 62);
      --color-muted-foreground: oklch(0.72 0.015 75);
      --color-accent: oklch(0.31 0.03 65);
      --color-accent-foreground: oklch(0.95 0.01 85);
      --color-destructive: oklch(0.704 0.191 22.216);
      --color-border: oklch(1 0 0 / 12%);
      --color-input: oklch(1 0 0 / 15%);
      --color-ring: oklch(0.85 0.09 75);
    }
  }
}

If you don't want to choose thirty colors by hand, you can generate a theme with the shadcn theme generator or tweakcn. Both export CSS variables, but you need to make two changes before the output works in this project:

1. Rename each variable to include the --color- prefix. For example, --primary becomes --color-primary.
2. Move the :root block inside @variant light, and the .dark block inside @variant dark.

Also remove --radius from what you paste, because the template already defines it along with the derived sizes. Remove any --shadow-* variables too, since nothing in the registry reads them.

Update lib/theme.ts

After you save and reload, the result looks like this:

The page is cream, the button is brown, and the badges have the right color, but the header is still white with a visible line under it. The reason is that React Navigation draws the header using lib/theme.ts, and that file still has the old palette. Nothing is broken and nothing warns you, so this mistake is easy to miss. If you're designing the same interface in Figma, the shadcn Figma resources can also help you keep the design and implementation aligned.

Update lib/theme.ts to match:

import { DarkTheme, DefaultTheme, type Theme } from 'expo-router/react-navigation';

export const THEME = {
  light: {
    background: '#fcf8f3',
    foreground: '#261d16',
    card: '#fffffd',
    primary: '#6e4836',
    border: '#e3d9cd',
    destructive: '#e7000b',
    /* the rest of the list */
  },
  dark: {
    background: '#130e0a',
    foreground: '#f4f1ec',
    card: '#201913',
    primary: '#f1c68b',
    border: '#3a3129',
    destructive: '#ff6467',
    /* the rest of the list */
  },
};

export const NAV_THEME: Record<'light' | 'dark', Theme> = {
  light: {
    ...DefaultTheme,
    colors: {
      background: THEME.light.background,
      border: THEME.light.border,
      card: THEME.light.background,
      notification: THEME.light.destructive,
      primary: THEME.light.primary,
      text: THEME.light.foreground,
    },
  },
  dark: {
    ...DarkTheme,
    colors: {
      background: THEME.dark.background,
      border: THEME.dark.border,
      card: THEME.dark.background,
      notification: THEME.dark.destructive,
      primary: THEME.dark.primary,
      text: THEME.dark.foreground,
    },
  },
};

This isn't a direct copy of global.css, so three points need explanation:

• Use hex colors instead of oklch(): Uniwind converts oklch() for your classes, but React Navigation does not, so give it a format that React Native can read directly. You can convert a color with any online converter, or paste the oklch() value into your browser's developer tools color picker and read the hex value.
• Map React Navigation's card to your background, not your card. The two names look the same but mean different things. In shadcn, card is a raised surface on top of the page. In React Navigation, card is the background of the screen and header. If you map them by name, the header ends up a shade lighter than the page. You won't notice this with the stock template because it uses the same value for card and background. It only shows up once you create a theme where cards stand out from the page, like this one.
• Use a solid color in place of a transparent border. In dark mode, --color-border is oklch(1 0 0 / 12%), which is white at 12% opacity. A navigation theme needs a solid color, so work out what that border looks like on your background and use that value.

After this change, the header and page match in both light and dark mode, and you didn't edit any component files:

Switch between light and dark a few times and watch the header. If it's a shade lighter or darker than the page, one of the values in lib/theme.ts is still from the old palette.

Common Mistakes and How to Fix Them

If you're coming from web development, some of these differences may catch you off guard. I've collected the issues covered in the tutorial in the table below, along with the fix for each one. You can refer back to it when something doesn't behave as expected.

The last row needs more explanation, because it looks like a bug in cn(), but it's not.

cn() uses tailwind-merge, which resolves conflicts between classes. It knows the default Tailwind scale, but it doesn't know about custom values you declare in global.css. The value hairline comes from --spacing-hairline: hairlineWidth(), so tailwind-merge can't tell that h-hairline and h-[1px] set the same property, and it keeps both:

cn('h-[1px] w-full', 'h-hairline my-1')  // 'h-[1px] w-full h-hairline my-1'
cn('h-[1px] w-full', 'h-2 my-1')         // 'w-full h-2 my-1'

The second result is correct. In the first, which height wins depends on the order of the CSS. The other overrides in this tutorial, such as size-14 over size-8, work correctly because those are names tailwind-merge recognizes. If you want it to understand your custom scale, you can teach it with extendTailwindMerge in lib/utils.ts. Otherwise, use an arbitrary value, or edit the component file directly, since you own it.

There's a related case in the stepper buttons. They pass size-7 to a Button whose icon size is h-10 w-10 sm:h-9 sm:w-9:

cn('h-10 w-10 sm:h-9 sm:w-9', 'size-7 rounded-full')
// 'sm:h-9 sm:w-9 size-7 rounded-full'

size-7 replaces the base h-10 w-10, but the two sm: classes stay, because tailwind-merge treats a responsive variant as a different class. On a phone this makes no difference, since sm: starts at 640px and phones are narrower than that. In a desktop browser, though, those buttons grow to 36 points.

Conclusion

In this tutorial, we built a coffee shop cart and checkout screen with React Native Reusables, Expo, and Uniwind. We added the order rows, pickup options, bill summary, fixed checkout bar, and confirmation dialog. We also looked at how the registry and CLI add component source code to the project and how the theme tokens control the app's colors.

One thing worth getting into the habit of is checking the component source when something doesn't behave the way you expect. Since the components live in your project, you can open them and see how they work. That's how we understood the difference in the Select label between web and native. It also makes customization easier because you can see which part of the component needs to change instead of adding more workarounds around it.

You can find the complete project in the GitHub repository. If you run into an issue or want to compare your code with the finished screen, clone the repository and check the implementation. If you're looking for more complete starting points for your next project, take a look at shadcn templates.

I captured the screenshots using the React Native Web build at a phone-sized viewport. The same project also runs on iOS and Android. I've called out the platform differences in the relevant sections, including the Select label and portal host in Step 7, safe area handling in Step 9, and haptics in Step 10.

Resources

React Native Reusables

• reactnativereusables.com: documentation and the registry
• Introduction: the list of differences from web shadcn
• CLI reference: the init, add, and doctor commands
• Create your own registry: publish components your team can add with the CLI
• The repository: MIT licensed
• Any registry entry is a public URL: reactnativereusables.com/r/uniwind/<name>.json or .../r/nativewind/<name>.json

Tools used

• RN Primitives
• Uniwind
• Nativewind
• Expo Router
• shadcn/ui and the registry specification

APIs used

• useSafeAreaInsets
• expo-haptics
• hitSlop
• numberOfLines
• tailwind-merge
• oklch()

But there's an interesting problem with this approach. What happens when a bot doesn't need to solve the CAPTCHA itself because a real person can solve it for them?

This is how CAPTCHA farms work. Attackers use services where real people solve CAPTCHA challenges on behalf of automated programs. The person completing the challenge is human, but the activity happening behind it may still be controlled by a bot. This makes it harder for websites to identify suspicious requests, even when their CAPTCHA system appears to be working correctly.

Here, we'll look at how CAPTCHA farm attacks work, why attackers use human solvers, and what makes these attacks difficult to detect. We'll also go through some of the security measures developers can use to identify suspicious activity and better protect their websites.

What We'll Cover:

• What Is a CAPTCHA Farm Attack?
• Behind the Scenes: The Four-Part Infrastructure
• How an Attack Unfolds: A Step-by-Step Look
• Why Attackers Rely on Human Solvers
• What CAPTCHA Farms Target
• Why These Attacks Are Difficult to Stop
• How Websites Can Defend Themselves
  • Behavioral Telemetry and Biometrics
  • Network and Device Fingerprinting
  • Modern Rate-Limiting Models
  • Post-Authentication Anomaly Detection
• Security Beyond the Checkbox
• Conclusion

What Is a CAPTCHA Farm Attack?

To understand how these attacks work, it helps to distinguish between the two primary ways attackers deal with verification gates: machine-driven recognition and human-driven outsourcing.

In an automated CAPTCHA-solving attack, an attacker uses computer vision models, optical character recognition (OCR), or neural networks to parse the challenge image and guess the answer without human intervention.

This approach is fast and computationally cheap, but it frequently fails when security vendors update their visual distortions, introduce interactive logic puzzles, or assess human-like mouse kinematics.

A CAPTCHA farm attack takes the opposite route. Instead of attempting to outsmart the defensive algorithm with software, the attacker routes the challenge to a human solving service. These commercial operations maintain large networks of manual workers who solve puzzles continuously around the clock. By inserting a human into the loop, the attacker converts what should be a technical roadblock into an outsourced labor pipeline.

The attack doesn't break the cryptography or reverse-engineer the underlying challenge code. Instead, it relies on a CAPTCHA relay attack: software manages the speed and scale of the attack, while real human eyes provide the cognitive validation the website expects.

Behind the Scenes: The Four-Part Infrastructure

A functional CAPTCHA farm is neither an ad-hoc group of rogue hackers nor an obscure black-box script. It's a commercial, multi-tiered infrastructure built around standard web development protocols.

Four distinct components work together to make the relay happen in a matter of seconds.

First is the attacker’s automated script. This client bot typically runs headlessly via browser automation tools like Puppeteer, Playwright, or custom HTTP client libraries. The script navigates to a target platform, such as a user registration portal, and fills in usernames, passwords, and demographic fields at machine speed until it hits a defensive challenge.

Second is the CAPTCHA-solving platform's API. Commercial solver platforms act as brokers between abuse operators and manual laborers. When the attacker's script encounters a challenge, it intercepts the site's public key, the challenge URL, and the visual assets, packaging them into an HTTP POST request directed at the solving service’s application programming interface (API).

Third is the distributed human workforce. Workers access these services through dedicated web dashboards, mobile apps, or browser plug-ins. When the API receives a task from an attacker, it pushes the image directly onto a worker’s screen. The worker identifies the bicycles or fire hydrants, types the distorted characters, or drags the puzzle slider into place, earning a microscopic payout, often ranging from $0.50 to $2.00 per thousand puzzles solved.

Fourth is the payload delivery back to the target. Once the worker submits the correct solution, the broker API returns the generated verification token back to the attacker’s script. The script injects this validation token into the target website's hidden form field and fires the final submission request. To the receiving server, the request bears an authentic verification signature generated by a real human session.

How an Attack Unfolds: A Step-by-Step Look

To see how these parts interact in practice, consider a credential-stuffing or mass-account registration campaign against an online service.

1. Initiation: The attacker's script dispatches an HTTP request to establish a session with the target registration page, populating the input fields with generated credentials.
2. Challenge trigger: The target application evaluates the incoming request. Detecting an unfamiliar IP address or an incomplete browser fingerprint, it triggers a CAPTCHA modal, pausing the registration sequence until a valid solution token is supplied.
3. Extraction and dispatch: The bot reads the page DOM, captures the puzzle iframe parameters, site key, and challenge payload, and forwards this data to the CAPTCHA farm API.
4. Human execution: The farm's queuing system allocates the challenge to an active human worker. The worker completes the puzzle within an average response window of 10 to 25 seconds.
5. Token retrieval: The worker’s response yields an official validation token from the CAPTCHA provider's origin server. The solving farm's API returns this signed string to the attacker’s script.
6. Form finalization: The script injects the token into the page's response payload (such as g-recaptcha-response) and submits the form. The website’s backend queries the CAPTCHA provider's verification API, receives a confirmation that the challenge was successfully passed, and creates the account.

The entire loop completes well before typical session timeouts kick in, leaving the target server with no obvious visual anomaly to flag.

Why Attackers Rely on Human Solvers

Building and maintaining custom neural networks to break modern visual challenges requires constant development effort. Defensive providers frequently alter noise patterns, camera angles, distortion algorithms and semantic puzzles specifically to break automated image classifiers.

Human solvers bypass this arms race entirely because the human visual cortex processes semantic context effortlessly. A person instantly understands what constitutes a "motorcycle," even if the image is cropped awkwardly, partially obscured by street foliage, or rendered under strange lighting.

This human adaptability is supported by extensive security research. In a foundational study, Towards Understanding the Security of Modern Image Captchas and Underground Captcha-Solving Services, researchers analyzed the commercial ecosystem across 152 solving platforms. They found that human-solving services achieved near-flawless accuracy rates across complex, diverse image challenges where purely automated computer vision solvers repeatedly struggled or degraded over time.

Outsourcing the problem is also remarkably inexpensive. Because labor pools are drawn from regions with low living costs, attackers can bypass thousands of protective checkpoints for less than the price of a cup of coffee. The workflow is highly scalable: software handles millions of connections, while human labor is summoned on-demand only for the few seconds required to clear a barrier.

What CAPTCHA Farms Target

CAPTCHA farms rarely serve as self-contained attacks. Instead, they act as an operational enabler for wider abusive campaigns across the web.

First, they enable mass fake account creation. Malicious actors generate millions of disposable profiles on social media, dating networks, and developer platforms to distribute phishing links, spam search engines, or run coordinated disinformation campaigns.

They also facilitate credential stuffing. When attackers test databases of leaked usernames and passwords against banking or retail portals, defensive systems usually throw a CAPTCHA after a handful of failed attempts. Solver APIs allow the credential-testing bots to continue cycling through login credentials uninterrupted.

Inventory hoarding and scalping is another common use case. High-demand retail drops, concert tickets, and travel bookings are frequent targets. Security researchers tracking real-world bot traffic at DataDome documented an operation where an attacker combined bot automation with a CAPTCHA farm to orchestrate 18 million automated ticket-scalping attempts, successfully bypassing front-line interactive verification.

And they enable data scraping at scale. Web crawlers harvesting competitive pricing, directory databases, or intellectual property frequently utilize solver APIs whenever protected search and discovery pages present challenge gates.

In every case, the CAPTCHA farm doesn't execute the underlying abuse: it merely removes the specific verification tripwire meant to halt it.

Why These Attacks Are Difficult to Stop

Stopping CAPTCHA farms is inherently difficult because they exploit the core assumption behind standard challenge-response security: that the entity answering the challenge is the entity making the request.

This systemic blind spot is analyzed in the research paper On the Security and Usability of Dynamic Cognitive Game CAPTCHAs, which evaluated how puzzle formats hold up against relay systems. The study demonstrated that regardless of how cognitively engaging, gamified, or technically dynamic a test is, relay architectures successfully decouple cognitive processing from the requesting client. The server receives a mathematically legitimate, human-generated solution token, making the puzzle itself effectively irrelevant.

Also, attackers route their client requests through residential proxy networks. The initial HTTP request comes from one residential IP address, the CAPTCHA is rendered by an automated browser mimicking common hardware profiles, and the solution is completed remotely. The defender’s server can't verify the physical proximity between the solver and the requesting client, creating an asymmetric advantage for the attacker.

How Websites Can Defend Themselves

Because human solvers can easily clear visual and cognitive challenges, treating a solved puzzle as a blanket guarantee of trustworthiness is no longer a viable defensive strategy. Web applications require a defense-in-depth model that monitors behaviors before, during, and long after a verification challenge appears.

Behavioral Telemetry and Biometrics

Automated scripts can easily spoof screen resolutions and user-agent strings, but reproducing organic human cursor movement across an entire page requires far more work. Real users demonstrate micro-deviations, variable acceleration curves, pauses, and continuous mouse tremors.

When a CAPTCHA farm attack takes place, there's often a distinct behavioral mismatch: the form fields are filled out instantaneously or via scripted keyboard events, followed by an abrupt pause while the remote worker solves the puzzle, followed by an instantaneous token injection. Monitoring telemetry across the whole lifecycle of the page exposes this artificial stitching.

Network and Device Fingerprinting

Defenders must assess context beyond the single page interaction. Inspecting TCP/IP packet behavior, TLS fingerprints (JA3/JA4 fingerprints), HTTP/2 frame parameters, and device APIs reveals whether the underlying runtime environment is a standard consumer browser or an orchestrated automation tool running inside a data center.

Modern Rate-Limiting Models

Relying entirely on puzzle solving often introduces accessibility barriers for real users while doing little to stop funded attackers. As explored in research published by the Association for Computing Machinery regarding mCaptcha and Proof-of-Work Rate Limiting, defensive architectures can enforce cryptographic proof of work puzzles at the transport layer.

By forcing the connecting client's CPU to compute complex mathematical problems proportional to the platform's current traffic load, defense systems raise the economic and computational cost of running automated campaigns, neutralizing attacks without demanding manual human puzzle-solving.

Post-Authentication Anomaly Detection

Passing an authentication challenge should never grant unconditional trust. Web architectures should monitor post-login activity for anomalous actions:

• Does an account immediately attempt hundreds of data queries per minute right after registering?
• Does it immediately navigate directly to high-value purchase endpoints without loading associated asset stylesheets or images?
• Does the session change IP ranges and geographic locations between the initial page load and the final transaction?

Identifying these signals allows security teams to invalidate sessions even if the initial challenge was solved cleanly.

Security Beyond the Checkbox

CAPTCHA farms show why websites can't rely on a single security check to keep automated attacks away. Even when someone successfully completes a CAPTCHA, the request may still be part of an automated operation.

CAPTCHAs are designed to check whether a person can solve a particular challenge. But they can't tell whether that person is the actual user trying to access the website or someone solving the challenge on behalf of a bot. This is one of the reasons CAPTCHA farms can bypass a security measure that would normally stop automated traffic.

For developers, this means a completed CAPTCHA should be treated as just one part of the verification process. Websites also need to monitor user behavior, network activity, and suspicious requests to identify possible attacks. Combining these checks makes it easier to spot activity that a CAPTCHA alone might miss.

Conclusion

CAPTCHA farms make it difficult for websites to tell whether a completed verification challenge actually came from a legitimate user. Even when a real person solves the puzzle, the request may still be part of an automated attack.

For developers, this means it's worth paying attention to what happens before and after a CAPTCHA is completed. Things like unusual login attempts, repeated requests, unexpected changes in user behavior, and suspicious account activity can provide useful clues.

Using CAPTCHA alongside rate limiting, behavioral monitoring, and other security checks can help websites identify these attacks more effectively. It's also important to review these protections regularly as attackers change how they operate.

This is thanks to Socrates, a new tool we just launched. Socrates is built right into the freeCodeCamp curriculum. It can look at your code and give you hints to help you get unstuck.

When you ask Socrates for help, first it references the thousands of hints and test cases we've human-authored for the curriculum. And if none of those cover your situation, Socrates will come up with new hints to guide you.

Here're some photos of Socrates in action:

Socrates is live now. Try it on the freeCodeCamp curriculum.

Socrates frees up the forum to serve as a place for discussions

Since most people will be getting unstuck using Socrates, we think far fewer people will need to ask for help on the forum. So we can instead use the forum as a place to talk with fellow human beings about our hobbies, passions, studies, and goals.

Over the years we've built up a super chill mod team. Folks from all over the world with a broad range of backgrounds. These knights and dames keep the vibe positive and productive, and keep out the bots and spammers.

So here's what I want you to do.

1. Read our 85-word-long code of conduct.
2. Sign into the freeCodeCamp forum, read some threads, reply to some threads, and start some threads of your own.

As you use the forum, we'll trust you with more and more power there. More people will come to recognize you as a chill person who brings useful insights.

If you're looking for an alternative to divisive social media, a place where people talk WITH each other rather than PAST each other, well this is it. You've hit the jackpot.

I'm spending a lot of time there and hope you'll do the same.

Shout out to all the mods for helping everybody get the most out of the limited minutes in their day. See you on the forum.

Speed is a key part of it, too. A slow site can have very weak SEO, because most people won't spend much time waiting for a page to load, especially these days.

Site speed is a well-known topic with many problems of its own to consider, like Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), and server speed. But I'll leave those for another article.

This one is about the problems that stop search engines from reaching and reading your pages.

In my opinion, technical SEO is much harder to apply than regular SEO, which focuses on content and keywords. The technical side usually requires a developer's knowledge, and might need some changes that can feel a bit uncomfortable if you don't have a technical background.

A technical problem can stay unnoticed for months, because you usually don't see it. It's not a design problem. You only find it when you run specific checks, for example with Google PageSpeed Insights.

In this tutorial, you'll find and fix the most common ones on a small practice site. I didn't want to take a real website and shame its owners, so I built a practice site with the problems already in it.

Table of Contents

• Prerequisites
• What Is Technical SEO?
• How Common Are These Problems on Real Websites?
• How to Set Up the Practice Site
• How to Check a Page's HTTP Status Code
  • What Is a Soft 404?
• How to Find and Fix Redirect Chains
• How to Make Sure robots.txt Isn't Blocking Important Pages
• How to Find an Accidental noindex
  • How to Check the Robots Meta Tag
  • How to Check the X-Robots-Tag Header
• How to Use Canonical Tags Correctly
• How to Fix Missing and Duplicate Titles and Meta Descriptions
• How to Make Your Links Crawlable
• How to Check Whether Your Content Needs JavaScript to Appear
• Can You Check a Page in Five Minutes?
• Conclusion

Prerequisites

You don't need to be an experienced programmer to follow along. You'll need:

• A web browser, such as Chrome, Firefox, Edge or Safari. In Safari, first turn on Show features for web developers under Settings > Advanced.
• A terminal: Terminal on macOS, PowerShell on Windows, or any terminal on Linux.
• curl, a small program that downloads web pages. It comes with macOS, most Linux distributions, and Windows 10 (version 1803 and later) and Windows 11.
• Node.js, to run the practice site. The code was tested with Node.js 26.8 and curl 8.7.

On Windows PowerShell, type curl.exe instead of curl, because there curl is a shortcut to a different command. Replace | grep -i "text" with | Select-String "text", and /dev/null with NUL.

What Is Technical SEO?

Google has programs called crawlers. They search the internet all the time for new websites and new pages. When Google discovers a new address, it may crawl the page and process what's on it (the text, images, and videos).

If Google decides the page is worth indexing, it may add it to a very big database of web pages, called the index. Google can then consider the pages in its index for its search results, when they're relevant to what someone searches for. Google's guide to how Search works calls these three steps crawling, indexing, and serving.

So crawling doesn't guarantee indexing, and indexing doesn't guarantee a place in the results. The same guide says Google doesn't guarantee any of the three stages, even for a page that follows all of its rules.

Fixing technical problems won't necessarily make your site rank first on Google. But it does strengthen your chances of ranking higher, because every problem you fix makes your site better.

Technical SEO has to come together with regular SEO, like keywords, backlinks, engagement on social media, and so on.

How Common Are These Problems on Real Websites?

The numbers below come from audits run with the site-auditing tool I build. Each website counts once, using its first audit, and this data comes from October 25th.

Crawls check many pages on one site (a median of 10 pages here). Single-page audits check one page, usually the home page.

These are all technical problems, but they don't all weigh the same. Missing canonical tags are at the top, but Google doesn't require a canonical tag, so a page without one isn't broken by itself. It matters when the same or very similar content is reachable at more than one URL, as you'll see in the canonical section.

Duplicate titles are something I had myself: when you write code, it's easy to miss things like that. That's why there are tools that check for these problems.

Let's go over each issue in the table to make sure they're all clear:

• Missing canonical tag: a canonical tag is basically one of the many tags you put in the <head> of your HTML. When two or three pages have pretty much the same content, it tells search engines like Google which URL is the original, main version, the one you prefer to get indexed. It's not required, though: without it, Google picks the main version itself, so it matters mostly for pages that have duplicates.
• Duplicate titles: it's really easy to end up with the same title on two pages. You don't want a duplicated title because it's not helpful and can confuse Google. Each page should say what it's about.
• Missing meta description: this one is really important, because it helps search engines as well as AI tools like ChatGPT. The meta description is there to explain very briefly what the page is about and what it's for. If you go to Google and search for a website, you'll see it under the actual link to the site.
• A link to a 404 page: this basically means you have a broken link (maybe a link you probably don't use anymore) to a page that isn't there. So there's no reason for it to lead to something that doesn't exist. Use it to lead to something similar, or to something that does exist, so your links remain relevant.
• A page built mostly with JavaScript: Google can run JavaScript, so this alone doesn't keep a page out of Google. But the content appears only after the JavaScript loads and runs, which is slower for visitors and one more step that can fail, and not every crawler runs JS. That's why I prefer server-side rendering for the content that matters most.
• A link search engines can't follow: this isn't a huge deal, and it really depends where the link goes. But say I wrote a really nice article and I want it to help me rank on Google. If search engines can't follow the link to it, then you invested all this time and energy in this article that relatively few people will likely see.
• Errors in robots.txt: robots.txt basically helps you talk to search engines. If there are errors in this file, you might stop search engines from crawling pages you do want in search results.
• A page blocked by noindex or robots.txt: these are two different things. A noindex rule asks search engines to keep a page out of their results, while a robots.txt rule only stops them from crawling it. You'll learn more about both, and why the difference matters, later in this tutorial.

Soft 404s, redirect chains, and wrong canonical tags aren't in the table, because the audits don't record them.

How to Set Up the Practice Site

The practice site is a tiny website for a made-up shoe store called Acme Shoes. Every page on it has one problem built in. You don't need to understand every line of the code.

Create a new folder, add a file called server.js, and paste in this code:

// server.js: a tiny practice site with common technical SEO problems built in
const http = require('node:http');

const PORT = 8080;
const BASE = 'http://localhost:' + PORT;

// Builds a simple HTML page. Leave out a field to leave that tag out.
function page({ title, description, canonical, robots, body, script }) {
  return [
    '<!doctype html>',
    '<html lang="en">',
    '<head>',
    '<meta charset="utf-8">',
    title && '<title>' + title + '</title>',
    description && '<meta name="description" content="' + description + '">',
    canonical && '<link rel="canonical" href="' + BASE + canonical + '">',
    robots && '<meta name="robots" content="' + robots + '">',
    '</head>',
    '<body>',
    body,
    script && '<script>' + script + '</script>',
    '</body>',
    '</html>',
  ]
    .filter(Boolean)
    .join('\n');
}

const routes = {
  '/': {
    html: page({
      title: 'Acme Shoes: Running Shoes for Every Runner',
      description: 'Lightweight running shoes for road and trail, with free returns.',
      canonical: '/',
      body: [
        '<h1>Acme Shoes</h1>',
        '<a href="/products/blue-runner">Blue Runner</a>',
        '<span onclick="location.href=\'/sale\'">Summer sale</span>',
      ].join('\n'),
    }),
  },
  // Problem: a vague title and no meta description
  '/products/blue-runner': {
    html: page({
      title: 'Acme Shoes',
      canonical: '/products/blue-runner',
      body: '<h1>Blue Runner</h1>',
    }),
  },
  // Problem: a missing product that still answers "200 OK" (a soft 404)
  '/products/red-runner': {
    html: page({
      title: 'Acme Shoes',
      body: '<h1>Sorry, that product could not be found.</h1>',
    }),
  },
  // Problem: a redirect chain, /old-sale -> /sale-2025 -> /sale
  '/old-sale': { redirect: '/sale-2025' },
  '/sale-2025': { redirect: '/sale' },
  '/sale': {
    html: page({
      title: 'Summer Sale: Up to 40% Off Running Shoes | Acme Shoes',
      description: "Save up to 40% on last season's running shoes until August 31.",
      canonical: '/sale',
      body: '<h1>Summer sale</h1>',
    }),
  },
  // Problem: a noindex header nobody can see in the page itself
  '/about': {
    headers: { 'X-Robots-Tag': 'noindex' },
    html: page({
      title: 'About Acme Shoes',
      description: 'How a two-person workshop became a running shoe brand.',
      canonical: '/about',
      body: '<h1>About us</h1>',
    }),
  },
  // Problem: a canonical tag that points to the home page
  '/blog/choosing-trail-shoes': {
    html: page({
      title: 'How to Choose Trail Running Shoes | Acme Shoes',
      description: 'Grip, drop and fit: what to look for in a trail running shoe.',
      canonical: '/',
      body: '<h1>How to choose trail running shoes</h1>',
    }),
  },
  // Problem: the content only exists after JavaScript runs
  '/catalog': {
    html: page({
      title: 'All Running Shoes | Acme Shoes',
      description: 'Browse every Acme running shoe.',
      canonical: '/catalog',
      body: '<div id="app">Loading...</div>',
      script:
        "fetch('/api/products').then((r) => r.json()).then((products) => {" +
        "document.getElementById('app').innerHTML = products.map((p) => '<h2>' + p + '</h2>').join('');" +
        '});',
    }),
  },
  '/api/products': {
    type: 'application/json',
    html: JSON.stringify(['Blue Runner', 'Trail Grip 2', 'City Glide']),
  },
  // Problem: "Disallow: /blog" blocks every path that starts with /blog
  '/robots.txt': {
    type: 'text/plain',
    html: 'User-agent: *\nDisallow: /blog\n',
  },
};

http
  .createServer((req, res) => {
    const path = new URL(req.url, BASE).pathname;
    const route = routes[path];

    if (!route) {
      res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' });
      return res.end(page({ title: 'Page not found', body: '<h1>Page not found</h1>' }));
    }
    if (route.redirect) {
      res.writeHead(301, { Location: route.redirect });
      return res.end();
    }
    res.writeHead(200, {
      'Content-Type': (route.type || 'text/html') + '; charset=utf-8',
      ...route.headers,
    });
    res.end(route.html);
  })
  .listen(PORT, () => console.log('Practice site running at ' + BASE));

Each key in routes is a page address. The comments that start with Problem: say what's wrong with each page.

Start the server from the same folder:

node server.js

You should see:

Practice site running at http://localhost:8080

Leave the server running and open a second terminal for the commands below. When you change server.js, stop the server with Ctrl+C and start it again.

How to Check a Page's HTTP Status Code

I remember when I started building websites, I built all kinds of small things. I'm a full stack developer, and I kept trying experiments.

Once I had a problem on the server side and saw in the Network tab that it returned a 500 error. Another time I removed a page on purpose, because I wanted to see if I'd get a 404 or other problems. If you just play around with the site you're building, you'll learn a lot from the results.

HTTP status codes are the first thing a search engine reads. They're the server's way of talking to the client, such as your browser. The codes are split into five ranges: 1xx, 2xx, 3xx, 4xx, and 5xx. A 5xx code is a server problem, for example, and a 4xx code is a client-side problem.

404 is the most common error. It means a page on the site wasn't found. You see 404s all the time, and the fix is typically just to maintain your site and your links.

The codes you'll see in this tutorial are:

• 200 OK: here's the page.
• 301 Moved Permanently: the page lives at another address.
• 404 Not Found: there's no page here.

Google doesn't index URLs that return a 4xx code, according to its documentation on HTTP status codes.

To see the status code of the practice site's home page, use -I, which shows only the headers, and -s, which hides curl's progress meter:

curl -sI http://localhost:8080/

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Date: Sun, 25 Oct 2026 17:42:53 GMT
Connection: keep-alive
Keep-Alive: timeout=5

Now ask for an address that isn't in routes, to see what a correct 404 looks like:

curl -sI http://localhost:8080/products/does-not-exist

HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
Date: Sun, 25 Oct 2026 17:42:53 GMT
Connection: keep-alive
Keep-Alive: timeout=5

In the browser, open the developer tools (F12, or Cmd+Option+I on a Mac), go to the Network tab, and reload. The Status column shows the code.

What Is a Soft 404?

Check a product the store no longer sells:

curl -sI http://localhost:8080/products/red-runner

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Date: Sun, 25 Oct 2026 17:42:53 GMT
Connection: keep-alive
Keep-Alive: timeout=5

In the browser, the same page says "Sorry, that product could not be found."

A soft 404 is basically a "page not found", but the server still answers 200. It confuses Google, because the address is still there, but what's on it isn't current anymore.

To fix it, make missing pages return a real 404, which is what Google recommends. In the practice site, delete the '/products/red-runner' entry from routes. The server then answers 404.

Broken links lead to the same dead end. In the data, 18.9% of the 53 crawled sites had at least one link to a page that returned 404.

So don't leave links that lead to something that doesn't exist. Update them to lead to something similar, or to something that does exist.

If the page moved, add a 301 redirect from the old address to the new one. A 404 is the right answer only for a page that's really gone.

How to Find and Fix Redirect Chains

A redirect is basically when you want to send one URL (perhaps one that no longer exists) to another URL (that does exist). You might set up a redirect if, for example, you change your domain from example-x.com to example-y.com. You'll want everyone who types example-x.com to be redirected to example-y.com automatically.

Redirects are fine, and they can be quite helpful when used properly. A 301 means the page moved for good. A 302 means the move is temporary. Google's documentation on redirects explains how it treats each one, and its crawlers follow up to 10 redirect hops.

But a redirect chain happens when an old address, such as a domain you used in the past, redirects to a new one, and then that one redirects again, and again...you get the picture. A few redirects aren't a big deal, but five, six, or seven can be a real problem.

The first command below shows every step of the chain. The second gives you a one-line summary.

Add -L so curl follows the redirects:

curl -sIL http://localhost:8080/old-sale

HTTP/1.1 301 Moved Permanently
Location: /sale-2025
Date: Sun, 25 Oct 2026 17:42:53 GMT
Connection: keep-alive
Keep-Alive: timeout=5

HTTP/1.1 301 Moved Permanently
Location: /sale
Date: Sun, 25 Oct 2026 17:42:53 GMT
Connection: keep-alive
Keep-Alive: timeout=5

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Date: Sun, 25 Oct 2026 17:42:53 GMT
Connection: keep-alive
Keep-Alive: timeout=5

/old-sale goes to /sale-2025, which goes to /sale. For a one-line summary:

curl -sL -o /dev/null -w "%{num_redirects} redirects, ended at %{url_effective}\n" http://localhost:8080/old-sale

2 redirects, ended at http://localhost:8080/sale

-o /dev/null tells curl to write the page's HTML nowhere, so it doesn't fill your terminal and only the summary line is printed. -w sets what that summary line says.

To fix it, point the old/original address straight at the final page:

'/old-sale': { redirect: '/sale' },

Restart the server and run the summary again. It now says 1 redirects, ended at http://localhost:8080/sale.

How to Make Sure robots.txt Isn't Blocking Important Pages

robots.txt is the site's way of telling search engines like Google (and their crawlers) what they're allowed to explore and where they have access.

Look at the practice site's file:

curl -s http://localhost:8080/robots.txt

User-agent: *
Disallow: /blog

Disallow: /blog is dangerous because it stops crawlers from reading every path that starts with /blog. And usually, your articles are what promote your site the most.

Google's robots.txt documentation gives the same kind of example: Disallow: /fish also blocks /fish.html and /fishheads.

To fix it, make the rule match only what you meant to block, for example a folder of drafts:

User-agent: *
Disallow: /blog-drafts/

In the practice site, change the html line of the '/robots.txt' entry:

html: 'User-agent: *\nDisallow: /blog-drafts/\n',

robots.txt controls crawling, not indexing. Google says it's not a mechanism for keeping a page out of Google. For that, you need noindex.

A URL blocked in robots.txt can even appear in search results, usually without a description, if other pages link to it. Google just never reads what's on the page.

How to Find an Accidental noindex

noindex tells Google not to index a particular page. It's harmful when it ends up on pages you do want indexed and ranked, like a product page or your home page.

But it can be useful on pages you don't need to rank for, or that don't add much to the site, such as log in, sign in, and sign up pages.

noindex works only when the crawler can reach the page and read the rule. If robots.txt blocks the same URL, Google never sees the noindex, and the page can still show up in search results. So for a page you want out of Google, use noindex and leave the page crawlable.

In the data, 11 of 457 audited pages (2.4%) had a noindex robots meta tag. There are two ways to set it, and you need to check both.

How to Check the Robots Meta Tag

The first way is a tag in the page's <head>:

<meta name="robots" content="noindex">

Search the page for the word:

curl -s http://localhost:8080/about | grep -i noindex

On the About page, this prints nothing. You can also right-click the page, choose View Page Source, and search for noindex.

Fixing a noindex is really easy. You basically remove it, and then search engines can index the page.

Look for it in the page's code or template, and in your CMS or SEO plugin settings. In WordPress, the setting Discourage search engines from indexing this site adds it to every page.

How to Check the X-Robots-Tag Header

The second way is an HTTP header. Check the About page's headers:

curl -sI http://localhost:8080/about

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
X-Robots-Tag: noindex
Date: Sun, 25 Oct 2026 17:42:59 GMT
Connection: keep-alive
Keep-Alive: timeout=5

The header doesn't appear in View Page Source, only in the response headers. In the data, 5 of the 12 blocked pages had no noindex in their HTML: 2 had this header, and 3 were blocked from crawling by robots.txt.

To fix it in the practice site, delete the headers line from the '/about' entry. On a real site, check the server configuration, the hosting provider's header settings, and any SEO plugin.

How to Use Canonical Tags Correctly

If you have several pages that talk about more or less the same thing, but without enough meat to be different, you want to designate one main page. The canonical tag tells search engines which page that is.

The same page can also live at several addresses:

https://example.com/blog/choosing-trail-shoes
https://example.com/blog/choosing-trail-shoes?utm_source=newsletter
https://www.example.com/blog/choosing-trail-shoes

These three addresses show the same article. The first one is the main one: the address you want Google to show in search results. So all three carry the same canonical tag, pointing to that main page:

<link rel="canonical" href="https://example.com/blog/choosing-trail-shoes">

When Google sees this tag on the ?utm_source=newsletter version, it knows that page is a copy of the first address. The main address carries the same tag, pointing to itself. That's called a self-referencing canonical, and it says: I'm the main version.

Google treats it as a strong signal, not a command. If you use canonical tags, a self-referencing one on each main page is a good practice, and Google recommends it.

But you don't have to use canonical tags at all. Google says specifying a canonical isn't required: without one, it picks the version it thinks is best to show users. A canonical tag is a good choice when the same or very similar content is reachable at more than one URL, like the three addresses above.

That's why a missing canonical tag isn't a defect by itself. In the data, 27.1% of 457 audited pages had no canonical tag. What matters is whether any of them have duplicates, like a version with tracking parameters, that need one.

Check the practice site's trail shoe article:

curl -s http://localhost:8080/blog/choosing-trail-shoes | grep -i canonical

<link rel="canonical" href="http://localhost:8080/">

The article says its main version is the home page, so Google may show the home page instead of it, or ignore the tag.

The article isn't a copy of anything, so it's its own main version. To fix it, point the article's canonical tag to the article itself:

canonical: '/blog/choosing-trail-shoes',

How to Fix Missing and Duplicate Titles and Meta Descriptions

A good title or meta description is the right length, isn't overloaded, and says briefly what the page is about. It's sort of the essence of the page, like its introduction.

Look at the Blue Runner product page:

curl -s http://localhost:8080/products/blue-runner | grep -i -E "<title>|name=\"description\""

<title>Acme Shoes</title>

The title says nothing about the page, and there's no description line at all. In PowerShell, use | Select-String '<title>|name="description"' for this one.

Google's guides to titles and snippets ask for a unique, descriptive title and description on every page.

To fix it in the practice site, replace the title line of the '/products/blue-runner' entry with:

title: 'Blue Runner Road Running Shoe | Acme Shoes',
description: 'A lightweight road running shoe with a cushioned sole and free returns.',

How to Make Your Links Crawlable

Look at the practice site's home page:

curl -s http://localhost:8080/

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Acme Shoes: Running Shoes for Every Runner</title>
<meta name="description" content="Lightweight running shoes for road and trail, with free returns.">
<link rel="canonical" href="http://localhost:8080/">
</head>
<body>
<h1>Acme Shoes</h1>
<a href="/products/blue-runner">Blue Runner</a>
<span onclick="location.href='/sale'">Summer sale</span>
</body>
</html>

Everything else on this page is fine: the title, the description, the canonical tag and the Blue Runner link, which is a real <a> element with an href. The only problem is the "Summer sale" <span>.

A <span> is basically HTML that isn't semantic, meaning it has no meaning. A real link does have meaning: search engines can understand it's a link, and screen readers can understand it's a link.

Which links need to be crawlable? Basically, everything you want search engines to see. I mean the products you sell, your articles, your courses, and other things like that.

Google's link guidelines say it can only reliably crawl an <a> element with an href.

To fix it in the practice site, replace the <span> line with:

'<a href="/sale">Summer sale</a>',

How to Check Whether Your Content Needs JavaScript to Appear

With client-side rendering, the JavaScript has to load first, and only then can the other content load.

JavaScript usually builds things like product lists, prices, reviews and menus. Without it, a client-side page often shows only a loading message or an empty box.

Google does render JavaScript, but in a later phase. The page waits in a rendering queue, which can take a few seconds or longer, and a script that fails or is blocked can leave the rendered page without its content.

That's why server-side rendering is still a good idea, and it's what I prefer for the content that matters. Google's JavaScript guide says the same: server-side rendering makes the site faster for users and crawlers, and not all bots can run JavaScript.

In the data, 17.7% of 277 audited pages were built mostly with JavaScript. That doesn't mean Google couldn't index them, only that their main content depended on JavaScript running correctly.

With server-side rendering, the HTML content comes straight to the browser, and only after that does the JavaScript render.

Google can index pages built either way. Its crawler runs JavaScript with an up-to-date version of Chrome, so server-side rendering isn't a requirement for getting into Google's index.

The next test checks whether the important content is visible without JavaScript. It doesn't show what Google sees, because Google runs the JavaScript, but it shows what every crawler gets before any JavaScript runs.

Open http://localhost:8080/catalog in your browser. You'll see three products. Now download it with curl, which doesn't run JavaScript:

curl -s http://localhost:8080/catalog | grep -i "trail grip"

This prints nothing, because the product names aren't in the HTML the server sends. Inside <body>, the server only sends:

<div id="app">Loading...</div>
<script>fetch('/api/products').then((r) => r.json()).then((products) => {document.getElementById('app').innerHTML = products.map((p) => '<h2>' + p + '</h2>').join('');});</script>

Without curl, use View Page Source in your browser. On this page, you'll see "Loading..." and the script, but none of the product names, because the browser adds them only after the JavaScript runs.

On your own site, search the source for an important sentence from the page.

To see the page the way Google renders it, use Google's own tools on a live page. On your own site, the URL Inspection tool in Search Console can run a live test (Test live URL, then View tested page) and show the HTML Google rendered and a screenshot.

For any public page, the Rich Results Test shows the rendered HTML too. Google recommends both for finding JavaScript problems. Neither can reach localhost, so try them on your real site.

If you want the product names in the HTML from the start, render them on the server. In the practice site, add the product list above routes:

const products = ['Blue Runner', 'Trail Grip 2', 'City Glide'];

Replace the catalog's body and script lines with:

body: '<div id="app">' + products.map((p) => '<h2>' + p + '</h2>').join('') + '</div>',

And in the '/api/products' entry:

html: JSON.stringify(products),

Restart the server and run the curl command again:

<div id="app"><h2>Blue Runner</h2><h2>Trail Grip 2</h2><h2>City Glide</h2></div>

This works because the server now writes the product names into the HTML before it sends the page. Any crawler sees them, even one that can't run JavaScript, and you can still use JavaScript for the interactive parts.

Can You Check a Page in Five Minutes?

Honestly, it's very hard. There can be a lot of problems, and five minutes isn't enough.

To really know what the problems are, you need to run a full check, for example in Google PageSpeed Insights. If the site is yours, also use the URL Inspection tool in Google Search Console.

The commands from this tutorial are a good start:

1. curl -sI for the status code and an X-Robots-Tag header.
2. curl -sIL on an old address to count redirects.
3. /robots.txt, line by line.
4. View Page Source for noindex, canonical, <title>, description and your important content.

Conclusion

In this tutorial, you fixed eight problems on a practice site: a soft 404, a redirect chain, a robots.txt rule, a hidden noindex header, a wrong canonical tag, a vague title and a missing description, a link crawlers couldn't follow, and content that needed JavaScript.

The most important thing to remember is that you'll need to check your site all the time. Run scans, do maintenance, and make sure nothing breaks, especially when you make improvements or changes to the site.

If you want to go further, my tutorial on adding structured data (JSON-LD) to a Next.js site is a good next step.

If you'd like to check a live page for many of these issues in one go, my free tool Greadme Page Audit tests any URL with no sign-up needed.

But what about when you have the same project file setup that gets repeated over and over? How do you solve that?

Meet bash scripting. Bash scripts are written to execute certain sequences of commands on your machine automatically without you having to do anything. This is known as workflow automation, and that's what I'll be teaching you how to do in this article.

Table Of Contents

• Prerequisites
• What Motivated This Project?
• Introduction
• Conditions in bash
• Interactive Shell
• How to Create and Write to a File
• Bash Arguments and Flags
• How to Make Your Scripts Executable and Available on Your PC's Path
• Conclusion

Prerequisites

To follow along with this article, you should have:

• Git-bash installed on your machine
• Some experience using a terminal or command prompt to run and execute commands (helpful but not required)
• Understanding of basic programming concepts (like conditions and loops)
• Docker installed on your machine
• Basic understanding of Docker concepts (like images and containers)
• Experience using Postgres (optional but recommended)

What Motivated This Project?

I was recently setting up a Docker image for Postgres on a few projects I was working on, and I noticed that I was following the same pattern in creating the images. The only difference was that they had different database credentials and database names.

I also realized that a large portion of today's rapidly developed apps tend to use Supabase as their backend, which can come with resource limits such as database storage, bandwidth, concurrent connections, and API request quotas (depending on the service tier and size of the project). And these issues can be solved by setting up your database.

So I thought, why not make a CLI tool that could automate creating Docker images for Postgres? That's when I learned about writing executable shell commands using bash to create workflow automations.

You can find the full working example used in this guide in this git-repo.

Introduction

Bash is a shell and scripting language used to write and execute commands or scripts that perform operations on a computer, such as creating directories and files, manipulating files, automating tasks, and managing system processes.

In this guide, you'll learn to automate the process of creating a Docker image for a Postgres database so that you don't have to create the image from scratch for each new project.

Bash Scripting File Setup

To get started, open you preferred text-editor and create a directory or folder there. Then within that directory, create a file with the extension .sh.

At the beginning of a file, type:

#!/bin/bash

#!/bin/bash (known as a "shebang") tells the operating system to run the script using the Bash shell, so the commands inside the file are executed as Bash/terminal commands.

Conditions in bash

After you've finished creating a script file and adding shebang, let's start by exploring how if statements are used in bash.

The syntax of if looks like this:

if [[ condition ]];
    then
        command to execute
fi

The if in bash is no different from what you're used to in other programming languages:

• You use double square braces ([]) to add a condition you're checking against and a semicolon (;).
• You use then after the if declaration to specify what should be executed if the condition is true.
• You use the fi to close the condition statement.

When you're writing the condition inside the square braces, make sure you leave a space before the condition and another one after it (as you can see in the code above). If you omit these spaces, you'll get errors.

Working Example:

Since we are automating Postgres database Docker image creation, first check if the file exists and has content. If it does have content, end the script. If not, we'll proceed with the next script.

#!/bin/bash

if [[ -s docker-compose.yml ]];
    then
        echo "The file already exists"
        exit 0
fi

echo "Next command"

In the if condition, we use the flag -s to check if the file exists and has contents. File flags check file availability and permissions, and include but aren't limited to:

• -f: used to check if the file exists
• -s: used to check if the file exists and has contents
• -d: used to check if a directory exists
• -r: used to check if a file is readable
• -w: used to check if a file is writable
• -x: used to check if a file is executable

In the script, we're using -s to check if a file named docker-compose.yml exists in the directory where we're executing the command. If it's false, we use the echo keyword to print the text "Next command". If it's true, we print the text "The file already exists".

exit acts as a return keyword for bash scripting, 0 is used for success, and 1 is used for failure.

Let's test all this by creating a Docker Compose file and adding some content in the same directory where we're writing the bash script. In your terminal type bash name-of-file.sh, and you should see "The file already exists":

But if we delete the content in the file and run the command again, we should see the output saying "Next command":

Interactive Shell

To make an automation dynamic and flexible you will need to receive inputs, take an example of a database name you won't always have the same database name, the name will change based on the project,

you do need to setup away to use a given name of the database when creating a new docker image for that you read inputs using the read keyword.

There are different types of inputs based on the operation. And there are flags that are used to specify which type of input you're expecting, such as:

• -p: for prompting the user to write a text
• -s: used on passwords when you want the user input to stay hidden when writing it in the terminal
• -a: used when you're expecting the user to pass in multiple inputs or if you're expecting an array from user.

Here's the syntax for reading user input:

read -p 'input_label: ' variable_name

Working Example:

Now let's create scripts to receive user input about the Postgres database image you're going to create.

#!/bin/bash

# database credentials
read -p 'DataBase-name(*): ' db
read -p 'DataBase-user(*): ' user
read -sp 'DataBase-password(*): ' pwd
echo
echo "your database is -> $db with a username of $user and a password of $pwd"

The script uses -p on the read keyword that prompts a string of text and -sp that prompts the user to enter a string of text that's hidden (because the -s hides what's being typed).

If you don't use the -p option together with -s, you won't be able to display a prompt asking the user to enter a password. With -s alone, the input is hidden, but no prompt is shown unless you print one using echo or printf.

To print or use the input the user has added, use the dollar sign ($) followed with a variable name for the input you're expecting from the user. In the example above, we named the variable for getting the database name db, so we'll use $db when we want to access the name of the database the user has input.

Now if you run the script in the terminal, you should see a sequence of terminal prompts waiting for inputs. Once they're filled, you'll see all the input's values in the terminal:

How to Validate and Sanitize Input

You'll also need to validate input before executing anything. This is important because sometimes crucial field might be missing or mistyped. For example, you might forget to input the database name for the image you're trying to create.

When validating input, you'll use one of these flags (among others):

• -z: checks if a variable value is empty
• -n: checks if a variable value is not empty
• -lt: checks if a number is less than a given number
• -gt: checks if a number is greater than a given number
• -eq: checks for equality of two values

You can use the -z flag on every input that you need to make sure isn't empty before moving on to the next step:

#!/bin/bash

# database credentials
read -p 'DataBase-name(*): ' db
if [[ -z $db ]]
    then
        echo "The database field cannot be empty!"
        exit 1
fi

read -p 'DataBase-user(*): ' user
if [[ -z $user ]]
    then
        echo "The user field cannot be empty!"
        exit 1
fi

read -sp 'DataBase-password(*): ' pwd
if [[ -z $pwd ]]
    then
        echo "The password field cannot be empty!"
        exit 1
fi

This script helps you make sure that all critical information about the database is present before proceeding to another input.

Default Values

You may want some fields to use default value (for example, the container name of the image, port, or volume of the container). For such scenarios you can use := to assign a variable default value:

#!/bin/bash

# container information
read -p 'Container-name: ' container_name
read -p 'Container-port(if omitted, the container will use default postgresql default port of 5432): ' port
read -p 'Volume-name: ' vol_name

echo "container-name-> ${container_name:=cont_one}, port->${port:=5432}, volume_name->${vol_name:=backend_data}"

When you run the script and skip all three of those inputs, bash will use the default value(s) you've used as fallbacks.

But if you pass value for those inputs, bash uses the provided values. For example, supply all three inputs and see the output you get:

How to Create and Write to a File

Now that you know how to create a Docker image for a Postgres database, you need to create a docker-compose.yml file that will be executed when starting and stopping your containers.

In Bash, there are multiple ways of creating a file:

• First, you can use > filename. This creates a file if it doesn't exist. If it exists, its contents are overwritten (replaced).
• There's also >> filename: This appends contents to a file or creates a file if one doesn't exist.
• Finally, there's touch filename: This creates a file if it doesn't exist. If the file already exists, its contents are preserved and only the file's timestamps are updated.

How to Use > to Create and Write to a File

When you want to create a file and write content to it at the same time, you'll want to use echo in front of > and then add the filename, like this:

#!/bin/bash

echo Hello> test.txt

This will create a test.txt file with "hello" as content inside.

How to Use >> to Append Contents to an Existing File

To append contents to an existing file, add the contents before the >> and then follow with the filename you want to append content onto. Let's add Africa after Hello in the test.txt file we created in the previous script.

#!/bin/bash

echo Africa!>> test.txt

Now test.txt will have Hello and Africa! on the new line.

Using those symbols, let's create a docker-compose.yml file that will hold contents about our Postgres database setup.

#!/bin/bash

> docker-compose.yml

And just like that you have your docker-compose file created in your directory.

How to Write Multiple Different Contents to a File

You can also use the cat keyword to write to a file. Typically, cat is used for reading the contents of a file. But when you combine it with <<EOF and the sign for appending contents to a file >> (that we just discussed), you can add multiple contents to a file in the format you want. The syntax looks like this:

# writing docker compose contents

cat <<EOF>> docker-compose.yml

  # file contents
EOF

The <<EOF tells bash to write contents to a file until it finds the EOF keyword (end of file). Then you use >> filename to append the contents to the file. With a Docker compose setup it would look like this:

#!/bin/bash

#file creation and writing
 >  docker-compose.yml

cat<<EOF>>docker-compose.yml
 services:
    postgres:
        image: postgres:18-alpine
        container_name: ${container_name:= $db}

        environment:
            POSTGRES_USER: $user
            POSTGRES_PASSWORD: $pwd
            POSTGRES_database: $db

        ports:
            - ${port:=5432}:5432
        volumes:
            - ${vol_name:=database-data}:/var/postgresql

 volumes:
    ${vol_name:=database-data}:

EOF

Bash Arguments and Flags

With Bash arguments, you can pass values in the same line while executing a script. To use arguments, add the values while executing the script on the same line, like this:

bash script val1 val2 

To read arguments value(s), use the dollar sign ($) followed by the position in which you inputted your values (positions start at 1, not 0).

In the example, if you want to echo the content of the second argument value, you can use echo $2.

To understand this better, let's enhance data input experience by passing the database credentials on the fly using arguments:

#!/bin/bash

# database credentials

if [[ -z $1 ]]; then
    read -p 'DataBase-name(*): ' db
 else
    db="$1"
fi

# database checking and validating

if [[ -z $2 ]]; then
    read -p 'DataBase-user(*): ' user
 else
    user="$2"
fi

# user checking and validating

if [[ -z $1 ]]; then
    read -sp 'DataBase-password(*): ' pwd
 else
    pwd=$3
fi

# password vaidation and checking

The snippet first checks if there's an argument. If there aren't any, you use the prompt to input the value. If there are arguments, you assign the argument value to a variable that represents the given database credentials (database name, password, and so on...). Now you can run the script with arguments:

bash image.sh customers ABC-Company secret123!

The image that will be created from the above script will have a database of customers, user ABC-Company, and a password of secret123!.

Bash Flags/Options

The script has a section that asks for information about the image that you're creating, but the info can be optional. With bash option/flags, you can skip the step that prompts for container information input using the -D option. This lets you explicitly keep the default container info before the script runs.

Here's an example:

#!/bin/bash

while getopts "ny" options; do
	case "$options" in
		n) echo "You choose no";;
		y) echo "You choose yes";;
		*) echo "No such option/flag"; exit 1;;
    esac
done

shift $((OPTIND - 1))

In the above script:

1. The while loop keeps running as long as getopts isn't empty
2. getopts gets the passed option in the script
3. "ny" are the options we're expecting from user when running the script
4. options is a variable that will keep track of the input option between "n" and "y"
5. do starts the loop
6. case checks if the selected option is in the defined option using the in keyword
7. We then define what happens when we call the script with the option -n or -y and use a double semi-colon (;;) to close the option definition
8. The * is used in case the input options aren't defined.
9. esac then closes the case
10. done ends the loop so the loop doesn't continue running forever
11. shift $((OPTIND - 1)) helps avoid a conflict that may occur when the script also expects arguments by shifting the remaining arguments left over the flags, effectively discarding the flags from the parameter list.

You can then apply the syntax in the script to skip the step that asks for container info when -D is passed as an option during the script execution.

#!/bin/bash

ask_container_info=true

while getopts "D" options; do
	case "$options" in
		D) ask_container_info=false;;
		*) echo "No such option/flag"; exit 1;;
    esac
done

shift $((OPTIND - 1))

if [[ $ask_container_info == true ]]; then
	#Prompt the user to input custom container information
    read -p 'Container-name: ' container_name
    read -p 'Container-port(if omitted, the container will use default postgresql default port of 5432): ' port
    read -p 'Volume-name: ' vol_name
fi

There is one option here, which is why the option section only has D. ask_container_info starts as true, meaning unless the option is passed, the script will prompt the user to enter the container information. We then change the value of ask_container_info to false when the -D is passed with the script's execution.

How to Make Your Scripts Executable and Available on Your PC's Path

The next step is to make the script available and executable in every terminal you use on your machine. At the moment, the script just works in the current directory you're using to create and write your scripts.

We'll start by making the script file executable and remove the file extension from the file, so we don't need to always call our script with the .sh extension.

How to Make a File Executable

To make a file executable, use the Linux chmod command. It stands for change mode. Mode includes file permissions like write, read, and execute.

chmod +x image

Here, x makes the file executable, and then you've listed the file name you want to make executable (image).

How to Add Your Directory to the system/machine Path

To make this available in every terminal you open, regardless of the directory, you'll need to register your scripts in the system paths where all global scripts and commands are stored.

To do that, copy the full path of your directory and then in your terminal type the following:

export PATH="$PATH:<YOUR_DIRECTORY_LOCATION>"

Replace <YOUR_DIRECTORY_LOCATION> with your directory. This command will add the script directory into the current working terminal. But if you try to switch to another terminal and run your script, it'll fail.

Now let's configure the directory globally so every terminal will be able to execute the script:

nano ~/.bash_profile

After this you should see something that looks like this:

You can see in the image above that I already have my path declared in the file (see the selected text).

If it's not in you're file, you can copy-paste export PATH="$PATH:<YOUR_DIRECTORY_LOCATION>" inside the file. When you're done, press Ctrl+O and then enter to save. Then press Ctrl+x to exit the nano editor.

Then re-load the machine path again to include your scripts there:

source ~/.bash_profile

After this, you'll be able to run your script in any terminal on your machine using the script file name only (I named my file image):

Conclusion

In this guide, you learned how to create your own scripts to automate your workflows. I hope it helps you reduce the amount of energy and time you waste on repetitive tasks that can be automated using script commands.

You can find the full working CLI tool that we used as an example in this guide on this git-repo. There you'll find the installation guide and usage tips. If you find it helpful, please consider starring the repo and sharing it with your collogues who might benefit from it.

Thanks!

That sounds simple, until the first question appears. What happens when the mobile version doesn't exist? What if the animation that looks perfect in Figma performs badly on a real phone? Who decides what happens when the client requests Google login three days before launch? And when a technical problem appears, does the developer speak directly to the client or go through the studio?

These questions aren't unimportant side issues. They're part of building the product. Research on designer-developer collaboration supports this. A 2025 systematic review covering 45 papers found recurring challenges around how designers and developers communicate, coordinate work, and understand each other's responsibilities.

If you're a freelance developer, your job isn't just about writing code. You also need to make sure that design, technology, scope, communication and client expectations are moving in the same direction.

In this guide, we'll look at how you can work effectively with design studios, from understanding project requirements and handling design handoffs to managing client expectations and technical challenges. We'll also cover some practical ways to make sure projects move smoothly from the initial design to the final launch.

What We'll Cover Here:

• First, Understand What the Design Studio Is Actually Hiring You For
  • Are You the Developer, the Technical Partner, or Just the Implementer?
• Don't Start Coding Until You Understand the Project
  • Ask Questions Before Opening Your Code Editor
• Treat the Figma File as a Conversation, Not a Contract
• Define Who Owns Which Decisions
  • The One Question Every Freelancer Should Ask
• Set Up a Workflow That Doesn't Depend on Constant Messages
  • Give Every Stage a Clear "Done"
  • Create a Single Source of Truth
• Handle Design Handoffs Like an Engineer
  • Look for the Screens That Don't Exist
• Scope Creep Is Easier to Prevent Than to Fight
  • Use a Simple Change Rule
• Don't Hide Technical Problems Until the Deadline
• Review the Build Together, Not Just at the End
• Learn to Push Back Without Becoming Difficult to Work With
• Keep the Relationship Healthy After Launch
• A Simple Collaboration Checklist for Freelance Developers
• Final Thoughts

First, Understand What the Design Studio Is Actually Hiring You For

This is an important section because freelancers often misunderstand their exact role in a project. A design studio or a branding agency might hire you for frontend development, full-stack development, prototyping, or straight design to code implementation. They might also bring you in for CMS integration, API integration, performance optimization, or ongoing maintenance after launch.

But the role can vary dramatically depending on the studio's internal capabilities and the client's specific needs.

Are You the Developer, the Technical Partner, or Just the Implementer?

You must explain the difference and define your boundaries.

As an implementer, you simply receive finished designs and build them exactly as specified without questioning the logic. As a developer, you build the product but also actively raise technical concerns when you spot potential issues. As a technical partner, you get involved much earlier in the process and help determine what can actually be built within the budget and timeline.

Clarifying this exact dynamic before starting the work prevents many structural problems later.

Don't Start Coding Until You Understand the Project

A Figma file can tell you exactly what something looks like on a screen. It doesn't necessarily tell you how it should behave in the real world.

It won't show you what happens when data is missing from the server. It doesn't explain what happens on slow cellular networks or what happens on obscure mobile devices. It also leaves out what happens when user-generated text becomes too long or when users make critical mistakes. And it doesn't talk about which interactions are absolutely essential, and which parts are merely visual prototypes rather than final requirements.

Ask Questions Before Opening Your Code Editor

You need a practical checklist to run through before touching your keyboard.

Regarding the product, ask: What problem is the product solving? Who is using it? What's the single most important user action?

Regarding the design, ask: Are these designs entirely final? Are there dedicated mobile and tablet versions available? Are all the shown animations part of the strict requirement?

Regarding the technical side, ask: Is there an existing backend in place? What specific technology stack is expected? Are all necessary APIs already available? Who handles the hosting environment?

Regarding the client, ask: Who communicates directly with the client? Who ultimately approves changes? Who gives you final feedback?

Google's engineering guidance similarly stresses clear objectives and requirements because poor communication and vague expectations directly contribute to project failures

Treat the Figma File as a Conversation, Not a Contract

Explain to your partners that developers shouldn't treat design files as sacred objects that must be reproduced pixel for pixel regardless of technical reality. Instead, treat them as a starting point for an ongoing discussion.

For example, a designer creates a complex scrolling animation that looks genuinely great in the initial prototype. But during implementation you discover that it causes massive performance issues on lower-end mobile devices.

The wrong approach is saying something like: "The design says so, so I'll build it anyway." Another wrong approach is shutting it down by saying: "That simply won't work."

A much better approach is saying something along the lines of: "This interaction is entirely possible, but it may affect performance on mobile devices. Could we simplify the animation specifically for smaller screens?" That's constructive technical feedback without turning the conversation into a hostile design vs development argument.

This dynamic is supported by a comprehensive 2025 systematic review of designer-developer collaboration, which revealed that separate decision-making procedures and a lack of mutual understanding are persistent challenges in the field.

Define Who Owns Which Decisions

This is especially important when you're a freelancer working directly between a studio and its end client. You need to create a simple, clear responsibility framework. Usually, visual design is led solely by the design studio. UX decisions are generally handled by the design studio alongside the client.

Technical architecture, database structure and API implementation are led exclusively by the developer. Product priorities are decided by the client and the studio. Technical feasibility falls entirely to the developer. Final design approval rests with the client and the studio.

Emphasize that this framework isn't totally rigid. The important thing is universally knowing who has the final say in any given category.

The One Question Every Freelancer Should Ask

"If we disagree about a design or technical decision, who makes the final call?" That one specific question can save countless hours of confusion and resentment later in the process.

Set Up a Workflow That Doesn't Depend on Constant Messages

A simple, predictable workflow eliminates chaos, and you can systematically organize a standard workflow.

First is the brief, followed by the design review. Next comes technical planning and then the actual development phase. After that is the internal review, followed by client feedback. This leads to the revision stage, moving into QA and finally culminating in the launch.

Explaining each phase briefly ensures everyone knows where the project stands at any given moment.

Give Every Stage a Clear "Done"

For example, a design review is officially complete when desktop and mobile designs exist, missing interactive states are identified, visual assets are available, and complex interactions are understood.

The development phase is complete when the feature actually works, responsive behavior is thoroughly checked, known bugs are actively documented, and the studio has a functional review build.

This clarity inherently prevents the classic miscommunication of: "I thought you were still working on it."

Create a Single Source of Truth

The core problem with freelance collaborations is that crucial information can become quickly scattered across Slack, email, WhatsApp, Figma comments, GitHub, Notion, Google Docs, random video calls, and text messages. Then six days later someone inevitably asks: "Why did we decide to remove that specific feature?" Nobody likely remembers the exact reason.

Recommend having one centralized place for core requirements, open questions, finalized decisions, technical constraints, scope changes, project deadlines and feedback.

An observational study of software developers' work practices found that developers spend about 45% of their time collaborating with colleagues and seeking information, making information visibility an essential part of software work. Google's SRE guidance also recommends writing decisions and project information down to heavily reduce problems caused by distance and fragmented communication.

Handle Design Handoffs Like an Engineer

Instead of simply receiving a Figma link and guessing what to do, create a proper, methodical handoff checklist. Check typography, colors, spacing and breakpoints. Verify all assets, icons, component states and hover states. Confirm loading states, error states and empty states. Double-check mobile behavior, accessibility requirements and complex animations.

Look for the Screens That Don't Exist

Designers naturally often show the happy path where everything works perfectly. But developers absolutely have to build the empty dashboards and the failed API requests. You must account for loading screens, invalid forms, expired sessions, and missing images. You have to handle long usernames breaking the layout and slow connections timing out. This is precisely where developers add tangible value beyond simply translating a Figma canvas into HTML, CSS, and JavaScript.

Scope Creep Is Easier to Prevent Than to Fight

The studio might initially say: "The client also wants a small dashboard." Then a few days later: "Can we subtly add notifications?" Then the next week: "Could we also seamlessly add Google login?"

None of these requests sound huge individually. But together, they can easily turn a straightforward two week project into an exhausting month-long project.

Use a Simple Change Rule

Whenever something new appears in the pipeline, ask a series of questions. Is this part of the original scope? How much active work will it require? Does it negatively affect the deadline? Does it conflict with another feature? Who formally approves the change?

Don't make the section sound like aggressive negotiation advice. Frame it entirely as protecting the overall project from unclear expectations and budget overruns.

Don't Hide Technical Problems Until the Deadline

Explain the freelancer's ethical and professional responsibility here. If you discover the API isn't actually ready, state it immediately. If the animation isn't practical, the design doesn't account for accessibility, the database structure needs completely changing, or a feature will take three days instead of three hours, say it early. Not two agonizing days before the scheduled launch. You can introduce a very simple principle: bad news gets significantly more expensive when you delay it.

Review the Build Together, Not Just at the End

Explain clearly why continuous reviews are infinitely better than one giant final review at the very end of the timeline. A suggested review rhythm keeps everyone in the loop.

After a major component is finished, conduct a studio review. After the main page is completed, run a design review. After responsive implementation is coded, initiate a mobile review. Before the actual launch, perform a full QA.

This creates significantly smaller, highly manageable feedback loops. Instead of hearing: "The entire website is completely wrong," you get: "The spacing on this specific card is 4px too large." This is much easier and cheaper to fix.

Learn to Push Back Without Becoming Difficult to Work With

Developers sometimes respond to highly unrealistic requirements with a flat: "That's impossible."

Instead, you should frame it differently: "We can certainly build this, but there are two distinct trade-offs." Then explain the available paths clearly. Option A is visually closer to the design, but requires much more development time. Option B is a much simpler implementation, delivering significantly better performance. Option C is to keep the current approach for desktop interfaces and drastically simplify it on mobile devices.

This directly makes the developer a strategic problem solver rather than someone who simply says yes or no to every request.

Keep the Relationship Healthy After Launch

The professional relationship shouldn't abruptly end the exact second the site goes live on the server. Clarify the boundaries of the bug-fix period and ongoing maintenance. Discuss future features, hosting responsibilities and comprehensive documentation. Manage the handover of access credentials and establish clear code ownership.

Most importantly, don't ever leave ownership ambiguous. The design studio should confidently know what happens if the client comes back three months later aggressively asking for a brand new feature.

A Simple Collaboration Checklist for Freelance Developers

Before the project officially starts, thoroughly define the core business logic, clarify your exact engineering responsibilities, and audit the UI/UX designs for edge cases or missing interactive states.

Once you understand the primary goals, confirm the complete technology stack, from the frontend framework to the database architecture, while setting strict boundaries around API dependencies, version control repositories, and sprint deadlines.

As you move into active development, consistently flag performance bottlenecks or query inefficiencies early, ensuring you document all major architectural shifts within your codebase. Rather than jumping straight into writing, break down the visual files into reusable component logic and shared design tokens before implementation begins. You should also share live staging builds frequently, track scope creep meticulously through an issue tracker, and continuously test how your DOM renders across various viewport breakpoints to catch responsive errors.

Finally, before pushing to the production environment, audit the compiled build against the original designs to ensure high-fidelity accuracy. Rigorously test state management across critical user routing flows, debug any layout shifts on mobile browsers, and verify that your semantic HTML meets baseline WCAG accessibility standards.

To wrap up the collaboration seamlessly, lock down the CI/CD deployment pipeline responsibilities and hand over a comprehensively documented repository that clearly explains the environmental variables, build scripts, and third-party integrations the studio will need moving forward.

Final Thoughts

A Figma file shows how a product should look, while development reveals everything it needs to handle when real people start using it.

That's why working with a design studio involves more than a simple design-to-code handoff. You'll also need to catch technical problems early, keep responsibilities clear, and make decisions before small issues become launch-day problems.

Throughout the project, stay in touch with the design team, share your technical concerns, and discuss changes before they affect the timeline. This will make it easier to handle unexpected problems and deliver a product that works well for the client and the people who will eventually use it.

We just published a comprehensive course on the freeCodeCamp.org YouTube channel that will teach you how vector databases work, starting with the math and ending with a working semantic search project. This course is from codeEdx, whose instructor has worked as a software engineer for 15 years and as a lead AI engineer for the last four. No prior knowledge is required.

In this course, you will learn:

• Vectors & Similarity Math
  Learn what a vector is and how cosine similarity and Euclidean distance measure how close two pieces of data are.
• Tokens & Tokenization
  See why AI models can't read raw text and how a tokenizer splits a word like "indivisible" into more than one token.
• Embeddings & Embedding Models
  Understand how text becomes vectors that capture meaning, including the classic king minus man plus woman equals queen example.
• Generating Embeddings with Gemini
  Follow a live demo using Google's Gemini embedding model, then visualize the results in 3D with principal component analysis (PCA).
• Inside a Vector Database
  Explore the storage, indexing, and query processing layers, and how IVF and HNSW indexes avoid slow brute force search.
• Semantic Search with ChromaDB
  Create a Chroma client and collection, store your embeddings, and run queries that return results based on meaning.

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

When an invoice arrives, an automated rules engine checks it against static thresholds. It checks whether the dollar amount falls within normal limits, whether the vendor is on an approved vendor list, and whether the submitting IP address looks familiar. If the individual attributes look plausible, the payment clears.

The problem with this approach is structural. Sophisticated fraud schemes like money mule rings, circular invoicing loops, and vendor collision rarely produce transactions that alert individual thresholds. A shell company invoicing $4,800 to stay under a $5,000 dual sign-off threshold looks completely fine in isolation. But when 25 seemingly independent vendors all route disbursements to the same bank account, the coordinated pattern starts to become clear.

You won't find the warning in the attributes of an isolated transaction. It lives in the topology of the payment network.

In a relational database, tracing these multi-entity relationships requires recursive cell joins across tables of vendors, invoices, payments, and bank accounts. But as tables grow into millions of rows, deep path traversals quickly degrade query performance. Graph databases solve this by storing relationships as first-class, index-free adjacency pointers, turning multi-hop traversals into constant-time lookups.

In this tutorial, you'll explore the architecture of an end-to-end relational fraud detection pipeline built on Neo4j. You'll see how to model financial entities as a graph, precompute derived edges to optimize query latency, and write parameterized Cypher queries to uncover five core procurement fraud schemes.

The complete reference implementation is available in the fraud-detection-knowledge-graphs repository.

What We'll Cover:

• Why Tabular Rules Miss Relational Fraud
• Prerequisites
• How to Model the Financial Graph and Ingestion Schema
• How to Detect Five Fraud Patterns with Cypher Queries
• How to Run the End-to-End Pipeline and Validate Results
• Production Architecture: How to Scale the Graph Pipeline
• Key Architectural Lessons and Takeaways
• Conclusion

Why Tabular Rules Miss Relational Fraud

In accounts payable pipelines, risk checks typically operate on isolated records:

# Transaction-level view — nothing suspicious
transactions = [
    {"vendor": "Alpha Corp", "amount": 5200.00, "date": "2025-08-01"},
    {"vendor": "Beta LLC", "amount": 4800.00, "date": "2025-08-02"},
    {"vendor": "Gamma Inc", "amount": 5100.00, "date": "2025-08-03"},
]
# All amounts within normal range ($1K–$15K). All vendors valid.
# Dates are sequential. Nothing triggers any rule.

When you map those same records to an interconnected graph, the hidden structure becomes clear right away:

# Graph view — all three vendors pay to the same account
connections = {
    "ACC-MULE-001": ["Alpha Corp", "Beta LLC", "Gamma Inc"],
    "ACC-0042":     ["Delta Corp", "Epsilon LLC"],
    "ACC-0099":     ["Zeta GmbH"],
}
# ACC-MULE-001 receives from 25+ vendors. That's a money mule ring.
# The convergence is the red flag.

The underlying data hasn't changed. But when you evaluate transactions within an entity graph, the coordinated funnel stands out.

In a relational database, connecting these dots requires multiple joins across separate table. In a knowledge graph, the connections are stored directly as edges connecting nodes, which allows you to query them in a single traversal.

A knowledge graph doesn't replace rules engines or ML models. But it does fill the gap they can't reach: relationships.

Prerequisites

To follow along with this tutorial, you'll need:

• Python 3.10 or higher installed on your machine.
• Docker and Docker Compose installed to run a local Neo4j instance.
• Basic familiarity with Python and database concepts.

How to Model the Financial Graph and Ingestion Schema

Before running fraud queries, you need to structure your data into a cohesive property graph. The reference dataset models six entity types commonly found in financial systems:

The base relationships form a bipartite payment network:

(Employee)-[:APPROVED]->(Payment)-[:LINKED_TO]->(Invoice)-[:ISSUED_BY]->(Vendor)
                                   |
                                   v
                            (Payment)-[:PAID_TO]->(BankAccount)

Step 1: How to Generate the Dataset with Known Injected Patterns

Real-world financial datasets are difficult to access because of privacy and regulatory restrictions. Using synthetic data allows you to inject known fraud patterns and systematically verify that your detection queries find them.

The dataset generator creates approximately 500 entities with five known patterns embedded:

• 12 duplicate invoice pairs
• 1 circular invoice ring (3 vendors)
• 1 money mule ring (25 vendors for 1 account)
• 1 vendor collusion cluster (4 vendors)
• 3 payment anomalies

from dataset.generate import FraudDatasetGenerator

gen = FraudDatasetGenerator(
    num_vendors=100,
    num_employees=30,
    num_organizations=5,
    seed=42,
)
output_dir = gen.save("dataset/output")

Setting a fixed seed=42 makes the dataset fully reproducible. Running the generator produces the exact same fraud patterns each time, giving you a reliable benchmark for testing queries:

Vendors: 100
Invoices: 220 (200 base + 20 fraud)
Payments: 331 (300 base + 31 fraud)
Bank Accounts: 51 (50 + 1 mule)
Employees: 30
Organizations: 5
Fraud Patterns: 5 types

The generator also exports a ground-truth manifest ground_truth.json that logs every injected anomaly, and this serves as your automated validation oracle.

Step 2: How to Connect to Neo4j and Create Constraints

You can spin up a local Neo4j 5.20 container with APOC procedures enabled using Docker Compose:

docker compose up -d

Next, initialize the database driver and establish uniqueness constraints:

from graph.connection import FraudGraph

with FraudGraph() as graph:
    graph.create_constraints()

These constraints are critical for query performance. In Neo4j, unique property constraints automatically build underlying B-tree indexes. Without them, every MERGE operation forces an unindexed full scan across all nodes in the database:

class FraudGraph:
    def __init__(self, uri=None, user=None, password=None):
        self.uri = uri or os.environ.get('NEO4J_URI', 'bolt://localhost:7687')
        self.user = user or os.environ.get('NEO4J_USER', 'neo4j')
        self.password = password or os.environ.get('NEO4J_PASSWORD', 'password')
        self.driver = None

    def connect(self):
        self.driver = GraphDatabase.driver(
            self.uri, auth=(self.user, self.password),
            max_connection_pool_size=50,
            connection_acquisition_timeout=30,
        )
        with self.driver.session() as session:
            session.run('RETURN 1')
        return self

    def __enter__(self):
        self.connect()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self.close()

    def create_constraints(self):
        with self.driver.session() as session:
            session.run("CREATE CONSTRAINT vendor_tax_id IF NOT EXISTS FOR (v:Vendor) REQUIRE v.tax_id IS UNIQUE")
            session.run("CREATE CONSTRAINT invoice_id IF NOT EXISTS FOR (i:Invoice) REQUIRE i.invoice_id IS UNIQUE")
            session.run("CREATE CONSTRAINT account_id IF NOT EXISTS FOR (a:BankAccount) REQUIRE a.account_id IS UNIQUE")
            session.run("CREATE CONSTRAINT employee_id IF NOT EXISTS FOR (e:Employee) REQUIRE e.employee_id IS UNIQUE")

Step 3: How to Load Entities into the Graph

The FraudGraphLoader uses Cypher's UNWIND to batch-insert entities in parameterized transactions:

from graph.loader import FraudGraphLoader

with FraudGraph() as graph:
    graph.create_constraints()
    loader = FraudGraphLoader(graph)
    loader.load_all(data)

The loading sequence respects foreign key dependencies: organizations are loaded first, followed by vendors, bank accounts, and employees, with invoices and payments loaded last.

Each load method follows the same pattern:

UNWIND $data AS v
MERGE (vendor:Vendor {tax_id: v.tax_id})
SET vendor.name = v.name,
    vendor.country = v.country,
    vendor.city = v.city
WITH vendor, v
MATCH (org:Organization {org_id: v.organization})
MERGE (vendor)-[:BELONGS_TO]->(org)

MERGE creates or matches a node (using the constraint for O(1) lookup), SET attaches properties, and MERGE on the relationship connects nodes.

Step 4: How to Materialize Derived Relationships for Fast Queries

A central architectural decision in graph databases is deciding whether to compute relationships at query time or materialize them during ingestion.

Discovering whether two vendors share a bank account requires traversing a four-hop path:

(Vendor)<-[:ISSUED_BY]-(Invoice)<-[:LINKED_TO]-(Payment)-[:PAID_TO]->(BankAccount)<-[:PAID_TO]-(Payment)-[:LINKED_TO]->(Invoice)-[:ISSUED_BY]->(Vendor)

Evaluating this four-hop path during every real-time fraud query causes significant computational overhead. Instead, you can materialize derived edges when data enters the system. This adds a slight write latency during batch ingestion, but it turns multi-hop traversals into direct, single-hop lookups during runtime detection queries.

The first derived relationship is SHARED_ACCOUNT_WITH, which links vendors that share a destination bank account:

MATCH (v1:Vendor)<-[:ISSUED_BY]-(i1:Invoice)<-[:LINKED_TO]-(p1:Payment)-[:PAID_TO]->(a:BankAccount)
MATCH (v2:Vendor)<-[:ISSUED_BY]-(i2:Invoice)<-[:LINKED_TO]-(p2:Payment)-[:PAID_TO]->(a)
WHERE id(v1) < id(v2)
MERGE (v1)-[:SHARED_ACCOUNT_WITH]->(v2)

The filter WHERE id(v1) < id(v2) ensures that the relationship is stored as a single directed edge between the internal node IDs, which prevents duplicate reverse edges.

You can also materialize shared geographic locations and banking routing prefixes to detect loose collusion networks:

-- Same city and country
MATCH (v1:Vendor), (v2:Vendor)
WHERE id(v1) < id(v2)
  AND v1.city = v2.city
  AND v1.country = v2.country
MERGE (v1)-[:SHARED_LOCATION]->(v2)

-- Bank accounts with same routing prefix (first 3 digits)
MATCH (v1:Vendor)<-[:ISSUED_BY]-(i1:Invoice)<-[:LINKED_TO]-(p1:Payment)-[:PAID_TO]->(a1:BankAccount)
MATCH (v2:Vendor)<-[:ISSUED_BY]-(i2:Invoice)<-[:LINKED_TO]-(p2:Payment)-[:PAID_TO]->(a2:BankAccount)
WHERE id(v1) < id(v2)
  AND a1.account_id <> a2.account_id
  AND substring(a1.routing_number, 0, 3) = substring(a2.routing_number, 0, 3)
MERGE (v1)-[:SHARED_ROUTING_PREFIX]->(v2)

Once ingestion completes, you can inspect the graph topology to confirm that both base and derived relationships loaded properly:

info = graph.get_info()
for label, count in sorted(info['nodes'].items(), key=lambda x: -x[1]):
    print(f"  {label}: {count} nodes")
for rel, count in sorted(info['relationships'].items(), key=lambda x: -x[1]):
    print(f"  {rel}: {count} relationships")

The output shows raw entities and the generated derived relationships:

  Invoice: 220 nodes
  Payment: 331 nodes
  Vendor: 100 nodes
  BankAccount: 51 nodes
  Employee: 30 nodes

  SHARED_ACCOUNT_WITH: 412 relationships
  SHARED_LOCATION: 387 relationships
  LINKED_TO: 331 relationships
  PAID_TO: 331 relationships
  ISSUED_BY: 220 relationships
  APPROVED: 331 relationships
  SHARED_ROUTING_PREFIX: 52 relationships

These derived relationships are designed specifically for high-speed detection. In a relational database, discovering shared accounts requires a self-join across multiple tables. In a graph, it becomes a precomputed edge, turning complex traversals into direct lookups.

How to Detect Five Fraud Patterns with Cypher Queries

Once your schema and derived relationships are established, you can construct parameterized Cypher queries that'll flag five widespread procurement fraud patterns.

Pattern 1: How to Find Duplicate Invoices

Fraudulent actors often submit duplicate invoices spaced days or weeks apart, assuming accounts payable teams will process them as routine recurring expenses.

Rule-based engines often catch exact matches, but they can miss invoices with slight date shifts. In a graph, you can query across all invoices issued by the same vendor within a rolling date window:

// graph/queries.py — detect_duplicates()
MATCH (v:Vendor)<-[:ISSUED_BY]-(i1:Invoice),
      (v)<-[:ISSUED_BY]-(i2:Invoice)
WHERE i1.invoice_id < i2.invoice_id
  AND i1.amount = i2.amount
  AND i1.date < i2.date
  AND duration.between(date(i1.date), date(i2.date)).days <= $max_days
RETURN i1.invoice_id AS invoice_a,
       i2.invoice_id AS invoice_b,
       v.name AS vendor,
       i1.amount AS amount,
       i1.date AS date_a,
       i2.date AS date_b,
       duration.between(date(i1.date), date(i2.date)).days AS days_apart
ORDER BY days_apart

Key points here:

• The condition i1.invoice_id < i2.invoice_id prevents returning the same pair twice like (A, B) and (B, A).
• i1.amount = i2.amount is the fraud signal: same amount means likely the same invoice submitted twice.
• By scoping the search to invoices issued by the same vendor v, the query leverages index lookups on the vendor before evaluating date intervals with the native temporal duration.between() function.

You can execute this query through the Python wrapper:

from graph.queries import FraudQueries

queries = FraudQueries(graph)
duplicates = queries.detect_duplicates(max_days_apart=14)
print(f"Found {len(duplicates)} duplicate invoice pairs")
for dup in duplicates[:5]:
    print(f"  {dup['invoice_a']} ↔ {dup['invoice_b']} | "
          f"{dup['vendor']} | ${dup['amount']} | "
          f"{dup['days_apart']} days apart")

The query detects all 12 duplicate pairs injected into the synthetic dataset, achieving 100% recall.

Pattern 2: How to Uncover Circular Invoicing Rings

In circular invoicing schemes, three or more vendors bill one another in a closed loop. Each transaction appears legitimate on its own, but no actual goods or services are delivered.

Because you precomputed SHARED_ACCOUNT_WITH, cycle detection is simplified to finding three-node triangles in the vendor sub-graph:

// graph/queries.py — detect_circular_schemes()
MATCH path = (v1:Vendor)-[:SHARED_ACCOUNT_WITH]-(v2:Vendor)
              -[:SHARED_ACCOUNT_WITH]-(v3:Vendor)
              -[:SHARED_ACCOUNT_WITH]-(v1)
WHERE id(v1) < id(v2) AND id(v2) < id(v3)
RETURN path,
       [n IN nodes(path) | {name: n.name, tax_id: n.tax_id}] AS vendors,
       length(path) AS hops

Key points here:

• The constraint id(v1) < id(v2) AND id(v2) < id(v3) eliminates cyclic permutations. Without it, a single three-node ring (A, B, C) would be returned three separate times.
• If you ran this query directly over raw four-hop transactional paths without materialized edges, finding a three-cycle would require traversing twelve hops, which causes high CPU usage on large datasets.

circles = queries.detect_circular_schemes(min_cycle_length=3)
print(f"Found {len(circles)} circular invoice rings")
for ring in circles:
    vendor_names = [v['name'] for v in ring['vendors']]
    print(f"  Ring ({ring['hops']} hops): {' ↔ '.join(vendor_names)}")

The query catches the circular invoicing ring with 100% recall.

Pattern 3: How to Detect Money Mule Networks

In a money mule setup, multiple shell entities funnel money into a single account controlled by a syndicate. The individual disbursements are small, but the fan-in degree of the destination account is anomalously high.

You can uncover this pattern by performing degree analysis on destination bank accounts:

// graph/queries.py — detect_money_mule_rings()
MATCH (a:BankAccount)<-[p_paid:PAID_TO]-(p:Payment)-[:LINKED_TO]->(i:Invoice)
                  -[:ISSUED_BY]->(v:Vendor)
WITH a, collect(DISTINCT v) AS vendors,
     sum(p.amount) AS total_received,
     count(DISTINCT v) AS unique_vendors,
     count(p) AS payment_count
WHERE unique_vendors >= $min_vendors
RETURN a.account_id,
       a.routing_number,
       a.bank_name,
       unique_vendors AS vendor_count,
       payment_count,
       total_received AS total_amount,
       [vendor IN vendors | vendor.name] AS vendor_names
ORDER BY unique_vendors DESC

You can use the following risk guide to evaluate accounts based on incoming connections:

In production, you can add a threshold on total received amount to minimize false positives:

WHERE unique_vendors >= 10 AND total_received > 50000

Running the detection query in Python:

mules = queries.detect_money_mule_rings(min_vendor_count=5)
for acct in mules:
    print(f"  {acct['a.account_id']} ({acct['a.bank_name']}) | "
          f"{acct['vendor_count']} vendors | ${acct['total_amount']:.0f}")

The query successfully identifies the injected mule ring (ACC-MULE-001), which aggregates payments across 25 shell vendors.

Pattern 4: How to Identify Vendor Collusion Clusters

Colluding shell companies often mask their affiliation by registering under different corporate names. But they frequently leak metadata, such as shared physical office suites or identical banking branch routing prefixes.

To identify these clusters, you can evaluate multiple derived relationships concurrently and compute a composite structural risk score:

// graph/queries.py — detect_vendor_collusion()
MATCH (v:Vendor)
OPTIONAL MATCH (v)-[:SHARED_ACCOUNT_WITH]->(v2)
OPTIONAL MATCH (v)-[:SHARED_LOCATION]->(v3)
OPTIONAL MATCH (v)-[:SHARED_ROUTING_PREFIX]->(v4)
WITH v,
     collect(DISTINCT v2) AS shared_account_vendors,
     collect(DISTINCT v3) AS shared_location_vendors,
     collect(DISTINCT v4) AS shared_routing_vendors
WITH v,
     size(shared_account_vendors) AS sc,
     size(shared_location_vendors) AS sl,
     size(shared_routing_vendors) AS sr
WHERE (sc + sl + sr) >= $min_score AND (sc + sl + sr) > 0
RETURN v.name AS vendor,
       v.tax_id,
       (sc + sl + sr) AS risk_score,
       [n IN shared_account_vendors + shared_location_vendors + shared_routing_vendors | n.name] AS related_vendors,
       [x IN range(1, sc) | 'shared_account'] +
       [x IN range(1, sl) | 'shared_location'] +
       [x IN range(1, sr) | 'shared_routing'] AS flags
ORDER BY risk_score DESC

Key points here:

• Using OPTIONAL MATCH is essential here. A strict MATCH would drop vendors that exhibit shared routing and location but haven't yet shared a bank account.
• You can tune the risk score based on your business environment. Sharing a city is common in large commercial hubs, but sharing a routing prefix and an office suite at the same time elevates the composite score past the investigative threshold.

collusion = queries.detect_vendor_collusion(min_risk_score=2)
for vendor in collusion[:10]:
    print(f"  {vendor['vendor']} | Risk: {vendor['risk_score']} | "
          f"Flags: {vendor['flags']}")

The multi-attribute scoring query successfully flags the four-vendor collusion cluster.

Pattern 5: How to Flag Out-of-Jurisdiction Payment Approvals

Internal fraud often relies on an employee approving an invoice outside their departmental authority. For instance, an HR manager might approve an engineering infrastructure vendor invoice without authorization.

Approval systems often confirm that an approver has signing authority, but they rarely validate whether the approver's department has jurisdiction over the invoice category. A graph query can traverse the full approval path and evaluate departmental permissions:

// graph/queries.py — detect_payment_anomalies()
MATCH (inv:Invoice)<-[:LINKED_TO]-(p:Payment),
      (e:Employee)-[:APPROVED]->(p),
      (e)-[:WORKS_FOR]->(org:Organization)
WITH inv, p, e, org,
     CASE
       WHEN inv.category = 'procurement' AND
            e.department IN ['finance', 'operations', 'procurement']
            THEN 'ok'
       WHEN inv.category = 'payroll' AND
            e.department IN ['hr', 'finance']
            THEN 'ok'
       WHEN inv.category = 'travel' AND
            e.department IN ['operations', 'finance', 'hr']
            THEN 'ok'
       WHEN inv.category = 'marketing' AND
            e.department IN ['marketing', 'finance']
            THEN 'ok'
       WHEN inv.category = 'consulting' AND
            e.department IN ['finance', 'operations', 'procurement']
            THEN 'ok'
       WHEN inv.category = 'services' AND
            e.department IN ['finance', 'operations', 'procurement']
            THEN 'ok'
       WHEN inv.category = 'supplies' AND
            e.department IN ['operations', 'procurement', 'finance']
            THEN 'ok'
       WHEN inv.category = 'maintenance' AND
            e.department IN ['operations', 'procurement', 'finance']
            THEN 'ok'
       WHEN inv.category = 'software' AND
            e.department IN ['engineering', 'operations', 'finance']
            THEN 'ok'
       ELSE 'ANOMALY'
     END AS approval_status
WHERE approval_status = 'ANOMALY'
RETURN inv.invoice_id, inv.amount, inv.category,
       inv.vendor_name, inv.date,
       e.name AS approver, e.employee_id,
       e.department AS approver_department
ORDER BY inv.date DESC

Key points here:

• The default-deny ELSE 'ANOMALY' structure ensures that any invoice category not explicitly authorized fails closed.
• In enterprise architectures, you should materialize this policy logic directly in the graph using (:Department)-[:AUTHORIZED_FOR]->(:Category) nodes rather than hardcoding values in queries. This allows compliance teams to update authority matrices without deploying new code.

anomalies = queries.detect_payment_anomalies()
print(f"Found {len(anomalies)} anomalous approvals")
for a in anomalies:
    print(f"  Invoice {a['inv.invoice_id']}: "
          f"{a['e.name']} ({a['e.department']}) approved "
          f"{a['inv.category']} | ${a['inv.amount']}")

The query surfaces all 3 injected approval anomalies with 100% recall.

How to Run the End-to-End Pipeline and Validate Results

You can orchestrate these steps into an automated command-line pipeline:

python analysis/run_detections.py

The end-to-end data flow operates in six distinct phases:

Generate Dataset → Load to Neo4j → Build Derived Relationships → Run 5 Queries → Save Results → Validate

How to Run Ingestion and Detection

The main pipeline script orchestrates data generation, schema creation, relationship materialization, and query execution:

# analysis/run_detections.py
from dataset.generate import FraudDatasetGenerator
from graph.connection import FraudGraph
from graph.loader import FraudGraphLoader
from graph.queries import FraudQueries

def run_pipeline(output_dir='analysis/output', force_regenerate=False):
    os.makedirs(output_dir, exist_ok=True)

    # Step 1: Generate or load dataset
    dataset_path = os.path.join(output_dir, 'data')
    if not os.path.exists(os.path.join(dataset_path, 'vendors.json')) or force_regenerate:
        gen = FraudDatasetGenerator(seed=42)
        gen.save(dataset_path)
    else:
        print(f'Dataset already at: {dataset_path}')

    # Load JSON files
    data = {}
    for name in ['vendors', 'invoices', 'payments', 'bank_accounts',
                  'employees', 'organizations', 'ground_truth']:
        with open(os.path.join(dataset_path, f'{name}.json')) as f:
            data[name] = json.load(f)

    # Step 2: Load into Neo4j
    graph = FraudGraph()
    graph.connect()
    graph.create_constraints()
    loader = FraudGraphLoader(graph)
    loader.load_all(data)
    loader.create_shared_account_relationships()
    loader.create_attribute_based_relationships()

    info = graph.get_info()
    print('Graph loaded:')
    for label, count in sorted(info['nodes'].items(), key=lambda x: -x[1]):
        print(f'  {label}: {count} nodes')

    # Step 3: Run all detections
    queries = FraudQueries(graph)
    results = queries.detect_all()

    # Step 4: Save results
    with open(os.path.join(output_dir, 'detection_results.json'), 'w') as f:
        json.dump(results, f, indent=2, default=str)

    for pattern, items in results.items():
        print(f'  {pattern}: {len(items)} findings')

The detect_all() method runs all five queries and returns a single dict:

# graph/queries.py
def detect_all(self):
    return {
        'duplicate_invoices': self.detect_duplicates(),
        'circular_schemes': self.detect_circular_schemes(),
        'money_mule_rings': self.detect_money_mule_rings(),
        'vendor_collusion': self.detect_vendor_collusion(),
        'payment_anomalies': self.detect_payment_anomalies(),
    }

How to Validate Recall Against Injected Ground Truth

The validation script compares query results against the ground-truth file to measure recall:

# analysis/validate.py
from collections import defaultdict

def validate(results_path, output_path=None):
    with open(results_path) as f:
        results = json.load(f)

    with open(os.path.join(os.path.dirname(results_path), 'data',
                           'ground_truth.json')) as f:
        ground_truth = json.load(f)

    gt_by_pattern = defaultdict(list)
    for pattern in ground_truth:
        gt_by_pattern[pattern['pattern']].append(pattern)

The verification logic evaluates detection accuracy for each pattern type:

for pattern_name, gt_patterns in gt_by_pattern.items():
    found = results.get(pattern_name, [])
    gt_count = len(gt_patterns)

    if pattern_name == 'duplicate_invoices':
        print(f"DUPLICATE INVOICES: DETECTED {len(found)} of {gt_count} pairs — {len(found)/max(1,gt_count):.0%} recall")

    elif pattern_name == 'money_mule_rings':
        matched = sum(1 for gt in gt_patterns
                      for r in found
                      if r.get('a.account_id') == gt['shared_account'])
        print(f"MONEY MULE RINGS: DETECTED {matched} of {gt_count} rings — {matched/max(1,gt_count):.0%} recall")

Running the validator against a dataset generated with seed=42 produces these results:

DUPLICATE INVOICES: DETECTED 12 of 12 pairs — 100% recall
CIRCULAR SCHEMES: DETECTED 1 of 1 rings — 100% recall
MONEY MULE RINGS: DETECTED 1 of 1 rings — 100% recall
VENDOR COLLUSION: 89 high-risk vendors flagged (multi-attribute scoring)
PAYMENT ANOMALIES: DETECTED 3 of 3 anomalies — 100% recall

How to Execute the Complete Workflow

Here's the complete sequence of terminal commands to set up the environment, run the pipeline, and validate the results:

# 1. Start Neo4j
docker compose up -d

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the full pipeline
python analysis/run_detections.py

# 4. Validate results
python analysis/validate.py

# 5. (Optional) Regenerate with fresh data and re-run
python analysis/run_detections.py --regenerate

Production Architecture: How to Scale the Graph Pipeline

While the reference prototype operates on hundreds of nodes, production fraud detection engines handle millions of transactions daily. Scaling this architecture requires addressing key operational bottlenecks.

New Transaction
    ↓
Stage 1 — Deterministic queries (fast, rule-based)
    ↓  (if any pattern matches)
Stage 2 — ML scoring on graph features
    ↓
Risk Score → Alert / Approve / Escalate

How to Implement a Two-Stage Detection Architecture

Running global cycle detection queries synchronously on every incoming transaction inside an online payment path will exhaust database connection pools.

Instead, you should partition detection into two tiers:

• Stage 1 (Synchronous Gating): Sub-millisecond Cypher queries that catch known patterns. They're fast because they use indexed properties, pre-built relationships, and bounded pattern lengths.
• Stage 2 (Asynchronous Graph Analytics): For transactions that don't trigger a deterministic rule, compute graph-derived features and score them:

How to Tune Thresholds and Manage False Positives

Detection systems inevitably produce false positives. In production, review feedback from compliance analysts should be used to continuously calibrate query thresholds:

#Tune thresholds based on false positive rate

queries.detect_money_mule_rings(min_vendor_count=10) # was 5
queries.detect_duplicates(max_days_apart=7) # was 14
queries.detect_vendor_collusion(min_risk_score=3) # was 2

You can rerun validation after each threshold update to monitor the effect on recall:

python analysis/validate.py --input analysis/output/detection_results.json

How to Mitigate Supernode Expansion

A common failure in graph systems is the "supernode" problem. Legitimate shared entities (for example, a major corporate landlord, a national power utility, or internal payroll accounts) can accumulate tens of thousands of incoming edges.

When a query attempts to traverse through a supernode without filtering, traversal latency spikes exponentially.

You can mitigate this with two strategies:

• Degree Limits: Add degree pruning in traversals:

MATCH (a:BankAccount)

WHERE size((a)<-[:PAID_TO]-()) < 1000

• Node Labels: Tag known high-volume institutional entities with a :Whitelisted or :Utility label, and explicitly exclude them from collusion and money mule scans.

How to Use Graph Features for Machine Learning

The most effective fraud detection systems don't treat graphs and machine learning as competing paradigms. Instead, the graph acts as an advanced feature store for predictive models:

• Degree Centrality: Measures the connectivity of an account to identify mule convergence.
• Betweenness Centrality: Identifies entities that act as bridges between seemingly disconnected vendor groups.
• PageRank and Community Detection: Quantifies cluster association and entity importance across the network.

An ML classifier relying solely on transaction amounts might see nothing unusual about a $4,900 payment. But when paired with a graph-derived feature showing the vendor has a high betweenness centrality and shares a second-degree connection with a confirmed fraud ring, the classifier flags the transaction with high precision.

Key Architectural Lessons and Takeaways

Building and tuning graph-based fraud pipelines highlights several key trade-offs:

First, in a relational database, schema design prioritizes third normal form (3NF) to eliminate data redundancy. In a graph, design your schema around the traversals you need to execute. If a query repeatedly traverses four hops to find correlated attributes, materialize that correlation as a direct relationship during ingestion.

Second, unique property constraints aren't just for data integrity. They provide the underlying hash indexes that make node lookups $O(1)$. Omitting constraints turns every graph merge into an unindexed full scan.

Third, you should curate the rule Inventory**.** Start with a focused set of four or five high-signal patterns. Each pattern requires threshold calibration and triage workflows. Adding dozens of unverified heuristics simultaneously creates operational noise and alert fatigue for compliance teams.

And finally, close the analyst feedback loop. The output of a detection query is a hypothesis, not a final verdict. When compliance analysts investigate an alert and confirm fraud, write that status back into the graph as a node property or label (for example, :ConfirmedFraud). This enriches the neighborhood topology and provides clean ground truth for training downstream machine learning models.

Conclusion

In this tutorial, you explored why point-in-time relational checks miss complex fraud schemes, how to model accounts payable data as an interconnected graph, and how to materialize derived edges to accelerate traversal latency.

You also implemented five Cypher queries capable of detecting duplicate billing, circular rings, money mules, vendor collusion, and unauthorized payment approvals.

The companion code for this article is available at github.com/kamalct/fraud-detection-knowledge-graphs. All data is synthetic and fully reproducible.