https://github.com/mcabreradev/the-music-finder
https://github.com/mcabreradev/the-music-finder
Last synced: 10 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/mcabreradev/the-music-finder
- Owner: mcabreradev
- Created: 2025-03-07T01:22:12.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-29T18:55:03.000Z (about 1 year ago)
- Last Synced: 2025-04-29T19:48:19.367Z (about 1 year ago)
- Language: TypeScript
- Homepage: https://the-music-finder.vercel.app/
- Size: 288 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# MusicFinder
A modern web application for discovering and exploring music artists and their albums. Built with Next.js 15, TypeScript, and Tailwind CSS.
## Features
- 🎵 Search for artists and explore their discography
- 💿 Detailed album views with track listings
- 🎨 Beautiful, responsive UI inspired by modern music platforms
- 🌗 Light/Dark mode support
- 🚀 Fast and optimized performance
- ♿ Accessible design
- 📱 Mobile-friendly interface
- ❤️ Follow artists and like songs with local storage persistence
- 📚 Personal library with followed artists and liked songs
- 🎼 Track details including duration and music video links
## Tech Stack
- **Framework**: [Next.js 15](https://nextjs.org/)
- **Language**: [TypeScript](https://www.typescriptlang.org/)
- **Styling**: [Tailwind CSS](https://tailwindcss.com/)
- **UI Components**: [shadcn/ui](https://ui.shadcn.com/)
- **State Management**: [TanStack Query](https://tanstack.com/query)
- **API**: [TheAudioDB](https://www.theaudiodb.com/)
- **Testing**: Jest & React Testing Library
- **Documentation**: Storybook
## Getting Started
### Prerequisites
- Node.js 16.8 or later
- npm or yarn
### Installation
1. Clone the repository:
```bash
git clone https://github.com/mcabreradev/music-finder.git
cd music-finder
```
2. Install dependencies:
```bash
npm install
```
3. Start the development server:
```bash
npm run dev
```
4. Open [http://localhost:3000](http://localhost:3000) in your browser.
## Project Structure
```
├── app/ # Next.js 15 app directory
│ ├── album/ # Album-related pages
│ ├── artist/ # Artist-related pages
│ ├── search/ # Search functionality
│ └── layout.tsx # Root layout
├── components/ # React components
│ ├── ui/ # Reusable UI components
│ └── ... # Feature-specific components
├── features/ # List of Features
│ ├── album/ # Album-related pages
│ ├── artist/ # Artist-related pages
│ ├── search/ # Search functionality
│ └── layout.tsx # Root layout
├── lib/ # Utility functions and API
├── types/ # TypeScript type definitions
├── hooks/ # Custom React hooks
├── stories/ # Storybook stories
└── __tests__/ # Test files
```
## Available Scripts
- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm start` - Start production server
- `npm test` - Run tests
- `npm run storybook` - Start Storybook
- `npm run build-storybook` - Build Storybook
## API Integration
The application uses TheAudioDB API to fetch music data. Key features include:
### Artist Endpoints
```typescript
// Search for artists
const artists = await searchArtists("query");
// Get artist details
const artist = await getArtistById("artistId");
// Get artist albums
const albums = await getAlbumsByArtistId("artistId");
```
### Album Endpoints
```typescript
// Get album with tracks
const album = await getAlbumById("albumId");
// Get track details
const track = await getTrackById("trackId");
```
Rate limiting is implemented to ensure API stability:
- Maximum 2 requests per second
- Queue system for managing requests
- Error handling for rate limits and failed requests
## Components
### Core Components
- `SearchForm`: Artist search functionality
- `ArtistCard`: Display artist information
- `AlbumCard`: Display album information
- `AlbumList`: Grid of albums
- `ArtistHeader`: Artist page header
- `Sidebar`: Navigation sidebar
### UI Components
Built using shadcn/ui, including:
- Buttons
- Cards
- Input fields
- Badges
- Skeletons for loading states
- Toast notifications
## Local Storage
The application uses local storage to persist user preferences:
```typescript
// Follow/Unfollow artists
const { followedArtistIds, toggleFollow } = useFollowedArtists();
// Like/Unlike songs
const { likedTrackIds, toggleLike } = useLikedTracks();
```
## Testing
Tests are written using Jest and React Testing Library. Key test files:
- `__tests__/components/search-form.test.tsx`
- `__tests__/components/album-list.test.tsx`
- `__tests__/lib/api.test.ts`
Run tests with:
```bash
npm test
```
## Storybook
Component documentation and development environment available through Storybook:
```bash
npm run storybook
```
Key stories:
- `stories/album-card.stories.tsx`
- `stories/artist-card.stories.tsx`
- `stories/search-form.stories.tsx`
## Performance Optimization
- Image optimization with Next.js Image component
- Client-side data caching with TanStack Query
- Lazy loading of components
- Optimized fonts with next/font
- Responsive images with appropriate sizes
## Accessibility
- ARIA labels and roles
- Keyboard navigation support
- Color contrast compliance
- Screen reader friendly
- Focus management
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Development Guidelines
- Follow the existing code style and conventions
- Write tests for new features
- Update documentation as needed
- Ensure accessibility standards are maintained
- Test across different browsers and devices
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [TheAudioDB](https://www.theaudiodb.com/) for providing the API
- [shadcn/ui](https://ui.shadcn.com/) for the beautiful UI components
- [Unsplash](https://unsplash.com/) for placeholder images
- [Lucide Icons](https://lucide.dev/) for the icon set