Welcome to the documentation! Iksi is a high-performance, secure URL shortener built with SvelteKit, Prisma, and modern web technologies. The name "Iksi" comes from the Filipino word for "short", reflecting its core purpose—making long URLs concise and easy to share. This guide will help you set up and use Iksi efficiently.
This version includes significant performance and security optimizations:
- Optimized Database Connections - Singleton Prisma client prevents connection pool exhaustion
- Cryptographic Random Generation - Uses
crypto.randomBytes()for better short URL uniqueness - Client-Side Validation - Real-time URL and alias validation for improved UX
- Enhanced CSS Performance - Hardware acceleration and optimized animations
- Smart Code Splitting - Optimized Vite configuration for faster builds
- URL Encryption - Long URLs are encrypted before storage using AES-256-GCM for enhanced privacy
- Rate Limiting - Configurable request limits (20 req/min in production)
- Input Sanitization - Comprehensive server-side validation
- Security Headers - XSS protection, content type options, and frame guards
- SSRF Protection - Blocks localhost/internal network URLs
- Request Size Limits - 4KB request body limit prevents abuse
- Progressive Enhancement - Graceful loading states and error handling
- Accessibility - ARIA labels, keyboard navigation (Ctrl/Cmd+Enter)
- Better Error Messages - User-friendly feedback with auto-clearing
- Improved Copy Functionality - Cross-browser clipboard support with fallbacks
Ensure you have the following installed:
- Node.js
- PostgreSQL or another supported database
- Prisma
- npm
git clone https://github.com/ardey26/iksi.git
cd iksinpm installCreate a .env file in the project root and add your database connection string and encryption key:
DATABASE_URL="postgresql://user:password@localhost:5432/iksi"
SECRET_KEY="your-32-character-secret-encryption-key"Important: The SECRET_KEY is used for encrypting URLs. Use a strong, unique 32+ character key in production.
npx prisma generatePush the schema to your database:
npx prisma db pushnpm run devThe app should now be running at http://localhost:5173/
Iksi includes environment-based configuration for optimal performance:
- Production: 20 requests per minute per IP
- Development: 100 requests per minute per IP
- Length: 7 characters (optimized for readability)
- Character Set: Excludes confusing characters (0, O, I, l)
- Collision Retries: 5 attempts before failing
- URL Length: Max 2048 characters
- Custom Alias: Max 50 characters
- Request Body: Max 4KB
- Lightning-Fast URL Shortening - Optimized algorithms for quick processing
- Flexible Input Format - Accepts simple domains (example.com) or full URLs
- Custom Aliases - Create branded, memorable short links
- Collision-Free Generation - Cryptographic randomness prevents duplicates
- URL Validation - Comprehensive security checks and format validation
- Database Optimizations - Efficient queries with selective field fetching
- Error Resilience - Graceful handling of timeouts, database issues, and network errors
- Rate Limiting - Prevents abuse while maintaining good user experience
- Responsive Design - Optimized for mobile and desktop devices
- URL Encryption - All long URLs are encrypted using AES-256-GCM before database storage, ensuring privacy even with database access
- URL Hash Indexing - Efficient duplicate detection using SHA-256 with full backward compatibility
- Input Validation - Server and client-side protection against malicious input
- SSRF Protection - Blocks internal network and localhost URLs
- Content Security - Headers and policies to prevent common web attacks
- Request Monitoring - Rate limiting and size restrictions
Create a shortened URL with optional custom alias.
Endpoint: POST /api/shorten
Request Headers:
Content-Type: application/json
Payload:
{
"longURL": "example.com",
"customURL": "my-awesome-link" // Optional: custom alias (max 50 chars)
}Success Response (200):
{
"shortURL": "my-awesome-link"
}Error Responses:
// Invalid URL
{
"error": "you provided an invalid URL"
}
// Custom alias already exists
{
"error": "custom link alias already exists, pick another one"
}
// Rate limit exceeded
{
"error": "Too many requests. Please wait a minute."
}Navigate to any shortened URL to be redirected:
Endpoint: GET /{shortURL}
Response: 302 redirect to original URL
The API returns appropriate HTTP status codes:
200- Success400- Bad Request (invalid input)409- Conflict (alias already exists)413- Request too large429- Rate limit exceeded500- Server error
- Frontend: SvelteKit + Tailwind CSS
- Backend: SvelteKit API Routes
- Database: PostgreSQL with Prisma ORM
- Security: Built-in rate limiting and validation
- Performance: Optimized bundling and caching
/src/routes/+page.svelte- Main URL shortening interface/src/routes/api/shorten/+server.js- URL shortening API/src/routes/[slug]/+page.js- URL redirect handler/src/lib/prisma.js- Database connection singleton/src/lib/rateLimit.js- Request rate limiting/src/lib/utils/- Validation and utility functions
- Build Optimization: Run
npm run buildfor production builds - Database Indexes: Consider adding indexes on frequently queried fields
- Caching: Implement Redis or similar for enhanced performance
- CDN: Use a CDN for static assets
- Environment Variables: Set
NODE_ENV=production
- Monitor rate limit violations
- Track database connection pool usage
- Watch for error patterns in logs
- Monitor response times and throughput
src/
├── lib/
│ ├── components/ # Svelte components
│ ├── utils/ # Utility functions
│ ├── prisma.js # Database singleton
│ ├── rateLimit.js # Rate limiting logic
│ └── config.js # Environment configuration
├── routes/
│ ├── api/shorten/ # URL shortening API
│ ├── [slug]/ # Dynamic redirect routes
│ └── +page.svelte # Main interface
└── app.html # HTML template
npm run dev- Start development servernpm run build- Build for productionnpm run preview- Preview production buildnpm run lint- Run ESLintnpm run format- Format code with Prettier
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes with proper tests
- Follow the code style using the included ESLint and Prettier configs
- Submit a pull request with a clear description
- Use ESLint and Prettier configurations
- Follow SvelteKit conventions
- Add comments for complex logic
- Include error handling
Iksi is licensed under the MIT License. See the LICENSE file for details.
For questions, issues, or contributions:
- GitHub Issues: Report bugs or request features
- Discussions: Community discussions
Built with modern web technologies:
- SvelteKit - The web framework
- Prisma - Database toolkit
- Tailwind CSS - Utility-first CSS
- Vite - Build tool