I encountered this problem while I was building my SaaS app. I scoured through StackOverflow, Reddit, and Quora, but didn't find a satisfying answer. Some solutions were impractical, while others needed complex configuration.

After going through the struggle, I said, “You know what? Screw it. Let me build my own little PDF parser”. With the help of Claude and Node.js, I built a custom PDF parser for my SaaS app.

In this tutorial, I’ll show you how I built my custom PDF parser using Node.js and how you can do the same.

Table of Contents

• Why Build a Custom PDF Text Extractor?

• Sample of What We’ll Be Building

• Prerequisites

• Setting Up the Project

• Core Implementation: Building the Extractor

• Adding Page-Specific Extraction

• Adding a Lightweight Metadata-Only Endpoint

• Adding Search/Find Functionality

• Creating the Search/Find Function

• Handling Edge Cases and Best Practices

• Best Practices

• Unit Testing Your PDF Parser

• Deploying Your PDF Parser API

• Next Steps: Integrate Into Your SaaS

• Conclusion

• Resources

Why Build a Custom PDF Text Extractor?

You might ask yourself: "Why build a custom PDF parser when libraries already exist?"

Popular JavaScript PDF parsers have various trade-offs. Here's a quick comparison of common options:

These libraries work well for specific use cases, but building your own parser still has advantages:

• You choose the tech stack that fits your application

• You add only the features your project needs

And the good news is, you can build a JavaScript-native parser for your project's needs without having to rely on external dependencies or adapt libraries built for different ecosystems.

A custom parser gives you full control without the bloat of unnecessary functionality.

Sample of What We’ll Be Building

Here’s a screen recording of our text extractor in action:

Prerequisites

To follow along with this tutorial, I assume:

• You have Node.js installed on your machine. If you don’t have Node.js installed, you can install it from the official Node.js website.

• You know how to write basic TypeScript code.

Setting Up the Project

In this section, you’ll set up your project. This project uses TypeScript in Node.js rather than JavaScript.

Don’t worry if you don’t know how to configure TypeScript for Node.js. I’ll show you how to do it in this section.

Initializing a Node.js app

Open the folder where you want your project to live, and create a Node.js project:

npm init -y

Install the necessary packages:

npm install cors express-fileupload pdf-parse

• cors: Enables Cross-Origin Resource Sharing, allowing your API to accept requests from different domains or ports.

• express-fileupload: Middleware for handling file uploads in Express, making it easy to process uploaded PDFs.

• pdf-parse: A lightweight PDF parsing library for extracting text and metadata from PDF files.

• express: The web framework for Node.js that handles routing, middleware, and server setup.

Now let’s continue with our installs:

npm install -D typescript ts-node @types/node @types/express nodemon prettier dotenv @types/cors @types/express-fileupload

The -D flag directs npm to install these libraries as development dependencies.

• ts-node: Lets you run TypeScript code directly in Node.js without compiling to JavaScript first

• @types/node: Adds TypeScript type definitions for Node.js core modules like fs, path, and http

• @types/express: Provides TypeScript type definitions for the Express.js framework and its middleware

• nodemon: Automatically restarts your development server whenever you save changes to your code

• prettier: A code formatter that ensures consistent style and readability across your entire project

Configuring TypeScript in the Node.js app

Let’s start by generating a tsconfig.json file:

npx tsc --init

TypeScript projects use the tsconfig.json file to manage the project’s settings. The configuration file is located in the root of your project.

After running the command, you should see a tsconfig.json file that looks like this:

{
  // Visit https://aka.ms/tsconfig to read more about this file
  "compilerOptions": {
    // File Layout
    // "rootDir": "./src",
    // "outDir": "./dist",

    // Environment Settings
    // See also https://aka.ms/tsconfig/module
    "module": "nodenext",
    "target": "esnext",
    "types": [],
    // For nodejs:
    // "lib": ["esnext"],
    // "types": ["node"],
    // and npm install -D @types/node

    // Other Outputs
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    // Stricter Typechecking Options
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // Style Options
    // "noImplicitReturns": true,
    // "noImplicitOverride": true,
    // "noUnusedLocals": true,
    // "noUnusedParameters": true,
    // "noFallthroughCasesInSwitch": true,
    // "noPropertyAccessFromIndexSignature": true,

    // Recommended Options
    "strict": true,
    "jsx": "react-jsx",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true,
  }
}

Add "node" to the types array like this:

"types": ["node"]

Then modify your package.json file with the following code:

{
    "main": "index.ts",
    "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "nodemon --watch src --ext ts,json --exec \"node --loader ts-node/esm src/server.ts\"",
    "build": "tsc",
    "start": "node src/server.js"
  },
    "type": "module"
}

This ensures that the entry point of your app is a TypeScript file, and you can use import statement instead of require.

In the next section, you’re going to build the PDF parser.

Core Implementation: Building the Extractor

After configuring your Node.js app, the next step is to build the PDF parser.

Create a new directory in your Node.js app, and create a server.ts file.

Now import the necessary packages for building the PDF parser:

import express, { type Request, type Response } from "express";
import fileUpload, { type UploadedFile } from "express-fileupload";
import { PDFParse } from "pdf-parse";
import cors from "cors";

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

Let’s understand what’s happening:

• fileUpload is the module for uploading files in an Express app. The UploadedFile type is a TypeScript type for the uploaded file.

• PDFParse is the core parsing module. It provides the basic functionality of parsing PDF files.

• cors is the module for protecting the app from origins not specified.

• You created an Express app with the following line: const app = express();.

• PORT is the port you want your app to be hosted on.

Configuring CORS Middleware

Setting up CORS allows requests from specified origins. This protects your app from attacks.

app.use(
  cors({
    origin: ["http://localhost:3000", "https://yourwebsite.com"],
  })
);

Implementing File Upload Middleware

To handle file uploads in your API, you’ll use the express-fileupload middleware. This middleware intercepts incoming file uploads and makes them accessible through req.files.

You can run checks on the incoming file, such as file size and number of files.

import fileUpload, { type UploadedFile } from "express-fileupload";

app.use(
  fileUpload({
    limits: { fileSize: 50 * 1024 * 1024 }, // 50 MB limit
    abortOnLimit: true,
  })
);

Key options:

• fileSize: Sets the maximum file size allowed (50 MB in this case)

• abortOnLimit: When true, automatically rejects uploads that exceed the size limit and prevents further processing

Here’s why this is important:

• Security: Limits prevent server overload from massive files.

• Performance: Automatically rejects oversized PDFs before processing.

• User Experience: Gives clear error messages for files that are too large.

Creating the Parser Logic

The parser logic is the core function that parses the PDFs. It’s an asynchronous function that extracts text content and metadata from a PDF buffer.

async function parsePDF(file: Uint8Array) {
  const parser = new PDFParse(file);
  const data = await parser.getText();
  const info = await parser.getInfo({ parsePageInfo: true });
  return { text: data?.text || "", info, numpages: info?.pages || 0 };
}

Let’s understand what’s happening in the code:

• The function accepts a Uint8Array buffer containing the raw PDF file data.

• You initialized a new PDFParse object with the PDF buffer.

• You called getText() to extract all text content from the PDF.

• You called getInfo() with parsePageInfo: true to retrieve document information, including page count.

• You returned an object containing:

  • text: The extracted text content (or empty string if none found)

  • info: Document metadata (author, title, creation date, and so on)

  • numpages: Total number of pages in the PDF

Why is the parser logic asynchronous?

Both getText() and getInfo() are asynchronous operations. They require time to parse through the PDF document, so await ensures the operations complete before returning results. This prevents blocking your server while processing large PDF files.

Creating the PDF Upload and Processing Endpoint

Now that you have the core parsePDF() function, you need an endpoint that accepts file uploads and processes them using this function.

app.post("/upload", async (req: Request, res: Response) => {
  try {
    if (!req.files || !("file" in req.files)) {
      return res.status(400).json({
        error: "No PDF file shared.",
        body: `Body is ${JSON.stringify(req.body)}`,
      });
    }

    const pdfFile = req.files.file as UploadedFile;
    const unit8ArrayData = new Uint8Array(pdfFile?.data);
    const result = await parsePDF(unit8ArrayData);
    console.log("PDF parsed successfully: ", result);
    res.json({ result, success: true });
  } catch (error) {
    console.error("Error processing PDF:", error);
    if (error instanceof Error) {
      return res.status(500).json({ error: error.message, success: false });
    }
    res.status(500).json({
      error: "Failed to process PDF due to an unknown error.",
      success: false,
    });
  }
});

Let's break down what's happening in this code:

• You defined a POST route handler at /upload that processes PDF file uploads. The handler uses req.files to access uploaded files and validate that a "file" field exists in the request.

• The handler extracts the uploaded PDF file and converts it to a Uint8Array buffer, which is the required format for the parsePDF() function that performs the actual PDF parsing.

• You implemented comprehensive error handling with a try-catch block that:

  • Logs errors to the console for debugging purposes

  • Returns specific error messages when the error is an instance of the Error class

  • Provides a generic error response for unexpected failures while maintaining the success: false flag for consistent client responses

This route handler creates a PDF processing endpoint that validates inputs, processes files efficiently, and provides clear error feedback.

Starting Your Server

The last step is to start your Express server and confirm it’s running correctly.

const PORT = process.env.PORT || 8080;

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

• app.listen(): Binds the Express server to the specified PORT and starts listening for incoming requests.

• PORT configuration: The server uses the PORT environment variable if set, otherwise defaults to 8080.

• Callback function: Once the server starts, the callback logs a message to the console with the server URL.

Use the following command to start your server:

npm run dev

When the server starts successfully, you'll see the message below in your console:

🚀 Server is running on http://localhost:8080

Your PDF parser API is now ready to accept file uploads and process PDFs.

You can verify that your PDF parser is working by visiting the URL using Postman or any API client of your choice.

Congratulations! You’ve built a custom PDF parser.

This PDF parser is sufficient for simple parsing tasks. But you can extend the functionality of the parser to make it more robust.

In the next sections, you’ll add extra features, such as handling corrupt files.

Adding Page-Specific Extraction

When working with large PDF documents, extracting the entire file can be inefficient and unnecessary. This feature allows users to specify a page range and extract text only from those pages. This makes your parser more flexible and performant for real-world use cases.

For example, a user might want to extract only pages 5-10 from a 100-page report. By adding optional query parameters startPage and endPage to your endpoint, you give users fine-grained control over which portions of a PDF they want parsed.

In this section, you’ll create a page-specific extraction function and an endpoint to handle parameters from request queries.

Creating the Page-specific extraction function

The page-specific extraction function is the core function that parses the specified pages.

// function to extract text from a range of pages
async function parsePageRangeFromPDF(
  file: Uint8Array,
  startPage: number,
  endPage: number,
) {
  const parser = new PDFParse(file);
  const info = await parser.getInfo({ parsePageInfo: true });
  const totalPages = Array.isArray(info?.pages)
    ? info.pages.length
    : (info?.pages as number) || 0;

  if (startPage < 1 || endPage > totalPages || startPage > endPage) {
    throw new Error(
      `Invalid page range. PDF has ${totalPages} pages. Please provide a valid range where start >= 1, end <= ${totalPages}, and start <= end.`,
    );
  }

  const data = await parser.getText();
  const lines = data?.text?.split("\n") || [];

  // Note: pdf-parse doesn't provide direct page filtering, so getText() returns all text
  // For accurate page range extraction, consider using a different PDF library
  return { text: data?.text || "", startPage, endPage, totalPages };
}

Let's break down what's happening in this code:

1. You defined an async function parsePageRangeFromPDF that extracts text from a specific range of pages within a PDF document. The function accepts a Uint8Array PDF file and two numeric parameters for the start and end page range.

2. The function uses the PDFParse library to analyze the PDF structure, first extracting metadata, including the total page count, using parser.getInfo(). It then validates that the requested page range falls within the actual PDF boundaries.

3. After successful validation, the function extracts all text from the PDF using parser.getText() and splits it into individual lines. The function returns an object containing the extracted text along with metadata about the requested range and total pages.

This function creates a reusable utility for extracting specific page ranges from PDFs with proper validation and error handling.

Creating the Page-Specific Extraction Endpoint

Now that you’ve created the function for parsing specified pages of a PDF, you’ll create the endpoint for accepting uploads and parsing specified pages.

// Page range PDF text extraction endpoint
app.post("/upload-page-range", async (req: Request, res: Response) => {
  try {
    if (!req.files || !("file" in req.files)) {
      return res.status(400).json({
        error: "No PDF file shared.",
      });
    }

    // Get page range from query params or body
    const startPage = parseInt(
      (req.query.startPage as string) || (req.body?.startPage as string) || "1"
    );
    const endPage = parseInt(
      (req.query.endPage as string) || (req.body?.endPage as string) || "1"
    );

    if (isNaN(startPage) || isNaN(endPage)) {
      return res.status(400).json({
        error:
          "Invalid page range. Please provide valid integers for startPage and endPage.",
      });
    }

    const pdfFile = req.files.file as UploadedFile;
    const unit8ArrayData = new Uint8Array(pdfFile?.data);
    const result = await parsePageRangeFromPDF(
      unit8ArrayData,
      startPage,
      endPage
    );
    console.log(
      `Pages ${startPage}-${endPage} extracted successfully: `,
      result
    );
    res.json({ result, success: true });
  } catch (error) {
    console.error("Error processing PDF: ", error);
    if (error instanceof Error) {
      return res.status(400).json({ error: error.message, success: false });
    }
    res.status(500).json({
      error: "Failed to process PDF due to an unknown error.",
      success: false,
    });
  }
});

Let's break down what's happening in this code:

1. You defined a POST route handler at /upload-page-range that extracts text from a specific page range within uploaded PDF files. The handler first validates that a PDF file exists in the request using req.files, returning a 400 error if no file is provided.

2. The function extracts the startPage and endPage parameters from either query parameters or request body, providing default values of "1" if neither is specified. It then validates that both values are valid integers using isNaN() checks. This ensures robust input handling for page range requests.

3. Once the PDF is converted to a buffer, it's passed to parsePageRangeFromPDF() to extract the requested page range. The API responds with the extracted text and range details, while errors are clearly categorized: validation issues return 400, server problems return 500.

This endpoint creates a specialized PDF processing route that allows clients to extract text from specific page ranges rather than entire documents.

Now, you can extract from specific pages using request parameters:

curl -F "file=@yourfile.pdf" "http://localhost:8080/upload-page-range?startPage=5&endPage=7"

or using request body:

curl -X POST -F "file=@yourfile.pdf" \
  -F "startPage=5" \
  -F "endPage=7" \
  http://localhost:8080/upload-page-range

In the next section, you’ll add an endpoint for getting only the metadata of an uploaded file.

Adding a Lightweight Metadata-Only Endpoint

Creating a lightweight metadata-only endpoint allows your users to quickly validate and inspect PDFs without fully processing the document.

This is useful for previewing document info before processing.

Creating the Metadata Extraction Function

Add a new function that retrieves only document information:

async function getPDFMetadata(file: Uint8Array) {
  const parser = new PDFParse(file);
  const info = await parser.getInfo({ parsePageInfo: true });
  return {
    title: info?.info?.Title || "N/A",
    author: info?.info?.Author || "N/A",
    subject: info?.info?.Subject || "N/A",
    creator: info?.info?.Creator || "N/A",
    producer: info?.info?.Producer || "N/A",
    creationDate: convertPDFDateToReadable(info?.info?.CreationDate || "N/A"),
    modificationDate: convertPDFDateToReadable(info?.info?.ModDate || "N/A"),
    pages: info?.total || 0,
  };
}

Let's break down what's happening in this code:

1. You defined an async function getPDFMetadata that extracts and processes metadata from PDF documents. The function accepts a Uint8Array PDF file buffer and uses the PDFParse library to retrieve document information.

2. The function extracts key PDF metadata fields, including title, author, subject, creator, and producer, providing fallback values of "N/A" when these fields are missing. This ensures the function always returns a complete metadata object, even for PDFs with missing information.

3. You implemented date processing using a convertPDFDateToReadable helper function to transform the PDF's specialized date formats into human-readable strings. The function returns a structured object containing all extracted metadata along with the total page count.

This utility function provides a clean interface for extracting and normalizing PDF metadata. It makes it easy to access document information like authorship, creation dates, and page counts in a standardized format.

Here’s the convertPDFDateToReadable function:

function convertPDFDateToReadable(pdfDateString: string): string {
  try {
    // Remove "D:" prefix if present
    let dateStr = pdfDateString.startsWith("D:")
      ? pdfDateString.slice(2)
      : pdfDateString;

    // Extract date and time components (format: YYYYMMDDHHmmss)
    const year = dateStr.substring(0, 4);
    const month = dateStr.substring(4, 6);
    const day = dateStr.substring(6, 8);
    const hour = dateStr.substring(8, 10);
    const minute = dateStr.substring(10, 12);
    const second = dateStr.substring(12, 14);

    // Validate date components
    const monthNum = parseInt(month);
    const dayNum = parseInt(day);

    if (monthNum < 1 || monthNum > 12 || dayNum < 1 || dayNum > 31) {
      throw new Error("Invalid date values");
    }

    // Return in dd/mm/yyyy format
    return `${day}/${month}/${year}`;
  } catch (error) {
    console.error("Error converting PDF date:", error);
    return "Invalid date";
  }
}

Creating the Metadata Endpoint

Create a POST endpoint that accepts file uploads and returns only metadata:

app.post("/metadata", async (req: Request, res: Response) => {
  try {
    if (!req.files || !("file" in req.files)) {
      return res.status(400).json({
        error: "No PDF file shared.",
      });
    }

    const pdfFile = req.files.file as UploadedFile;
    const unit8ArrayData = new Uint8Array(pdfFile?.data);
    const metadata = await getPDFMetadata(unit8ArrayData);

    console.log("PDF metadata extracted successfully: ", metadata);
    res.json({ metadata, success: true });
  } catch (error) {
    console.error("Error extracting metadata:", error);
    if (error instanceof Error) {
      return res.status(500).json({ error: error.message, success: false });
    }
    res.status(500).json({
      error: "Failed to extract metadata due to an unknown error.",
      success: false,
    });
  }
});

Let's break down what's happening in this code:

1. You defined a POST route handler at /metadata that extracts and returns metadata from uploaded PDF files. The handler begins with validation to ensure a PDF file exists in the request using req.files, returning a 400 error with a clear message if no file is provided.

2. The function converts the uploaded PDF file to a Uint8Array buffer format, which is required by the getPDFMetadata() utility function you created earlier. This conversion ensures the PDF data is in the proper format for the PDF parsing library to process.

3. After successfully extracting metadata, the route logs the results and returns them in a structured JSON response. The comprehensive error handling catches any issues during processing and returns appropriate 500 errors with descriptive messages while maintaining the consistent response format.

This endpoint provides a dedicated API for extracting PDF metadata like title, author, creation dates, and page counts. This provides your users with an easy way to analyze PDF document properties without needing to parse the entire file content.

Now, you can extract only the metadata of uploaded files:

curl -X POST -F "file=@document.pdf" http://localhost:8080/metadata

Your response should look like this:

{
    "metadata": {
        "title": "MSA",
        "author": "N/A",
        "subject": "N/A",
        "creator": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/144.0.0.0 Safari/537.36",
        "producer": "Skia/PDF m144",
        "creationDate": "22/01/2026",
        "modificationDate": "22/01/2026",
        "pages": 26
    },
    "success": true
}

Adding Search/Find Functionality

When working with large PDFs, finding specific information manually can be time-consuming. The search functionality allows users to locate keywords within a PDF and get immediate results showing which pages contain the keyword and how many times it appears.

This is especially valuable for research, compliance, or document analysis tasks.

For example, a user may wish to find all instances of "invoice" in a 50-page financial report, or locate "clause 3.2" in a legal document. By adding a dedicated search endpoint that accepts a PDF file and a keyword, you give clients the ability to quickly navigate large documents without reading through every page.

In this section, you'll create a search function that finds keywords within PDF text and an endpoint that accepts file uploads along with search queries.

Creating the Search/Find Function

The search function is the core utility that finds keywords within PDF documents and returns detailed results about their locations.

async function searchPDFText(
  file: Uint8Array,
  searchQuery: string,
  caseSensitive: boolean = false
) {
  const parser = new PDFParse(file);
  const info = await parser.getInfo({ parsePageInfo: true });
  const totalPages = Array.isArray(info?.pages)
    ? info.pages.length
    : (info?.pages as number) || 0;

  const results = {
    query: searchQuery,
    caseSensitive,
    matchCount: 0,
    matches: [] as Array<{
      page: number;
      text: string;
      position: number;
    }>,
  };

  // Extract text from all pages
  for (let page = 1; page <= totalPages; page++) {
    const data = await parser.getText();
    const pageText = data?.text || "";

    // Determine search text based on case sensitivity
    const searchText = caseSensitive ? searchQuery : searchQuery.toLowerCase();
    const compareText = caseSensitive ? pageText : pageText.toLowerCase();

    let searchIndex = 0;
    while ((searchIndex = compareText.indexOf(searchText, searchIndex)) !== -1) {
      // Extract context (100 characters before and after)
      const startContext = Math.max(0, searchIndex - 50);
      const endContext = Math.min(pageText.length, searchIndex + searchQuery.length + 50);
      const contextText = pageText.substring(startContext, endContext);

      results.matches.push({
        page,
        text: contextText.trim(),
        position: searchIndex,
      });

      results.matchCount++;
      searchIndex += searchText.length;
    }
  }

  return results;
}

Let's break down what's happening in this code:

1. You defined an async function searchPDFText that performs text search within PDF documents with optional case sensitivity. The function accepts a PDF file buffer, a search query string, and a caseSensitive parameter with a default value of false for more flexible searching.

2. The function uses the PDFParse library to first extract the total page count from the PDF metadata. It then initializes a results object to track the search query, case sensitivity setting, total match count, and individual matches with their page numbers, context text, and positions.

3. For each page in the PDF, the function extracts text and performs the search using either case-sensitive or case-insensitive comparison based on the parameter. When matches are found, it captures a 100-character context window around each match (50 characters before and after) and records the page number, position, and contextual text in the results.

This function creates a comprehensive PDF search utility that can locate specific text within documents, while providing contextual snippets for each match. This makes it useful for document analysis and content retrieval applications.

Creating the Search/Find Endpoint

Now that you've created the search function, you'll create an endpoint that accepts file uploads along with a search query. The endpoint also supports case-sensitive searches.

app.post("/search", async (req: Request, res: Response) => {
  try {
    if (!req.files || !("file" in req.files)) {
      return res.status(400).json({
        error: "No PDF file shared.",
      });
    }

    // Get search query and options
    const query = (req.query.query as string) || (req.body?.query as string);
    const caseSensitive =
      (req.query.caseSensitive as string) === "true" ||
      req.body?.caseSensitive === true;

    if (!query || query.trim() === "") {
      return res.status(400).json({
        error: "Search query is required.",
      });
    }

    const pdfFile = req.files.file as UploadedFile;
    const unit8ArrayData = new Uint8Array(pdfFile?.data);
    const results = await searchPDFText(unit8ArrayData, query, caseSensitive);

    if (results.matchCount === 0) {
      return res.json({
        result: results,
        success: true,
        message: "No matches found.",
      });
    }

    console.log(`Found ${results.matchCount} matches for "${query}"`);
    res.json({ result: results, success: true });
  } catch (error) {
    console.error("Error searching PDF:", error);
    if (error instanceof Error) {
      return res.status(400).json({ error: error.message, success: false });
    }
    res.status(500).json({
      error: "Failed to search PDF due to an unknown error.",
      success: false,
    });
  }
});

Let's break down what's happening in this code:

1. You defined a POST route handler at /search that enables full-text search within uploaded PDF documents. The handler begins with validation to ensure that both a PDF file and a search query are provided, returning 400 errors with descriptive messages if either is missing or empty.

2. The function extracts the search query and caseSensitive option from either query parameters or the request body, with proper type conversion for the boolean flag. It converts the uploaded PDF to a Uint8Array buffer and passes it to your searchPDFText() utility function along with the search parameters.

3. The handler provides informative responses based on search results: returning a success response with a "No matches found" message when no matches are detected, or returning the full results when matches exist. Error handling differentiates between client errors (400) for invalid inputs and server errors (500) for processing failures.

This endpoint creates a powerful PDF search API that allows clients to locate specific text within documents with configurable case sensitivity, providing contextual matches and comprehensive results for document analysis applications.

Now, you can search for keywords within PDFs using query parameters.

Search for “example” (case-insensitive):

curl -F "file=@document.pdf" "http://localhost:8080/search?query=example"

Search for “Example” (case-sensitive):

curl -F "file=@document.pdf" "http://localhost:8080/search?query=Example&caseSensitive=true"

You can use the request body:

curl -X POST -F "file=@document.pdf" \
  -F "query=PDF" \
  -F "caseSensitive=true" \
  http://localhost:8080/search

Your response should look like this:

{
  "result": {
    "query": "PDF",
    "caseSensitive": false,
    "matchCount": 3,
    "matches": [
      {
        "page": 1,
        "text": "...This is a PDF document. The PDF format is...",
        "position": 10
      },
      {
        "page": 2,
        "text": "...Learn more about PDF standards...",
        "position": 25
      }
    ]
  },
  "success": true
}

You’ve now added three important features to your PDF parser.

In the next section, we’ll look at handling edge cases.

Handling Edge Cases and Best Practices

When building your custom PDF parser, there are some edge cases you should keep in mind if you want to build a more robust and reliable parser.

Below are some edge cases to watch out for:

Corrupted or Malformed PDFs

Some users may upload corrupted PDFs – that is, PDFs with invalid structure or corrupted headers. This can cause errors during processing.

You can wrap your parsing operations in a try-catch block to handle the parsing errors gracefully. Also, you’ll want to provide clear error messages that distinguish corrupted files from other errors.

Password-Protected PDFs

PDFs can be encrypted with user or owner passwords. This poses a challenge as pdf-parse has limited support for password-protected files.

There are two ways you can solve this problem:

• Implement a mechanism that rejects password-protected files.

• Accept a password query you can use to decrypt the files.

Scanned PDFs (Image-Based)

PDFs created from scanned documents are images with no extractable text. If you try to parse these documents as is, you’ll get empty or minimal text.

You can implement OCR (Optical Character Recognition) to extract text from scanned PDFs.

Special Characters and Encoding

Your users may upload PDFs that contain special characters, Unicode symbols, or non-Latin scripts. If your extraction function doesn’t support such characters, your users may lose a good chunk of their files.

You’ll want to make sure that your text extraction can handle UTF-8 encoding and various character sets.

Best Practices

Below are some best practices to adopt when building your own custom PDF parser:

1. Validate incoming files before processing:

function validatePDFFile(pdfFile: UploadedFile): { valid: boolean; error?: string } {
  // Check MIME type
  if (pdfFile.mimetype !== "application/pdf") {
    return { valid: false, error: "Invalid MIME type. Expected application/pdf" };
  }

  // Check file size (already limited by middleware, but double-check)
  const maxSize = 50 * 1024 * 1024; // 50 MB
  if (pdfFile.size > maxSize) {
    return { valid: false, error: "File exceeds maximum size of 50 MB" };
  }

  // Check for empty file
  if (pdfFile.size === 0) {
    return { valid: false, error: "File is empty" };
  }

  // Check file signature (PDF magic bytes)
  const data = new Uint8Array(pdfFile.data as ArrayBuffer);
  const header = String.fromCharCode(...data.slice(0, 4));
  if (header !== "%PDF") {
    return { valid: false, error: "Invalid PDF file format" };
  }

  return { valid: true };
}

2. Implement request timeouts to avoid server hangs

// Set timeout for long-running PDF operations
const parseWithTimeout = (file: Uint8Array, timeoutMs = 30000) => {
  return Promise.race([
    parsePDF(file),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error("PDF parsing timeout")), timeoutMs)
    ),
  ]);
};

3. Implement rate limiting to avoid abuse. You can use the express-rate-limit library to apply rate limiting to your Express apps.

import rateLimit from 'express-rate-limit';

const app = express();

// Create the rate limiting middleware
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Limit each IP to 100 requests per `windowMs`
  message:
    'Too many requests from this IP, please try again after 15 minutes',
  standardHeaders: true, // Enable standard RateLimit headers (draft-7)
  legacyHeaders: false, // Disable legacy X-RateLimit-* headers
});

// Apply the rate limiting middleware to all requests
app.use(limiter);

4. Sanitize each keyword or search query to avoid injection attacks.

Unit Testing Your PDF Parser

Testing is critical when building PDF processing tools, as real-world PDFs vary widely in structure, encoding, and complexity. Jest provides an excellent framework for testing Express endpoints and ensuring your extraction logic works reliably across different scenarios.

Setting Up Jest Tests

The test suite I've created uses Jest with Supertest (an HTTP assertion library) to simulate requests to your API endpoints without running a server.

To start, install Jest, Supertest, and their types:

npm install --save-dev jest @types/jest supertest @types/supertest ts-jest

Then update your package.json to include Jest configuration:

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch"
  },
  "jest": {
    "preset": "ts-jest",
    "testEnvironment": "node",
    "extensionsToTreatAsEsm": [".ts"],
    "moduleNameMapper": {
      "^(\\.{1,2}/.*)\\.js$": "$1"
    },
    "transform": {
      "^.+\\.tsx?$": [
        "ts-jest",
        {
          "useESM": true,
          "tsconfig": {
            "module": "esnext"
          }
        }
      ]
    }
  }
}

Understanding the Test Structure

The test file includes comprehensive coverage for all your endpoints. For example, the /upload-page-range endpoint tests verify both happy paths and error handling:

describe("POST /upload-page-range", () => {
  it("should return error when no file is provided", async () => {
    const response = await request(app)
      .post("/upload-page-range")
      .query({ startPage: 1, endPage: 2 });
    expect(response.status).toBe(400);
    expect(response.body.error).toBe("No PDF file shared.");
  });

  it("should return error for invalid page range", async () => {
    const mockPdfBuffer = Buffer.from("%PDF-1.4 mock pdf");
    const response = await request(app)
      .post("/upload-page-range")
      .query({ startPage: "invalid", endPage: 2 })
      .attach("file", mockPdfBuffer, "test.pdf");

    expect(response.status).toBe(400);
    expect(response.body.error).toContain("valid integers");
  });

  it("should extract text from page range", async () => {
    const mockPdfBuffer = Buffer.from("%PDF-1.4 mock pdf");
    const response = await request(app)
      .post("/upload-page-range")
      .query({ startPage: 1, endPage: 2 })
      .attach("file", mockPdfBuffer, "test.pdf");

    expect(response.status).toBe(200);
    expect(response.body.success).toBe(true);
    expect(response.body.result.startPage).toBe(1);
    expect(response.body.result.endPage).toBe(2);
  });
});

Notice how the tests mock the PDFParse library rather than requiring actual PDF files. This approach makes tests:

• Fast: No disk I/O, tests run in milliseconds

• Reliable: No dependency on external files that might change

• Focused: Each test verifies specific behavior, not file handling

The mock returns consistent data for all test cases, allowing you to verify your endpoint logic, handle responses correctly, validate parameters properly, and return appropriate error messages.

Running Tests

Execute your test suite with:

# Run tests once
npm test

# Run tests in watch mode for development
npm run test:watch

# Generate coverage report
npm test -- --coverage

A successful test run confirms that all endpoints, /upload, /metadata, /search, and /upload-page-range, handle valid requests, reject invalid inputs, and return data in the expected format.

Deploying Your PDF Parser API

Once your tests pass, you're ready to deploy your Express app. The deployment process depends on your hosting platform, but here are the essentials:

Running Locally

Start your development server with:

npm run dev

This runs the server from server.ts using ts-node and Nodemon. The API will be available at http://localhost:8080.

Test your endpoints with curl:

# Test the health check
curl http://localhost:8080/

# Upload and parse a PDF
curl -F "file=@sample.pdf" http://localhost:8080/upload

# Extract specific pages
curl -F "file=@sample.pdf" "http://localhost:8080/upload-page-range?startPage=1&endPage=5"

# Search for text
curl -F "file=@sample.pdf" "http://localhost:8080/search?query=invoice"

# Get metadata only
curl -F "file=@sample.pdf" http://localhost:8080/metadata

Production Deployment

Before deploying to production, build your TypeScript:

npm run build

Then start the compiled server:

npm start

For cloud platforms like Heroku, AWS, or DigitalOcean, ensure your environment variables are set (particularly the PORT variable). The API is designed to scale horizontally, since it doesn't maintain state. Each request processes independently.

Consider adding these production improvements:

• Rate limiting: Prevent abuse with express-rate-limit

• Logging: Use Winston or Pino for structured logging

• Monitoring: Set up error tracking with Sentry or similar services

• Database: Store extraction results in MongoDB or PostgreSQL for historical access

• Caching: Cache metadata for frequently accessed PDFs to reduce processing overhead

Next Steps: Integrate Into Your SaaS

This PDF parser is now a production-ready API that you can integrate into any SaaS platform needing document processing capabilities. Here's how to get started:

Fork the repository and customize it for your use case. Add features like:

• Support for additional document formats (DOCX, XLSX, images)

• Batch processing endpoints for handling multiple files

• Webhook support for asynchronous processing

• User authentication and per-user quotas

• Advanced text extraction options (tables, forms, structured data)

Conclusion

Building a production-ready PDF parser gives you complete control over document processing while maintaining modularity for future extensions.

You've learned to build an Express API that handles full extraction, page ranges, text search, and metadata retrieval – all with robust error handling and validation patterns that apply to any document processing tool.

This tested, deployable foundation is ready to scale in real applications, whether you're building a SaaS product or adding PDF capabilities to existing systems.

As you integrate these patterns into your projects, consider exploring advanced libraries like pdfjs-dist or pdf-lib while applying the same validation and modular design principles you've mastered here.

Resources

• GitHub repo

Traditionally, writing Redux logic required a lot of boilerplate code, configuration, and dependency installations. This made Redux difficult to work with. RTK was created to solve these issues. RTK contains utilities that simplify common Redux tasks such as store configuration, creation of reducers, and immutable state update logic.

Redux Toolkit Query (RTK Query) is an optional add-on included in the Redux ToolKit package. It was created to simplify data fetching and caching in web applications. RTK Query is built on top of Redux Toolkit and employs Redux for its internal architectural design.

In this article, you'll learn how to integrate RTK Query with Redux Toolkit in your React applications by building a simple CRUD Movie app.

Table of Contents

1. Prerequisites

2. Understanding RTK Query and core concepts

3. Integrating RTK Query with Redux Toolkit

4. Handling Data Caching with RTK Query

5. Error Handling and Loading States

6. Best Practices

7. Conclusion

Prerequisites

For this article, I assume that you are familiar with React.

Understanding RTK Query and Core Concepts

At the core of RTK Query is the createApi function. This function allows you to define an API slice, which includes the server's base URL and a set of endpoints that describe how to fetch and mutate data from the server.

RTK Query automatically generates a custom hook for each of the defined endpoints. These custom hooks can be used in your React component to conditionally render content based on the state of the API request.

The code below shows how to create an API slice using the createApi function:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

export const apiSlice = createApi({
    reducerPath: 'api',
    baseQuery: fetchBaseQuery({ baseUrl: 'https://server.co/api/v1/'}),
    endpoints: (builder) => ({
        getData: builder.query({
            query: () => '/data',
        })
    })
})

export const { useGetDataQuery } = apiSlice;

fetchBaseQuery is a lightweight wrapper around the native JavaScript fetch function that simplifies API requests. The reducerPath property specifies the directory where your API slice is stored. A common convention is to name the directory api. The baseQuery property uses the fetchBaseQuery function to specify the base URL of your server. You can think of it as the root URL in which your endpoints are appended.

useGetDataQuery is an auto-generated hook that you can use in your components.

How to Integrate RTK Query with Redux Toolkit

In this section, you will learn how to integrate RTK Query with Redux Toolkit by building a simple Movie app. In this app, users will be able to view movies stored in your backend (though it's a mock backend), add movies, and update and delete any movie. In essence, you will build a CRUD app using RTK Query.

Also, I will be using TypeScript for this tutorial. If you're using JavaScript, skip the type annotations and/or interfaces and replace .tsx/.ts with .jsx/.js.

Setting up the development environment

Create a new React project using the following command:

npm create vite@latest

Follow the prompts to create your React app.

Install the react-redux and @reduxjs/toolkit packages using the following command:

# npm
npm install @reduxjs/toolkit react-redux

# yarn
yarn add @reduxjs/toolkit react-redux

For the backend, you're going to use json-server. json-server is a light-weight Node.js tool that simulates a RESTful API using JSON files as the data source. It lets frontend developers create mock APIs without writing any server-side code.

You can read more about json-server here.

Use the following command to install json-server:

npm install -g json-server

Folder structure

In the root directory of your application, create a data folder. Inside this folder, create a db.json file. This will be where your "backend" is stored.

In the src directory, create two folders: component and state.

Inside the component folder, create two folders: CardComponent and Modal, and a file:Movies.tsx.

Inside the state folder, create a movies folder and a file: store.ts.

After creating the folders and files, your app structure should look like this:

Building the app

First, you're going to set up your JSON server.

Open the db.json file and paste in the following code:

{
  "movies": [
    {
      "title": "John Wick",
      "description": "Retired assassin John Wick is pulled back into the criminal underworld when gangsters kill his beloved dog, a gift from his late wife. With his unmatched combat skills and a thirst for vengeance, Wick single-handedly takes on an entire criminal syndicate.",
      "year": 2014,
      "thumbnail": "https://m.media-amazon.com/images/M/MV5BNTBmNWFjMWUtYWI5Ni00NGI2LWFjN2YtNDE2ODM1NTc5NGJlXkEyXkFqcGc@._V1_.jpg",
      "id": "2"
    },
    {
      "id": "3",
      "title": "The Dark Knight",
      "year": 2008,
      "description": "Batman faces off against his archenemy, the Joker, a criminal mastermind who plunges Gotham City into chaos. As the Joker tests Batman’s limits, the hero must confront his own ethical dilemmas to save the city from destruction.",
      "thumbnail": "https://m.media-amazon.com/images/M/MV5BMTMxNTMwODM0NF5BMl5BanBnXkFtZTcwODAyMTk2Mw@@._V1_FMjpg_UX1000_.jpg"
    },
    {
      "title": "Die Hard",
      "description": "NYPD officer John McClane finds himself in a deadly hostage situation when a group of terrorists takes control of a Los Angeles skyscraper during a Christmas party. Armed only with his wit and a handgun, McClane must outsmart the heavily armed intruders to save his wife and others.",
      "year": 1988,
      "thumbnail": "https://m.media-amazon.com/images/M/MV5BMGNlYmM1NmQtYWExMS00NmRjLTg5ZmEtMmYyYzJkMzljYWMxXkEyXkFqcGc@._V1_.jpg",
      "id": "4"
    },
    {
      "title": "Mission: Impossible – Fallout",
      "description": "Ethan Hunt and his IMF team must track down stolen plutonium while being hunted by assassins and former allies. With incredible stunts and non-stop action sequences, Hunt races against time to prevent a global catastrophe.",
      "year": 2018,
      "thumbnail": "https://m.media-amazon.com/images/M/MV5BMTk3NDY5MTU0NV5BMl5BanBnXkFtZTgwNDI3MDE1NTM@._V1_.jpg",
      "id": "5"
    },
    {
      "title": "Gladiator",
      "description": "Betrayed by the Emperor’s son and left for dead, former Roman General Maximus rises as a gladiator to seek vengeance and restore honor to his family. His journey from slavery to becoming a champion captures the hearts of Rome’s citizens.",
      "year": 2010,
      "thumbnail": "https://m.media-amazon.com/images/M/MV5BZmExODVmMjItNzFlZC00MDA0LWJkYjctMmQ0ZTNkYTcwYTMyXkEyXkFqcGc@._V1_.jpg",
      "id": "6"
    }
  ]
}

Start up your JSON server using the following command:

json-server --watch data\db.json --port 8080

This command will start up your JSON server and wrap the API endpoint running on port 8080. Your terminal should look like this:

Next, you are going to create an API slice. This API slice will be used to configure your Redux store.

Navigate to the movies folder and create a movieApiSlice.ts file. Open themovieApiSlice.ts file and paste in the following code:

import { createApi, fetchBaseQuery } from "@reduxjs/toolkit/query/react";

export const moviesApiSlice = createApi({
  reducerPath: "movies",
  baseQuery: fetchBaseQuery({
    baseUrl: "http://localhost:8080",
  }),
  endpoints: (builder) => {
    return {
      getMovies: builder.query({
        query: () => `/movies`,
      }),

      addMovie: builder.mutation({
        query: (movie) => ({
          url: "/movies",
          method: "POST",
          body: movie,
        }),
      }),

      updateMovie: builder.mutation({
        query: (movie) => {
          const { id, ...body } = movie;
          return {
            url: `movies/${id}`,
            method: "PUT",
            body
          }
        },
      }),

      deleteMovie: builder.mutation({
        query: ({id}) => ({
          url: `/movies/${id}`,
          method: "DELETE",
          body: id,
        }),
      }),
    };
  },
});

export const {
  useGetMoviesQuery,
  useAddMovieMutation,
  useDeleteMovieMutation,
  useUpdateMovieMutation,
} = moviesApiSlice;

In the code above, you created a movieApiSlice using the createApi function from RTK Query, which takes in an object as a parameter.

The reducerPath property specifies the path of the API slice.

The baseQuery uses the fetchBaseQuery. The fetchBaseQuery function takes in an object as a parameter, which has a baseURL property. The baseURL property specifies the root URL of our API.

In this case, you are using http://localhost:8080, which is the URL of the JSON server.

The endpoints property is what your API interacts with. It’s a function that takes in a builder parameter and returns an object with methods (getMovies, addMovie, updateMovie, and deleteMovie) for interacting with your API.

Lastly, you are exporting custom hooks generated automatically by RTK Query. The custom hook starts with "use" and ends with "query" and is named based on the methods defined in the endpoints property.

These custom hooks let you interact with the API from your functional components.

Next, you are going to set up your Redux store. Navigate to the store.ts file located in the state folder and paste in the following code:

import { configureStore } from "@reduxjs/toolkit";
import { moviesApiSlice } from "./movies/moviesApiSlice";

export const store = configureStore({
    reducer: {
        [moviesApiSlice.reducerPath]: moviesApiSlice.reducer,
    },
    middleware: (getDefaultMiddleware) => {
        return getDefaultMiddleware().concat(moviesApiSlice.middleware);
    }
})

In the code above, you are setting up a Redux store using the configureStore function from Redux Toolkit. The reducer property specifies a reducer for updating the state in the Redux store. The moviesApiSlice.reducer is the reducer for updating the state of your API.

For the middleware property, you are creating a middleware for handling asynchronous state updates. You don't have to worry too much about this part and what it does. This is required for all the caching functionality and all the other benefits that RTK Query provides.

Before we move further, you have to add your Redux store to your application. To do this, navigate to your main.tsx or index.tsx file (depending on what it is called in your application) and replace the code with the following code:

// main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.tsx";
import { Provider } from "react-redux";
import { store } from "./state/store.ts";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <Provider store={store}>
      <App />
    </Provider>
  </StrictMode>
);

In the code above, you are importing the Provider component from react-redux and the store you created earlier. Also, you are wrapping the Provider component around your App component. The store prop is used to pass your Redux store to your application.

Building the Movie component

In this section, you're going to build out the Movies.tsx component, which is where all of your application logic lives.

Navigate to your Movies.tsx file and paste in the following code:

import "../movie.css";
import { ChangeEvent, FormEvent, useState } from "react";

import {
  useGetMoviesQuery,
  useAddMovieMutation,
  useDeleteMovieMutation,
} from "../state/movies/moviesApiSlice";
import MovieCard from "./CardComponent/MovieCard";

export interface Movie {
  title: string;
  description: string;
  year: number;
  thumbnail: string;
  id: string;
}


export default function Movies() {
  // Form input states
  const [title, setTitle] = useState<string>("");
  const [year, setYear] = useState<string>("");
  const [thumbnail, setThumbnail] = useState<string>("");
  const [description, setDescription] = useState<string>("");

  const { data: movies = [], isLoading, isError } = useGetMoviesQuery({});

  const [ addMovie ] = useAddMovieMutation();
  const [ deleteMovie ] = useDeleteMovieMutation();

  // Handle form submission to add a new movie
  const handleSubmit = (e: FormEvent<HTMLFormElement>): void => {
    e.preventDefault();
    console.log("New movie submitted:", { title, thumbnail, description, year });
    addMovie({ title, description, year: Number(year), thumbnail, id: String(movies.length + 1) })
    // Reset form inputs after submission
    setTitle("");
    setThumbnail("");
    setDescription("");
    setYear("");
  };

  if (isError) {
    return <div>Error</div>;
  }

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div className="movie-container">
      <h2>Movies to Watch</h2>

      {/* Form to add a new movie */}
      <div className="new-movie-form">
        <form onSubmit={handleSubmit}>
          <div className="form-group">
            <label htmlFor="title">Title</label>
            <input
              type="text"
              name="title"
              id="title"
              placeholder="Enter movie title"
              value={title}
              onChange={(e: ChangeEvent<HTMLInputElement>) => setTitle(e.target.value)}
              required
            />
          </div>

          <div className="form-group">
            <label htmlFor="imageAddress">Image Link:</label>
            <input
              type="text"
              name="imageAddress"
              id="imageAddress"
              placeholder="Enter image link address"
              value={thumbnail}
              onChange={(e: ChangeEvent<HTMLInputElement>) => setThumbnail(e.target.value)}
              required
            />
          </div>

          <div className="form-group">
            <label htmlFor="year">Year of release:</label>
            <input
              type="text"
              name="year"
              id="year"
              placeholder="Enter year of release"
              value={year}
              onChange={(e: ChangeEvent<HTMLInputElement>) => setYear(e.target.value)}
            />
          </div>

          <div className="form-group">
            <label htmlFor="description">Description</label>
            <textarea
              name="description"
              id="description"
              placeholder="Enter movie description"
              value={description}
              onChange={(e: ChangeEvent<HTMLTextAreaElement>) => setDescription(e.target.value)}
              required
            ></textarea>
          </div>

          <button type="submit">Add Movie</button>
        </form>
      </div>

      {/* Render list of movies */}
      <div className="movie-list">
        {movies.length === 0 ? (
          <p>No movies added yet.</p>
        ) : (
          movies.map((movie: Movie) => (
            <div key={movie.id}>
              <MovieCard movie={movie} deleteMovie={deleteMovie} />
            </div>
          ))
        )}
      </div>
    </div>
  );
}

In the code above, you're creating a Movies component and using RTK Query to handle CRUD operations.

Let's go step-by-step through what each part of the code does.

In the top part, you imported the useGetMoviesQuery, useAddMovieMutation, and useDeleteMovie functions from the moviesApiSlice you created earlier. The functions will be used for fetching, adding, and deleting movies, respectively.

You also imported a MovieCard component, which you'll use to display each movie. You'll create the MovieCard component in a second.

The Movie interface defines the shape of each movie object. It ensures consistency in the structure of movie data across the component. Again, ignore if you're using JavaScript.

You defined some state variables: title, year, thumbnail, and description to store form input values.

The useGetMoviesQuery hook fetches the movie data when the component mounts. The hook returns an object with several properties, but we're focusing on three properties: data aliased as movies, isLoading, and isError.

The useAddMovieMutation and useDeleteMovieMutation hooks return two functions: addMovie and deleteMovie, respectively.

The handleSubmit function handles the submission of the form. When the form is submitted, the addMovie function is called with the new movie details. The year is converted to a number, and the id is generated based on the current length of the movie array.

If an error occurs while fetching the movies (isError), a simple error message is displayed.

If the API request is still loading (isLoading), a loading message is shown.

If everything goes well, the main JSX structure of the component is returned, which includes:

• a form for adding new movies.

• a list of movies rendered using the MovieCard component. EachMovieCard is passed the individual movie data along with the deleteMovie function to handle deletions.

Now, let's create our MovieCard component.

Inside the CardComponent folder, create a MovieCard.tsx file. Open the MovieCard.tsx and paste in the following code:

import { useRef, useState } from "react";
import EditModal from "../Modal/EditModal";
import { Movie } from "../Movies";

type DeleteMovie = (movie:{id:string}) => void;

interface MovieCardProps {
  movie: Movie;
  deleteMovie: DeleteMovie;
}

function MovieCard({ movie, deleteMovie }: MovieCardProps) {

  const dialogRef = useRef<HTMLDialogElement | null>(null);
  const [selectedMovie, setSelectedMovie] = useState<Movie>(movie);

  const handleSelectedMovie = () => {
    setSelectedMovie(movie);
    dialogRef.current?.showModal();
    document.body.style.overflow = 'hidden';
  }

  const closeDialog = (): void => {
    dialogRef.current?.close();
    document.body.style.overflow = 'visible';
  }

  return (
    <div className="movie-wrapper" key={movie.id}>
      <div className="img-wrapper">
        <img src={movie.thumbnail} alt={`${movie.title} poster`} />
      </div>
      <h3>
        {movie.title} ({movie.year})
      </h3>
      <p>{movie.description}</p>
      <div className="button-wrapper">
        <button onClick={handleSelectedMovie}>Edit</button>
        <button onClick={() => deleteMovie({ id: movie.id })}>Delete</button>
      </div>

      <EditModal dialogRef={dialogRef} selectedMovie={selectedMovie} closeDialog={closeDialog} />

    </div>
  );
}

export default MovieCard;

In the code above, you're creating a MovieCard component for displaying the movies on the screen.

You're importing the useRef and useState hooks from React to manage the component’s state and references. You also import the EditModal component, which will handle editing the movie details, and theMovie type to enforce the shape of the movie object (this is for TypeScript).

The MovieCard component accepts two props: movie and deleteMovie.

The dialogRef variable is used to manage the reference to the modal dialog element.

The selectedMovie state is initialized with the movie prop. This will be used to track the currently selected movie for editing purposes.

The handleSelectedMovie function is called when the Edit button is clicked. It does the following:

• Sets selectedMovie to the current movie object.

• Opens the EditModal dialog using dialogRef.current?.showModal().

• Prevents the page from scrolling while the modal is open by setting document.body.style.overflow to 'hidden'.

The closeDialog function closes the modal dialog using dialogRef.current?.close() and resets the page’s scroll behavior by setting document.body.style.overflow back to 'visible'.

In the return statement, a JSX structure is returned that displays:

• an image for the movie's thumbnail,

• the movie's title and year of release in an h3 element,

• a short description of the movie,

• two buttons:

  • The "Edit" button triggers the handleSelectedMovie function to open the EditModal.

  • The "Delete" button calls the deleteMovie function, passing the movie’s queryID to delete the specified movie from your API.

The EditModal component is also rendered, passing dialogRef, closeDialog, and selectedMovie as props. This ensures that the EditModal has access to the selected movie's details and a function to close itself.

Next up, you're going to create the EditModal component.

Inside the Modal folder, create a file: EditModal.tsx, that will house the modal component.

Open the EditModal.tsx file and paste in the following code:

import { useUpdateMovieMutation } from "../../state/movies/moviesApiSlice";
import { Movie } from "../Movies";
import "./modal.css";
import { useState, RefObject, FormEvent } from "react";

interface EditModalProps {
  dialogRef: RefObject<HTMLDialogElement>;
  selectedMovie: Movie;
  closeDialog: () => void;
}

function EditModal({ dialogRef, selectedMovie, closeDialog }: EditModalProps) {
  const [title, setTitle] = useState<string>(selectedMovie.title);
  const [year, setYear] = useState<string | number>(selectedMovie.year);
  const [description, setDescription] = useState<string>(selectedMovie.description);
  const [thumbnail, setThumbnail] = useState<string>(selectedMovie.thumbnail);

  const [updateMovie] = useUpdateMovieMutation();

  async function handleUpdateMovie(e: FormEvent<HTMLFormElement>){
    e.preventDefault();
    try {
      await updateMovie({title, description, year: Number(year), thumbnail, id: selectedMovie.id});
      closeDialog();
    } catch (error) {
      alert(`${error} occurred`);
    }
  }

  return (
    <dialog ref={dialogRef} className="modal-dialog">
      <form onSubmit={handleUpdateMovie}>
        <div className="form-group">
          <label htmlFor="title">Title:</label>
          <input
            type="text"
            id="title"
            value={title}
            onChange={(e) => setTitle(e.target.value)}
          />
        </div>

        <div className="form-group">
          <label htmlFor="year">Year of release:</label>
          <input
            type="text"
            id="year"
            value={year}
            onChange={(e) => setYear(e.target.value)}
          />
        </div>

        <div className="form-group">
          <label htmlFor="thumbnail">Image URL:</label>
          <input
            type="text"
            id="thumbnail"
            value={thumbnail}
            onChange={(e) => setThumbnail(e.target.value)}
          />
        </div>

        <div className="form-group">
          <label htmlFor="description">Description:</label>
          <textarea
            id="description"
            value={description}
            onChange={(e) => setDescription(e.target.value)}
          ></textarea>
        </div>
        <button type="submit">Save</button>
      </form>
      <button className="close-btn" onClick={closeDialog}>
        Close
      </button>
    </dialog>
  );
}

export default EditModal;

In the code above, you're simply creating a modal dialog using the native HTML <dialog> element. Inside the dialog element is a form field populated with the details of the selected movie, obtained from the state variables: title, year, description, and thumbnail.

You imported the useUpdateMovieMutation hook from your moviesApiSlice. The useUpdateMovieMutation hook returns an updateMovie function you can use to update movie details.

The handleUpdateMovie is called when the Save button is clicked. It does the following:

• updates the movie details by calling the updateMovie function

• closes the dialog using the closeDialog function

Mounting our component

Navigate to your App.tsx file and add in your Movies component the following code:

import "./App.css";
import Movies from "./components/Movies";

function App() {
  return (
    <div>
      <Movies />
    </div>
  );
}

export default App;

In your browser, open your localhost and you should see something like this:

Congratulations! You've successfully integrated RTK Query with the Redux Toolkit.

In the next section, you'll learn how caching in RTK Query works and how to invalidate caches.

How to Handle Data Caching with RTK Query

In this section, you'll learn how caching works in RTK Query and how to invalidate caches.

In programming, caching is one of the hardest things to do. But RTK Query makes handling caching easier for us.

When you call your API, RTK Query automatically caches the result of successfully calling your API. This means that subsequent calls to the API return the cached result.

For example, if you try editing any movie in your app, you'll notice that nothing changes. This doesn't mean that it's not working – in fact, it is working. And the results returned are the cached version (the results when you first called the API, that is on component mount).

To stop this behaviour, you need to invalidate the cache each time you make changes to your backend. This will cause RTK Query to automatically refetch the data to reflect your changes.

Navigate to your moviesApiSlice.ts file and replace that code with the following code:

import { createApi, fetchBaseQuery } from "@reduxjs/toolkit/query/react";

export const moviesApiSlice = createApi({
  reducerPath: "movies",
  baseQuery: fetchBaseQuery({
    baseUrl: "http://localhost:8080",
  }),
  tagTypes: ['Movies'],
  endpoints: (builder) => {
    return {
      getMovies: builder.query({
        query: () => `/movies`,
        providesTags: ['Movies']
      }),

      addMovie: builder.mutation({
        query: (movie) => ({
          url: "/movies",
          method: "POST",
          body: movie,
        }),
        invalidatesTags: ['Movies']
      }),

      updateMovie: builder.mutation({
        query: (movie) => {
          const { id, ...body } = movie;
          return {
            url: `movies/${id}`,
            method: "PUT",
            body
          }
        },
        invalidatesTags: ['Movies']
      }),

      deleteMovie: builder.mutation({
        query: ({id}) => ({
          url: `/movies/${id}`,
          method: "DELETE",
          body: id,
        }),
        invalidatesTags: ['Movies']
      }),
    };
  },
});

export const {
  useGetMoviesQuery,
  useAddMovieMutation,
  useDeleteMovieMutation,
  useUpdateMovieMutation,
} = moviesApiSlice;

In the code above, you added the tagTypes property to your moviesApiSlice and set it to[Movies]. This will be used to invalidate the cached results when you make changes to your backend.

In the getMovies function, you added the providesTags property. This means that you're providing a tag to your API call, which you can invalidate with the mutation functions.

In the mutation functions (addMovie, updateMovie, and deleteMovie), you added the invalidatesTags property set to the value of the tagTypes property. This invalidates the cache whenever each of these mutation functions are called, which causes RTK Query to automatically refetch the data.

With these changes, you can update and delete movies and see the result of your changes.

Error Handling and Loading States

When you were building your app, you handled any errors that might arise from calling your API by simply displaying a "Error..." text.

In real-world applications, you want to display something meaningful, such as a UI that tells your users what went wrong exactly.

Similarly, when your API request is loading, you want to display a loading spinner or a loading skeleton UI so that your users know that your app data is loading.

For the purposes of this article, we are not going to dive into advanced error handling or managing loading states – but these would be things you’d want to look into.

Best Practices

Below are some of the best practices to consider when working with RTK Query:

1. Separate multiple API slices: if you have multiple API slices for different APIs, consider separating them into different API slices. This keeps your API slices modular, making it easier to maintain and debug.

2. Use the Redux Devtools: the Redux Devtools let you get an inside look at what is going on in your Redux store as well as your queries and mutations. This makes debugging much easier. The Redux Devtools are available as a Chrome extension.

3. Prefetch data: use the usePrefetch hook to make a data fetch before a user navigates to a page on your website or loads some known content. This reduces load time and makes the UI feel faster.

4. Use middleware for complex logic: implement middleware when you need to intercept and modify actions or responses, such as adding authentication tokens to headers or logging specific errors.

5. Use optimistic updates: when using useMutation to update or change existing data, you can implement an optimistic update to the UI. This helps to give the impression of immediate changes. If the request fails, you can roll back the update.

Conclusion

In this article, you learned what RTK Query is and how to integrate RTK Query with Redux Toolkit by building a CRUD React Movie app. You also learned about the caching strategies of RTK Query and how to invalidate the caches.

Thanks for reading!

In this article, you will learn how to handle forms in Next.js using server actions and zod.

Table of Contents

• Introduction to Server Actions in Next.js

• Introduction to zod for Validation

• How to Build the Contact Form Component

• How to Create the Server Actions and Validate the Form Data with zod

• How to Integrate the Server Action into Our Contact Form

• Conclusion

Prerequisites and Setting Up the Project

For this tutorial, I assume that you know JavaScript and how to set up a Next.js project (I'm not going to walk through that set up here).

If you haven’t yet set up your Next.js project, use the following command and follow the prompts:

npx create-next-app

This is what we are going to build in this tutorial:

Note: this tutorial mainly focuses on the logic and not the design. For the complete design, you can visit the GitHub repository which I’ve linked to at the end.

Introduction to Server Actions in Next.js

So what are server actions? Server actions are pretty much what they sound like—actions or functions that run on the server. With server actions, you can make calls to external APIs or fetch data from a database.

Prior to Next.js 13, you had to use routes to handle API calls and form submissions. This was complex and cumbersome.

But the introduction of server actions lets you communicate with external APIs and databases directly in your Next.js components.

By running on the server, server actions enable secure handling of data processing, mitigating security risks.

Server actions are also useful in handling forms as they let you communicate directly with your server and limit the exposure of important credentials to the client.

There are two ways to create server actions:

• The first method is using the "use server" directive at the top level of a function. You can only use this method inside a server component. Using it inside a client component will result in an error.

For example:

async function getPosts() {
  "use server"; // this makes getPosts a server actions

  // rest of code
}

• The other method is to create a separate file and add "use server" at the top of the file. This ensures that any async function exported from the file is a server action.

// action.ts

"use server";

export async function getPosts() {
  const res = await fetch("https:...");
  const data = res.json();

  return data;
}

In the code example above, getPosts is a server action.

Introduction to Zod for Validation

Zod is a validation library that you can use to validate form entries on the server side. This ensures consistency across both the client and server.

Zod is a TypeScript-first library, which means that it comes with type safety out of the box.

To install Zod in your Next.js application, use the following command:

npm install zod

At the core of the Zod library are schemas. You can use schemas to validate inputs.

Here's how to define a schema:

import { z } from "zod";

const contactSchema = z.object({
  name: z.string().min(2, { message: "Name must be at least 2 characters" }),
  email: z.string().email({ message: "Invalid email address" }),
  message: z
    .string()
    .min(10, { message: "Message must be at least 10 characters" }),
});

Inside the contactSchema, we are specifying that:

• name is of type string and should be a minimum of 2 characters,

• email is of type string and email, and

• message is of type string and should be a minimum of 10 characters.

The message property is what will be displayed on the screen when all or any of the validation fails.

In the next section, we are going to build the contact form.

How to Build the Contact Form Component

In this section, we are going to build the UI of the contact form.

Inside the app directory, create a folder called "components."

Inside of the components folder, create a new file, contactForm.tsx, and add the following code:

"use client";

function ContactForm() {
  return (
    <form action="">
      <input type="text" name="name" placeholder="Enter your name" />
      <input type="email" name="email" placeholder="Enter your email" />
      <textarea name="message" cols={30} rows={10} placeholder="Type in your message"></textarea>
      <button type="submit">Send Message</button>
    </form>
  );
}

export default ContactForm;

In the code above, we are creating a simple contact form. We made it a client component – you’ll see why in a bit.

Import the ContactForm component in your page.tsx file:

import ContactForm from "./components/contactForm.tsx";

function Home() {
  return (
    <div>
      <h2>Contact Form</h2>
      <ContactForm />
    </div>
  );
}

You should have something like this:

Next, we are going to validate our form data using zod.

How to Create the Server Actions and Validate the Form Data with zod

In this section, we are going to create our server action and validate our form entries with zod.

In the app folder, create another folder, api.

Inside the api folder, create a file called action.ts and paste in the following code:

"use server";

import { z } from "zod";

const contactFormSchema = z.object({
  name: z.string().trim().min(1, { message: "Name field is required" }),
  email: z.string().email({ message: "Invalid email address" }),
  message: z.string().trim().min(1, { message: "Please type in a message" }),
});

export async function sendEmail(prevState: any, formData: FormData) {
  const contactFormData = Object.fromEntries(formData);
  const validatedContactFormData = contactFormSchema.safeParse(contactFormData);


  if (!validatedContactFormData.success) {
    const formFieldErrors =
      validatedContactFormData.error.flatten().fieldErrors;

    return {
      errors: {
        name: formFieldErrors?.name,
        email: formFieldErrors?.email,
        message: formFieldErrors?.message,
      },
    };
  }

  return {
    success: "Your message was sent successfully!",
  };
}

In the code above, we defined a contactFormSchema for validating our form entries.

The sendEmail function (which is our server action) accepts two arguments:

• prevState which will be used in to display our error and success messages, and

• formData which is the entries from our form

FormData makes it possible for our function to have access to the form fields without using useState and it relies on the name attribute.

We are using Object.fromEntries() to convert the raw formData into a regular JavaScript object and we’re storing it in the contactFormData variable.

Next, we are validating the contactFormData using the safeParse() method of our zod schema, contactFormSchema.

As a good programming practice, we return early by checking if the validation fails. If the validation fails, we return an object with an error property, which is an object containing the error message of each form field.

formFieldsError is assigned the value of the error object from zod, which contains the error message of each form field.

If everything goes well, we simply return an object with a success property.

Note: this is where you send the message to your email using any email service provider of your choice. For the sake of the article, we are simply returning an object.

In the next section, we are going to integrate the server action in our contact form.

How to Integrate the Server Action into Our Contact Form

In this section, we are going to integrate the server action into our contact form.

Navigate to the contactForm.tsx file and replace the content with the following code:

"use client";

import { useFormState, useFormStatus } from "react-dom";
import { sendEmail } from "../api/action";

const initialState = {
  success: "",
  errors: {
    name: "",
    email: "",
    message: "",
  }
};

function ContactForm() {
  const [state, formAction] = useFormState(sendEmail, initialState);

  return (
    <div>
      <div className="py-6">
        <form action={formAction}>
          <div className="mb-4">
            <label htmlFor="name">Your name</label>
            <br />
            <input
              type="text"
              name="name"
              id="name"
              // required
              className="border w-full md:w-3/4 py-2 pl-2 rounded-lg rounded-l-lg block md:inline focus:outline-slate-500 border-gray-500"
              placeholder="Enter your name..."
            />
            {state.errors?.name && (
              <p className="text-red-500">{state.errors.name}</p>
            )}
          </div>
          <div className="mb-4">
            <label htmlFor="email">Your email</label>
            <br />
            <input
              type="email"
              name="email"
              id="email"
              // required
              className="border w-full md:w-3/4 py-2 pl-2 rounded-lg rounded-l-lg block md:inline focus:outline-slate-500 border-gray-500"
              placeholder="Enter your email..."
            />
            {state.errors?.email && (
              <p className="text-red-500">{state.errors.email}</p>
            )}
          </div>
          <div>
            <label htmlFor="message">Message</label>
            <br />
            <textarea
              name="message"
              id="message"
              // required
              cols={100}
              rows={10}
              className="border w-full md:w-3/4 py-3 pl-2 rounded-lg focus:outline-slate-500 border-gray-500"
              placeholder="Enter your message..."
            ></textarea>
            {state.errors?.message && (
              <p className="text-red-500">{state.errors.message}</p>
            )}
          </div>
          <SubmitButton />
        </form>
      </div>
      {state?.success && <p className="text-green-600">{state.success}</p>}
    </div>
  );
}

export default ContactForm;

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending ? true : false}
      className="bg-green-600 text-white font-semibold px-3 py-2 rounded-lg"
    >
      {pending ? (
        <span>
          Submitting <RiLoader5Fill className="animate-spin" />
        </span>
      ) : (
        "Submit"
      )}
    </button>
  );
}

In the updated code above, we imported two hooks: useFormState and useFormStatus from "react-dom" and sendEmail from "api/action.ts".

Next, we created a initialState variable to hold our initial state. This will be used in the useFormState hook.

initialState is an object with:

• a success property for the success message of our server action, and

• an errors object, which is equal to the errors object we return in our server action if the validation fails.

Inside our ContactForm component, we are using the useFormState hook. This hook accepts two arguments: a server action and an initial state and returns an array with two values: current state and formAction.

formAction will be passed into the action prop of the form element. This will handle the submission of our form, which incorporates the zod validation.

Below each form field, we conditionally render the error message of each of the form field respectively.

Below the form element, we render the success message if the form was successfully submitted.

The submit button is put into a different component, SubmitButton so we can make use of the useFormStatus hook.

The useFormStatus hook returns an object with a pending property, which we can use to disable the submit button when the form is submitted.

Assuming everything went correctly, you should have a working contact form like this:

Congratulations! You have just created a contact form using server actions and the zod validation library.

Conclusion

In this article, you learned what server actions are and how to use the zod library. You also used server actions and zod to build a contact form.

Server actions are not limited to form submission and can also be used for fetching data from external APIs and databases.

You can learn more with these resources:

• zod documentation

• server action documentation

Here's the GitHub repository of the complete project.

These concepts, though often misunderstood, play a crucial role in determining how variables and functions behave within the code.

Scope dictates the accessibility of variables, closures enable powerful programming patterns, and hoisting can lead to unexpected results if not understood properly.

In this comprehensive guide, we will delve deep into the realms of scope, closures, and hoisting in JavaScript, unraveling their complexities, providing practical examples, and offering best practices to empower you in your journey as a JavaScript developer.

So, buckle up as we embark on this enlightening exploration of JavaScript's dynamic trio.

Table Of Contents

• Prerequisites

• Scope in JavaScript

• Types of scope in JavaScript

• Closures

• Hoisting

  • Variable hoisting

  • Function hoisting

  • Class hoisting

  • Import hoisting

• Best practices

• Conclusion

Prerequisites

You should have a basic understanding of the JavaScript language to follow along with this article.

Scope in JavaScript

In programming, scope refers to the context in which variables and functions are declared and accessed.

Scope determines the visibility and lifecycle of these variables and functions within a program, ensuring that they are used in the intended context.

In JavaScript, scope follows the concept of lexical scope. In lexical scope, the visibility of variables and functions are determined by the context in which the variables and functions are defined.

Types of scope in JavaScript

In JavaScript, there are three main types of scope:

Global scope

Variables and functions defined in the global scope can be accessed by any part of the program. Variables and functions that are declared in the global scope are said to be global-scoped.

let globalScopeVariable = "I'm in the global scope";



function logScope(){

console.log(globalScopeVariable)

}

logScope(); // I'm in the global scope



for(let i=0; i<3; i++){

console.log(globalScopeVariable);

}

// I'm in the global scope

// I'm in the global scope

// I'm in the global scope



if(true){

console.log(globalScopeVariable);

}

// I'm in the global scope



console.log(globalScopeVariable); // "I'm in the global scope"

In the code above, the globalScopeVariable can be accessed by any part of the program, whether it's inside a function, loop, conditional statements, or in the global scope itself.

You can think of global scope as your local supermarket – everyone has access to it.

Note: when building real-world applications, it is recommended to minimize the number of variables that are global-scoped. This is to reduce unpredictability in your code which can lead to bugs.

Function scope

When variables and functions are declared within functions, the variables and functions are in the function scope.

These variables and functions can only be accessed within the function they were declared in.

Variables declared in function scope are said to be function-scoped.

function doubleNum(){

let num = 23;

console.log(num * 2)

}

doubleNum(); // 46



console.log(num); // Reference error: "num" is not defined

In the code above, logging num will result in a Reference error as num can only be accessed within doubleNum function.

You can think of function scope as a message sent to a group chat – only the group participants can view and interact with the message.

Block scope

Curly braces, {}, denote a code block. Variables declared within these curly braces cannot be accessed outside the curly braces.

{

let blockScopedVariable = "I'm block-scoped";

console.log(blockScopedVariable); // I'm block-scoped

}



console.log(blockScopedVariable); // ReferenceError: blockScopedVariable is not defined

In the code above, blockScopedVariable can only be accessed within the curly braces as it was defined inside the curly braces.

Though block scope seems similar with function scope, there's a little difference.

The key difference between block scope and function scope is that function scope refers to variables defined within functions, while block scope refers to variables defined in a pair of curly braces.

You can say that function scope is a subset of block scope.

Note: variables declared within a function using var cannot be accessed outside that function.

function logScope(){

var x = 4;

}

console.log(x); // ReferenceError: x is not defined

Closures

A closure is the combination of a function and its lexical scope. In other words, a closure is a function defined in another function that remembers its lexical environment.

Remembering its lexical environment means that closure function has access to variables declared within the parent function, even after the parent function has finished executing.

function parentFunction(){

let x = 3;

function childFunction(y){

return x + y

}

return childFunction

}



let res = parentFunction();




console.log(res(6));

In the code above, childFunction forms a closure inside parentFunction. childFunction has access to variables defined in the childFunction's lexical environment even after parentFunction has finished executing in let res = parentFunction(). This is why console.log(res(6)) gives 9.

Hoisting

Hoisting in JavaScript refers to the process by which the JavaScript interpreter moves the declaration of variables, functions, classes, and imports to the top of the code before execution.

You can view hoisting as declarations being "lifted" up before code execution.

Variable hoisting

Only variables declared using var are hoisted. This is because var is not block-scoped, meaning that the var-declared variable can be referred to anywhere in its scope regardless of the position of the variable's declaration.

console.log(x); // undefined

var x = 4;

Running the code above will log undefined to the console. This is because only variable declarations are hoisted or 'lifted up' and not the initializations.

Prior to code execution, the code will look like this:

var x;

console.log(x);

x = 4

Tip: var x is the variable declaration. x = 4 is the initialization.

Variables declared with let and const are not hoisted. This means that referring to the variables before declaration results in ReferenceError.

console.log(y); // ReferenceError: Cannot access "y" before initialization

let y = 3;

Function hoisting

Functions are hoisted just like var-declared variables.

console.log(addNums(1,3)); // 4



function addNums(a,b){

return a + b;

}

During execution, the code looks like this:

function addNums(a,b){

return a + b;

}



console.log(addNums(1,3));

However, it's important to know that only function declarations are hoisted. Function expressions are not hoisted.

console.log(addNums(1,3)); // ReferenceError: cannot access "addNums" before initialization



const addNums = function (a,b) {

return a + b;

}

Running the code above will result in a ReferenceError.

Class hoisting

Unlike function declaration, class declarations are not hoisted. This means you cannot accessed a class before its declaration.

new Car(); // ReferenceError: cannot access "Car" before initialization

class Car{}

Import hoisting

Import declarations are hoisted. This means that all methods and functions of an imported value are accessible in another module even before its declaration.

const sum = f.add(2+3);

import f from './library/package'

In the code above, f functions and methods are accessible even though the declaration comes later.

Best practices

Keep scope as local as possible

You should keep your scope local as possible.

When creating variables, you should aim to create the variables where you want to use them. This is especially true if you are going to be using the variables in only one or few parts of your code.

const num = 3;

function addNum(){
    return 2 + num; // 3
}

function multiplyNum(a){
    return 3 * a;
}

In the code above, num is used only once, in the addNum function. It is a better practice to declare num inside of the addNum function.

function addNum(){
    const num = 3;
    return 2 + num;
}

// rest of code

For better modularity, you can pass num as an argument to the addNum function.

function addNum(num){
    return 2 + num
}
addNum(3); //5

Use closures to protect data

In programming, there are times you may want to protect some variables from being accessed from outside of an object. This is where closures can be very useful.

Use closures to protect private data from outside functions and other parts of your code.

function encapsulateData(){
    const user = {
        name: 'Chidera',
        age: 23
    }
    return updateUserAge(){
        return data.age++;
    }
}

const updateHandler = encapsulateData();
const updatedAge = updateHandler(); // 24
console.log(user); // undefined

In the code above, updateAge increases the age of the user without user being accessible from the outside.

Declare variables and functions before using them

It is recommended to always declare variables before using them. This helps to avoid unpredictability and unwanted bugs in your code.

Always use let and const to create variables

let and const are the standard way of declaring variables in JavaScript. They remove the unpredictable code behavior that comes with using var.

There is almost no reason to use var to declare variables in modern JavaScript.

Conclusion

In summary, scopes determine where a variable can be accessed.

Scope can be divided into three: global, local, and block scopes.

Closures are functions inside a function. Closure functions have access to parent function variables, even after the parent function has returned. Closure is a crucial part of asynchronous JavaScript.

Hoisting makes variables accessible even before their creation.

Remember to adhere to best practices when working with closures and hoisting. Declaring variables before usage and using closures to encapsulate data can help to prevent code unpredictability and protect private data.

In this article, you'll learn how to connect your app and fetch data from a third-party API by building a crypto exchange web application in React.

Table of Contents

• Prerequisites

• How to Set Up the Project

  • Initialize a new React project

  • Install the necessary dependencies

  • Set up your project structure

• How to Build the UI

• How to Fetch Data with React Query

• How to Display Data in the UI

• Error Handling

• Conclusion

Prerequisites

This tutorial assumes you have foundational knowledge of React. Also, you should be able to work with Axios, specifically for making API calls.

Also, you will need an API key from RapidAPI to follow along with this tutorial.

How to Set Up the Project

Initialize a new React project

Use the following command to initialize a new React project using Vite: npm create vite@latest

Then follow the prompts that come after.

Vite is a build tool that enables fast reloading of your React apps. For more information on Vite, you can check out their official documentation.

Install the necessary dependencies

For this tutorial, you will need a few packages:

• Axios: a library for making promise-based API calls.

• react-query: a data fetching library that handles caching, loading, and error state of our API call.

• antd (Ant Design): a UI library of pre-built React components.

Use the following command to install these packages: npm install react-query antd axios

Set up your project structure

In this section, you are going to create some folders inside the src folder. This is to keep your app structure clean and easy to work with.

Inside the src folder, create a new folder called components.

Inside of the components folder, create three folders: fetchData, UI, and currencies.

With the project setup out of the way, let's move to building the application.

How to Build the UI

In this section, you are going to create the UI of the app. There will be little to no logic.

Navigate to the UI folder inside the components folder.

Create a new file, ExchangeRateUI.jsx, inside of the UI folder.

Add the following code inside the ExchangeRateUI.jsx file:

import { Typography, Card } from "antd";

export function ExchangeRateUI(props) {
 return (
   <div className="exchange-rate-ui">
     <Card
       extra={3}
       bordered={false}
       style={{ width: 350, backgroundColor: "#4d4add", color: "#fff" }}
       size="default"
     >
       <Typography.Paragraph style={{ color: "#fff" }}>Bitcoin</Typography.Paragraph>
     </Card>
   </div>
 );
}

In the code above, you used the Card and Typography components of the Ant Design UI library to create the UI of our app.

Next, navigate to the currencies folder and create a currencies.jsx file.

Add the following code inside currencies.jsx:

export const cryptocurrencies = [
  { value: "BTC", label: "Bitcoin" },
  { value: "ETH", label: "Ethereum" },
  { value: "BCH", label: "Bitcoin Cash" },
  { value: "XRP", label: "Ripple" },
  { value: "SOL", label: "Solana" },
  { value: "ADA", label: "Cardano" },
  { value: "BNB", label: "Binance Coin" },
];

export const fiatCurrencies = [
  { value: "USD", label: "US Dollar" },
  { value: "GBP", label: "British Pound" },
  { value: "EUR", label: "Euro" },
  { value: "NGN", label: "Naira" },
  { value: "CNY", label: "Chinese Yuan" },
  { value: "RUB", label: "Russian Ruble" },
  { value: "SGD", label: "Singaporean Dollar" },
];

In the code above, you created two arrays, fiatCurrencies and cryptocurrencies, and exported those arrays. They will be used by the Ant Design Select components.

Next, create a file, ExchangeRate.jsx, inside the components folder.

Add the following code inside the ExchangeRate.jsx file:

import { useState } from "react";
import { Typography, Select } from "antd";
import { cryptocurrencies, fiatCurrencies } from "./currencies/currencies.jsx";
import { ExchangeRateUI } from "./UI/ExchangeRateUI.jsx";

function ExchangeRate() {
  const [fromCurrency, setFromCurrency] = useState(cryptocurrencies[0].value);
  const [toCurrency, setToCurrency] = useState(fiatCurrencies[0].value);

  const handleFromCurrencyChange = (e) => {
    setFromCurrency(e);
    console.log(e);
  };

  const handleToCurrencyChange = (e) => {
    setToCurrency(e);
    console.log(e);
  };

  return (
    <section className="exchange-rate">
      <Typography.Title style={{ color: "#4d4add" }} level={2}>
        Exchange Rate
      </Typography.Title>
      <Typography.Text>
        Get the latest exchange rate of cryptocurrencies in your favorite
        currency
      </Typography.Text>
      <section className="select-group" style={{ display: "flex", marginTop: "1rem", gap: "1rem", justifyContent: "space-around" }}>
        <Select defaultValue={cryptocurrencies[0].value} options={cryptocurrencies} onChange={handleFromCurrencyChange} />
        <Select defaultValue={fiatCurrencies[0].value} options={fiatCurrencies} onChange={handleToCurrencyChange} />
      </section>
      <section style={{ marginTop: "1rem" }}>
        <ExchangeRateUI />
      </section>
    </section>
  );
}

export default ExchangeRate;

In the ExchahgeRate component, you imported the fiatCurrencies and cryptocurrencies arrays from the currencies folder. The fiatCurrencies and cryptocurrencies arrays are used by the Select component to render the selected currencies you wish to convert.

The useState hook is used to keep track of the selected currencies.

The return statement renders the ExchangeRateUI component.

Update your App.jsx file with the following code: import ExchangeRate from './components/ExchangeRate.jsx' function App(){ return ( <ExchangeRate/> ) } export default App;

If you followed each step correctly, your web app should look like this:

GIF of the crypto app UI

Now that the app's UI is set up, let's move on to implementing the data fetching logic.

How to Fetch Data with React Query

In this section, you are going to implement the data fetching logic.

Replace the code in the App.jsx file with the following code:

import { QueryClient, QueryClientProvider } from "react-query";
import ExchangeRate from "./components/ExchangeRate.jsx";

const queryClient = new QueryClient(); // Instantiate a new QueryClient instance

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ExchangeRate />
    </QueryClientProvider>
  );
}

export default App;

In the code above, you created a queryClient using QueryClient() from react-query. The queryClient is passed to the QueryClientProvider via the client props. This allows the child components to have access to the queryClient, which will be used for data fetching.

React-query comes with good default configurations, but you are going to alter some of these default configurations. This is to avoid rate limiting due to excessive requests to the API.

Replace the queryClient declaration with the following code in your App.jsx:

// previous code

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      method: "GET", // Default HTTP method for queries
      refetchOnWindowFocus: false, // Disable automatic refetching on window focus
      refetchInterval: 60000, // Refetch queries every 60 seconds
    },
  },
});

// remaining code

In the code above, you are stopping the component from refetching when you refocus on the web page. Also, you are increasing the background refetching time to six seconds.

After making the changes, your App.jsx should look like this:

import { QueryClient, QueryClientProvider } from "react-query";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      refetchOnWindowFocus: false, // Disable automatic refetching on focus
      refetchInterval: 60000, // Refetch queries every 60 seconds
    },
  },
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <ExchangeRate />
    </QueryClientProvider>
  );
}

export default App;

Next, you are going to create the data fetching function in the fetchData folder.

Create a new file called fetchData.jsx in the fetchData folder.

Add the following code in the fetchData.jsx file:

import axios from 'axios' 

export function getExchangeRate(fromCurrency, toCurrency){ 

    const options = { 
        method: 'GET', 
        url: 'https://alpha-vantage.p.rapidapi.com/query', 
        params: { from_currency: fromCurrency, function: 'CURRENCY_EXCHANGE_RATE', to_currency: toCurrency }, 
        headers: { 'X-RapidAPI-Key': 'YOUR API KEY', 'X-RapidAPI-Host': 'alpha-vantage.p.rapidapi.com' } 
    }; 

    return axios.request(options)
        .then(res => { return res.data; })
        .catch((err) => { return err; }) 

}

In the code above, you used Axios to fetch data from the AlphaVantage API through RapidAPI.

Remember to replace YOUR API KEY with your API key from RapidAPI.

Navigate to your ExchangeRate component, and add the following code:

import { useQuery } from 'react-query';
import { getExchangeRate } from './fetchData/fetchData.jsx';

function ExchangeRate() {
  // previous code

  const dependencies = {
    fromCurrency: fromCurrency,
    toCurrency: toCurrency,
  };

  const { data, isLoading, isError, error } = useQuery({
    queryKey: ["exchangeRate", dependencies],
    queryFn: () => fetchData(fromCurrency, toCurrency),
    staleTime: 1000 * 60,
    retry: 1,
    retryDelay: 6000,
  });

  // further code
}

In the code above, you used the useQuery hook to fetch the exchange rate data with specified parameters.

The useQuery hook returns an object with many properties – but the following are the properties that are of interest:

• data: holds the fetched data.

• isLoading: indicates if the data is still being fetched.

• isError: indicates if an error occurred during fetching.

• error: contains the error details if there's an issue.

The queryKey is an array representing a unique identifier for this query, and staleTime sets the cache to consider data stale after a minute. retry and retryDelay control retry attempts.

Let's look at the data property.

The data property is the response object that is successfully returned from our call to the AlphaVantage API.

The data property looks like this:

{
  "Realtime Currency Exchange Rate": {
    "1. From_Currency Code": "BTC",
    "2. From_Currency Name": "Bitcoin",
    "3. To_Currency Code": "USD",
    "4. To_Currency Name": "United States Dollar",
    "5. Exchange Rate": "44138.96000000",
    "6. Last Refreshed": "2024-01-05 00:16:03",
    "7. Time Zone": "UTC",
    "8. Bid Price": "44138.96000000",
    "9. Ask Price": "44138.97000000"
  }
}

We are only interested in the 5. Exchange Rate property of the data property as it contains the exchange rate.

Since we only need the 5. Exchange Rate, pass it as props to the ExchangeRateUI component.

After making the changes, your ExchangeRate component should look like this:

import React, { useState, useEffect } from 'react';
import { Typography, Select, Spin } from 'antd';
import { cryptocurrencies, fiatCurrencies } from './currencies/currencies.jsx';
import { ExchangeRateUI } from './UI/ExchangeRateUI.jsx';
import { useQuery } from 'react-query';
import { fetchData } from './fetchData/fetchData.jsx';

function ExchangeRate() {
  const [fromCurrency, setFromCurrency] = useState(cryptocurrencies[0].value);
  const [toCurrency, setToCurrency] = useState(fiatCurrencies[0].value);
  const [currencySymbol, setCurrencySymbol] = useState("Bitcoin");

  const handleFromCurrencyChange = (e) => {
    setFromCurrency(e);
    console.log(e);
  };

  const handleToCurrencyChange = (e) => {
    setToCurrency(e);
    console.log(e);
  };

  useEffect(() => {
    const fromCurrencyLabel = cryptocurrencies.find(currency => currency.value === fromCurrency)?.label;
    setCurrencySymbol(fromCurrencyLabel);
  }, [fromCurrency]);

  const dependencies = { fromCurrency: fromCurrency, toCurrency: toCurrency };
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ["exchangeRate", dependencies],
    queryFn: () => fetchData(fromCurrency, toCurrency),
    staleTime: 1000 * 60,
    retry: 1,
    retryDelay: 60000
  });

  console.log(data);

  return (
    <section className="exchange-rate">
      <Typography.Title style={{ color: "#4d4add" }} level={2}>Exchange Rate</Typography.Title>
      <Typography.Text>Get the latest exchange rate of cryptocurrencies in your favorite currency</Typography.Text>
      <section className="select-group" style={{ display: "flex", marginTop: "1rem", gap: "1rem", justifyContent: "space-around" }}>
        <Select defaultValue={cryptocurrencies[0].value} options={cryptocurrencies} onChange={handleFromCurrencyChange} />{' '}
        <Select defaultValue={fiatCurrencies[0].value} options={fiatCurrencies} onChange={handleToCurrencyChange} />
      </section>
      <section style={{ marginTop: '1rem' }}>
        {isLoading ? (
          <Spin tip="Fetching results" spinning size="large" />
        ) : isError ? (
          <div>Error: {error.message}</div>
        ) : (
          <div>
            <ExchangeRateUI price={data["Realtime Currency Exchange Rate"]["5. Exchange Rate"]} dataObj={dependencies} currencySymbol={currencySymbol} />
          </div>
        )}
      </section>
    </section>
  );
}

export default ExchangeRate;

In the code above, you used the ternary operator to render different content based on the state of the data fetching.

currencySymbol is used to keep track of the cryptocurrency you're checking the exchange rate of.

Open your console and you should see something like this:

Now that you're done implementing the data fetching logic, let's display the data in the UI.

How to Display the data in the UI

In this section, you are going to add the final touches to the web app.

Update your ExchangeRateUI.jsx file with the following code:

import React from "react";
import { Typography, Card } from "antd";

export function ExchangeRateUI(props) {
  const { price, dataObj, currencySymbol } = props;
  const toCurrency = dataObj.toCurrency;
  let value = Number(price);
  let currencyCode = toCurrency;

  let currency = new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: currencyCode,
  });

  let formattedCurrency = currency.format(value);

  return (
    <div className="exchange-rate-ui">
      <Card extra={currencySymbol} bordered={false} style={{ width: 350, backgroundColor: "#4d4add", color: '#fff' }} size="default">
        <Typography.Paragraph style={{ color: "#fff" }}>{formattedCurrency}</Typography.Paragraph>
      </Card>
    </div>
  );
}

Let's understand what's going on in the code above.

First, you take the raw price representing the exchange rate, ensure it's treated as a number, determine the currency code, and then format the numeric value into a user-friendly currency string. This formatted currency is used for display in the user interface to provide a clear and standardized representation of the exchange rate.

Next, the formatted currency is displayed within a styled Card component from Ant Design. The Card includes the currencySymbol as an extra element. The background color, width, and text color are styled for a visually appealing UI.

Your app should look like this:

GIF of complete working crypto app

Congratulations. You have built a crypto exchange rate web app in React.

Error Handling

Error handling is a crucial aspect of developing web apps. This is because web apps and software in general can experience crashes and down time.

In React, when your app crashes, it usually shows a white/blank screen. This doesn't make for a good user experience. You'll want to display some kind of information to your users if your app crashes.

In this section, you are going to use the ErrorBoundary component to handle app crashes.

Create a file called ErrorBoundary.jsx in the src folder.

Add the following code in the ErrorBoundary.jsx file:

import React from "react";
import { Typography } from "antd";

export default class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    // Update state so the next render will show the fallback UI.
    return { hasError: true };
  }

  componentDidCatch(error, errorInfo) {
    // You can also log the error to an error reporting service
    console.error("Caught error: ");
  }

  render() {
    if (this.state.hasError) {
      // You can render any custom fallback UI
      return <Typography.Title level={4}>Something went wrong.</Typography.Title>;
    }

    return this.props.children;
  }
}

In the code above, you are rendering the message "Something went wrong" if there's an error rendering your app.

Update your index.jsx file with the following code:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import ErrorBoundary from './ErrorBoundary';

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <ErrorBoundary>
      <App />
    </ErrorBoundary>
  </React.StrictMode>
);

Visit the React docs for more information on ErrorBoundary.

Conclusion

This article walked you through how to work with third-party APIs in React by building a crypto exchange rate web app.

But don't stop here. You can improve this project by adding a news feature and styling it to your taste. Also, you can decide to support more currencies.

Additional resources

• React-query documentation

• Ant Design UI library