TypeScript Tutorial: Building a Simple Web-Based Unit Converter

Written by

learnmodernjavascript

in

In the digital age, we’re constantly bombarded with numbers – distances, weights, temperatures, currencies, and more. While we often rely on online tools for unit conversions, understanding the underlying principles and being able to build your own can be incredibly empowering. This tutorial will guide you through creating a simple, yet functional, web-based unit converter using TypeScript. We’ll cover everything from setting up your development environment to handling user input and displaying results. By the end, you’ll not only have a practical tool but also a solid understanding of TypeScript fundamentals, including types, functions, and DOM manipulation.

Why Build Your Own Unit Converter?

While ready-made unit converters are plentiful, building your own offers several advantages:

  • Learning Opportunity: It’s a fantastic way to solidify your understanding of TypeScript and web development concepts.
  • Customization: You can tailor the converter to include the specific units you frequently use.
  • Offline Access: A locally hosted converter works even without an internet connection.
  • Control: You have complete control over the design, functionality, and data privacy.

Setting Up Your Development Environment

Before we dive into the code, let’s ensure you have the necessary tools installed:

  1. Node.js and npm: Node.js provides the JavaScript runtime environment, and npm (Node Package Manager) helps manage project dependencies. Download and install them from https://nodejs.org/.
  2. TypeScript: Install the TypeScript compiler globally using npm: npm install -g typescript.
  3. Code Editor: Choose a code editor like Visual Studio Code (VS Code), Sublime Text, or Atom. VS Code is highly recommended due to its excellent TypeScript support.
  4. Basic HTML, CSS, and JavaScript knowledge: This tutorial assumes you have a fundamental understanding of these technologies.

Project Structure

Let’s create a basic project structure:

unit-converter/
├── src/
│   ├── index.ts
│   └── style.css
├── index.html
├── tsconfig.json
└── package.json

Explanation:

  • unit-converter/: The root directory for our project.
  • src/: Contains our TypeScript source code and CSS files.
  • index.ts: The main TypeScript file where we’ll write our logic.
  • style.css: For styling our unit converter.
  • index.html: The HTML file that structures the web page.
  • tsconfig.json: TypeScript configuration file.
  • package.json: Manages project dependencies.

Creating the HTML Structure (index.html)

Create an index.html file with the following content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Unit Converter</title>
    <link rel="stylesheet" href="src/style.css">
</head>
<body>
    <div class="container">
        <h1>Unit Converter</h1>
        <div class="converter-box">
            <div class="input-group">
                <label for="input-value">Value:</label>
                <input type="number" id="input-value" placeholder="Enter value">
            </div>
            <div class="input-group">
                <label for="from-unit">From:</label>
                <select id="from-unit">
                    <option value="meters">Meters</option>
                    <option value="feet">Feet</option>
                    <option value="yards">Yards</option>
                </select>
            </div>
            <div class="input-group">
                <label for="to-unit">To:</label>
                <select id="to-unit">
                    <option value="meters">Meters</option>
                    <option value="feet">Feet</option>
                    <option value="yards">Yards</option>
                </select>
            </div>
            <button id="convert-button">Convert</button>
            <div id="result">Result: </div>
        </div>
    </div>
    <script src="src/index.js"></script>
</body>
</html>

This HTML provides the basic structure for our unit converter. It includes:

  • A title and stylesheet link.
  • Input fields for the value and unit selection.
  • Dropdowns (select elements) for selecting “from” and “to” units.
  • A button to trigger the conversion.
  • A div to display the result.

Styling the Converter (style.css)

Create a basic stylesheet (src/style.css) to make the converter visually appealing:

body {
    font-family: sans-serif;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    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;
}

.converter-box {
    display: flex;
    flex-direction: column;
    gap: 15px;
    margin-top: 20px;
}

.input-group {
    display: flex;
    flex-direction: column;
    align-items: flex-start;
}

label {
    margin-bottom: 5px;
    font-weight: bold;
}

input[type="number"], select {
    padding: 8px;
    border: 1px solid #ccc;
    border-radius: 4px;
    font-size: 16px;
    width: 100%;
}

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

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

#result {
    margin-top: 15px;
    font-size: 18px;
}

This CSS provides a basic layout and styling for the unit converter’s elements.

Configuring TypeScript (tsconfig.json)

Create a tsconfig.json file in the root directory to configure the TypeScript compiler:

{
  "compilerOptions": {
    "target": "ES5",
    "module": "ESNext",
    "moduleResolution": "node",
    "sourceMap": true,
    "outDir": "./src/",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

Key configuration options:

  • target: Specifies the JavaScript version to compile to (ES5 for wider browser compatibility).
  • module: Specifies the module system (ESNext for modern JavaScript).
  • moduleResolution: Specifies how modules are resolved (node for Node.js-style module resolution).
  • sourceMap: Generates source map files for debugging.
  • outDir: Specifies the output directory for compiled JavaScript files. We are compiling our TS files into the same directory for simplicity in this example.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • forceConsistentCasingInFileNames: Enforces consistent casing in filenames.
  • strict: Enables strict type checking.
  • skipLibCheck: Skips type checking of declaration files.
  • include: Specifies the files to include in the compilation.

Writing the TypeScript Code (index.ts)

Now, let’s write the core TypeScript logic in src/index.ts. This is where the unit conversion magic happens.


// Define unit conversion rates
const conversionRates: { [key: string]: { [key: string]: number } } = {
    meters: {
        feet: 3.28084,
        yards: 1.09361,
        meters: 1, // Conversion to itself
    },
    feet: {
        meters: 0.3048,
        yards: 0.333333,
        feet: 1,
    },
    yards: {
        meters: 0.9144,
        feet: 3,
        yards: 1,
    },
};

// Get DOM elements
const inputValue = document.getElementById('input-value') as HTMLInputElement;
const fromUnit = document.getElementById('from-unit') as HTMLSelectElement;
const toUnit = document.getElementById('to-unit') as HTMLSelectElement;
const convertButton = document.getElementById('convert-button') as HTMLButtonElement;
const resultElement = document.getElementById('result') as HTMLDivElement;

// Function to perform the conversion
function convertUnits(): void {
    const from = fromUnit.value;
    const to = toUnit.value;
    const value = parseFloat(inputValue.value);

    // Input validation
    if (isNaN(value)) {
        resultElement.textContent = 'Result: Invalid input';
        return;
    }

    // Conversion logic
    if (conversionRates[from] && conversionRates[from][to]) {
        const convertedValue = value * conversionRates[from][to];
        resultElement.textContent = `Result: ${convertedValue.toFixed(2)} ${to}`;
    } else {
        resultElement.textContent = 'Result: Conversion not supported';
    }
}

// Event listener for the convert button
convertButton.addEventListener('click', convertUnits);

Let’s break down the code:

  • conversionRates: This object stores the conversion factors between different units. The keys represent the base units, and the nested objects contain the conversion rates to other units.
  • DOM Element Selection: We use document.getElementById() to get references to the HTML elements we’ll be interacting with. The as HTMLInputElement, as HTMLSelectElement, and as HTMLButtonElement, and as HTMLDivElement are type assertions, which tell the TypeScript compiler that these elements are of the specified types. This allows us to use properties and methods specific to those element types (e.g., .value for input fields).
  • convertUnits() function:
    • Gets the “from” and “to” units from the select elements.
    • Parses the input value as a floating-point number using parseFloat().
    • Input Validation: Checks if the input is a valid number using isNaN(). If not, it displays an error message.
    • Conversion Logic:
      • Checks if the conversion rates exist in our conversionRates object.
      • If the conversion is supported, it performs the calculation using the appropriate conversion factor.
      • Displays the result, formatted to two decimal places using toFixed(2).
  • Event Listener: We attach an event listener to the “Convert” button. When the button is clicked, the convertUnits() function is executed.

Compiling the TypeScript Code

Open your terminal, navigate to the project directory (where your tsconfig.json is located), and compile the TypeScript code using the following command:

tsc

This command will use the settings in tsconfig.json to compile your TypeScript files (index.ts) into JavaScript files (index.js) in the specified output directory (src/ in our case). If everything goes well, you should see a new index.js file in your src/ directory.

Running the Application

Open index.html in your web browser. You should see the unit converter interface. Enter a value, select the units, and click “Convert” to see the result. If you encounter errors, check the browser’s developer console (usually accessed by pressing F12) for any JavaScript errors. Make sure your file paths in the HTML are correct (e.g., <script src="src/index.js"></script>).

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

  • Incorrect File Paths: Double-check the file paths in your HTML (e.g., for the CSS and JavaScript files). Typos can prevent your styles and scripts from loading.
  • Type Errors: TypeScript helps catch type errors during development. Carefully review any errors reported by the TypeScript compiler. Use type annotations (: string, : number, etc.) to specify the expected types of variables and function parameters.
  • Uninitialized Variables: Make sure to initialize variables before using them. TypeScript might throw errors if you try to use a variable that hasn’t been assigned a value.
  • DOM Element Selection Errors: If you are getting errors like “Cannot read properties of null (reading ‘value’)”, this means that the HTML element you are trying to access is not found. Double-check your element IDs in your HTML and your TypeScript code for any typos.
  • Incorrect Conversion Rates: Always verify the accuracy of your conversion rates. Incorrect rates will lead to incorrect results.
  • Forgetting to Compile: Remember to compile your TypeScript code (using the tsc command) after making changes. Your browser will run the JavaScript, not the TypeScript code directly.

Enhancements and Future Considerations

This is a basic unit converter, but there are many ways to enhance it:

  • Add More Units: Expand the conversionRates object to include more units (e.g., temperature, currency, time).
  • Error Handling: Implement more robust error handling (e.g., displaying more informative error messages).
  • User Interface Improvements: Improve the user interface with better styling, more intuitive input controls, and potentially a more responsive layout.
  • Unit Grouping: Group units by category (e.g., length, weight, temperature) in the dropdowns for better organization.
  • Dynamic Unit Loading: Consider loading unit data from an external source (e.g., a JSON file or an API) to make it easier to add or update units.
  • Accessibility: Ensure the converter is accessible to users with disabilities (e.g., using ARIA attributes).
  • Frameworks: For more complex applications, consider using a JavaScript framework like React, Angular, or Vue.js.

Summary / Key Takeaways

In this tutorial, we’ve successfully built a simple web-based unit converter using TypeScript. We’ve covered the essential steps, from setting up the development environment and project structure to writing the TypeScript code, handling user input, and displaying the results. You’ve gained practical experience with TypeScript fundamentals, including types, functions, DOM manipulation, and event handling. This project not only provides a functional tool but also serves as a strong foundation for further learning and exploration in TypeScript and web development. Remember to practice, experiment, and build upon this foundation to expand your skills and create more sophisticated applications.

FAQ

Q: How do I add more unit conversions?

A: Simply add the new conversion rates to the conversionRates object in your index.ts file. Make sure to update the HTML to include the new units in the dropdowns.

Q: How can I debug my TypeScript code?

A: Most code editors (like VS Code) have built-in debugging tools. You can set breakpoints in your TypeScript code, step through the execution, and inspect the values of variables. Make sure your tsconfig.json has "sourceMap": true to enable debugging.

Q: Why is my result showing “NaN”?

A: “NaN” (Not a Number) usually indicates that the input value is not a valid number. Double-check your input and ensure that you’re parsing the input value correctly using parseFloat(). Also, verify that you are not dividing by zero or performing other invalid numerical operations.

Q: Can I use this unit converter on my phone?

A: Yes, the unit converter should work on your phone, as long as your phone has a web browser. The responsiveness will depend on the styling of the HTML and CSS. You might want to improve the CSS to make the interface more mobile-friendly.

Further Exploration

Building this unit converter has likely sparked your curiosity about the power of TypeScript and web development. Continue to explore these concepts by building more complex projects, reading documentation, and participating in online communities. The more you practice, the more proficient you’ll become. The world of web development is constantly evolving, so embrace continuous learning to stay ahead. The ability to build tools that solve real-world problems is a valuable skill, and with TypeScript, you have a powerful tool in your arsenal. The journey of a thousand lines of code begins with a single step, so keep coding and keep learning!

More posts