{"id":26221820,"url":"https://github.com/mcabreradev/the-music-finder","last_synced_at":"2025-09-12T18:09:24.208Z","repository":{"id":281103504,"uuid":"944217761","full_name":"mcabreradev/the-music-finder","owner":"mcabreradev","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-29T18:55:03.000Z","size":295,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-29T19:48:19.367Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://the-music-finder.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcabreradev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-07T01:22:12.000Z","updated_at":"2025-04-29T18:55:06.000Z","dependencies_parsed_at":"2025-03-07T02:28:42.807Z","dependency_job_id":"0132d240-acb9-492e-9f5f-f2e72e653973","html_url":"https://github.com/mcabreradev/the-music-finder","commit_stats":null,"previous_names":["mcabreradev/the-music-finder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mcabreradev/the-music-finder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcabreradev%2Fthe-music-finder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcabreradev%2Fthe-music-finder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcabreradev%2Fthe-music-finder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcabreradev%2Fthe-music-finder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcabreradev","download_url":"https://codeload.github.com/mcabreradev/the-music-finder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcabreradev%2Fthe-music-finder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274851306,"owners_count":25361552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-12T02:00:09.324Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-12T16:30:20.927Z","updated_at":"2025-09-12T18:09:24.196Z","avatar_url":"https://github.com/mcabreradev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MusicFinder\n\nA modern web application for discovering and exploring music artists and their albums. Built with Next.js 15, TypeScript, and Tailwind CSS.\n\n![MusicFinder Screenshot](https://images.unsplash.com/photo-1511671782779-c97d3d27a1d4?q=80\u0026w=1200\u0026auto=format\u0026fit=crop)\n\n## Features\n\n- 🎵 Search for artists and explore their discography\n- 💿 Detailed album views with track listings\n- 🎨 Beautiful, responsive UI inspired by modern music platforms\n- 🌗 Light/Dark mode support\n- 🚀 Fast and optimized performance\n- ♿ Accessible design\n- 📱 Mobile-friendly interface\n- ❤️ Follow artists and like songs with local storage persistence\n- 📚 Personal library with followed artists and liked songs\n- 🎼 Track details including duration and music video links\n\n## Tech Stack\n\n- **Framework**: [Next.js 15](https://nextjs.org/)\n- **Language**: [TypeScript](https://www.typescriptlang.org/)\n- **Styling**: [Tailwind CSS](https://tailwindcss.com/)\n- **UI Components**: [shadcn/ui](https://ui.shadcn.com/)\n- **State Management**: [TanStack Query](https://tanstack.com/query)\n- **API**: [TheAudioDB](https://www.theaudiodb.com/)\n- **Testing**: Jest \u0026 React Testing Library\n- **Documentation**: Storybook\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 16.8 or later\n- npm or yarn\n\n### Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/mcabreradev/music-finder.git\n   cd music-finder\n   ```\n\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Start the development server:\n   ```bash\n   npm run dev\n   ```\n\n4. Open [http://localhost:3000](http://localhost:3000) in your browser.\n\n## Project Structure\n\n```\n├── app/                   # Next.js 15 app directory\n│   ├── album/             # Album-related pages\n│   ├── artist/            # Artist-related pages\n│   ├── search/            # Search functionality\n│   └── layout.tsx         # Root layout\n├── components/            # React components\n│   ├── ui/                # Reusable UI components\n│   └── ...                # Feature-specific components\n├── features/              # List of Features\n│   ├── album/             # Album-related pages\n│   ├── artist/            # Artist-related pages\n│   ├── search/            # Search functionality\n│   └── layout.tsx         # Root layout\n├── lib/                  # Utility functions and API\n├── types/                # TypeScript type definitions\n├── hooks/                # Custom React hooks\n├── stories/              # Storybook stories\n└── __tests__/           # Test files\n```\n\n## Available Scripts\n\n- `npm run dev` - Start development server\n- `npm run build` - Build for production\n- `npm start` - Start production server\n- `npm test` - Run tests\n- `npm run storybook` - Start Storybook\n- `npm run build-storybook` - Build Storybook\n\n## API Integration\n\nThe application uses TheAudioDB API to fetch music data. Key features include:\n\n### Artist Endpoints\n\n```typescript\n// Search for artists\nconst artists = await searchArtists(\"query\");\n\n// Get artist details\nconst artist = await getArtistById(\"artistId\");\n\n// Get artist albums\nconst albums = await getAlbumsByArtistId(\"artistId\");\n```\n\n### Album Endpoints\n\n```typescript\n// Get album with tracks\nconst album = await getAlbumById(\"albumId\");\n\n// Get track details\nconst track = await getTrackById(\"trackId\");\n```\n\nRate limiting is implemented to ensure API stability:\n- Maximum 2 requests per second\n- Queue system for managing requests\n- Error handling for rate limits and failed requests\n\n## Components\n\n### Core Components\n\n- `SearchForm`: Artist search functionality\n- `ArtistCard`: Display artist information\n- `AlbumCard`: Display album information\n- `AlbumList`: Grid of albums\n- `ArtistHeader`: Artist page header\n- `Sidebar`: Navigation sidebar\n\n### UI Components\n\nBuilt using shadcn/ui, including:\n- Buttons\n- Cards\n- Input fields\n- Badges\n- Skeletons for loading states\n- Toast notifications\n\n## Local Storage\n\nThe application uses local storage to persist user preferences:\n\n```typescript\n// Follow/Unfollow artists\nconst { followedArtistIds, toggleFollow } = useFollowedArtists();\n\n// Like/Unlike songs\nconst { likedTrackIds, toggleLike } = useLikedTracks();\n```\n\n## Testing\n\nTests are written using Jest and React Testing Library. Key test files:\n\n- `__tests__/components/search-form.test.tsx`\n- `__tests__/components/album-list.test.tsx`\n- `__tests__/lib/api.test.ts`\n\nRun tests with:\n```bash\nnpm test\n```\n\n## Storybook\n\nComponent documentation and development environment available through Storybook:\n\n```bash\nnpm run storybook\n```\n\nKey stories:\n- `stories/album-card.stories.tsx`\n- `stories/artist-card.stories.tsx`\n- `stories/search-form.stories.tsx`\n\n## Performance Optimization\n\n- Image optimization with Next.js Image component\n- Client-side data caching with TanStack Query\n- Lazy loading of components\n- Optimized fonts with next/font\n- Responsive images with appropriate sizes\n\n## Accessibility\n\n- ARIA labels and roles\n- Keyboard navigation support\n- Color contrast compliance\n- Screen reader friendly\n- Focus management\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Follow the existing code style and conventions\n- Write tests for new features\n- Update documentation as needed\n- Ensure accessibility standards are maintained\n- Test across different browsers and devices\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [TheAudioDB](https://www.theaudiodb.com/) for providing the API\n- [shadcn/ui](https://ui.shadcn.com/) for the beautiful UI components\n- [Unsplash](https://unsplash.com/) for placeholder images\n- [Lucide Icons](https://lucide.dev/) for the icon set\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcabreradev%2Fthe-music-finder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcabreradev%2Fthe-music-finder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcabreradev%2Fthe-music-finder/lists"}