TypeScript Tutorial: Building a Simple Interactive PDF Viewer

Written by

learnmodernjavascript

in

In the digital age, PDFs are everywhere. From official documents to eBooks, they’re a common format for sharing and storing information. As web developers, we often need to display PDFs within our applications. While there are numerous libraries and tools available, building a simple, interactive PDF viewer from scratch provides a fantastic learning opportunity, especially when utilizing the power and type safety of TypeScript. This tutorial will guide you through the process, covering the core concepts and providing a practical, hands-on experience.

Why Build a PDF Viewer?

Why not just use a pre-built library? While libraries like PDF.js are excellent, building your own viewer has several benefits:

  • Learning: It deepens your understanding of how PDFs work and how they are rendered on a web page.
  • Customization: You have complete control over the user interface and functionality.
  • Optimization: You can tailor the viewer to your specific needs, potentially improving performance.
  • TypeScript Mastery: It’s a great way to practice TypeScript concepts like types, interfaces, and classes in a real-world scenario.

Prerequisites

Before we begin, make sure you have the following:

  • Node.js and npm (or yarn): Required for managing project dependencies.
  • A text editor or IDE: Such as Visual Studio Code, Sublime Text, or Atom.
  • Basic knowledge of HTML, CSS, and JavaScript: Familiarity with these languages is essential.
  • A modern web browser: Chrome, Firefox, Safari, or Edge.

Setting Up the Project

Let’s get started by creating a new project directory and initializing it with npm. Open your terminal and run the following commands:

mkdir pdf-viewer-tutorial
cd pdf-viewer-tutorial
npm init -y

This creates a new directory, navigates into it, and initializes a package.json file with default settings. Now, let’s install TypeScript and some necessary dependencies:

npm install typescript --save-dev
npm install pdfjs-dist --save
  • typescript: This is the TypeScript compiler.
  • pdfjs-dist: This is the PDF.js library, which we’ll use to parse and render PDFs.

Next, we need to create a tsconfig.json file to configure the TypeScript compiler. Run the following command:

npx tsc --init --rootDir src --outDir dist

This command generates a tsconfig.json file with default settings. We’ve added --rootDir src and --outDir dist to specify the source and output directories, respectively. This is a good practice for organizing your project.

Project Structure

Here’s how we’ll structure our project:


pdf-viewer-tutorial/
├── src/
│   ├── index.ts          # Main application logic
│   ├── styles.css        # Styles for the viewer
│   └── index.html        # HTML structure
├── dist/
│   ├── index.js          # Compiled JavaScript
│   ├── styles.css
│   └── index.html
├── node_modules/
├── package.json
├── tsconfig.json
└── ...

Creating the HTML Structure

Let’s start by creating the basic HTML structure. Create a file named index.html inside the src directory and add the following code:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Simple PDF Viewer</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <div class="container">
        <canvas id="pdf-canvas"></canvas>
        <div class="controls">
            <button id="prev-page">Previous</button>
            <button id="next-page">Next</button>
            <span id="page-num">Page: <span id="current-page">1</span> / <span id="total-pages">?</span></span>
        </div>
    </div>
    <script src="index.js"></script>
</body>
</html>

This HTML provides the basic structure for our PDF viewer. It includes a canvas element where the PDF pages will be rendered, and controls for navigating between pages. Also, it links to our styles.css and index.js files, which we’ll create next.

Adding Basic Styling (styles.css)

Create a file named styles.css inside the src directory and add the following CSS to style the viewer:

body {
    font-family: sans-serif;
    margin: 0;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    background-color: #f0f0f0;
}

.container {
    background-color: white;
    border-radius: 8px;
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
    padding: 20px;
    width: 80%;
    max-width: 800px;
}

#pdf-canvas {
    border: 1px solid #ccc;
    margin-bottom: 10px;
    max-width: 100%;
}

.controls {
    display: flex;
    justify-content: space-between;
    align-items: center;
}

button {
    padding: 8px 12px;
    border: none;
    background-color: #007bff;
    color: white;
    border-radius: 4px;
    cursor: pointer;
}

button:hover {
    background-color: #0056b3;
}

#page-num {
    font-size: 14px;
    color: #555;
}

This CSS provides basic styling for the layout, the canvas, and the navigation controls, ensuring a clean and user-friendly interface.

Writing the TypeScript Logic (index.ts)

This is where the magic happens. Create a file named index.ts inside the src directory and add the following code:

import * as pdfjsLib from 'pdfjs-dist';

// PDF file path (replace with your PDF file)
const pdfPath = 'your-pdf-file.pdf'; // Replace with the path to your PDF file

// DOM elements
const canvas = document.getElementById('pdf-canvas') as HTMLCanvasElement;
const prevPageButton = document.getElementById('prev-page') as HTMLButtonElement;
const nextPageButton = document.getElementById('next-page') as HTMLButtonElement;
const currentPageSpan = document.getElementById('current-page') as HTMLSpanElement;
const totalPagesSpan = document.getElementById('total-pages') as HTMLSpanElement;

let pdfDoc: pdfjsLib.PDFDocumentProxy;
let currentPage = 1;
let totalPages: number;

async function loadPdf(pdfPath: string) {
    try {
        const loadingTask = pdfjsLib.getDocument(pdfPath);
        const pdf = await loadingTask.promise;
        pdfDoc = pdf;
        totalPages = pdf.numPages;
        totalPagesSpan.textContent = String(totalPages);
        renderPage(currentPage);
    } catch (error) {
        console.error('Error loading PDF:', error);
        alert('Error loading PDF. Please check the file path.');
    }
}

async function renderPage(pageNumber: number) {
    if (!pdfDoc || !canvas) return;
    currentPage = pageNumber;
    currentPageSpan.textContent = String(currentPage);

    try {
        const page = await pdfDoc.getPage(pageNumber);
        const viewport = page.getViewport({ scale: 1.5 }); // Adjust scale for zoom

        const context = canvas.getContext('2d') as CanvasRenderingContext2D;
        canvas.height = viewport.height;
        canvas.width = viewport.width;

        const renderContext = {
            canvasContext: context,
            viewport: viewport,
        };
        await page.render(renderContext);
    } catch (error) {
        console.error('Error rendering page:', error);
        alert('Error rendering page.');
    }
}

function setupNavigation() {
    if (!prevPageButton || !nextPageButton) return;

    prevPageButton.addEventListener('click', () => {
        if (currentPage > 1) {
            renderPage(currentPage - 1);
        }
    });

    nextPageButton.addEventListener('click', () => {
        if (currentPage < totalPages) {
            renderPage(currentPage + 1);
        }
    });
}

// Initial setup
function initialize() {
    loadPdf(pdfPath);
    setupNavigation();
}

initialize();

Let’s break down this code:

  • Import pdfjs-dist: We import the PDF.js library.
  • DOM Element Selection: We select the HTML elements we’ll interact with. Using type assertions (as HTMLCanvasElement, etc.) ensures type safety.
  • loadPdf Function: This function loads the PDF from the specified path, gets the total number of pages, and calls renderPage to display the first page. Error handling is included.
  • renderPage Function: This function renders a specific page of the PDF onto the canvas. It uses the getPage method to get a PDF page, sets up the canvas dimensions based on the page’s viewport, and uses the render method to draw the page content.
  • setupNavigation Function: This function sets up event listeners for the previous and next page buttons.
  • initialize Function: This function calls loadPdf and setupNavigation to initialize the viewer.
  • Error Handling: The code includes try...catch blocks to handle potential errors during PDF loading and rendering.

Compiling and Running the Application

Now that we’ve written the code, let’s compile it and run the application:

  1. Compile the TypeScript code: In your terminal, run npm run build. This will compile your TypeScript code and put the resulting JavaScript into the dist directory. If you haven’t added a build script to your package.json, you can compile by running npx tsc.
  2. Serve the application: You can use a simple HTTP server to serve the files. One easy way is to use the `serve` package. Install it globally: 
    npm install -g serve

    Then, navigate to the dist directory in your terminal and run:

    serve

    This will start a local server, typically on port 5000 (or another available port).

  3. Open the application in your browser: Open your web browser and go to the address provided by the `serve` command (e.g., `http://localhost:5000`).
  4. Important: Replace the placeholder 'your-pdf-file.pdf' in index.ts with the actual path to your PDF file, relative to the dist directory. Make sure the PDF file is accessible to the server (e.g., in the same directory as index.html).

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

  • Incorrect File Path: The most common issue is an incorrect PDF file path. Double-check that the path in index.ts is correct relative to the dist directory, where your index.html and index.js files are located.
  • CORS Errors: If you’re trying to load a PDF from a different domain, you might encounter CORS (Cross-Origin Resource Sharing) errors. This is a browser security feature. To fix this, you’ll need to configure your server to allow requests from your domain. For local development, you might be able to disable CORS in your browser (not recommended for production).
  • Missing PDF.js Dependency: Make sure you have installed the pdfjs-dist package.
  • Canvas Context Errors: Ensure you’re getting the 2D context correctly from the canvas element.
  • Incorrect TypeScript Setup: Double-check your tsconfig.json file to make sure it’s configured correctly, especially the rootDir and outDir options.
  • Uncaught Errors: Always check the browser’s console for any error messages. They often provide valuable clues about what’s going wrong.

Enhancements and Next Steps

This is a basic PDF viewer, but you can enhance it in many ways:

  • Zoom and Pan: Implement zoom and pan functionality to allow users to explore the PDF in more detail.
  • Page Navigation: Add a page number input to allow users to jump to a specific page.
  • Loading Indicator: Display a loading indicator while the PDF is loading or pages are rendering.
  • Error Handling: Improve error handling to provide more informative messages to the user.
  • UI Improvements: Enhance the user interface with more controls and a better layout.
  • Support for Different PDF Features: Explore how to handle annotations, form fields, and other PDF features.
  • Mobile Responsiveness: Make the viewer responsive for different screen sizes.

Key Takeaways

We’ve successfully created a basic PDF viewer using TypeScript and the PDF.js library. This tutorial demonstrates how to load a PDF, render its pages on a canvas, and implement basic navigation. You’ve learned how to set up a TypeScript project, use a third-party library, and handle user interactions. The use of TypeScript provides type safety and improves code maintainability. This foundation can be extended to create a more feature-rich PDF viewer tailored to specific needs.

FAQ

Q: Why is the PDF not displaying?
A: The most common reasons are an incorrect file path to the PDF, CORS errors, or issues with the PDF itself (e.g., corruption). Double-check your file path, browser console for error messages, and ensure your server is configured correctly if loading from a different domain.

Q: How can I improve the performance of the viewer?
A: Optimizations include:

  • Caching rendered pages.
  • Using a smaller initial scale and allowing users to zoom.
  • Rendering pages only when they are visible in the viewport (lazy loading).

Q: Can I use this code in a production environment?
A: Yes, but you should consider further optimizations, robust error handling, and security measures. Also, make sure to handle the loading and serving of the PDF file securely.

Q: How can I add support for zooming?
A: You can add zooming by modifying the scale value in the getViewport method. You’ll also need to handle user input (e.g., mouse wheel or pinch gestures) to control the zoom level.

Q: How do I handle different PDF files?
A: The code should work with most standard PDF files. However, some PDFs may have complex features or be created in a way that causes rendering issues. The PDF.js library supports most PDF features, but you might need to adjust the rendering logic for more complex documents.

Building this PDF viewer provided a practical application for learning TypeScript and working with the PDF.js library. From setting up the project to rendering individual pages and implementing navigation, each step reinforced key programming concepts. As you continue to experiment and expand on this foundation, you will not only gain a deeper understanding of web development, but also the ability to tailor solutions to meet specific needs. The journey of creating a PDF viewer, from its initial conception to its interactive functionality, offers a valuable experience, enriching your skills and preparing you for more complex projects.

More posts