TypeScript Tutorial: Building a Simple Interactive Web-Based Recipe Search

Written by

learnmodernjavascript

in

In the digital age, we’re constantly bombarded with information. Finding the right recipe amidst the chaos of the internet can feel like searching for a needle in a haystack. Have you ever spent what feels like an eternity scrolling through endless websites, only to find a recipe that’s either poorly written or doesn’t quite fit your needs? This tutorial will guide you through building a simple, yet effective, web-based recipe search application using TypeScript. We’ll focus on creating a user-friendly interface that allows users to quickly search for recipes, view ingredients, and understand the steps involved in cooking their favorite dishes. This hands-on project will not only teach you the fundamentals of TypeScript but also provide a practical application for your skills.

Why TypeScript?

TypeScript, a superset of JavaScript, brings static typing to your projects. This means you can catch errors early in the development process, improving code quality and reducing debugging time. TypeScript also offers better code organization and enhanced autocompletion, making development more efficient and enjoyable. For this project, TypeScript will help us define the structure of our recipe data, ensuring consistency and preventing common data-related bugs.

Project Overview

Our recipe search application will have the following features:

  • A search bar to enter recipe keywords.
  • A display area to show recipe results.
  • The ability to view detailed recipe information, including ingredients and instructions.
  • A clean and intuitive user interface.

We’ll use HTML for the structure, CSS for styling, and TypeScript for the logic. We’ll keep the design simple to focus on the TypeScript aspects. Let’s get started!

Setting Up Your Development Environment

Before diving into the code, make sure you have the following installed:

  • Node.js and npm (Node Package Manager): These are essential for managing project dependencies and running TypeScript. You can download them from https://nodejs.org/.
  • A Code Editor: A code editor like Visual Studio Code (VS Code), Sublime Text, or Atom will make writing and editing code much easier. VS Code is a popular choice and offers excellent TypeScript support.

Once you have these installed, create a new project directory and navigate into it in your terminal. Then, initialize a new npm project by running:

npm init -y

This command creates a `package.json` file, which will store your project’s metadata and dependencies.

Installing TypeScript

Next, install TypeScript as a development dependency:

npm install --save-dev typescript

This command installs the TypeScript compiler (`tsc`) and saves it as a development dependency in your `package.json` file. Now, create a `tsconfig.json` file in your project root. This file tells the TypeScript compiler how to compile your code. You can generate a basic `tsconfig.json` by running:

npx tsc --init

This command creates a `tsconfig.json` file with default configurations. Open this file in your code editor and customize the settings as needed. For this project, you might want to uncomment and adjust the following settings:

  • "target": "es5": Specifies the JavaScript version to compile to. `es5` is widely supported.
  • "module": "commonjs": Specifies the module system to use. `commonjs` is a common choice for Node.js projects.
  • "outDir": "./dist": Specifies the output directory for the compiled JavaScript files.
  • "strict": true: Enables strict type checking. This is generally recommended.

Here’s an example of how your `tsconfig.json` might look:

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

Project Structure

Let’s set up a basic project structure. Create the following directories and files in your project root:

  • src/: This directory will contain your TypeScript source code.
  • src/index.ts: The main entry point for your application’s logic.
  • public/: This directory will contain your HTML and CSS files.
  • public/index.html: The main HTML file.
  • public/style.css: The CSS file for styling.

Defining Recipe Data with TypeScript

One of the key benefits of TypeScript is its ability to define data structures using types and interfaces. Let’s create an interface to represent a recipe. In your `src/index.ts` file, add the following code:

interface Recipe {
  title: string;
  ingredients: string[];
  instructions: string[];
  image?: string; // Optional image URL
}

This code defines an interface named `Recipe`. It specifies the properties each recipe object should have: `title` (a string), `ingredients` (an array of strings), `instructions` (an array of strings), and an optional `image` (a string). This structure ensures that all recipe data conforms to a consistent format, preventing type-related errors.

Creating the HTML Structure

Now, let’s create the basic HTML structure for our recipe search application. Open `public/index.html` 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>Recipe Search</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <div class="container">
    <h1>Recipe Search</h1>
    <div class="search-bar">
      <input type="text" id="search-input" placeholder="Search for recipes...">
      <button id="search-button">Search</button>
    </div>
    <div id="recipe-results">
      <!-- Recipe results will be displayed here -->
    </div>
  </div>
  <script src="index.js"></script>
</body>
</html>

This HTML provides a basic layout with a title, a search bar (input field and button), and a `div` element (`recipe-results`) where we’ll display the search results. The `<script src=”index.js”></script>` tag links to the compiled JavaScript file, which we’ll generate from our TypeScript code.

Adding Basic Styling with CSS

To make the application visually appealing, let’s add some basic styling. Open `public/style.css` and add the following CSS rules:

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

.container {
  max-width: 800px;
  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;
}

.search-bar {
  display: flex;
  margin-bottom: 20px;
}

#search-input {
  flex-grow: 1;
  padding: 10px;
  border: 1px solid #ccc;
  border-radius: 4px;
}

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

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

.recipe-card {
  border: 1px solid #ddd;
  padding: 15px;
  margin-bottom: 15px;
  border-radius: 8px;
  background-color: #f9f9f9;
}

.recipe-card h3 {
  margin-top: 0;
  color: #333;
}

.recipe-card img {
  max-width: 100%;
  height: auto;
  border-radius: 4px;
  margin-bottom: 10px;
}

.recipe-card ul {
  padding-left: 20px;
}

This CSS provides a basic layout, styling for the search bar, and some basic formatting for recipe cards. Feel free to customize the styles to your liking.

Writing the TypeScript Logic

Now, let’s write the core TypeScript logic for our recipe search application. Open `src/index.ts` and add the following code:

// Import the Recipe interface (if needed)
// import { Recipe } from './recipe'; // Assuming you have a recipe.ts file

// Sample recipe data (replace with a real API call later)
const recipes: Recipe[] = [
  {
    title: "Spaghetti Carbonara",
    ingredients: [
      "Spaghetti",
      "Eggs",
      "Pancetta",
      "Parmesan cheese",
      "Black pepper"
    ],
    instructions: [
      "Cook spaghetti according to package directions.",
      "Fry pancetta until crispy.",
      "Whisk eggs with parmesan and pepper.",
      "Combine cooked spaghetti, pancetta, and egg mixture.",
      "Serve immediately."
    ],
  },
  {
    title: "Chicken Stir-Fry",
    ingredients: [
      "Chicken breast",
      "Soy sauce",
      "Broccoli",
      "Carrots",
      "Rice"
    ],
    instructions: [
      "Cut chicken into small pieces.",
      "Stir-fry chicken with vegetables.",
      "Add soy sauce.",
      "Serve over rice."
    ],
  },
];

// Get references to HTML elements
const searchInput = document.getElementById('search-input') as HTMLInputElement;
const searchButton = document.getElementById('search-button') as HTMLButtonElement;
const recipeResults = document.getElementById('recipe-results') as HTMLDivElement;

// Function to display recipes
function displayRecipes(recipesToDisplay: Recipe[]): void {
  recipeResults.innerHTML = ''; // Clear previous results

  recipesToDisplay.forEach(recipe => {
    const recipeCard = document.createElement('div');
    recipeCard.classList.add('recipe-card');

    // Optional image (if available)
    const imageHTML = recipe.image ? `<img src="${recipe.image}" alt="${recipe.title}">` : '';

    recipeCard.innerHTML = `
      ${imageHTML}
      <h3>${recipe.title}</h3>
      <h4>Ingredients:</h4>
      <ul>${recipe.ingredients.map(ingredient => `<li>${ingredient}</li>`).join('')}</ul>
      <h4>Instructions:</h4>
      <ul>${recipe.instructions.map(instruction => `<li>${instruction}</li>`).join('')}</ul>
    `;

    recipeResults.appendChild(recipeCard);
  });
}

// Function to filter recipes based on search query
function filterRecipes(query: string): Recipe[] {
  const searchTerm = query.toLowerCase();
  return recipes.filter(recipe =>
    recipe.title.toLowerCase().includes(searchTerm)
  );
}

// Event listener for the search button
searchButton.addEventListener('click', () => {
  const searchTerm = searchInput.value;
  const filteredRecipes = filterRecipes(searchTerm);
  displayRecipes(filteredRecipes);
});

// Initial display (show all recipes on page load)
displayRecipes(recipes);

Let’s break down this code:

  • Import (Optional): If you defined the `Recipe` interface in a separate file (e.g., `recipe.ts`), you would import it here: `import { Recipe } from ‘./recipe’;`. This promotes code organization.
  • Sample Recipe Data: We create an array of `Recipe` objects. In a real application, you’d likely fetch this data from an API (we’ll cover that later).
  • HTML Element References: We get references to the HTML elements we’ll be interacting with (search input, search button, and recipe results area). The `as HTMLInputElement` and `as HTMLButtonElement` are type assertions, telling TypeScript the expected type of these elements.
  • `displayRecipes` Function: This function takes an array of `Recipe` objects and dynamically creates HTML elements to display them in the `recipe-results` div. It clears any previous results and then iterates through the recipes, creating a `recipe-card` for each one. It uses template literals (backticks) to build the HTML for each recipe card.
  • `filterRecipes` Function: This function takes a search query as input and returns a new array containing only the recipes whose titles match the search query (case-insensitive).
  • 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, filters the recipes using the `filterRecipes` function, and then calls `displayRecipes` to display the filtered results.
  • Initial Display: The `displayRecipes` function is called initially to display all recipes when the page loads.

Compiling and Running the Application

Now, let’s compile your TypeScript code and run the application. In your terminal, run the following command from your project root:

tsc

This command will compile your `src/index.ts` file and generate a corresponding `index.js` file in the `dist/` directory (as specified in your `tsconfig.json`). To serve the application, you can use a simple web server. A convenient option is the `serve` package, which you can install globally:

npm install -g serve

Then, navigate to your `public/` directory in your terminal and run:

serve

This will start a local web server, and you can access your application in your web browser (usually at `http://localhost:5000` or a similar address). Open your browser and navigate to the address provided by `serve`. You should see the recipe search application with a search bar and the initial list of recipes.

Adding Real-World Data (API Integration)

The sample data we’re using is fine for testing, but in a real-world application, you’d fetch recipe data from an API. Let’s modify our code to fetch data from a public API. For this example, we’ll use a free API like Spoonacular (you’ll need to sign up for an API key). Let’s assume you have an API key and the API endpoint is `https://api.spoonacular.com/recipes/complexSearch?apiKey=[YOUR_API_KEY]&query=[SEARCH_TERM]&number=10`. Replace `[YOUR_API_KEY]` with your actual API key.

Modify the `src/index.ts` file as follows:

interface Recipe {
  title: string;
  ingredients: string[];
  instructions: string[];
  image?: string; // Optional image URL
}

// Get references to HTML elements
const searchInput = document.getElementById('search-input') as HTMLInputElement;
const searchButton = document.getElementById('search-button') as HTMLButtonElement;
const recipeResults = document.getElementById('recipe-results') as HTMLDivElement;

// Function to fetch recipes from the API
async function fetchRecipes(query: string): Promise<Recipe[]> {
  const apiKey = "YOUR_API_KEY"; // Replace with your actual API key
  const apiUrl = `https://api.spoonacular.com/recipes/complexSearch?apiKey=${apiKey}&query=${query}&number=10`;

  try {
    const response = await fetch(apiUrl);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();

    // Adapt the data to our Recipe interface
    const recipes: Recipe[] = data.results.map((recipe: any) => ({
      title: recipe.title,
      ingredients: [], // The Spoonacular API doesn't directly provide ingredients in this endpoint; you might need another API call
      instructions: [], // The Spoonacular API doesn't directly provide instructions in this endpoint; you might need another API call
      image: recipe.image,
    }));

    return recipes;
  } catch (error: any) {
    console.error('Error fetching recipes:', error);
    // Handle errors (e.g., display an error message to the user)
    return [];
  }
}

// Function to display recipes
function displayRecipes(recipesToDisplay: Recipe[]): void {
  recipeResults.innerHTML = ''; // Clear previous results

  recipesToDisplay.forEach(recipe => {
    const recipeCard = document.createElement('div');
    recipeCard.classList.add('recipe-card');

    // Optional image (if available)
    const imageHTML = recipe.image ? `<img src="${recipe.image}" alt="${recipe.title}">` : '';

    recipeCard.innerHTML = `
      ${imageHTML}
      <h3>${recipe.title}</h3>
      <h4>Ingredients:</h4>
      <ul><li>Ingredients not available from this API</li></ul>
      <h4>Instructions:</h4>
      <ul><li>Instructions not available from this API</li></ul>
    `;

    recipeResults.appendChild(recipeCard);
  });
}

// Event listener for the search button
searchButton.addEventListener('click', async () => {
  const searchTerm = searchInput.value;
  const recipes = await fetchRecipes(searchTerm);
  displayRecipes(recipes);
});

// Initial display (no initial recipes, as we fetch from API)
// displayRecipes(recipes);

Key changes in this code:

  • `fetchRecipes` Function: This asynchronous function uses the `fetch` API to retrieve recipe data from the Spoonacular API. It constructs the API URL, makes the request, and parses the JSON response. It also includes error handling (using a `try…catch` block) to gracefully handle API errors. Note that the Spoonacular API might require additional API calls to get the full ingredient and instruction details, which is outside the scope of this simplified example. You might need to adjust the data mapping within the `fetchRecipes` function based on the API response structure.
  • `async/await`: The `fetchRecipes` function is declared as `async`, and it uses `await` to handle the asynchronous API calls. This makes the code more readable and easier to follow.
  • API Key: Remember to replace `”YOUR_API_KEY”` with your actual API key.
  • Event Listener Modification: The event listener for the search button now calls the `fetchRecipes` function and then calls `displayRecipes` with the fetched data.
  • Data Mapping: The `map` function transforms the API response data into the `Recipe` interface format. You’ll need to adjust this mapping based on the actual structure of the API response.
  • Initial Display Removed: The initial display of recipes is removed since we are fetching data from the API. The recipes will be displayed after a search is performed.

After making these changes, recompile your TypeScript code (`tsc`) and refresh your browser. Now, when you enter a search term and click the search button, the application should fetch and display recipes from the Spoonacular API (or any API you choose), provided you have a valid API key and have adapted the code to the API’s response structure. You might need to inspect the API response in your browser’s developer tools (Network tab) to understand the data structure and map the data correctly.

Handling Errors

Error handling is crucial for creating a robust application. Here are some common errors you might encounter and how to address them:

  • API Errors: The `fetchRecipes` function already includes basic error handling using a `try…catch` block. You can enhance this by displaying user-friendly error messages in the UI if the API request fails (e.g., “Failed to fetch recipes. Please try again later.”).
  • Network Errors: Network connectivity issues can also cause API requests to fail. You should handle these errors gracefully, perhaps by displaying a message like “No internet connection.”
  • Invalid API Key: If you use an incorrect API key, the API will likely return an error. Handle this situation by displaying an appropriate message to the user (e.g., “Invalid API key. Please check your configuration.”).
  • Data Parsing Errors: If the API response data doesn’t match the expected format, you might encounter errors during data mapping. Use `try…catch` blocks within the `fetchRecipes` function to handle these types of errors. Log the error to the console for debugging, and provide a fallback or informative message to the user.

Example of displaying an error message to the user:

// Inside the fetchRecipes function
} catch (error: any) {
  console.error('Error fetching recipes:', error);
  recipeResults.innerHTML = '<p class="error-message">Failed to fetch recipes. Please try again.</p>';
  return [];
}

Remember to add CSS styling for the `.error-message` class.

Common Mistakes and How to Fix Them

Here are some common mistakes beginners make when working with TypeScript and web applications, along with tips on how to fix them:

  • Incorrect TypeScript Setup: Double-check your `tsconfig.json` file. Ensure that the compiler options are configured correctly (e.g., `target`, `module`, `outDir`, `strict`). If you’re having trouble, try deleting the `tsconfig.json` and running `npx tsc –init` again to generate a fresh configuration.
  • Type Errors: TypeScript’s static typing can be both a blessing and a curse. If you encounter type errors, carefully read the error messages. They usually provide helpful information about what’s wrong. Use type annotations (`: string`, `: number`, etc.) to explicitly specify the types of variables and function parameters. Use interfaces or types to define the structure of your data.
  • Incorrect DOM Manipulation: When working with the DOM (Document Object Model), make sure you’re selecting the correct HTML elements using `document.getElementById()`, `document.querySelector()`, etc. Use type assertions (e.g., `as HTMLInputElement`) to help TypeScript understand the type of the element you’re working with.
  • Asynchronous Operations: When working with asynchronous operations (e.g., API calls), use `async/await` to make your code more readable and easier to manage. Remember to handle potential errors using `try…catch` blocks.
  • Incorrect Module Imports: If you’re using module imports (e.g., `import { Recipe } from ‘./recipe’;`), make sure the file paths are correct. Double-check the file extensions (e.g., `.ts` for TypeScript files).
  • Forgetting to Compile: Remember to compile your TypeScript code (`tsc`) after making changes. If you’re using a build process, make sure it’s configured to automatically compile your code whenever you save changes.
  • Not Understanding the API Response: When integrating with an API, carefully inspect the API’s documentation and the response data structure. Use your browser’s developer tools (Network tab) to see the actual API responses. This will help you map the data correctly to your TypeScript interfaces.

Key Takeaways

  • TypeScript Fundamentals: You’ve learned how to use interfaces, types, and type annotations to define data structures and improve code quality.
  • DOM Manipulation: You’ve gained experience in selecting HTML elements and dynamically updating the content of a web page.
  • Asynchronous Programming: You’ve learned how to use `async/await` to handle asynchronous API calls.
  • API Integration: You’ve learned how to fetch data from an API and integrate it into your web application.
  • Error Handling: You’ve learned the importance of error handling and how to handle common errors in your code.

FAQ

Here are some frequently asked questions:

  1. What is TypeScript? TypeScript is a superset of JavaScript that adds static typing. It helps you write more reliable and maintainable code by catching errors early in the development process.
  2. Why use TypeScript? TypeScript improves code quality, reduces debugging time, and enhances code organization. It also offers better autocompletion and refactoring support.
  3. How do I compile TypeScript code? You compile TypeScript code using the `tsc` command (the TypeScript compiler). This command converts your TypeScript files (with the `.ts` extension) into JavaScript files (with the `.js` extension).
  4. How do I handle API errors? Use `try…catch` blocks to handle potential errors during API calls. Display user-friendly error messages in the UI to inform the user about the issue.
  5. Where can I find more resources on TypeScript? The official TypeScript documentation (https://www.typescriptlang.org/docs/) is an excellent resource. You can also find many tutorials and examples online.

Building a web-based recipe search application is a rewarding project that combines core web development skills with the power of TypeScript. By following this tutorial, you’ve gained practical experience with TypeScript fundamentals, DOM manipulation, asynchronous programming, and API integration. The ability to define data structures, handle user input, and fetch data from external sources opens up a world of possibilities for creating dynamic and interactive web applications. As you continue to explore TypeScript, remember to practice, experiment, and embrace the benefits of static typing. The journey of learning never truly ends; the more you delve into it, the more you will discover, and the better you will become. Whether you are creating a recipe search or any other web application, the principles you’ve learned here will serve as a solid foundation for your future projects, empowering you to build more robust and maintainable software.

More posts