TypeScript Tutorial: Building a Simple Web-Based Image Gallery

Written by

learnmodernjavascript

in

In the digital age, images have become an integral part of how we communicate and consume information. From showcasing products online to sharing personal memories, the ability to effectively manage and display images is crucial. Building a web-based image gallery provides a practical, hands-on opportunity to learn TypeScript while creating a useful tool. This tutorial will guide you through the process, from setting up your development environment to deploying your gallery.

Why Build an Image Gallery with TypeScript?

TypeScript brings several benefits to web development, especially when working with complex applications like an image gallery:

  • Type Safety: TypeScript adds static typing to JavaScript, catching errors during development rather than at runtime. This leads to more reliable code and a smoother user experience.
  • Improved Code Readability: Types and interfaces make your code easier to understand and maintain, especially for collaborative projects.
  • Enhanced Developer Experience: TypeScript provides better autocompletion, refactoring, and navigation in modern IDEs, significantly boosting productivity.
  • Scalability: TypeScript facilitates the development of large, complex applications by providing structure and organization.

Building an image gallery provides a perfect opportunity to apply these benefits. You’ll work with data structures, event handling, and DOM manipulation, all while enjoying the advantages of TypeScript.

Setting Up Your Development Environment

Before we dive into the code, let’s set up the necessary tools:

  1. Node.js and npm: If you don’t have them already, download and install Node.js from nodejs.org. npm (Node Package Manager) comes bundled with Node.js.
  2. TypeScript Compiler: Install the TypeScript compiler globally using npm:
npm install -g typescript
  1. Code Editor: Choose your preferred code editor (VS Code, Sublime Text, Atom, etc.). VS Code is highly recommended due to its excellent TypeScript support.

Once you have these tools installed, create a new project directory and initialize a new npm project:

mkdir image-gallery
cd image-gallery
npm init -y

This will create a `package.json` file in your project directory.

Configuring TypeScript

Next, we need to configure TypeScript for our project. Create a `tsconfig.json` file in the root of your project:

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

Let’s break down some of the key options:

  • target: Specifies the JavaScript version to compile to (e.g., “es5”, “es6”).
  • module: Specifies the module system (e.g., “commonjs”, “esnext”).
  • outDir: The directory to output the compiled JavaScript files.
  • rootDir: The root directory of your TypeScript source files.
  • strict: Enables strict type checking. Highly recommended for catching potential errors.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • skipLibCheck: Skips type checking of declaration files (e.g., from node_modules).
  • forceConsistentCasingInFileNames: Enforces consistent casing in filenames.
  • include: Specifies which files to include in the compilation.

Project Structure

Organizing your project is crucial for maintainability. Create the following directory structure:

image-gallery/
├── src/
│   ├── index.ts
│   ├── styles.css
│   └── images/
│       ├── image1.jpg
│       ├── image2.jpg
│       └── ...
├── dist/
├── index.html
├── tsconfig.json
└── package.json
  • src/index.ts: The main TypeScript file where your gallery logic will reside.
  • src/styles.css: CSS file for styling the gallery.
  • src/images/: A directory to store your image files. Populate this with some sample images.
  • dist/: The directory where the compiled JavaScript and related files will be placed.
  • index.html: The main HTML file to display the image gallery.

Writing the HTML (index.html)

Let’s create the basic HTML structure for our image gallery in index.html:




    
    
    <title>Image Gallery</title>
    


    <div class="gallery-container">
        <div class="gallery-controls">
            <button id="prevBtn">Previous</button>
            <button id="nextBtn">Next</button>
        </div>
        <div class="image-container">
            <img id="galleryImage" src="" alt="">
        </div>
    </div>

This HTML provides the basic structure:

  • A container for the gallery.
  • Controls for navigation (previous and next buttons).
  • An image container to display the current image.
  • Links to the CSS stylesheet and the JavaScript file (which will be generated by the TypeScript compiler).

Writing the TypeScript Code (index.ts)

Now, let’s write the TypeScript code to handle image display and navigation in src/index.ts. We will start by defining an interface for our image data:

interface Image {
    src: string;
    alt: string;
}

This interface defines the structure of each image object, with a source (src) and an alternative text (alt). Next, we’ll create a simple array to hold our image data:

const images: Image[] = [
    { src: 'images/image1.jpg', alt: 'Image 1' },
    { src: 'images/image2.jpg', alt: 'Image 2' },
    // Add more images here
];

Replace the placeholder image paths with the actual paths to your images, relative to the index.html file. Now, let’s get references to our HTML elements:

const galleryImage = document.getElementById('galleryImage') as HTMLImageElement;
const prevBtn = document.getElementById('prevBtn') as HTMLButtonElement;
const nextBtn = document.getElementById('nextBtn') as HTMLButtonElement;

The as HTMLImageElement and as HTMLButtonElement assertions tell TypeScript that we know these elements are of the specified type. This provides type safety and better code completion. Next, we’ll create a variable to keep track of the current image index:

let currentImageIndex = 0;

Now, let’s create a function to display the current image:

function displayImage() {
    if (galleryImage) {
        galleryImage.src = images[currentImageIndex].src;
        galleryImage.alt = images[currentImageIndex].alt;
    }
}

This function updates the src and alt attributes of the image element based on the current index. Next, create functions to handle button clicks:

function showPrevImage() {
    currentImageIndex = (currentImageIndex - 1 + images.length) % images.length;
    displayImage();
}

function showNextImage() {
    currentImageIndex = (currentImageIndex + 1) % images.length;
    displayImage();
}

These functions calculate the new index, ensuring that it loops back to the beginning or end of the array. Finally, let’s add event listeners to the buttons:

if (prevBtn) {
    prevBtn.addEventListener('click', showPrevImage);
}

if (nextBtn) {
    nextBtn.addEventListener('click', showNextImage);
}

These lines attach the showPrevImage and showNextImage functions to the click events of the buttons. Call displayImage() initially to show the first image:

displayImage();

Here’s the complete src/index.ts file:

interface Image {
    src: string;
    alt: string;
}

const images: Image[] = [
    { src: 'images/image1.jpg', alt: 'Image 1' },
    { src: 'images/image2.jpg', alt: 'Image 2' },
    // Add more images here
];

const galleryImage = document.getElementById('galleryImage') as HTMLImageElement;
const prevBtn = document.getElementById('prevBtn') as HTMLButtonElement;
const nextBtn = document.getElementById('nextBtn') as HTMLButtonElement;

let currentImageIndex = 0;

function displayImage() {
    if (galleryImage) {
        galleryImage.src = images[currentImageIndex].src;
        galleryImage.alt = images[currentImageIndex].alt;
    }
}

function showPrevImage() {
    currentImageIndex = (currentImageIndex - 1 + images.length) % images.length;
    displayImage();
}

function showNextImage() {
    currentImageIndex = (currentImageIndex + 1) % images.length;
    displayImage();
}

if (prevBtn) {
    prevBtn.addEventListener('click', showPrevImage);
}

if (nextBtn) {
    nextBtn.addEventListener('click', showNextImage);
}

displayImage();

Styling the Gallery (styles.css)

Now, let’s add some basic styling to src/styles.css:

.gallery-container {
    width: 80%;
    margin: 20px auto;
    border: 1px solid #ccc;
    padding: 20px;
    text-align: center;
}

.image-container {
    margin-bottom: 10px;
}

img {
    max-width: 100%;
    height: auto;
}

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

This CSS provides a basic layout and styling for the gallery, including a container, image display, and buttons.

Compiling and Running the Application

Now that we have our TypeScript code, we need to compile it into JavaScript. Open your terminal and run the following command from the project root:

tsc

This command will use the TypeScript compiler (tsc) and the configuration in tsconfig.json to compile your .ts files into .js files in the dist/ directory. To run the application, open index.html in your web browser. You should see your image gallery with the images you added, and you should be able to navigate through them using the “Previous” and “Next” buttons.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

  • Incorrect File Paths: Make sure the file paths in your index.ts and index.html are correct. Double-check the paths to your images in the images array and the paths to your JavaScript and CSS files in index.html.
  • Type Errors: TypeScript will report type errors during compilation. Read the error messages carefully and fix the code according to the errors. Use your editor’s suggestions to help resolve type mismatches.
  • Incorrect Element IDs: Ensure that the element IDs in your HTML (e.g., “galleryImage”, “prevBtn”, “nextBtn”) match the IDs you are using in your TypeScript code.
  • Missing Images: Verify that your image files are present in the `images` directory.
  • Button Event Listeners Not Working: Make sure the event listeners are correctly attached to the buttons. Check for typos in the event listener function names.

Adding More Features

This is a basic example, but you can extend it with more features:

  • Image Preloading: Preload images to avoid delays when navigating.
  • Responsive Design: Make the gallery responsive to different screen sizes using CSS media queries.
  • Image Captions: Add captions for each image.
  • Full-Screen View: Implement a full-screen view for each image.
  • Keyboard Navigation: Add keyboard support (e.g., left and right arrow keys).
  • Image Zooming: Allow users to zoom in and out of images.
  • Loading Indicators: Show a loading indicator while images load.
  • Error Handling: Implement error handling for image loading failures.
  • Integration with a Backend: Fetch image data from a backend API.

Key Takeaways

This tutorial has shown you how to build a basic image gallery using TypeScript. You’ve learned how to set up a TypeScript project, write HTML, style with CSS, write TypeScript code to handle image display and navigation, and troubleshoot common issues. By following this guide, you’ve gained practical experience with:

  • TypeScript syntax and features.
  • Working with DOM elements.
  • Handling events.
  • Organizing code into functions.
  • Using interfaces to define data structures.

FAQ

Q: How do I add more images to my gallery?

A: Simply add more objects to the images array in src/index.ts, providing the src and alt attributes for each image.

Q: How can I change the styling of the gallery?

A: Modify the CSS in src/styles.css to change the appearance of the gallery. You can adjust the colors, fonts, layout, and other visual aspects.

Q: How do I deploy my image gallery?

A: You can deploy your image gallery to a web server. You will need to upload the compiled JavaScript (dist/index.js), HTML (index.html), CSS (styles.css), and image files to your server. Consider using a service like Netlify or GitHub Pages for easy deployment.

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

A: The tsconfig.json file configures the TypeScript compiler. It specifies how your TypeScript code should be compiled, including the target JavaScript version, module system, and other options.

Beyond the Basics

Building a web-based image gallery in TypeScript provides a solid foundation for understanding web development principles and the benefits of using TypeScript. From here, you can explore more advanced concepts, enhance the gallery’s functionality, and delve deeper into the world of front-end development. Remember to practice and experiment to solidify your knowledge and develop your skills. Embrace the learning process, and don’t hesitate to consult documentation, online resources, and communities to overcome challenges and achieve your goals. Continue to refine your skills, and you’ll be well on your way to becoming a proficient TypeScript developer!

More posts