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

Written by

learnmodernjavascript

in

In the vast landscape of software development, the ability to compare and understand code changes is paramount. Whether you’re collaborating with a team, reviewing your own modifications, or simply trying to grasp the evolution of a codebase, a code diff tool becomes an indispensable asset. This tutorial will guide you through building a simple, yet functional, web-based code diff tool using TypeScript. We’ll explore the core concepts, address potential challenges, and equip you with the knowledge to create a useful tool for your development workflow. This project is designed for beginner to intermediate developers who want to deepen their understanding of TypeScript and its practical applications.

Why Build a Code Diff Tool?

Code diff tools provide a clear and concise way to visualize the differences between two versions of a text file, typically code. They highlight additions, deletions, and modifications, making it easier to:

  • Review Changes: Understand the impact of code modifications before integrating them.
  • Track Evolution: See how a codebase has changed over time.
  • Identify Bugs: Pinpoint the exact lines of code that introduced an issue.
  • Collaborate Effectively: Facilitate code reviews and discussions within a team.

While numerous code diff tools are available, building your own offers several advantages:

  • Learning Experience: Deepen your understanding of TypeScript, algorithms, and web development.
  • Customization: Tailor the tool to your specific needs and preferences.
  • Portfolio Project: Showcase your skills and creativity to potential employers.

Project Setup and Prerequisites

Before we dive into the code, let’s set up our development environment. You’ll need the following:

  • Node.js and npm (or yarn): For managing dependencies and running the development server.
  • A Code Editor: Such as Visual Studio Code, Sublime Text, or Atom.
  • Basic HTML, CSS, and JavaScript knowledge: Familiarity with these technologies will be helpful, but not strictly required.
  • TypeScript: Ensure you have TypeScript installed globally or locally within your project.

Let’s create a new project directory and initialize it with npm:

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

Next, install TypeScript and a few other packages we’ll use:

npm install typescript @types/diff @types/highlight.js highlight.js

Here’s a breakdown of the packages:

  • typescript: The TypeScript compiler.
  • @types/diff: Type definitions for the `diff` library.
  • @types/highlight.js: Type definitions for the `highlight.js` library.
  • highlight.js: A library for syntax highlighting.

Create a `tsconfig.json` file in your project root. This file configures the TypeScript compiler. You can use the following basic configuration:

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "outDir": "./dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

Now, let’s create a simple HTML file (`index.html`) to serve as our user interface:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Code Diff Tool</title>
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css">
    <style>
        body {
            font-family: sans-serif;
        }
        .diff-container {
            display: flex;
        }
        .diff-column {
            width: 50%;
            padding: 10px;
        }
        .diff-line {
            display: flex;
            align-items: center;
            padding: 2px 0;
        }
        .diff-line-number {
            width: 40px;
            text-align: right;
            margin-right: 10px;
            color: #999;
        }
        .diff-line-content {
            white-space: pre;
            overflow-x: auto;
        }
        .diff-add {
            background-color: #e6ffed;
            color: #24292e;
        }
        .diff-remove {
            background-color: #ffeef0;
            color: #24292e;
        }
    </style>
</head>
<body>
    <h1>Code Diff Tool</h1>
    <div>
        <label for="code1">Code 1:</label>
        <textarea id="code1" rows="10" cols="50"></textarea>
    </div>
    <div>
        <label for="code2">Code 2:</label>
        <textarea id="code2" rows="10" cols="50"></textarea>
    </div>
    <button id="diffButton">Diff</button>
    <div class="diff-container">
        <div class="diff-column" id="diffColumn1">
            <h3>Code 1</h3>
        </div>
        <div class="diff-column" id="diffColumn2">
            <h3>Code 2</h3>
        </div>
    </div>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
    <script src="./dist/index.js"></script>
</body>
</html>

This HTML provides the basic structure: two textareas for entering code, a button to trigger the diff, and two columns to display the diff results.

Implementing the Code Diff Logic with TypeScript

Now, let’s create our main TypeScript file, `index.ts`, where the core logic resides. We’ll use the `diff` library to compare the code and generate the diff output.

import { diffChars } from 'diff';
import hljs from 'highlight.js';

// Get references to HTML elements
const code1Textarea = document.getElementById('code1') as HTMLTextAreaElement;
const code2Textarea = document.getElementById('code2') as HTMLTextAreaElement;
const diffButton = document.getElementById('diffButton') as HTMLButtonElement;
const diffColumn1 = document.getElementById('diffColumn1') as HTMLDivElement;
const diffColumn2 = document.getElementById('diffColumn2') as HTMLDivElement;

// Function to generate a diff and display it
function generateDiff() {
    const code1 = code1Textarea.value;
    const code2 = code2Textarea.value;

    // Clear previous diff results
    diffColumn1.innerHTML = '<h3>Code 1</h3>';
    diffColumn2.innerHTML = '<h3>Code 2</h3>';

    // Generate diff using diffChars (character-level diff)
    const diff = diffChars(code1, code2);

    let lineNumber1 = 1;
    let lineNumber2 = 1;

    // Helper function to create a diff line element
    function createDiffLine(lineContent: string, className: string, lineNumber: number): HTMLDivElement {
        const line = document.createElement('div');
        line.classList.add('diff-line');
        if (className) {
            line.classList.add(className);
        }

        const lineNumberSpan = document.createElement('span');
        lineNumberSpan.classList.add('diff-line-number');
        lineNumberSpan.textContent = lineNumber.toString();
        line.appendChild(lineNumberSpan);

        const contentSpan = document.createElement('span');
        contentSpan.classList.add('diff-line-content');
        contentSpan.innerHTML = lineContent;
        line.appendChild(contentSpan);

        return line;
    }

    // Iterate through diff results and display them
    diff.forEach((part) => {
        const color = part.added ? 'add' : part.removed ? 'remove' : null;
        const column = part.removed ? diffColumn1 : diffColumn2;
        const lineNumber = part.removed ? lineNumber1 : lineNumber2;

        if (part.added) {
            const lines = part.value.split('n');
            lines.forEach((line) => {
                column.appendChild(createDiffLine(hljs.highlight(line, { language: 'javascript' }).value, 'diff-add', lineNumber2++));
            });
        } else if (part.removed) {
            const lines = part.value.split('n');
            lines.forEach((line) => {
                diffColumn1.appendChild(createDiffLine(hljs.highlight(line, { language: 'javascript' }).value, 'diff-remove', lineNumber1++));
            });
        } else {
            const lines1 = part.value.split('n');
            lines1.forEach((line) => {
                diffColumn1.appendChild(createDiffLine(hljs.highlight(line, { language: 'javascript' }).value, '', lineNumber1++));
            });
            const lines2 = part.value.split('n');
            lines2.forEach((line) => {
                diffColumn2.appendChild(createDiffLine(hljs.highlight(line, { language: 'javascript' }).value, '', lineNumber2++));
            });
        }
    });
}

// Add event listener to the button
diffButton.addEventListener('click', generateDiff);

Let’s break down this code:

  • Imports: We import `diffChars` from the `diff` library and `hljs` from `highlight.js`.
  • Element References: We get references to the HTML elements we created in `index.html`.
  • `generateDiff` Function: This function is the core of our tool. It does the following:
    • Retrieves the code from the textareas.
    • Clears any existing diff results.
    • Uses `diffChars` to generate the diff. This function compares the two strings and returns an array of objects, each representing a part of the diff (added, removed, or unchanged). We use `diffChars` for character-level comparisons, which is generally more precise for code.
    • Iterates over the diff results. For each part, it determines whether it’s an addition, deletion, or unchanged.
    • Dynamically creates HTML elements (divs and spans) to display the diff results in the two columns. It uses CSS classes to style the added and removed lines.
    • It uses `highlight.js` to add syntax highlighting to the code.
  • Event Listener: We attach a click event listener to the “Diff” button, which calls the `generateDiff` function when clicked.

To compile the TypeScript code, run the following command in your terminal:

tsc

This will create a `dist` directory containing `index.js`, which is the compiled JavaScript code.

Running the Code Diff Tool

To run the tool, you’ll need a simple web server to serve the HTML and JavaScript files. A straightforward way to do this is using the `serve` package from npm:

npm install -g serve

Navigate to your project directory in the terminal and run:

serve

This will start a local web server (usually on `http://localhost:5000`). Open your browser and navigate to the address provided by `serve`. You should see the code diff tool. Paste code into the textareas, click the “Diff” button, and see the results.

Enhancements and Advanced Features

This simple tool provides a foundation. You can enhance it with more advanced features:

  • Line-by-Line Diff: Implement a line-by-line diff for more accurate comparisons, especially when dealing with code formatting differences. You can use the `diffLines` function from the `diff` library instead of `diffChars`.
  • Syntax Highlighting: Integrate a syntax highlighting library (like `highlight.js`, which we’ve already included) to make the code more readable. You’ll need to apply the highlighting to the diff output.
  • Language Detection: Automatically detect the programming language of the code to apply the correct syntax highlighting.
  • Code Folding: Allow users to collapse and expand sections of the code for better navigation, particularly for large files.
  • File Upload: Enable users to upload code files instead of pasting text.
  • Real-time Updates: Implement real-time updates as the user types, using event listeners to trigger the diff generation.
  • Diff Algorithm Selection: Offer the user the ability to select different diff algorithms, providing options for performance and accuracy.
  • Integration with Version Control: Integrate the tool with version control systems (e.g., Git) to compare code changes directly from your repositories.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Incorrect File Paths: Double-check the file paths in your HTML, especially the path to the compiled JavaScript file (`dist/index.js`). Make sure the paths are relative to the HTML file’s location.
  • TypeScript Compilation Errors: If you encounter TypeScript compilation errors, carefully review the error messages. They often provide valuable clues about the problem. Common issues include type mismatches, missing imports, and incorrect syntax.
  • Dependency Issues: Ensure you’ve installed all the required dependencies using npm or yarn. Verify that the package versions are compatible.
  • Syntax Highlighting Not Working: Make sure you’ve included the CSS for your chosen syntax highlighting library (e.g., `highlight.js`) in your HTML. Also, ensure you’re correctly applying the highlighting to the diff output.
  • Diff Display Issues: If the diff is not displayed correctly, check the CSS styles applied to the diff elements. Ensure the styles are correct and that the elements are positioned and sized appropriately. Also, check the console for any errors in the browser.

Key Takeaways and Best Practices

In building this code diff tool, we’ve covered several important aspects of TypeScript and web development:

  • TypeScript Fundamentals: We’ve used TypeScript’s type system, which improves code readability and reduces errors.
  • DOM Manipulation: We’ve learned how to interact with the Document Object Model (DOM) to dynamically create and update HTML elements.
  • External Libraries: We’ve integrated external libraries like `diff` and `highlight.js` to extend our tool’s functionality.
  • Event Handling: We’ve used event listeners to respond to user interactions, such as clicking the “Diff” button.
  • Modular Design: While this is a simple example, it’s a good practice to break down your code into smaller, reusable functions.

Here are some best practices to keep in mind:

  • Use Types: Leverage TypeScript’s type system to improve code quality and catch errors early.
  • Write Clear Code: Use meaningful variable names, comments, and consistent formatting to make your code easier to understand and maintain.
  • Test Your Code: Write unit tests to ensure your code functions correctly.
  • Modularize Your Code: Break down complex tasks into smaller, reusable functions or classes.
  • Handle Errors Gracefully: Use try-catch blocks to handle potential errors and provide informative error messages to the user.

FAQ

Q: Can I use this tool with different programming languages?
A: Yes, you can adapt the syntax highlighting to support various programming languages by configuring the `highlight.js` library appropriately. You might need to add language-specific CSS styles and modify the code to detect the programming language dynamically.

Q: How can I improve the performance of the diff generation?
A: For large code files, consider using more optimized diff algorithms, such as those that perform line-by-line comparisons. Also, you can explore techniques like caching diff results to avoid redundant calculations.

Q: How can I integrate this tool into a larger web application?
A: You can integrate this tool into a larger application by creating a reusable component or module. You can then import this component into your main application and use it to display code diffs. Consider using a framework like React or Angular to manage the component’s state and interactions more effectively.

Q: How can I deploy this tool to the web?
A: You can deploy your tool to platforms like Netlify or Vercel. These platforms automatically build and deploy your application from a Git repository. You can also deploy it to a traditional web server.

Q: What are the limitations of this simple tool?
A: The primary limitation is its simplicity. It may not handle very large code files efficiently. Also, the character-level diff might not always provide the most intuitive results, especially for code formatting differences. However, it serves as a great starting point for building a more feature-rich code diff tool.

Building a web-based code diff tool with TypeScript is a rewarding project that combines practical skills with the power of modern web technologies. By following the steps outlined in this tutorial, you’ve taken a significant step toward creating a useful and informative tool. As you continue to explore the possibilities, remember that the most important thing is to experiment, learn, and have fun. The journey of software development is a continuous process of learning and improvement. Embrace the challenges, celebrate your successes, and keep coding.

More posts