TypeScript Tutorial: Building a Simple Web-Based Pomodoro Timer

Written by

learnmodernjavascript

in

In the fast-paced world of software development, time management is crucial. Developers often juggle multiple tasks, deadlines, and the constant need to learn and adapt. The Pomodoro Technique, a time management method, can be a game-changer. It involves working in focused 25-minute intervals (pomodoros) followed by short breaks, interspersed with longer breaks after every four pomodoros. This tutorial will guide you through building a simple, yet functional, web-based Pomodoro timer using TypeScript. We’ll cover the core concepts, step-by-step implementation, and address common pitfalls, equipping you with a practical tool and a solid understanding of TypeScript fundamentals.

Why Build a Pomodoro Timer with TypeScript?

TypeScript offers several advantages for this project. Its static typing helps catch errors early, improving code quality and maintainability. The object-oriented features of TypeScript allow for a structured and organized approach to building the timer’s functionality. Furthermore, TypeScript’s tooling, such as auto-completion and refactoring support, significantly boosts developer productivity. Building this timer is an excellent way to learn and practice these concepts, providing a tangible project to solidify your understanding.

Setting Up Your Development Environment

Before we begin, you’ll need the following:

  • Node.js and npm (or yarn): Node.js provides the JavaScript runtime environment, and npm (Node Package Manager) or yarn is used for managing project dependencies.
  • A Text Editor or IDE: Visual Studio Code (VS Code) is highly recommended due to its excellent TypeScript support.

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

mkdir pomodoro-timer
cd pomodoro-timer
npm init -y

This will create a package.json file. Next, install TypeScript and a bundler like Parcel or Webpack. For simplicity, we’ll use Parcel:

npm install typescript parcel-bundler --save-dev

Now, initialize a TypeScript configuration file:

npx tsc --init

This creates a tsconfig.json file. You can customize this file to configure TypeScript compilation options. For this project, you can start with the default settings. Create a src directory and a file named index.ts inside it. This is where our code will reside.

Designing the HTML Structure

Create an index.html file in the project root. This file will contain the basic structure of our Pomodoro timer:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Pomodoro Timer</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="container">
        <h1 id="timer-display">25:00</h1>
        <div class="controls">
            <button id="start-button">Start</button>
            <button id="stop-button">Stop</button>
            <button id="reset-button">Reset</button>
        </div>
        <p id="status">Pomodoro</p>
    </div>
    <script src="index.ts"></script>
</body>
</html>

This HTML provides:

  • A container to hold the timer elements.
  • A display to show the remaining time.
  • Start, Stop, and Reset buttons.
  • A status indicator (e.g., “Pomodoro,” “Short Break,” “Long Break”).

Also, create an empty style.css file in the project root. We’ll add styling later.

Writing the TypeScript Code

Now, let’s write the TypeScript code in src/index.ts. This is where the core logic of our timer resides.


// Define the different states of the timer.
enum TimerState {
    Pomodoro = "Pomodoro",
    ShortBreak = "Short Break",
    LongBreak = "Long Break"
}

// Get references to HTML elements.
const timerDisplay = document.getElementById("timer-display") as HTMLHeadingElement;
const startButton = document.getElementById("start-button") as HTMLButtonElement;
const stopButton = document.getElementById("stop-button") as HTMLButtonElement;
const resetButton = document.getElementById("reset-button") as HTMLButtonElement;
const statusDisplay = document.getElementById("status") as HTMLParagraphElement;

// Define timer settings.
const pomodoroDuration = 25 * 60; // 25 minutes in seconds
const shortBreakDuration = 5 * 60; // 5 minutes in seconds
const longBreakDuration = 15 * 60; // 15 minutes in seconds
const longBreakInterval = 4; // Every 4 pomodoros

// Initialize timer variables.
let timerInterval: number | undefined;
let timeLeft: number = pomodoroDuration;
let timerState: TimerState = TimerState.Pomodoro;
let pomodoroCount: number = 0;

// Function to format time as MM:SS.
const formatTime = (seconds: number): string => {
    const minutes = Math.floor(seconds / 60);
    const remainingSeconds = seconds % 60;
    const formattedMinutes = String(minutes).padStart(2, '0');
    const formattedSeconds = String(remainingSeconds).padStart(2, '0');
    return `${formattedMinutes}:${formattedSeconds}`;
};

// Function to update the timer display.
const updateDisplay = () => {
    if (timerDisplay) {
        timerDisplay.textContent = formatTime(timeLeft);
    }
};

// Function to update the status display.
const updateStatus = () => {
    if (statusDisplay) {
        statusDisplay.textContent = timerState;
    }
};

// Function to start the timer.
const startTimer = () => {
    if (timerInterval) return; // Prevent multiple intervals.

    timerInterval = setInterval(() => {
        timeLeft--;
        updateDisplay();

        if (timeLeft <= 0) {
            clearInterval(timerInterval);
            timerInterval = undefined;
            switchTimerState();
            startTimer(); // Start the next timer.
        }
    }, 1000);
};

// Function to stop the timer.
const stopTimer = () => {
    if (timerInterval) {
        clearInterval(timerInterval);
        timerInterval = undefined;
    }
};

// Function to reset the timer.
const resetTimer = () => {
    stopTimer();
    timeLeft = pomodoroDuration;
    timerState = TimerState.Pomodoro;
    pomodoroCount = 0;
    updateDisplay();
    updateStatus();
};

// Function to switch between timer states.
const switchTimerState = () => {
    pomodoroCount++;

    if (timerState === TimerState.Pomodoro) {
        if (pomodoroCount % longBreakInterval === 0) {
            timerState = TimerState.LongBreak;
            timeLeft = longBreakDuration;
        } else {
            timerState = TimerState.ShortBreak;
            timeLeft = shortBreakDuration;
        }
    } else {
        timerState = TimerState.Pomodoro;
        timeLeft = pomodoroDuration;
    }

    updateStatus();
};

// Event listeners for the buttons.
startButton?.addEventListener("click", startTimer);
stopButton?.addEventListener("click", stopTimer);
resetButton?.addEventListener("click", resetTimer);

// Initial display update.
updateDisplay();
updateStatus();

Let’s break down this code:

  • Enums: The TimerState enum defines the different states of the timer, making the code more readable and maintainable.
  • Element References: We get references to the HTML elements to manipulate them. The as HTML...Element syntax is type assertion, telling TypeScript what type of element each variable refers to.
  • Timer Settings: Constants define the duration of each timer state.
  • Timer Variables: Variables to manage the timer’s state (interval ID, remaining time, current state, and pomodoro count).
  • formatTime() Function: Converts seconds into a user-friendly MM:SS format.
  • updateDisplay() and updateStatus() Functions: Updates the timer and status displays in the HTML.
  • startTimer() Function: Starts the timer interval, decrementing the timeLeft every second. When the timer reaches zero, it calls switchTimerState() to change the timer mode.
  • stopTimer() Function: Clears the timer interval, effectively stopping the timer.
  • resetTimer() Function: Resets the timer to its initial state.
  • switchTimerState() Function: Handles switching between Pomodoro, Short Break, and Long Break states, based on the pomodoroCount.
  • Event Listeners: Attaches event listeners to the buttons to trigger the corresponding actions (start, stop, reset).

Adding Styling with CSS

Now, let’s add some basic styling to style.css to make our timer visually appealing:


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

.container {
    background-color: #fff;
    padding: 20px;
    border-radius: 8px;
    box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
    text-align: center;
}

#timer-display {
    font-size: 3em;
    margin-bottom: 20px;
}

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

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

#status {
    font-style: italic;
}

Building and Running the Application

To build and run the application, use Parcel. In your terminal, run:

npx parcel index.html

Parcel will bundle your HTML, TypeScript, and CSS files and start a development server. You can then open the provided URL (usually http://localhost:1234) in your browser to see the running Pomodoro timer. Parcel automatically reloads the page when you make changes to your code.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

  • Incorrect Element Selection: Make sure your document.getElementById() calls correctly target the HTML elements. Double-check your element IDs in the HTML. Use type assertions (e.g., as HTMLButtonElement) to help TypeScript catch errors related to element types.
  • Incorrect Time Formatting: Ensure your formatTime() function correctly formats the time. The padStart() method is crucial for adding leading zeros.
  • Unclear Timer State Transitions: The logic for switching between timer states can be tricky. Carefully review the conditions in the switchTimerState() function to ensure the timer transitions correctly.
  • Multiple Timer Intervals: Prevent multiple timer intervals from running simultaneously. Use a check in the startTimer() function (if (timerInterval) return;) to avoid this.
  • Missing Event Listeners: Ensure your event listeners are correctly attached to the buttons. If the buttons don’t work, verify that the event listeners are properly set up.

Enhancements and Further Development

This is a basic Pomodoro timer. You can extend it with these features:

  • Sound Notifications: Add sound notifications at the end of each timer interval.
  • Customizable Durations: Allow users to customize the Pomodoro, short break, and long break durations.
  • User Interface Improvements: Improve the user interface with more advanced styling, progress bars, or visual cues.
  • Persistence: Save user settings and timer data (e.g., number of pomodoros completed) using local storage.
  • Integration with Task Management: Integrate the timer with a task management system to track time spent on specific tasks.

Summary / Key Takeaways

This tutorial provided a step-by-step guide to building a web-based Pomodoro timer using TypeScript, demonstrating the power and benefits of static typing, object-oriented programming, and modern web development practices. We covered setting up the development environment, designing the HTML structure, writing the TypeScript code to handle the timer’s logic, adding styling with CSS, and finally, running the application. You’ve gained practical experience with essential TypeScript concepts, including enums, event listeners, and time manipulation. The project also highlights the importance of modularity, code organization, and the benefits of using a bundler like Parcel for development. Understanding these concepts will empower you to create more complex and robust web applications. By applying the principles learned in this tutorial, you can effectively manage your time, improve your productivity, and enhance your software development workflow.

FAQ

Q: How do I handle errors in my TypeScript code?

A: TypeScript’s static typing helps catch many errors during development. Use the try...catch blocks for runtime errors. Also, use the browser’s developer tools to inspect the console for error messages.

Q: What is the purpose of the tsconfig.json file?

A: The tsconfig.json file configures the TypeScript compiler. It specifies compilation options, such as the target JavaScript version, module system, and whether to enable strict type checking. It is crucial for customizing how your TypeScript code is compiled.

Q: How can I debug my TypeScript code?

A: Most IDEs (like VS Code) have built-in debugging support for TypeScript. You can set breakpoints in your code, inspect variables, and step through the execution. Also, use console.log() statements to print values and trace the execution flow.

Q: Why use a bundler like Parcel?

A: A bundler simplifies the development process by handling tasks such as compiling TypeScript, bundling JavaScript and CSS files, and optimizing assets. It also provides features like hot module replacement, which automatically updates the browser when you make changes to your code, improving the development workflow.

Q: How can I deploy my Pomodoro timer to the web?

A: You can deploy your application to platforms like Netlify, Vercel, or GitHub Pages. These platforms provide free hosting and automatically build and deploy your application from a code repository. You can also use a traditional web server if you prefer.

By following the steps and understanding the concepts presented in this tutorial, you’ve gained the knowledge and skills to build a functional and practical Pomodoro timer. This project serves as a solid foundation for further exploring TypeScript and web development. You can now adapt and expand this project to meet your specific needs, customizing the timer’s features and functionality to enhance your productivity and time management skills. The knowledge acquired from this simple project can be applied to more complex web applications, making you a more proficient and effective developer. Now, go forth and build, armed with the power of TypeScript and the Pomodoro Technique to conquer your tasks and achieve your goals.

More posts