TypeScript Tutorial: Building a Simple Web-Based Code Search

Written by

learnmodernjavascript

in

In the vast landscape of software development, the ability to quickly and efficiently search through code is a crucial skill. Whether you’re a seasoned developer or just starting your journey, the ability to find specific functions, variables, or snippets of code can save you hours of time and frustration. In this tutorial, we’ll dive into building a simple, yet functional, web-based code search application using TypeScript. We’ll explore the core concepts, from setting up the project to implementing the search functionality, and along the way, you’ll gain a solid understanding of how to leverage TypeScript to create robust and maintainable applications. This project will not only teach you about code search but also provide practical experience with TypeScript, including working with APIs, handling user input, and displaying results.

Why Build a Code Search Tool?

Imagine you’re working on a large project with hundreds or thousands of lines of code. You remember a function that does something specific, but you can’t recall its exact name or where it’s located. Manually sifting through files would be a nightmare. A code search tool solves this problem by allowing you to quickly find any piece of code based on keywords or patterns. This is invaluable for:

  • Code navigation: Quickly jump to the definition of a function or variable.
  • Debugging: Find all occurrences of a bug or error message.
  • Refactoring: Identify all places where a specific code snippet is used before making changes.
  • Learning: Understand how existing code works by searching for related concepts.

Building your own code search tool is a fantastic learning experience. It forces you to think about data structures, algorithms, and user interface design. Plus, you get a practical tool you can use in your daily development workflow.

Setting Up the Development Environment

Before we start coding, we need to set up our development environment. We’ll be using:

  • Node.js and npm (or yarn): For managing project dependencies and running our application.
  • TypeScript: The language we’ll be using.
  • A code editor: Such as Visual Studio Code, which provides excellent TypeScript support.

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

mkdir code-search-app
cd code-search-app
npm init -y

Next, install TypeScript and some essential packages:

npm install typescript @types/node express cors --save

We’re installing:

  • typescript: The TypeScript compiler.
  • @types/node: Type definitions for Node.js, essential for working with Node.js APIs.
  • express: A web framework for building our backend.
  • cors: Middleware to enable Cross-Origin Resource Sharing, allowing our frontend to communicate with our backend.

Now, let’s configure TypeScript. Create a tsconfig.json file in your project root with the following content:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

This configuration tells the TypeScript compiler to:

  • target: es2016: Compile to the ES2016 JavaScript standard.
  • module: commonjs: Use the CommonJS module system (used by Node.js).
  • outDir: ./dist: Output compiled JavaScript files to a ‘dist’ directory.
  • rootDir: ./src: Look for TypeScript files in the ‘src’ directory.
  • strict: true: Enable strict type checking.
  • esModuleInterop: true: Allow interoperability between CommonJS and ES modules.
  • skipLibCheck: true: Skip type checking of declaration files.
  • forceConsistentCasingInFileNames: true: Enforce consistent casing in filenames.

Creating the Backend (Server-Side)

Our backend will be a simple Express.js server that handles search requests. Create a directory named src and inside it, create a file named server.ts. This will be our entry point for the backend.

// src/server.ts
import express, { Request, Response } from 'express';
import cors from 'cors';

const app = express();
const port = 3001; // Or any available port

app.use(cors()); // Enable CORS for all origins (for development)
app.use(express.json()); // Middleware to parse JSON request bodies

// Dummy data for demonstration
const codeData = [
    { filename: 'main.ts', content: 'console.log("Hello, world!");' },
    { filename: 'utils.ts', content: 'function add(a: number, b: number): number { return a + b; }' },
    { filename: 'types.ts', content: 'type User = { name: string; age: number; };' }
];

app.post('/search', (req: Request, res: Response) => {
    const searchTerm = req.body.searchTerm;
    if (!searchTerm) {
        return res.status(400).json({ error: 'Search term is required' });
    }

    const results = codeData.filter(item => item.content.toLowerCase().includes(searchTerm.toLowerCase()));
    res.json(results);
});

app.listen(port, () => {
    console.log(`Server listening at http://localhost:${port}`);
});

Let’s break down the code:

  • Import statements: We import the necessary modules: express for the server, cors for handling CORS, and the request and response types from express.
  • Express app setup: We create an Express application instance and set the port.
  • Middleware: We use cors() middleware to enable Cross-Origin Resource Sharing, allowing our frontend (running on a different port) to make requests to our backend. We also use express.json() to parse JSON request bodies.
  • Dummy data: codeData is an array of objects, simulating file content. In a real-world scenario, you would read code from files.
  • Search endpoint: We define a POST endpoint at /search. This endpoint expects a JSON body with a searchTerm property.
  • Search logic: Inside the endpoint, we retrieve the searchTerm from the request body. If the search term is missing, we return a 400 error. We then filter the codeData array to find items where the content includes the search term (case-insensitive).
  • Response: We send back the search results as a JSON response.
  • Server start: Finally, we start the server and listen on the specified port.

To run the backend, add a `build` and `start` script to your `package.json` file. Your `package.json` should look similar to this:

{
  "name": "code-search-app",
  "version": "1.0.0",
  "description": "",
  "main": "dist/server.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "ts-node-dev --respawn --transpile-only src/server.ts"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "cors": "^2.8.5",
    "express": "^4.18.2"
  },
  "devDependencies": {
    "@types/cors": "^2.8.17",
    "@types/express": "^4.17.21",
    "ts-node-dev": "^2.0.0",
    "typescript": "^5.3.3"
  }
}

After updating the `package.json` file, run `npm install` to install any new dependencies. Then, you can build and start the server using these commands:

npm run build
npm start

Alternatively, for development, use the command:

npm run dev

This will use `ts-node-dev` to automatically restart the server whenever you make changes to your TypeScript files.

Creating the Frontend (Client-Side)

Now, let’s create the frontend using HTML, CSS, and JavaScript (with TypeScript). We’ll keep it simple for this tutorial, focusing on the core functionality.

Create an index.html file in the project root:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Code Search App</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="container">
        <h1>Code Search</h1>
        <input type="text" id="searchInput" placeholder="Search code...">
        <button id="searchButton">Search</button>
        <div id="searchResults"></div>
    </div>
    <script src="script.js"></script>
</body>
</html>

This HTML provides a basic structure with:

  • A title.
  • An input field for the search query.
  • A search button.
  • A div to display the search results.
  • Links to the CSS and JavaScript files (which we’ll create next).

Create a style.css file in the project root. This is a basic CSS file to style the page. You can customize this to your liking.

body {
    font-family: sans-serif;
    margin: 0;
    padding: 0;
    background-color: #f4f4f4;
}

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

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

input[type="text"] {
    width: 100%;
    padding: 10px;
    margin-bottom: 10px;
    border: 1px solid #ccc;
    border-radius: 4px;
    box-sizing: border-box; /* Important for width calculation */
}

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

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

#searchResults {
    margin-top: 20px;
}

.result-item {
    padding: 10px;
    border: 1px solid #ddd;
    margin-bottom: 10px;
    border-radius: 4px;
    background-color: #f9f9f9;
}

Now, create the script.ts file in the project root. This is where the core logic for the frontend resides:

// script.ts
const searchInput = document.getElementById('searchInput') as HTMLInputElement;
const searchButton = document.getElementById('searchButton') as HTMLButtonElement;
const searchResults = document.getElementById('searchResults') as HTMLDivElement;

async function searchCode(searchTerm: string) {
    try {
        const response = await fetch('http://localhost:3001/search', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ searchTerm })
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        displayResults(data);
    } catch (error: any) {
        console.error('Error during search:', error);
        searchResults.innerHTML = `<p>Error: ${error.message}</p>`;
    }
}

function displayResults(results: any[]) {
    searchResults.innerHTML = ''; // Clear previous results

    if (results.length === 0) {
        searchResults.innerHTML = '<p>No results found.</p>';
        return;
    }

    results.forEach(result => {
        const resultItem = document.createElement('div');
        resultItem.classList.add('result-item');
        resultItem.innerHTML = `
            <p>Filename: ${result.filename}</p>
            <pre><code>${escapeHtml(result.content)}</code></pre>
        `;
        searchResults.appendChild(resultItem);
    });
}

function escapeHtml(unsafe: string): string {
    return unsafe
        .replace(/&/g, "&")
        .replace(/</g, "<")
        .replace(/>/g, ">")
        .replace(/"/g, """)
        .replace(/'/g, "'");
}

searchButton.addEventListener('click', () => {
    const searchTerm = searchInput.value;
    if (searchTerm.trim() !== '') {
        searchCode(searchTerm);
    }
});

Let’s break down the frontend code:

  • Element selection: We select the input field, search button, and results div from the HTML using their IDs. Type assertions (as HTMLInputElement, etc.) are used to tell TypeScript the type of these elements.
  • searchCode function: This asynchronous function handles the search logic:
    • It sends a POST request to the backend’s /search endpoint, including the search term in the request body.
    • It uses fetch to make the API call.
    • It handles potential errors by checking the response status.
    • It parses the JSON response from the backend.
    • It calls the displayResults function to show the search results.
  • displayResults function: This function takes an array of results and displays them in the searchResults div:
    • It clears any previous results.
    • If no results are found, it displays a “No results found” message.
    • It iterates over the results and creates a new div for each result.
    • It displays the filename and content of each result, using a pre tag for code formatting and escaping HTML.
  • escapeHtml function: This function is crucial for preventing cross-site scripting (XSS) vulnerabilities. It escapes HTML entities in the code content so they are displayed safely in the browser.
  • Event listener: An event listener is attached to the search button. When the button is clicked, it retrieves the search term from the input field, trims any whitespace, and calls the searchCode function if the search term is not empty.

To run the frontend, you’ll need a simple web server to serve the index.html file. You can use a static server like the one provided by the `serve` npm package or any other simple HTTP server. Install `serve` globally:

npm install -g serve

Then, navigate to your project directory and run:

serve

This will typically start a server on `http://localhost:5000` (or a similar port). Open this address in your web browser. You should now see the search interface. Enter a search term, and click the search button. If everything is set up correctly, you should see the results from your backend (the dummy data) displayed below.

Important Considerations and Improvements

While this is a functional code search tool, there are several areas for improvement and considerations for a real-world application:

  • Data source: Instead of hardcoded data, you’d need to read code from actual files. This would involve file system operations (using Node.js’s fs module on the backend). You might also want to index the files to improve search performance.
  • Error handling: Implement more robust error handling, including displaying more informative error messages to the user and logging errors on the server.
  • User interface: Improve the user interface with features like syntax highlighting, code folding, and more sophisticated display of results. Consider using a UI framework like React, Vue, or Angular for a more dynamic and feature-rich frontend.
  • Search algorithm: For larger codebases, consider more efficient search algorithms, such as using regular expressions or specialized search libraries.
  • Performance: Optimize performance by caching results, using asynchronous operations, and minimizing the amount of data transferred between the client and server.
  • Security: Sanitize user input to prevent security vulnerabilities, such as cross-site scripting (XSS) and SQL injection (if you were querying a database).
  • Indexing: For large codebases, indexing the code files would significantly improve search performance. This would involve creating a data structure (like an inverted index) that maps keywords to file locations.
  • Advanced search features: Implement features like:
    • Filtering: Allow users to filter results by file type, directory, or other criteria.
    • Regular expression search: Enable users to use regular expressions for more powerful pattern matching.
    • Code context: Display snippets of code around the search results to provide context.
    • Autocomplete: Suggest search terms as the user types.

Common Mistakes and How to Fix Them

Here are some common mistakes developers make when building code search tools and how to avoid them:

  • Incorrect file paths: Make sure you are using the correct file paths when reading code files. Double-check your file system structure and adjust your code accordingly.
  • CORS issues: If your frontend and backend are on different domains (which is common during development), you might encounter CORS (Cross-Origin Resource Sharing) errors. Ensure your backend is configured to handle CORS requests, as shown in the example code.
  • Asynchronous operations: When working with file system operations (reading files), use asynchronous functions to avoid blocking the main thread. This will keep your application responsive.
  • HTML escaping: Always escape HTML entities in your code display to prevent XSS vulnerabilities. Use a function like the escapeHtml function provided in the example.
  • Ignoring errors: Always handle errors gracefully. Use try...catch blocks to catch exceptions and display informative error messages to the user. Log errors on the server to help with debugging.
  • Inefficient search algorithms: For large codebases, a simple linear search can be very slow. Consider using more efficient search algorithms or indexing techniques.

Summary / Key Takeaways

We’ve successfully created a basic web-based code search application using TypeScript! We’ve covered the essential steps, from setting up the development environment and creating a backend with an Express.js server to building a frontend with HTML, CSS, and TypeScript. You’ve learned how to handle user input, make API calls, and display results. You’ve gained practical experience with TypeScript, including type annotations, asynchronous functions, and working with APIs. Remember to adapt the principles and techniques learned here to build more sophisticated and feature-rich code search tools to suit your specific needs. The key is to iterate, experiment, and constantly refine your understanding of both TypeScript and the underlying concepts of code search.

FAQ

Q: Can I use this code search tool for any programming language?

A: Yes, the basic principles apply to any programming language. You would need to adapt the code to read and parse files of that language. The backend would need to handle the specific file extensions and syntax.

Q: How can I improve the performance of the search?

A: For improved performance, consider indexing your code files. An index would map keywords to file locations, allowing for faster lookups. You can also optimize your search algorithm and cache results.

Q: How do I handle large codebases?

A: When dealing with large codebases, you will need to implement indexing to improve search performance. You will also need to consider techniques for handling large files efficiently, such as streaming file content.

Q: What are the best practices for displaying code in the results?

A: Use a `pre` tag for code formatting and a `code` tag to highlight the code. Use syntax highlighting libraries for better readability. Always escape HTML entities to prevent XSS vulnerabilities. Provide context around the search result (e.g., a few lines before and after the matched code).

Q: How can I deploy this application?

A: You can deploy the backend to a platform like Heroku, AWS, or Google Cloud. The frontend can be deployed to a static hosting service like Netlify or Vercel.

Building a code search tool is more than just a coding exercise; it’s a deep dive into the practical application of TypeScript and the principles of software development. It enables you to not only find the code you need quickly but also to understand the structure and functionality of your projects more deeply. The skills you acquire in this process – from managing data and handling user input to designing an efficient search algorithm – are invaluable for any software engineer. As you refine your search tool, you’ll also be honing your problem-solving abilities and expanding your understanding of how software interacts. Keep building, keep learning, and keep exploring the possibilities that TypeScript and code search offer.

More posts