TypeScript Tutorial: Creating a Simple URL Shortener

Written by

learnmodernjavascript

in

In today’s digital landscape, long, unwieldy URLs are a common nuisance. They clutter social media posts, make sharing links cumbersome, and often look unprofessional. This is where URL shorteners come in, transforming lengthy web addresses into compact, shareable links. In this tutorial, we’ll dive into how to build your own URL shortener using TypeScript, exploring the core concepts, and guiding you through the step-by-step process of creating a functional application. By the end of this guide, you’ll not only understand the fundamentals of URL shortening but also gain practical experience with TypeScript, a powerful language that enhances code quality and maintainability.

Why Build a URL Shortener?

Creating your own URL shortener offers several advantages:

  • Control: You have complete control over your shortened links and the associated data.
  • Branding: Use your own domain for a professional look.
  • Customization: Tailor the functionality to your specific needs, such as adding analytics or advanced features.
  • Learning: It’s an excellent project for learning TypeScript and web development principles.

Prerequisites

Before we begin, ensure you have the following installed:

  • Node.js and npm (Node Package Manager): These are essential for managing project dependencies and running the application. You can download them from nodejs.org.
  • TypeScript: Install TypeScript globally using npm: npm install -g typescript
  • A Code Editor: Visual Studio Code (VS Code) is highly recommended, but you can use any editor you prefer.

Setting Up the Project

Let’s start by creating a new project directory and initializing it with npm:

mkdir url-shortener
cd url-shortener
npm init -y

This will create a package.json file, which will manage our project dependencies. Next, let’s initialize a TypeScript configuration file:

tsc --init

This command creates a tsconfig.json file. We’ll need to configure this file to specify how TypeScript compiles our code. Open tsconfig.json and make the following adjustments:

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

Here’s what each option means:

  • target: Specifies the JavaScript version to compile to (ES2015 is a good choice for modern browsers).
  • module: Specifies the module system (commonjs is common for Node.js projects).
  • outDir: Defines the output directory for compiled JavaScript files.
  • rootDir: Specifies the root directory of your TypeScript source files.
  • strict: Enables strict type checking.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • skipLibCheck: Skips type checking of declaration files (improves build times).
  • forceConsistentCasingInFileNames: Enforces consistent casing in file names.
  • include: Specifies which files to include in the compilation.

Installing Dependencies

We’ll need a few dependencies for our project:

  • Express: A web application framework for Node.js.
  • shortid: A library for generating short, unique IDs.
  • cors: A middleware for enabling Cross-Origin Resource Sharing (CORS).

Install these dependencies using npm:

npm install express shortid cors

Creating the Core Files

Create a src directory and inside it, create the following files:

  • src/index.ts: The main entry point of our application.
  • src/routes/urlRoutes.ts: Handles the URL shortening and redirection logic.
  • src/models/Url.ts: Defines the structure of the URL data.

Implementing the URL Model (src/models/Url.ts)

In src/models/Url.ts, we’ll define a simple interface for our URL data:

// src/models/Url.ts

export interface Url {
  originalUrl: string;
  shortId: string;
  createdAt: Date;
}

This interface defines the properties of a URL object: the original URL, the short ID, and the creation timestamp.

Implementing the URL Routes (src/routes/urlRoutes.ts)

This file will handle the logic for shortening URLs and redirecting users. Add the following code to src/routes/urlRoutes.ts:

// src/routes/urlRoutes.ts
import express, { Request, Response } from 'express';
import shortid from 'shortid';
import { Url } from '../models/Url';

const router = express.Router();

// In-memory storage (replace with a database in a real application)
const urls: Url[] = [];

// POST /shorten - Shorten a URL
router.post('/shorten', (req: Request, res: Response) => {
  const { originalUrl } = req.body;

  if (!originalUrl) {
    return res.status(400).json({ error: 'Original URL is required' });
  }

  try {
    const shortId = shortid.generate();
    const newUrl: Url = {
      originalUrl,
      shortId,
      createdAt: new Date(),
    };
    urls.push(newUrl);

    return res.status(201).json({ shortId, originalUrl });
  } catch (error) {
    console.error(error);
    return res.status(500).json({ error: 'Failed to shorten URL' });
  }
});

// GET /:shortId - Redirect to the original URL
router.get('/:shortId', (req: Request, res: Response) => {
  const { shortId } = req.params;
  const url = urls.find((url) => url.shortId === shortId);

  if (url) {
    return res.redirect(url.originalUrl);
  } else {
    return res.status(404).json({ error: 'URL not found' });
  }
});

export default router;

Let’s break down this code:

  • Imports: We import necessary modules like express, shortid, and our Url interface.
  • In-Memory Storage: const urls: Url[] = []; This array will store our shortened URLs. Important: In a real-world application, you would replace this with a database (e.g., MongoDB, PostgreSQL) for persistent storage.
  • /shorten (POST): This route handles the URL shortening process.
    • It extracts the originalUrl from the request body.
    • It generates a unique shortId using shortid.generate().
    • It creates a new Url object and adds it to the urls array.
    • It returns the shortId and the original URL in the response.
    • It includes error handling for missing URLs and potential issues during the shortening process.
  • /:shortId (GET): This route handles the redirection.
    • It extracts the shortId from the request parameters.
    • It searches for the corresponding URL in the urls array.
    • If found, it redirects the user to the originalUrl.
    • If not found, it returns a 404 error.

Implementing the Main Application (src/index.ts)

This file sets up the Express application and integrates the URL routes. Add the following code to src/index.ts:

// src/index.ts
import express from 'express';
import cors from 'cors';
import urlRoutes from './routes/urlRoutes';

const app = express();
const port = process.env.PORT || 3000;

// Middleware
app.use(cors()); // Enable CORS for all origins (for development - configure properly in production)
app.use(express.json()); // Parse JSON request bodies

// Routes
app.use('/', urlRoutes);

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

Let’s break down this code:

  • Imports: We import express, cors, and our urlRoutes.
  • App Setup: We create an Express application instance and define the port.
  • Middleware:
    • cors(): Enables CORS. Important: In a production environment, you should configure CORS to allow only specific origins for security.
    • express.json(): Parses JSON request bodies.
  • Routes: app.use('/', urlRoutes) mounts our URL routes at the root path.
  • Server Start: app.listen() starts the server and listens for incoming requests.

Compiling and Running the Application

Now, let’s compile and run our application:

tsc
node dist/index.js

The tsc command compiles the TypeScript code into JavaScript, and node dist/index.js runs the compiled code.

Testing the Application

You can test your application using tools like curl, Postman, or a web browser with a REST client extension.

Shorten a URL (POST request to /shorten):

curl -X POST -H "Content-Type: application/json" -d '{"originalUrl":"https://www.example.com/very/long/path/to/a/resource"}' http://localhost:3000/shorten

This should return a JSON response containing the shortId and the originalUrl.

Redirect to the original URL (GET request to /:shortId):

Replace <shortId> with the shortId you received from the previous request:

curl -I http://localhost:3000/<shortId>

This should return a 302 redirect to the original URL. You can also test this in a web browser by navigating to http://localhost:3000/<shortId>.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

  • Incorrect TypeScript Configuration: Ensure your tsconfig.json is set up correctly. Pay close attention to the outDir, rootDir, and module options. Incorrect configurations can lead to compilation errors or unexpected behavior.
  • CORS Issues: In development, enabling CORS for all origins (cors()) is convenient. However, in production, you must configure CORS to allow requests only from your specific domain or authorized origins to prevent security vulnerabilities.
  • Database Integration: The in-memory storage is fine for testing, but it won’t persist data. Remember to replace the urls array with a database (e.g., MongoDB, PostgreSQL, MySQL) for a production-ready application. You’ll need to install a database client library (e.g., mongoose for MongoDB) and configure your database connection.
  • Error Handling: While the example includes basic error handling, expand it to provide more informative error messages and handle different types of errors gracefully. Consider logging errors for debugging.
  • Input Validation: Always validate user input, especially the originalUrl. Ensure it’s a valid URL before processing it to prevent unexpected errors. Use a library like validator for URL validation.
  • Security Considerations:
    • Rate Limiting: Implement rate limiting to prevent abuse and protect your server from being overwhelmed by requests.
    • Input Sanitization: Sanitize user input to prevent cross-site scripting (XSS) attacks.
    • HTTPS: Always use HTTPS in production to encrypt traffic between the client and the server.

Enhancements and Advanced Features

Here are some ways to enhance your URL shortener:

  • Database Integration: Implement a database (MongoDB, PostgreSQL, etc.) to persist shortened URLs.
  • Custom Short URLs: Allow users to specify a custom short ID (e.g., /my-custom-url).
  • Analytics: Track clicks, referrers, and other metrics to provide insights into link usage.
  • User Authentication: Add user accounts to manage shortened URLs and track usage.
  • API Rate Limiting: Implement rate limiting to prevent abuse.
  • QR Code Generation: Generate QR codes for shortened URLs.
  • URL Expiration: Allow URLs to expire after a certain period.
  • User Interface (UI): Create a web interface for easy URL shortening and management.

Key Takeaways

  • TypeScript enhances code quality and maintainability.
  • Express.js simplifies the creation of web applications.
  • shortid is a convenient library for generating unique IDs.
  • CORS is essential for handling cross-origin requests.
  • Database integration is crucial for persistent storage in a real-world application.
  • Proper error handling and input validation are essential for a robust application.

FAQ

Q: What database should I use?

A: The choice of database depends on your needs. MongoDB is a popular NoSQL database that’s easy to get started with. PostgreSQL is a powerful relational database. Choose the database you’re most comfortable with or that best suits your project’s requirements.

Q: How can I deploy this application?

A: You can deploy your application to various platforms, such as Heroku, AWS, Google Cloud Platform, or a dedicated server. You’ll need to configure your environment to run Node.js applications and ensure your database is accessible.

Q: How do I handle URL validation?

A: Use a library like validator to validate URLs. Here’s an example:

import validator from 'validator';

if (!validator.isURL(originalUrl)) {
  return res.status(400).json({ error: 'Invalid URL' });
}

Q: How can I improve the performance of my URL shortener?

A: Optimize database queries, use caching, and consider a content delivery network (CDN) for serving static assets. Proper indexing in your database can significantly improve query performance.

Conclusion

Building a URL shortener with TypeScript provides a solid foundation for understanding web application development and mastering the TypeScript language. By following this tutorial, you’ve created a functional application and gained valuable insights into key concepts like routing, middleware, and data management. Remember to prioritize security, error handling, and input validation to build a robust and reliable application. This project not only enhances your coding skills but also equips you with the knowledge to tackle more complex web development challenges. As you continue to experiment and add features, you’ll discover the power and flexibility of TypeScript, solidifying your expertise in creating efficient and maintainable code. The evolution of your URL shortener will undoubtedly be a testament to your growing proficiency in the world of web development.

More posts