TypeScript Tutorial: Creating a Simple Web Application for a Basic Dictionary

Written by

learnmodernjavascript

in

In the digital age, information is at our fingertips, and dictionaries, once bound in physical volumes, have transformed into accessible online resources. This tutorial guides you through creating a simple, yet functional, web-based dictionary application using TypeScript. You’ll learn the fundamentals of TypeScript while building a practical project that demonstrates how to fetch data from an API, handle user input, and display results dynamically. This project is ideal for both beginners and intermediate developers looking to deepen their understanding of TypeScript and web application development.

Why Build a Dictionary Application?

Building a dictionary application offers several advantages for learning and practicing TypeScript:

  • Practical Application: It allows you to apply core TypeScript concepts in a real-world context.
  • API Interaction: You’ll learn how to fetch data from an external API, a crucial skill for modern web development.
  • User Interface (UI) Interaction: You’ll gain experience in handling user input and dynamically updating the UI.
  • Modular Design: The project can be easily extended and improved, promoting good coding practices.

By the end of this tutorial, you’ll have a working dictionary application and a solid foundation for building more complex web applications using TypeScript.

Prerequisites

Before you start, make sure you have the following:

  • Basic knowledge of HTML, CSS, and JavaScript: Familiarity with these web technologies is essential.
  • Node.js and npm (Node Package Manager) installed: These are required to set up your development environment.
  • A code editor: Choose your preferred code editor (e.g., VS Code, Sublime Text, Atom).
  • TypeScript installed globally: You can install it using npm: npm install -g typescript

Setting Up Your Project

Let’s get started by setting up the project structure:

  1. Create a project directory: Create a new directory for your project, such as dictionary-app.
  2. Initialize npm: Navigate to your project directory in the terminal and run npm init -y. This creates a package.json file.
  3. Create TypeScript configuration file: In the terminal, run tsc --init. This generates a tsconfig.json file, which configures the TypeScript compiler.
  4. Create source files: Create a file named index.html, src/index.ts, and src/style.css in your project directory.

Your project structure should look like this:

dictionary-app/
├── index.html
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts
    └── style.css

Building the HTML Structure (index.html)

Let’s create the basic HTML structure for our dictionary application in index.html:

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

This HTML provides:

  • A title and basic meta tags.
  • A container to hold the content.
  • An input field for the user to enter a word.
  • A button to trigger the search.
  • A div to display the search results.
  • A link to the CSS file and the JavaScript file (which we will create next).

Styling the Application (style.css)

Add some basic styling to src/style.css to improve the application’s appearance:

body {
    font-family: sans-serif;
    margin: 0;
    padding: 0;
    background-color: #f4f4f4;
    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: 600px;
}

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;
}

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

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

#results {
    margin-top: 20px;
    padding: 10px;
    border: 1px solid #ddd;
    border-radius: 4px;
    background-color: #f9f9f9;
}

This CSS provides basic styling for the body, container, headings, input field, button, and results div, making the application more visually appealing.

Writing the TypeScript Logic (src/index.ts)

Now, let’s write the TypeScript code in src/index.ts to handle the dictionary functionality. We’ll break this down into several steps.

1. Define Types and Interfaces

First, define the necessary types and interfaces for the data we’ll be receiving from the API. We’ll use the free Dictionary API from RapidAPI (https://rapidapi.com/dictionaryapi/api/dictionary-by-api-ninjas):


interface Definition {
    definition: string;
    example?: string;
    synonyms?: string[];
    antonyms?: string[];
}

interface Meaning {
    partOfSpeech: string;
    definitions: Definition[];
}

interface WordData {
    word: string;
    phonetic?: string;
    meanings: Meaning[];
}

These interfaces define the structure of the data we’ll be working with. Definition represents a single definition, Meaning represents a part of speech and its definitions, and WordData represents the entire word data including word, phonetic, and meanings.

2. Fetch Data from the API

Next, let’s create a function to fetch the word data from the API. You’ll need to sign up for a free API key from the Dictionary API (https://rapidapi.com/dictionaryapi/api/dictionary-by-api-ninjas) and replace ‘YOUR_API_KEY’ with your actual API key. This function will use the fetch API to make the request and handle the response.


async function getWordData(word: string): Promise<WordData[] | null> {
    const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key
    const apiUrl = `https://api.api-ninjas.com/v1/dictionary?word=${word}`;

    try {
        const response = await fetch(apiUrl, {
            headers: {
                'X-Api-Key': apiKey,
                'Content-Type': 'application/json',
            },
        });

        if (!response.ok) {
            if (response.status === 404) {
                // Word not found
                return null;
            }
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data: WordData[] = await response.json();
        return data;

    } catch (error: any) {
        console.error('Error fetching data:', error);
        return null;
    }
}

This function:

  • Takes a word as input.
  • Constructs the API URL.
  • Uses fetch to make a GET request to the API.
  • Handles potential errors, including 404 (word not found) and other HTTP errors.
  • Parses the response as JSON and returns the word data, or null if an error occurs.

3. Display the Results

Now, let’s create a function to display the results in the results div. This function takes the word data and dynamically generates HTML to display the definitions, part of speech, and other information.


function displayResults(data: WordData[] | null): void {
    const resultsDiv = document.getElementById('results');
    if (!resultsDiv) return;

    resultsDiv.innerHTML = ''; // Clear previous results

    if (!data || data.length === 0) {
        resultsDiv.textContent = 'Word not found.';
        return;
    }

    data.forEach(wordData => {
        const wordHeading = document.createElement('h3');
        wordHeading.textContent = wordData.word;
        resultsDiv.appendChild(wordHeading);

        if (wordData.phonetic) {
            const phonetic = document.createElement('p');
            phonetic.textContent = `Phonetic: ${wordData.phonetic}`;
            resultsDiv.appendChild(phonetic);
        }

        wordData.meanings.forEach(meaning => {
            const partOfSpeechHeading = document.createElement('h4');
            partOfSpeechHeading.textContent = meaning.partOfSpeech;
            resultsDiv.appendChild(partOfSpeechHeading);

            const definitionsList = document.createElement('ul');
            meaning.definitions.forEach(definition => {
                const definitionItem = document.createElement('li');
                definitionItem.textContent = definition.definition;
                definitionsList.appendChild(definitionItem);

                if (definition.example) {
                    const exampleItem = document.createElement('p');
                    exampleItem.textContent = `Example: ${definition.example}`;
                    definitionsList.appendChild(exampleItem);
                }
                if (definition.synonyms && definition.synonyms.length > 0) {
                    const synonymsItem = document.createElement('p');
                    synonymsItem.textContent = `Synonyms: ${definition.synonyms.join(', ')}`;
                    definitionsList.appendChild(synonymsItem);
                }
                if (definition.antonyms && definition.antonyms.length > 0) {
                    const antonymsItem = document.createElement('p');
                    antonymsItem.textContent = `Antonyms: ${definition.antonyms.join(', ')}`;
                    definitionsList.appendChild(antonymsItem);
                }
            });
            resultsDiv.appendChild(definitionsList);
        });
    });
}

This function:

  • Clears any existing content in the results div.
  • Checks if the data is null or empty and displays a “Word not found.” message if necessary.
  • Iterates through the word data and creates HTML elements to display the word, phonetic, part of speech, definitions, examples, synonyms, and antonyms.
  • Appends the created elements to the results div.

4. Handle User Input and Search

Finally, let’s add the event listener to the search button and retrieve the word the user entered in the input field. This function will call the getWordData function and then display the results.


function setupSearch() {
    const searchInput = document.getElementById('search-input') as HTMLInputElement;
    const searchButton = document.getElementById('search-button') as HTMLButtonElement;

    if (!searchInput || !searchButton) return;

    searchButton.addEventListener('click', async () => {
        const word = searchInput.value.trim();
        if (word) {
            const wordData = await getWordData(word);
            displayResults(wordData);
        }
    });
}

setupSearch();

This function:

  • Gets references to the input field and search button.
  • Adds a click event listener to the search button.
  • Retrieves the value from the input field.
  • Calls getWordData to fetch the word data.
  • Calls displayResults to display the data.

Compiling and Running the Application

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

tsc src/index.ts --outDir . --target es5

This command compiles src/index.ts into index.js in the root directory and specifies the target ECMAScript version (ES5 for wider browser compatibility). You can then open index.html in your browser to test the application. If you have a local server set up (recommended for development), you can use that to serve the files.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid or fix them:

  • Incorrect API Key: Double-check that you’ve entered your API key correctly in the getWordData function.
  • CORS Errors: If you encounter CORS (Cross-Origin Resource Sharing) errors, you might need to use a proxy server or configure your development server to handle CORS requests. Many online API services have built-in CORS handling or provide guidance on how to manage it.
  • Type Errors: TypeScript will highlight type errors during development. Make sure your types and interfaces match the data structure returned by the API.
  • Incorrect HTML Element References: Ensure that your document.getElementById() calls correctly match the IDs in your HTML.
  • Not Handling API Errors: Always include error handling in your API calls (e.g., checking response.ok) to gracefully handle situations where the API request fails.

Key Takeaways

  • TypeScript Fundamentals: You’ve used interfaces, types, and asynchronous functions.
  • API Integration: You’ve learned how to fetch data from an external API using fetch.
  • DOM Manipulation: You’ve gained experience in dynamically updating the DOM (Document Object Model) to display data.
  • Error Handling: You’ve implemented basic error handling to make your application more robust.

FAQ

  1. How can I deploy this application?

    You can deploy this application by hosting the HTML, CSS, and JavaScript files on a web server like Netlify, Vercel, or GitHub Pages. Make sure to compile your TypeScript code to JavaScript before deploying.

  2. Can I use a different API?

    Yes, you can use any dictionary API. You’ll need to adjust the API URL and data structure (types/interfaces) accordingly. Be sure to check the API’s documentation.

  3. How can I add more features?

    You can add features like word suggestions, pronunciation audio, and a history of searched words. You can also improve the user interface with more advanced CSS and JavaScript.

  4. How can I handle different languages?

    To support different languages, you would need to find an API that supports multiple languages and adjust the API URL and any language-specific display logic within your JavaScript code.

This tutorial has provided a foundational understanding of building a dictionary application with TypeScript. You’ve learned to integrate APIs, manage user input, and dynamically update the UI. As you continue to build projects and explore TypeScript, you’ll find yourself proficient in creating increasingly complex and feature-rich web applications. The skills you’ve gained here, from setting up the project to handling API responses and displaying data, are fundamental building blocks for your journey in web development.

More posts