A powerful, feature-rich full-stack URL shortener with advanced analytics, custom slugs, and seamless user management
Features • Structure • Quick Start • API Docs • Docker • Contributing • License
|
⚡ Lightning-fast URL shortening |
🛡️ Rate limiting protection |
📈 Detailed click tracking |
- 🔗 URL Shortening: Create short, memorable links with custom slugs
- 📊 Advanced Analytics: Track clicks, geographic data, device information, and more
- 🎨 QR Code Generation: Generate QR codes for your shortened links
- 👤 User Authentication: Secure login with Google and GitHub OAuth
- 🔐 Password Reset: Secure password recovery system
- ⚡ Rate Limiting: Protection against abuse and spam
- 🌐 Public Links: Share links without authentication
- 📱 Responsive Design: Works seamlessly on all devices
- 🐳 Docker Support: Easy deployment with Docker containers
This is a monorepo containing both the frontend and backend applications:
📦 Link Manager (Monorepo)
├── 🎨 client/ # React + TypeScript Frontend
│ ├── 📦 package.json # Frontend dependencies
│ ├── ⚙️ vite.config.ts # Vite configuration
│ ├── 🎯 tsconfig.json # TypeScript config
│ ├── 🎨 src/ # Source code
│ │ ├── 📱 components/ # React components
│ │ ├── 📄 pages/ # Page components
│ │ ├── 🔧 hooks/ # Custom hooks
│ │ ├── 🎨 styles/ # CSS/styling
│ │ └── 🔌 utils/ # Utility functions
│ └── 📦 public/ # Static assets
├── ⚙️ server/ # Node.js + Express Backend
│ ├── 📦 package.json # Backend dependencies
│ ├── 🐳 Dockerfile # Docker configuration
│ ├── 🗄️ prisma/ # Database schema & migrations
│ ├── 📡 src/ # Source code
│ │ ├── 🛣️ routes/ # API routes
│ │ ├── 🎮 controllers/ # Request handlers
│ │ ├── 🔧 services/ # Business logic
│ │ ├── 🗄️ models/ # Database models
│ │ ├── 🛡️ middlewares/ # Express middlewares
│ │ ├── 🔧 utils/ # Utility functions
│ │ └── ✅ validation/ # Input validation
│ └── 📚 docs/ # API documentation
├── 🏗️ package.json # Workspace configuration
├── 🔒 package-lock.json # Dependency locks
├── 📝 README.md # This file
└── 🙈 .gitignore # Git ignore rules
|
|
- Node.js (v18 or higher) - Download
- PostgreSQL database - Download
- Git - Download
- Docker (optional) - Download
# Clone the repository
git clone https://github.com/Bhavyabhardwaj/linkweaver-server.git
cd linkweaver-server
# Install all dependencies (client + server)
npm run install:all
# Set up environment variables
cd server && cp .env.example .env
# Edit .env with your configuration
# Run database migrations
npx prisma migrate dev
# Start both frontend and backend
npm run dev🎉 That's it! Your application will be running at:
- Frontend: http://localhost:3000
- Backend: http://localhost:5000
- API Docs: http://localhost:5000/api-docs
Click to expand detailed setup instructions
-
Navigate to server directory:
cd server -
Install dependencies:
npm install
-
Set up environment variables:
cp .env.example .env
Edit
.envwith your configuration:# Database DATABASE_URL="postgresql://username:password@localhost:5432/linkweaver" # JWT JWT_SECRET="your-super-secret-jwt-key" # OAuth (optional) GOOGLE_CLIENT_ID="your-google-client-id" GOOGLE_CLIENT_SECRET="your-google-client-secret" GITHUB_CLIENT_ID="your-github-client-id" GITHUB_CLIENT_SECRET="your-github-client-secret"
-
Run database migrations:
npx prisma migrate dev
-
Start the development server:
npm run dev
-
Navigate to client directory:
cd client -
Install dependencies:
npm install
-
Start the development server:
npm run dev
# Navigate to server directory
cd server
# Build and start all services
docker-compose up -d
# View logs
docker-compose logs -f| Command | Description |
|---|---|
npm run dev |
🚀 Start both client and server in development mode |
npm run dev:client |
🎨 Start only the React frontend |
npm run dev:server |
⚙️ Start only the Node.js backend |
npm run build |
🏗️ Build both client and server for production |
npm run build:client |
🎨 Build only the frontend |
npm run build:server |
⚙️ Build only the backend |
npm run install:all |
📦 Install dependencies for both client and server |
npm run test |
🧪 Run tests for both client and server |
npm start |
🚀 Start the production server |
The comprehensive API documentation is available at /api-docs when the server is running.
Key Endpoints:
- 🔗 Links:
POST /api/links- Create shortened links - 📊 Analytics:
GET /api/analytics- Get link analytics - 👤 Auth:
POST /api/auth/login- User authentication - 📱 Public:
GET /:slug- Redirect to original URL
We love your contributions! Here's how to get started:
📝 Contributing Guidelines
-
Fork the repository
# Click the Fork button on GitHub -
Clone your fork
git clone https://github.com/YOUR_USERNAME/linkweaver-server.git cd linkweaver-server -
Create a feature branch
git checkout -b feature/amazing-feature
-
Make your changes
- Follow the existing code style
- Add tests for new features
- Update documentation as needed
-
Test your changes
npm run test npm run lint -
Commit your changes
git commit -m "✨ Add amazing feature" -
Push to your fork
git push origin feature/amazing-feature
-
Create a Pull Request
- Go to GitHub and create a PR
- Describe your changes clearly
- Wait for review and merge
- Use TypeScript for all new code
- Follow ESLint configuration
- Write meaningful commit messages
- Add JSDoc comments for functions
- Include tests for new features
This project is licensed under the GPL-3.0 License - see the LICENSE file for details.
If you found this project helpful, please consider giving it a star! ⭐