Spolitics - Personal Spotify Analytics Dashboard

A modern, sleek web application for real-time personal Spotify analytics. Discover your music DNA with beautiful visualizations and insights.

Features

Analytics Views

• Overview Dashboard: Get a quick snapshot of your music taste with stats cards, currently playing widget, and top tracks/artists
• Top Tracks: View your most played tracks with time range filters (4 weeks, 6 months, all time) and audio feature visualizations
• Top Artists: Discover your favorite artists with genre distribution and popularity metrics
• Audio Analysis: Deep dive into your music's characteristics with radar charts, key distribution, and mood analysis
• Listening History: Calendar heatmap showing daily activity, hour-of-day patterns, and recent play timeline
• Currently Playing: Real-time view of what you're listening to right now

Key Features

• Spotify OAuth authentication
• Real-time currently playing updates (every 5 seconds)
• Beautiful dark mode UI inspired by Spotify
• Responsive design (desktop, tablet, mobile)
• Interactive charts and visualizations
• Audio feature analysis (danceability, energy, valence, etc.)
• Activity heatmaps and listening patterns
• Time range selectors for historical data

Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Authentication: NextAuth.js with Spotify Provider
• Charts: Recharts
• Icons: Lucide React
• Date Utilities: date-fns

Getting Started

Prerequisites

• Node.js 18+ installed
• A Spotify account
• Spotify Developer Account (for API credentials)

1. Clone the Repository

git clone https://github.com/yourusername/spolitics.git
cd spolitics

2. Install Dependencies

npm install

3. Set Up Spotify Developer App

1. Go to Spotify Developer Dashboard
2. Log in with your Spotify account
3. Click "Create an App"
4. Fill in the details:
   • App Name: Spolitics (or your preferred name)
   • App Description: Personal Spotify Analytics Dashboard
5. After creating, you'll see your Client ID and Client Secret
6. Click "Edit Settings"
7. Add the following to Redirect URIs:

   http://localhost:3000/api/auth/callback/spotify
   

8. Save your settings

4. Configure Environment Variables

📖 For detailed explanation of all environment variables, see ENV_VARIABLES_GUIDE.md

Create a .env.local file in the root directory:

cp .env.local.example .env.local

Edit .env.local and add your credentials:

# Spotify API Credentials
SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here

# NextAuth Configuration
# NEXTAUTH_URL determines the callback URL: {NEXTAUTH_URL}/api/auth/callback/spotify
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_secret_key_here

Note: The redirect URI in Spotify settings must match {NEXTAUTH_URL}/api/auth/callback/spotify

To generate a secure NEXTAUTH_SECRET, run:

openssl rand -base64 32

5. Run the Development Server

npm run dev

Open http://localhost:3000 in your browser.

6. Sign In with Spotify

1. Click "Connect with Spotify"
2. Authorize the app to access your Spotify data
3. You'll be redirected to the dashboard

Project Structure

spolitics/
├── app/
│   ├── api/
│   │   └── auth/
│   │       └── [...nextauth]/
│   │           └── route.ts          # NextAuth configuration
│   ├── dashboard/
│   │   ├── analysis/
│   │   │   └── page.tsx              # Audio Analysis page
│   │   ├── artists/
│   │   │   └── page.tsx              # Top Artists page
│   │   ├── history/
│   │   │   └── page.tsx              # Listening History page
│   │   ├── playing/
│   │   │   └── page.tsx              # Currently Playing page
│   │   ├── tracks/
│   │   │   └── page.tsx              # Top Tracks page
│   │   ├── layout.tsx                # Dashboard layout with sidebar
│   │   └── page.tsx                  # Overview dashboard
│   ├── globals.css                   # Global styles
│   ├── layout.tsx                    # Root layout
│   └── page.tsx                      # Login page
├── components/
│   ├── AnimatedBackground.tsx        # Canvas animation for login
│   ├── ArtistCard.tsx               # Artist card component
│   ├── CurrentlyPlaying.tsx         # Currently playing widget
│   ├── EmptyState.tsx               # Empty state component
│   ├── LoadingState.tsx             # Loading skeleton
│   ├── Providers.tsx                # Session provider wrapper
│   ├── Sidebar.tsx                  # Navigation sidebar
│   ├── StatCard.tsx                 # Stat card component
│   ├── TimeRangeSelector.tsx        # Time range filter
│   └── TrackCard.tsx                # Track card component
├── lib/
│   └── spotify.ts                   # Spotify API client
├── types/
│   ├── next-auth.d.ts               # NextAuth type extensions
│   └── spotify.ts                   # Spotify data types
├── .env.local.example               # Environment variables template
├── next.config.ts                   # Next.js configuration
├── package.json                     # Dependencies
├── tailwind.config.ts               # Tailwind configuration
└── tsconfig.json                    # TypeScript configuration

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm start - Start production server
• npm run lint - Run ESLint

Design System

Colors

• Background: #121212 (spotify-black), #181818 (spotify-darkgray)
• Primary: #1DB954 (spotify-green)
• Text: #FFFFFF (white), #B3B3B3 (gray)
• Accents: Purple, Pink, Blue gradients for charts

Typography

• Font: Inter (system fallback: system-ui, sans-serif)

Components

All components follow a dark theme with:

• Rounded corners (lg, xl)
• Subtle borders (border-spotify-lightgray/20)
• Hover effects (scale, color transitions)
• Smooth animations

API Scopes

The app requests the following Spotify scopes:

• user-read-email - Read user email
• user-read-private - Read user profile
• user-top-read - Read top artists and tracks
• user-read-recently-played - Read recently played tracks
• user-read-currently-playing - Read currently playing track
• user-read-playback-state - Read playback state
• playlist-read-private - Read private playlists
• playlist-read-collaborative - Read collaborative playlists

Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import project to Vercel
3. Add environment variables in Vercel dashboard
4. Update Spotify redirect URI to include your production URL:

   https://your-domain.vercel.app/api/auth/callback/spotify
   

5. Deploy!

Other Platforms

Make sure to:

1. Set all environment variables
2. Update Spotify redirect URIs
3. Build the project with npm run build

Troubleshooting

"Invalid redirect URI" error

Make sure the redirect URI in your Spotify app settings matches exactly:

http://localhost:3000/api/auth/callback/spotify

"No data available"

• Make sure you've been using Spotify regularly
• Some endpoints require listening history
• Try different time ranges

Authentication issues

• Check that your Client ID and Client Secret are correct
• Verify NEXTAUTH_SECRET is set
• Clear cookies and try again

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - feel free to use this project for personal or commercial purposes.

Acknowledgments

• Inspired by stats.fm and Spotify's own analytics
• Built with Spotify Web API
• Design inspired by Spotify's UI/UX

Support

If you encounter any issues or have questions:

1. Check the Troubleshooting section
2. Open an issue on GitHub
3. Check Spotify API documentation

---

Made with love and TypeScript | Powered by Spotify API