TypeScript: Building a Simple URL Shortener

Written by

learnmodernjavascript

in

In today’s digital landscape, links are everywhere. From social media posts to email campaigns, we constantly encounter URLs. Long, unwieldy URLs can be off-putting and difficult to share. This is where URL shorteners come in. They take a long URL and transform it into a much shorter, more manageable one, making them easier to share, remember, and track. This tutorial will guide you through building a simple URL shortener using TypeScript, providing a solid foundation for understanding how these systems work and how to implement them.

Why Build a URL Shortener?

Creating your own URL shortener offers several advantages:

  • Learning Experience: It’s a fantastic project for learning TypeScript, data structures, and basic web development principles.
  • Customization: You have complete control over features, branding, and data storage.
  • Understanding the Fundamentals: You’ll gain a deeper understanding of how URL shortening services operate under the hood.

This tutorial will cover the core components needed to build a functional URL shortener, including generating short codes, storing and retrieving URLs, and handling redirection.

Prerequisites

Before we begin, ensure you have the following installed and set up:

  • Node.js and npm (or yarn): You’ll need Node.js and npm (Node Package Manager) or yarn to manage project dependencies. Download and install them from https://nodejs.org/.
  • TypeScript: Install TypeScript globally using npm: npm install -g typescript
  • A Code Editor: Choose a code editor like Visual Studio Code, Sublime Text, or Atom.
  • Basic Knowledge: Familiarity with JavaScript and the command line is helpful.

Project Setup

Let’s start by setting up our project. Create a new directory for your project and navigate into it using your terminal:

mkdir url-shortener
cd url-shortener

Initialize a new Node.js project:

npm init -y

This command creates a package.json file, which will store your project’s metadata and dependencies.

Next, initialize a TypeScript project:

tsc --init

This creates a tsconfig.json file, which configures the TypeScript compiler. You can customize this file to control how your TypeScript code is compiled.

Installing Dependencies

We’ll need a few dependencies for our URL shortener:

  • Express: A web application framework for Node.js.
  • nanoid: For generating unique short codes.

Install these dependencies using npm:

npm install express nanoid @types/express

We also install @types/express for TypeScript type definitions for Express. This helps with type checking and autocompletion in your code editor.

Project Structure

Let’s establish a basic project structure:

url-shortener/
├── src/
│   ├── index.ts          # Main application file
│   ├── routes.ts         # Handles routes
│   └── utils.ts          # Utility functions (e.g., short code generation)
├── tsconfig.json
├── package.json
└── .gitignore

Create these files and directories in your project.

Writing the Code

1. src/utils.ts

This file will contain utility functions, such as generating short codes. We’ll use the nanoid library for this.

import { nanoid } from 'nanoid';

// Generate a unique short code
export function generateShortCode(): string {
  return nanoid(6); // You can adjust the length (e.g., 8, 10) for more/less unique codes
}

2. src/routes.ts

This file will handle our API routes. We’ll define routes for shortening URLs and redirecting to the original URLs.

import express, { Request, Response } from 'express';
import { generateShortCode } from './utils';

const router = express.Router();

// In-memory storage (replace with a database in a real application)
const urlMap: { [key: string]: string } = {};

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

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

  try {
    const shortCode = generateShortCode();
    urlMap[shortCode] = longUrl;
    return res.status(201).json({ shortCode: shortCode, shortUrl: `http://localhost:3000/${shortCode}` }); // Replace with your domain
  } catch (error) {
    console.error(error);
    return res.status(500).json({ error: 'Internal server error' });
  }
});

// GET /:shortCode - Redirect to the original URL
router.get('/:shortCode', (req: Request, res: Response) => {
  const { shortCode } = req.params;
  const longUrl = urlMap[shortCode];

  if (!longUrl) {
    return res.status(404).json({ error: 'URL not found' });
  }

  res.redirect(longUrl);
});

export default router;

Explanation of the code:

  • We import the necessary modules: express for routing, and generateShortCode from our utility functions.
  • We create an in-memory urlMap object to store the short code-to-long URL mappings. Important: In a production environment, you would use a database (e.g., MongoDB, PostgreSQL) to persist this data.
  • /shorten (POST): This route handles the URL shortening process.
    • It extracts the longUrl from the request body.
    • It validates that longUrl is provided.
    • It generates a shortCode using the generateShortCode function.
    • It stores the mapping in the urlMap.
    • It returns the shortCode and the full short URL (e.g., http://localhost:3000/shortcode).
  • /:shortCode (GET): This route handles the redirection.
    • It extracts the shortCode from the URL parameters.
    • It retrieves the corresponding longUrl from the urlMap.
    • If the longUrl is found, it redirects the user to that URL using res.redirect().
    • If the longUrl is not found, it returns a 404 error.

3. src/index.ts

This is the main application file. It sets up the Express server and connects the routes.

import express from 'express';
import routes from './routes';
import bodyParser from 'body-parser';

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

// Middleware
app.use(bodyParser.json()); // Parse JSON request bodies
app.use('/', routes);

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

Explanation:

  • We import express, the routes from routes.ts, and body-parser.
  • We create an Express application instance (app).
  • We set the port (using an environment variable or defaulting to 3000).
  • We use middleware:
    • bodyParser.json(): Parses JSON request bodies. This is essential for receiving the longUrl in the POST request.
    • /: Mounts the routes defined in routes.ts at the root path (/).
  • We start the server and listen on the specified port.

Running the Application

To run your application, you’ll need to compile the TypeScript code and then run the compiled JavaScript. Add these scripts to your package.json file, inside the “scripts” section:

"scripts": {
  "build": "tsc",
  "start": "node dist/index.js",
  "dev": "ts-node-dev --respawn --transpile-only src/index.ts"
}

Explanation of the scripts:

  • build: Compiles the TypeScript code into JavaScript using the tsc command. This generates the JavaScript files in a dist directory.
  • start: Executes the compiled JavaScript code using Node.js. It runs the index.js file located in the dist directory.
  • dev: Uses ts-node-dev which is a development tool that automatically recompiles and restarts the server when changes are made to the TypeScript files. It’s very useful for development as it avoids having to manually rebuild the project every time you make a change. The --respawn flag ensures the server restarts. The --transpile-only flag speeds up the restart process by only transpiling the code without type checking, which is done by your IDE usually.

Now, run the build script:

npm run build

Then, start the server in development mode:

npm run dev

The server should now be running, typically on http://localhost:3000.

Testing the URL Shortener

You can test your URL shortener using a tool like curl, Postman, or any other API testing tool. Here’s how to test it using curl from your terminal:

1. Shorten a URL:

curl -X POST -H "Content-Type: application/json" -d '{"longUrl":"https://www.example.com"}' http://localhost:3000/shorten

This command sends a POST request to the /shorten endpoint with the longUrl in the request body. The response will include a shortCode and a shortUrl.

2. Redirect to the Original URL:

Copy the shortCode from the response of the previous command. Then, use the following command to access the shortened URL:

curl http://localhost:3000/<your_short_code>

Replace <your_short_code> with the actual short code you received. You should be redirected to https://www.example.com.

If you’re using a browser, you can also paste the short URL (e.g., http://localhost:3000/<your_short_code>) directly into the address bar. The browser should redirect you to the original URL.

Common Mistakes and How to Fix Them

1. Not Handling Errors Properly

Mistake: Not handling errors in your routes, which can lead to unexpected behavior and a poor user experience.

Fix: Implement proper error handling using try...catch blocks and return appropriate HTTP status codes and error messages. See the examples in the routes.ts file for guidance.

2. Using In-Memory Storage in Production

Mistake: Using in-memory storage (like the urlMap in this example) in a production environment. This means that all your short URLs will be lost if the server restarts.

Fix: Use a database (e.g., MongoDB, PostgreSQL, MySQL) to persist your URL mappings. This will ensure that your data is saved even if the server restarts. You will need to install the appropriate database client library (e.g., mongoose for MongoDB) and configure your application to connect to the database.

3. Not Validating Input

Mistake: Not validating the longUrl input. This can lead to security vulnerabilities and unexpected errors.

Fix: Add input validation to your /shorten route to ensure that the longUrl is a valid URL. You can use a library like validator or write your own validation logic using regular expressions. This can also help prevent malicious users from injecting bad data.

4. Not Setting Up HTTPS

Mistake: Running your URL shortener over HTTP. This means that all the data transmitted between the client and the server is not encrypted.

Fix: Set up HTTPS by obtaining an SSL/TLS certificate (e.g., from Let’s Encrypt) and configuring your server to use it. This will encrypt the data transmitted between the client and the server, making your application more secure.

5. Not Considering Rate Limiting

Mistake: Not implementing rate limiting. Without rate limiting, malicious users could potentially flood your server with requests, leading to performance issues and potential denial-of-service (DoS) attacks.

Fix: Implement rate limiting using middleware like express-rate-limit. This will restrict the number of requests a user can make within a given time window.

Enhancements and Next Steps

Here are some ways you can enhance your URL shortener:

  • Database Integration: Integrate a database (e.g., MongoDB, PostgreSQL) to store URL mappings persistently.
  • User Authentication: Implement user authentication so users can manage their shortened URLs.
  • Analytics: Track clicks on shortened URLs.
  • Custom Short Codes: Allow users to customize their short codes.
  • API Documentation: Create API documentation using tools like Swagger or OpenAPI.
  • Rate Limiting: Implement rate limiting to prevent abuse.
  • HTTPS Implementation: Secure your application with HTTPS.

Key Takeaways

  • You’ve learned the fundamentals of building a URL shortener with TypeScript.
  • You understand how to generate short codes, handle URL redirection, and manage data.
  • You’ve been introduced to essential concepts like routing, middleware, and error handling.
  • You have a foundation for building more complex web applications with TypeScript.

FAQ

Q: What are the benefits of using TypeScript for this project?

A: TypeScript provides static typing, which helps catch errors early, improves code readability, and enhances maintainability. It also provides better autocompletion and code navigation in your IDE.

Q: How can I deploy this application?

A: You can deploy your application to a cloud platform like Heroku, AWS, Google Cloud Platform, or Azure. You’ll need to configure your environment to run the application, including setting up a database if you’re using one.

Q: How do I handle URL validation?

A: You can use a library like validator to validate URLs. It provides functions to check if a string is a valid URL, among other things.

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

A: Implement HTTPS, validate user input, use rate limiting, and protect against common web vulnerabilities like cross-site scripting (XSS) and cross-site request forgery (CSRF).

Q: Can I use a different database?

A: Yes, you can use any database you prefer (e.g., MongoDB, PostgreSQL, MySQL, etc.). You’ll need to install the appropriate database client library and modify your code to interact with that database.

Building a URL shortener with TypeScript is more than just creating shorter links; it’s a practical exercise in web development fundamentals. The journey from a long URL to a concise, shareable link is paved with core programming concepts, from handling HTTP requests to managing data. By building this simple application, you have taken a significant step toward understanding the architecture of web applications, and you are well-equipped to tackle more complex projects with confidence.

More posts