TypeScript Tutorial: Creating a Simple Web-Based Pomodoro Timer

Written by

learnmodernjavascript

in

In the fast-paced world we live in, effective time management is crucial for productivity and well-being. The Pomodoro Technique, a time management method developed by Francesco Cirillo, can help you stay focused and accomplish more in less time. This tutorial will guide you through creating a simple, web-based Pomodoro timer using TypeScript, a powerful superset of JavaScript that adds static typing.

Why Build a Pomodoro Timer with TypeScript?

While numerous Pomodoro timers are available, building your own offers several advantages. Firstly, it allows you to learn and practice TypeScript, enhancing your programming skills. Secondly, you gain complete control over the timer’s functionality and appearance, customizing it to your specific needs. Finally, it’s a fun and rewarding project that demonstrates your ability to build interactive web applications.

This tutorial is designed for beginners to intermediate developers. We’ll break down the process step-by-step, explaining the concepts and providing code examples with comments. By the end, you’ll have a functional Pomodoro timer and a solid understanding of fundamental TypeScript concepts.

Setting Up Your Development Environment

Before we begin, ensure you have the following installed:

  • Node.js and npm (Node Package Manager): Used for managing project dependencies and running the development server. Download from nodejs.org.
  • A Code Editor: Such as Visual Studio Code (VS Code), Atom, or Sublime Text. VS Code is highly recommended due to its excellent TypeScript support.
  • TypeScript Compiler: Install it globally using npm: npm install -g typescript

Project Structure

Let’s create a basic project structure:

  1. Create a new directory for your project (e.g., `pomodoro-timer`).
  2. Inside the directory, create the following files and folders:
    • index.html (HTML file for the user interface)
    • src/ (directory for your TypeScript source code)
    • src/index.ts (main TypeScript file)
    • tsconfig.json (TypeScript configuration file)

Configuring TypeScript (tsconfig.json)

The tsconfig.json file tells the TypeScript compiler how to compile your code. Create this file in the root directory of your project with the following content:

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

Explanation of key options:

  • target: Specifies the JavaScript version to compile to (es5 for broader browser compatibility).
  • module: Specifies the module system (commonjs for Node.js).
  • outDir: Specifies the output directory for the compiled JavaScript files (dist).
  • rootDir: Specifies the root directory of your TypeScript files (src).
  • strict: Enables strict type checking. Highly recommended for catching errors early.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • skipLibCheck: Skips type checking of declaration files (improves compilation speed).
  • forceConsistentCasingInFileNames: Enforces consistent casing in file names.
  • include: Specifies which files to include in the compilation.

Building the HTML (index.html)

Create the basic HTML structure for your Pomodoro timer 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>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>
    </div>
    <script src="dist/index.js"></script>
</body>
</html>

This HTML includes:

  • A title and meta tags for responsiveness.
  • A container div for the timer.
  • An h1 element to display the timer (initially set to 25:00).
  • A div for the control buttons (Start, Stop, Reset).
  • A link to a stylesheet (style.css – we’ll create this later).
  • A script tag to include the compiled JavaScript file (index.js) in the dist folder.

Styling with CSS (style.css)

Create a basic CSS file (style.css) to style your timer. Place this file in the same directory as your index.html file.

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

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

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

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

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

Writing the TypeScript Code (src/index.ts)

This is where the magic happens. Open src/index.ts and add the following code:


// Define constants for the timer durations in minutes
const WORK_DURATION: number = 25;
const BREAK_DURATION: number = 5;

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

// Initialize variables
let timeLeft: number = WORK_DURATION * 60; // Time remaining in seconds
let timerInterval: number | undefined;
let isRunning: boolean = false;
let isBreak: boolean = false;

// Function to format the time into MM:SS format
function formatTime(seconds: number): string {
  const minutes = Math.floor(seconds / 60);
  const remainingSeconds = seconds % 60;
  const minutesString = String(minutes).padStart(2, '0');
  const secondsString = String(remainingSeconds).padStart(2, '0');
  return `${minutesString}:${secondsString}`;
}

// Function to update the timer display
function updateTimerDisplay(): void {
  if (timerDisplay) {
    timerDisplay.textContent = formatTime(timeLeft);
  }
}

// Function to start the timer
function startTimer(): void {
  if (isRunning) return; // Prevent multiple timers
  isRunning = true;
  timerInterval = setInterval(() => {
    timeLeft--;
    if (timeLeft < 0) {
      clearInterval(timerInterval);
      isRunning = false;
      if (isBreak) {
        timeLeft = WORK_DURATION * 60; // Reset to work time
        isBreak = false;
        alert("Break is over! Time to work.");
      } else {
        timeLeft = BREAK_DURATION * 60; // Start break
        isBreak = true;
        alert("Time for a break!");
      }
      updateTimerDisplay();
      startTimer(); // Start the timer again
      return;
    }
    updateTimerDisplay();
  }, 1000);
}

// Function to stop the timer
function stopTimer(): void {
  clearInterval(timerInterval);
  isRunning = false;
}

// Function to reset the timer
function resetTimer(): void {
  stopTimer();
  timeLeft = WORK_DURATION * 60;
  isBreak = false;
  updateTimerDisplay();
}

// Add event listeners to the buttons
startButton.addEventListener('click', startTimer);
stopButton.addEventListener('click', stopTimer);
resetButton.addEventListener('click', resetTimer);

// Initial display update
updateTimerDisplay();

Code Explanation:

  • Constants: WORK_DURATION and BREAK_DURATION store the work and break durations in minutes.
  • Element References: The code gets references to the HTML elements using their IDs. The as HTMLHeadingElement and as HTMLButtonElement are type assertions, telling TypeScript the expected type of the elements. This helps with type safety.
  • Variables:
    • timeLeft: Stores the remaining time in seconds.
    • timerInterval: Stores the interval ID returned by setInterval.
    • isRunning: A boolean flag to track if the timer is running.
    • isBreak: A boolean flag to track if it’s currently a break period.
  • formatTime(seconds: number): string: This function takes the time in seconds and formats it into a MM:SS string (e.g., “25:00”).
  • updateTimerDisplay(): void: Updates the content of the timer display element with the formatted time.
  • startTimer(): void:
    • Checks if the timer is already running to prevent multiple timers.
    • Sets isRunning to true.
    • Uses setInterval to decrement timeLeft every second (1000 milliseconds).
    • Inside the setInterval callback:
      • Checks if timeLeft is less than 0 (timer finished).
      • Clears the interval using clearInterval.
      • Toggles between work and break periods using the isBreak flag.
      • Resets timeLeft to the appropriate duration.
      • Displays an alert to notify the user. (consider using a more user-friendly notification in a real app)
      • Calls updateTimerDisplay() to update the display.
      • Recursively calls startTimer() to restart the timer for the next cycle.
  • stopTimer(): void: Clears the interval using clearInterval and sets isRunning to false.
  • resetTimer(): void: Stops the timer, resets timeLeft to the work duration, and updates the display.
  • Event Listeners: Adds event listeners to the Start, Stop, and Reset buttons to call the corresponding functions when clicked.
  • Initial Display Update: Calls updateTimerDisplay() to initialize the timer display when the page loads.

Compiling and Running the Application

Now, let’s compile the TypeScript code and run the application:

  1. Compile the TypeScript code: Open your terminal or command prompt, navigate to your project directory, and run: tsc
  2. This will create a dist folder containing the compiled JavaScript file (index.js).
  3. Open index.html in your web browser: You can double-click the HTML file or use a local web server (e.g., live-server, which you can install via npm: npm install -g live-server, and then run live-server in your project directory).
  4. You should see the Pomodoro timer interface. Click “Start” to begin the timer.

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 <script src="dist/index.js"></script> tag) and CSS files (<link rel="stylesheet" href="style.css">).
  • Typos: Carefully review your code for typos, especially in variable names, function names, and HTML element IDs. TypeScript’s strict mode can help catch these errors.
  • Incorrect Element References: Make sure the IDs in your TypeScript code match the IDs in your HTML (e.g., document.getElementById('timer-display')).
  • Compiler Errors: If you encounter compiler errors (e.g., “Cannot find name ‘document’”), ensure your tsconfig.json is set up correctly and that you’re using the correct TypeScript compiler version. Check the console in your browser’s developer tools for error messages.
  • Timer Not Updating: If the timer doesn’t update, check if the setInterval function is working correctly, and the updateTimerDisplay() function is being called. Use console.log() statements to debug the values of timeLeft and other variables.
  • Multiple Timers Running: The startTimer() function includes a check to prevent multiple timers from running simultaneously.

Enhancements and Next Steps

This is a basic Pomodoro timer. You can enhance it in several ways:

  • Add sound notifications: Play a sound when the timer reaches zero or when switching between work and break.
  • Implement a settings panel: Allow the user to customize the work and break durations.
  • Add visual cues: Change the background color or display a progress bar to indicate the time remaining.
  • Use a more sophisticated notification system: Instead of alert(), use browser notifications.
  • Add a “long break” feature: Implement a longer break after a certain number of work cycles.
  • Store user preferences: Use local storage to save the user’s settings.
  • Improve the UI/UX: Make the timer more visually appealing and user-friendly. Consider using a framework like React, Angular, or Vue.js for more complex UI interactions.

Key Takeaways

  • This tutorial provided a practical introduction to building web applications with TypeScript.
  • You learned how to set up a TypeScript project, write TypeScript code, compile it, and run it in a web browser.
  • You gained experience with fundamental TypeScript concepts like variables, functions, event listeners, and type assertions.
  • You built a functional Pomodoro timer that can help you manage your time effectively.
  • You learned about common mistakes and how to debug your code.

FAQ

  1. Why use TypeScript for a simple timer? TypeScript adds type safety and improves code maintainability, even for small projects. It helps catch errors early and makes your code more readable.
  2. What if I don’t want to use HTML and CSS? You can use a framework like React, Angular, or Vue.js to build the user interface and handle styling. These frameworks often provide more sophisticated ways to manage the UI.
  3. How can I deploy this timer online? You can deploy your timer to a platform like Netlify, Vercel, or GitHub Pages. These platforms provide free hosting for static websites.
  4. Where can I learn more about TypeScript? The official TypeScript documentation (typescriptlang.org/docs/) is an excellent resource. You can also find many tutorials and courses online.
  5. Can I contribute to this project? Yes! You can fork the project, add new features, fix bugs, and submit a pull request.

Building this Pomodoro timer is a stepping stone to more complex web development projects. By understanding the fundamentals of TypeScript and web development, you can create a wide range of web applications. The key is to practice, experiment, and keep learning. Embrace the challenge, and enjoy the process of building something useful and unique.

More posts