TypeScript Tutorial: Building a Simple Web-Based Code Diff Viewer

Written by

learnmodernjavascript

in

Ever found yourself staring at two versions of code, struggling to spot the differences? It’s a common problem for developers, especially when collaborating on projects or reviewing changes. Manually comparing code snippets can be tedious and error-prone. What if you could visualize those differences instantly, highlighting the additions, deletions, and modifications with ease? In this tutorial, we’ll dive into building a simple web-based code diff viewer using TypeScript. This tool will allow you to quickly and efficiently compare two blocks of code, making code reviews and version control a breeze. This tutorial is designed for beginners and intermediate developers, providing a clear and comprehensive guide to building a practical tool using modern web technologies.

What is a Code Diff Viewer and Why Build One?

A code diff viewer, or diff tool, is a program that compares two sets of text files and highlights the differences between them. These differences can include added lines, deleted lines, and modified lines. Diff viewers are invaluable for a variety of tasks:

  • Code Reviews: Quickly identify changes introduced by other developers.
  • Version Control: Understand the evolution of code over time.
  • Debugging: Pinpoint the source of bugs by comparing different versions of code.
  • Merging: Resolve conflicts when merging code from different branches.

Building your own code diff viewer offers several advantages. You can customize it to suit your specific needs, learn about the underlying algorithms, and gain a deeper understanding of how diff tools work. Plus, it’s a fun and rewarding project!

Prerequisites

Before we begin, make sure you have the following installed:

  • Node.js and npm (or yarn): We’ll use these to manage our project dependencies and run our development server. You can download them from nodejs.org.
  • A Text Editor or IDE: VS Code, Sublime Text, or any other editor you prefer.
  • Basic Understanding of HTML, CSS, and JavaScript: While we’ll be focusing on TypeScript, a basic understanding of these web technologies will be helpful.

Setting Up the Project

Let’s get started by creating a new project directory and initializing it with npm:

mkdir code-diff-viewer
cd code-diff-viewer
npm init -y

This will create a `package.json` file in your project directory. Next, install TypeScript and some development dependencies:

npm install typescript --save-dev
npm install @types/diff --save-dev
npm install diff --save

We’re installing the `typescript` compiler, the `@types/diff` package (which provides type definitions for the `diff` library), and the `diff` library itself. The `diff` library is a JavaScript library that provides functions for comparing strings and generating the diff output.

Now, let’s create a `tsconfig.json` file to configure the TypeScript compiler. In your project directory, run:

npx tsc --init

This will generate a `tsconfig.json` file with default settings. You can customize this file to suit your project’s needs. For this tutorial, we’ll keep the default settings, but you might want to adjust the target (e.g., `es6` or `esnext`) and module (e.g., `commonjs` or `esnext`) options later.

Project Structure

Let’s set up a basic project structure:


code-diff-viewer/
├── src/
│   ├── index.ts
│   └── style.css
├── index.html
├── package.json
├── tsconfig.json
└── ...
  • `src/index.ts`: This is where our main TypeScript code will reside.
  • `src/style.css`: This will hold our CSS styles for the UI.
  • `index.html`: This is the main HTML file for our application.

Writing the HTML

Create an `index.html` file in the root of your project directory with the following content:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Code Diff Viewer</title>
  <link rel="stylesheet" href="src/style.css">
</head>
<body>
  <div class="container">
    <h1>Code Diff Viewer</h1>
    <div class="input-container">
      <textarea id="code1" placeholder="Enter Code 1"></textarea>
      <textarea id="code2" placeholder="Enter Code 2"></textarea>
    </div>
    <button id="diffButton">Show Diff</button>
    <div id="diffOutput"></div>
  </div>
  <script src="src/index.js"></script>
</body>
</html>

This HTML provides the basic structure of our application. It includes two textareas for entering the code, a button to trigger the diff, and a `div` to display the diff output. We also link to our CSS file and our JavaScript file (which we’ll generate from TypeScript).

Writing the CSS

Create a `src/style.css` file and add some basic styling to make our application look presentable:

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

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

h1 {
  text-align: center;
  color: #333;
}

.input-container {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 10px;
  margin-bottom: 10px;
}

textarea {
  width: 100%;
  padding: 10px;
  border: 1px solid #ccc;
  border-radius: 4px;
  font-family: monospace;
  resize: vertical;
}

button {
  background-color: #4CAF50;
  color: white;
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 16px;
}

button:hover {
  background-color: #3e8e41;
}

#diffOutput {
  margin-top: 10px;
  font-family: monospace;
  white-space: pre-wrap;
}

.diff-added {
  background-color: #ccffcc;
}

.diff-deleted {
  background-color: #ffcccc;
  text-decoration: line-through;
}

This CSS provides basic styling for the layout, input fields, and diff output. We’ve added some highlighting for added and deleted lines.

Writing the TypeScript Code

Now, let’s write the core logic in `src/index.ts`. This is where we’ll use the `diff` library to compare the code and display the results.

import { diffChars } from 'diff';

// Get references to the HTML elements
const code1 = document.getElementById('code1') as HTMLTextAreaElement;
const code2 = document.getElementById('code2') as HTMLTextAreaElement;
const diffButton = document.getElementById('diffButton') as HTMLButtonElement;
const diffOutput = document.getElementById('diffOutput') as HTMLDivElement;

// Function to generate the diff HTML
function generateDiffHTML(diff: diff.Change[]): string {
  let html = '';
  diff.forEach((part) => {
    // added, removed, or common
    const color = part.added ? 'diff-added' : part.removed ? 'diff-deleted' : '';
    html += `<span class="${color}">${part.value}</span>`;
  });
  return html;
}

// Event listener for the diff button
diffButton.addEventListener('click', () => {
  const text1 = code1.value;
  const text2 = code2.value;

  // Generate the diff using the diffChars function
  const diff = diffChars(text1, text2);

  // Generate the HTML for the diff output
  const diffHTML = generateDiffHTML(diff);

  // Display the diff output
  diffOutput.innerHTML = diffHTML;
});

Let’s break down the code:

  1. Import the `diffChars` function: We import the `diffChars` function from the `diff` library. This function will be used to compare the two code snippets.
  2. Get references to HTML elements: We get references to the `textarea` elements (for code input), the button, and the `div` element where we’ll display the diff output. We use type assertions (`as HTMLTextAreaElement`, etc.) to tell TypeScript the type of these elements.
  3. `generateDiffHTML` function: This function takes the diff result (an array of changes) and generates the HTML to display the differences. It iterates through the changes, applying CSS classes (`diff-added`, `diff-deleted`) to highlight additions and deletions.
  4. Event listener for the diff button: When the button is clicked, this event listener does the following:
    • Gets the text from the two textareas.
    • Calls `diffChars` to generate the diff.
    • Calls `generateDiffHTML` to create the HTML for the diff output.
    • Sets the `innerHTML` of the `diffOutput` div to display the diff.

Compiling the TypeScript

Now, let’s compile the TypeScript code to JavaScript. Open your terminal and run the following command in your project directory:

tsc

This will create a `src/index.js` file, which is the JavaScript version of our TypeScript code. If you have any errors in your TypeScript code, the compiler will report them here.

Running the Application

Open `index.html` in your web browser. You should see two text areas and a button. Enter some code into the text areas, click the “Show Diff” button, and see the differences highlighted. You can open the HTML file directly in your browser, or, for a more convenient development experience, use a simple web server.

One easy way to run a simple web server is using the `serve` package. Install it globally if you don’t have it already:

npm install -g serve

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

serve

This will start a web server and give you a local URL (usually `http://localhost:5000` or similar) where you can view your application.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Incorrect File Paths: Double-check that the file paths in your `index.html` (e.g., for the CSS and JavaScript) are correct.
  • Typos: Carefully check your code for typos, especially in variable names and HTML element IDs. TypeScript’s type checking should help catch many of these.
  • Missing Dependencies: Make sure you’ve installed all the necessary dependencies (TypeScript, the `diff` library, and the `@types/diff` package).
  • Compiler Errors: If you get compiler errors from `tsc`, read the error messages carefully. They usually indicate the line number and the nature of the problem.
  • Browser Console Errors: Open your browser’s developer console (usually by pressing F12) and check for any errors. These can provide valuable clues about what’s going wrong.

Enhancements and Next Steps

This is a basic code diff viewer, but there are many ways you can enhance it:

  • Line-by-line Diff: Instead of character-by-character diffs, implement a line-by-line comparison for better readability, especially for large code blocks. The `diff` library supports this with the `diffLines` function.
  • Syntax Highlighting: Integrate a syntax highlighting library (like Prism.js or highlight.js) to color-code the code snippets for improved readability.
  • Code Folding: Implement code folding to allow users to collapse and expand sections of the code, making it easier to navigate large files.
  • User Interface Improvements: Improve the UI with features such as:
    • A clear indication of which lines have changed
    • The ability to switch between different diff algorithms
    • Options to customize the display (e.g., color schemes)
  • File Input: Add the ability to upload or load code from files.
  • Integration with Version Control: Integrate the diff viewer with a version control system like Git.

Key Takeaways

  • You’ve learned how to set up a TypeScript project and use a third-party library (`diff`).
  • You’ve built a functional web-based code diff viewer.
  • You’ve gained practical experience with HTML, CSS, and JavaScript, alongside TypeScript.
  • You understand the basic principles of diffing algorithms.

FAQ

  1. Q: Why use TypeScript for this project?

    A: TypeScript adds static typing, which helps catch errors early, improves code readability, and makes it easier to refactor and maintain the code. It also provides better tooling support, such as autocompletion and refactoring, in your IDE.

  2. Q: Can I use this code diff viewer in a production environment?

    A: The current implementation is a basic example. For production use, you’d want to add more robust error handling, security measures, and consider performance optimizations. You might also want to use a more feature-rich diff library or integrate it with a version control system.

  3. Q: How can I improve the performance of the diff viewer?

    A: For large code files, consider optimizing the diffing algorithm. You might also use techniques like virtual DOM diffing to update only the changed parts of the display. Additionally, consider using web workers to perform the diffing in a separate thread, preventing the UI from freezing.

  4. Q: What are some alternative diff libraries?

    A: Besides the `diff` library we used in this tutorial, other popular options include `jsdiff` and libraries that are part of more comprehensive code comparison tools.

Building a code diff viewer is a valuable learning experience that gives you a deeper understanding of software development. It combines front-end development, algorithmic thinking, and the practical application of libraries. By understanding the core principles behind diffing, you’re well-equipped to tackle more complex tasks in your software development journey. The skills you’ve gained in this tutorial, from setting up a TypeScript project to working with a third-party library, are transferable to a wide range of web development projects, and your ability to visually compare code will now be far more effective.

More posts