ShortURL 🔗

A modern, free, fast, and open-source URL shortener built with TypeScript, Express, and MongoDB.

✨ Features

• 🚀 Fast & Lightweight - Built with performance in mind
• 🔒 URL Validation - Ensures only valid URLs are shortened
• 📊 Click Tracking - Track how many times your short URLs are accessed
• 🎨 Modern UI - Beautiful, responsive interface
• 🔗 Easy Sharing - One-click copy to clipboard
• 📱 Mobile Friendly - Works seamlessly on all devices
• 🐳 Docker Support - Easy deployment with Docker Compose
• 📝 TypeScript - Fully typed for better development experience
• 🔄 Real-time Updates - See your URLs instantly after shortening
• 🌐 RESTful API - Full API for programmatic access

🚀 Quick Start

Prerequisites

• Node.js (v18 or higher)
• MongoDB (local or cloud instance)
• npm or yarn

Installation

1. Clone the repository

   git clone https://github.com/Vaporjawn/ShortURL.git
   cd ShortURL

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env

   Edit .env with your configuration:

   PORT=5000
   NODE_ENV=development
   MONGODB_URI=mongodb://localhost:27017/urlShortener
   BASE_URL=http://localhost:5000

4. Start MongoDB (if running locally)

   mongod

5. Run the application

   Development mode with hot reload:

   npm run dev

   Production mode:

   npm run build
   npm start

6. Open your browser

   Navigate to http://localhost:5000

🐳 Docker Setup

Run with Docker Compose (includes MongoDB):

docker-compose up -d

This will start both the application and MongoDB in containers.

📖 API Documentation

Create Short URL

POST /shortUrls

curl -X POST http://localhost:5000/shortUrls \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "fullUrl=https://example.com/very/long/url"

Get All URLs

GET /api/urls

curl http://localhost:5000/api/urls

Response:

[
  {
    "_id": "...",
    "full": "https://example.com/very/long/url",
    "short": "abc123",
    "clicks": 42,
    "createdAt": "2025-10-08T00:00:00.000Z",
    "updatedAt": "2025-10-08T00:00:00.000Z"
  }
]

Get URL Statistics

GET /api/stats/:shortUrl

curl http://localhost:5000/api/stats/abc123

Response:

{
  "full": "https://example.com/very/long/url",
  "short": "abc123",
  "clicks": 42,
  "createdAt": "2025-10-08T00:00:00.000Z",
  "updatedAt": "2025-10-08T00:00:00.000Z"
}

Delete Short URL

DELETE /api/urls/:shortUrl

curl -X DELETE http://localhost:5000/api/urls/abc123

Redirect to Original URL

GET /:shortUrl

curl -L http://localhost:5000/abc123

This will redirect to the original URL and increment the click counter.

🛠️ Technology Stack

• Backend: Node.js, Express.js, TypeScript
• Database: MongoDB with Mongoose ODM
• Frontend: EJS templating, Bootstrap 5
• URL Generation: ShortID
• Development: ts-node-dev, nodemon
• Code Quality: ESLint, TypeScript strict mode

📁 Project Structure

ShortURL/
├── src/
│   ├── config/
│   │   └── database.ts        # MongoDB connection
│   ├── middleware/
│   │   └── errorHandler.ts    # Error handling middleware
│   ├── models/
│   │   └── shortUrl.ts        # URL model and schema
│   ├── utils/
│   │   └── logger.ts          # Logging utility
│   └── server.ts              # Main application entry
├── views/
│   ├── index.ejs              # Home page
│   └── 404.ejs                # 404 error page
├── dist/                      # Compiled TypeScript output
├── .env.example               # Environment variables template
├── docker-compose.yml         # Docker configuration
├── tsconfig.json              # TypeScript configuration
├── package.json               # Project dependencies
└── README.md                  # This file

🔧 Development

Available Scripts

• npm run dev - Start development server with hot reload
• npm run build - Build TypeScript to JavaScript
• npm start - Run production server
• npm run lint - Lint code with ESLint
• npm test - Run tests
• npm run clean - Remove build artifacts

Code Style

This project uses ESLint with TypeScript rules. Run npm run lint to check code style.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

See CONTRIBUTING.md for more details.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Victor Williams

• GitHub: @Vaporjawn
• Email: victor.williams.dev@gmail.com

🙏 Acknowledgments

• Express.js - Fast, unopinionated web framework
• MongoDB - NoSQL database
• Bootstrap - CSS framework
• ShortID - Short ID generator

📊 Roadmap

• User authentication and private URLs
• Custom short URL aliases
• QR code generation
• Analytics dashboard
• Rate limiting
• URL expiration
• API key authentication
• Bulk URL shortening
• URL preview before redirect

🐛 Known Issues

None at the moment. Please report issues on the GitHub Issues page.

📞 Support

If you have any questions or need help, please:

• Open an issue on GitHub
• Contact via email: victor.williams.dev@gmail.com

---

Made with ❤️ by Victor Williams