🎵 Linkfy

The ultimate tool for seamless music platform conversion

Convert YouTube Music URLs to Spotify URLs with real-time preview and authentic metadata extraction

🚀 App • 📖 Documentation • 🗺️ Roadmap • 📅 Q4 Sprint Plan • 💬 Report Bug • ✨ Request Feature

---

🌟 Why Linkfy?

In the era of multiple music streaming platforms, sharing music between friends using different services has never been more challenging. Linkfy bridges this gap by providing instant, accurate conversions between YouTube Music and Spotify with authentic metadata extraction.

✨ Key Features

• 🎯 Real-time Track Preview - See song information instantly as you type
• 🔗 Authentic API Integration - Uses official YouTube Data API v3 and Spotify Web API
• 🎵 Smart Track Matching - Advanced algorithms for accurate track identification
• 📱 Chrome Extension Ready - Seamless browser integration
• 🎨 Modern UI/UX - Clean, responsive design with platform-native styling
• � Privacy-First - No data storage, no tracking, completely secure
• 🌐 Multi-language Support - Available in multiple languages
• ⚡ Lightning Fast - Optimized performance with smart caching

🎯 Use Cases

• Music Discovery - Found a great song on YouTube Music? Share it with Spotify friends instantly
• Playlist Migration - Convert individual tracks when moving between platforms
• Social Sharing - Share music across different streaming platforms seamlessly
• Content Creation - Perfect for DJs, music bloggers, and content creators

🚀 Quick Start

New to Linkfy? 📖 Check out our complete guide in the wiki!

☁️ Develop in the Cloud

Get started instantly with GitHub Codespaces - no local setup required! Click the badge above or read the Codespaces guide to learn more.

---

📅 What's Coming in Q4 2025

We're actively developing exciting new features! Check out our Q4 2025 Sprint Plan for details.

Upcoming Releases

• v2.3.0 (Oct 15) - 🔴 Critical stability fixes & mobile improvements ✅ COMPLETED
• v2.4.0 (Nov 10) - 🚀 Universal API + Notion backlog items ✅ COMPLETED
• v2.5.0 (Nov 24) - 💎 Dark mode, history, favorites & extension
• v2.6.0 (Dec 8) - ⚡ 2x faster with Redis caching & performance
• v2.7.0 (Dec 22) - 🎵 Integrated music player + drag & drop phase 1
• v2.8.0 (Dec 31) - 🎁 Production-ready polish & drag & drop phase 2

👉 Follow our progress: Roadmap | Sprint Plan | Current Sprint Status

🏛️ Architecture & Tech Stack

graph TB
    subgraph "🖥️ Client Side"
        UI[React 18 + TypeScript<br/>Tailwind + shadcn/ui]
        EXT[Chrome Extension<br/>Manifest v3]
    end
    
    subgraph "☁️ Backend Services"
        API[NestJS API<br/>TypeScript + Zod]
        AUTH[Supabase Auth<br/>PostgreSQL + Drizzle]
    end
    
    subgraph "🎵 External APIs"
        YT[YouTube Data API v3<br/>Video Metadata]
        SP[Spotify Web API<br/>Music Catalog]
    end
    
    subgraph "🔧 DevOps & Tools"
        BUILD[Vite + Yarn Workspaces]
        TEST[Jest + Vitest]
        DEPLOY[GitHub Actions<br/>Vercel + Docker]
    end
    
    UI --> API
    EXT --> API
    API --> AUTH
    API --> YT
    API --> SP
    
    BUILD --> UI
    BUILD --> API
    TEST --> UI
    TEST --> API
    DEPLOY --> BUILD
    
    style UI fill:#61DAFB,stroke:#000,color:#000
    style API fill:#E0234E,stroke:#000,color:#fff
    style YT fill:#FF0000,stroke:#000,color:#fff
    style SP fill:#1DB954,stroke:#000,color:#fff
    style AUTH fill:#3ECF8E,stroke:#000,color:#000

Loading

Frontend Stack

• ⚛️ React 18 - Modern UI library with hooks
• 📘 TypeScript - Type-safe development
• ⚡ Vite - Lightning-fast build tool
• 🎨 Tailwind CSS - Utility-first styling
• 🧩 shadcn/ui - Beautiful, accessible components
• 🔄 TanStack Query - Powerful data fetching & caching
• 🌐 React Router - Client-side routing
• 🌍 React i18next - Internationalization

Backend Stack

• 🚀 NestJS - Scalable Node.js framework
• 📘 TypeScript - End-to-end type safety
• 🔍 Zod - Runtime type validation
• 🔑 Supabase Auth - Authentication & user management
• 📊 Drizzle ORM - Type-safe database operations
• 🐘 PostgreSQL - Robust relational database
• 📈 Sentry - Error monitoring & performance

External APIs

• 🔴 YouTube Data API v3 - Video metadata extraction
• 🟢 Spotify Web API - Music catalog search & matching
• 🔐 Google OAuth 2.0 - Secure authentication

Development & DevOps

• 📦 Yarn Workspaces - Monorepo management
• 🧪 Jest + Vitest - Comprehensive testing
• 📏 ESLint + Prettier - Code quality & formatting
• 🐳 Docker - Containerization support
• 🚀 GitHub Actions - CI/CD automation

🧩 Chrome Extension

🌐 Browser Extension Details - Click to expand

Linkfy includes a fully-featured Chrome extension for seamless browser integration:

Features

• 🔗 One-click conversion from any YouTube Music page
• 📋 Smart URL detection in browser tabs
• 🎯 Context menu integration for right-click conversion
• 🎨 Native browser UI with consistent styling
• ⚡ Manifest v3 compliance for modern Chrome compatibility

Installation

1. Build the extension: yarn build:extension:client
2. Open Chrome Extensions (chrome://extensions/)
3. Enable "Developer mode"
4. Click "Load unpacked" and select client/dist-extension/

🤝 Contributing

🚀 How to Contribute - Click to expand

We welcome contributions from the community! Here's how you can help:

Development Workflow

1. Fork & Clone

   git clone https://github.com/your-username/linkfy.git
   cd linkfy

2. Create Feature Branch

   git checkout -b feature/amazing-feature

3. Set Up Development Environment

   yarn install
   # Follow setup instructions above

4. Make Changes & Test

   yarn test:client
   yarn test:server

5. Submit Pull Request

Code Guidelines

• ✅ Follow TypeScript strict mode
• ✅ Use conventional commits
• ✅ Add tests for new features
• ✅ Update documentation
• ✅ Ensure all checks pass

Areas for Contribution

• 🎵 New Music Platforms - Add support for Apple Music, Amazon Music, etc.
• 🌍 Internationalization - Translate to new languages
• 🎨 UI/UX Improvements - Enhanced user interface
• 🔧 Performance Optimization - Faster conversions and caching
• 📱 Mobile App - React Native implementation
• 🧪 Testing - Increase test coverage

🔒 Security & Privacy

• 🔐 Zero Data Storage - No user data or URLs are stored
• 🛡️ API Key Protection - Credentials secured via environment variables
• 🔒 HTTPS Only - All communications encrypted
• 🚫 No Tracking - Completely privacy-focused
• ✅ Input Validation - All endpoints protected against injection

📞 Support & Community

When Reporting Issues

Please include:

• 📝 Detailed description of the problem
• 🔄 Steps to reproduce the issue
• 🎯 Expected vs actual behavior
• 🖥️ Browser/OS information
• 📊 Console logs (if applicable)

---

⭐ Star this repository if Linkfy helped you!

Made with ❤️ by Prisma y Media