Spotify listening trends

Next.js app that connects to the Spotify Web API and shows your top artists, tracks, and albums by time range (4 weeks / 6 months / all time).

Setup

1. Copy .env.local.example to .env.local and fill in:

   • SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET — Spotify Developer Dashboard
   • NEXT_PUBLIC_APP_URL — local dev: http://127.0.0.1:3000 (required; Spotify rejects localhost). Production: your site origin, e.g. https://your-app.vercel.app
   • SESSION_SECRET — long random string (e.g. openssl rand -hex 32)

2. In the Spotify app settings, add a Redirect URI that matches exactly (character-for-character) what the app sends:

   • Usually: http://127.0.0.1:3000/api/auth/callback for local dev
   • Production: https://your-domain.com/api/auth/callback
   • If you use SPOTIFY_REDIRECT_URI in .env.local, register that full URL instead.

3. Install and run:

   npm install
   npm run dev

   npm run dev binds to 127.0.0.1 so it matches the redirect URI. Open http://127.0.0.1:3000 — not http://localhost:3000 (cookie/session origin should stay consistent).

4. Connect with Spotify.

Optional scripts: npm run dev:https (HTTPS on localhost — Spotify will still need a registered loopback URI; stick to http://127.0.0.1:3000 for the simplest local OAuth flow). npm run dev:any listens on all interfaces.

How it works

• Uses Spotify’s top tracks and top artists endpoints (not full play history).
• Albums are inferred from your top tracks (grouped by album).

Spotify Developer compliance

This app aims to follow Spotify Web API practices: Authorization Code on the server (acceptable when a secure backend holds the client secret; PKCE is preferred for fully public clients). Scopes: user-top-read only. Redirect: HTTPS in production; http://127.0.0.1 for local dev (not localhost). Rate limits: API calls retry on 429 using Retry-After or exponential backoff. Endpoints: verify paths against the OpenAPI schema. Terms: no long-term caching of Spotify content; UI attributes Spotify; API data is not used to train models. See .cursor/rules/spotify-web-api.mdc for full AI/agent rules.

Scripts

• npm run dev — dev server on 127.0.0.1 (Spotify-friendly)
• npm run build — production build
• npm run start — run production server