How to Add Spotify Now Playing to Your GitHub Profile README

The Spotify Now Playing widget is an open-source service hosted on GitHub as novatorem/novatorem. It connects to the Spotify Web API using OAuth and exposes a small API endpoint that returns an SVG image of your current playback state. When you're actively listening, it shows the track in real time with an animated equalizer bar. When you're offline, it falls back to your most recently played track.

The widget is self-hosted on Vercel, which means you control the service and your Spotify credentials stay in your own environment variables. It renders as a standard image tag in your README, so it works everywhere GitHub markdown is rendered — profile pages, repository READMEs, and organization pages.

Follow these steps to deploy and connect the widget:

1. Fork the repository at github.com/novatorem/novatorem.
2. Go to the Spotify Developer Dashboard (developer.spotify.com) and create a new application. Set the redirect URI to https://your-vercel-app.vercel.app/callback.
3. Copy your Client ID and Client Secret from the Spotify app settings.
4. Deploy your forked repo to Vercel. During setup, add these environment variables: SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET.
5. Visit https://your-vercel-app.vercel.app/login in your browser to complete the OAuth flow and get your SPOTIFY_REFRESH_TOKEN.
6. Add SPOTIFY_REFRESH_TOKEN as a fourth environment variable in Vercel and redeploy.
7. Add to your README:

[![Spotify](https://your-vercel-app.vercel.app/api/spotify)](https://open.spotify.com/user/YOUR_SPOTIFY_ID)

The default widget renders with a dark card background that fits most dark-mode GitHub profiles. You can modify the visual style by editing the api/spotify.js file in your fork before deploying. Common customizations include changing the card background color, adjusting the font size, or modifying the animated equalizer bar colors to match your profile's accent color.

For the link destination, replace YOUR_SPOTIFY_ID with your Spotify profile username (visible in your Spotify app under your profile). Linking the image to your Spotify profile lets visitors follow you or browse your public playlists — a nice community signal for developer profiles targeting creative or music-adjacent teams. Keep the image width constrained to 350px max for consistent rendering alongside stats cards.

The most common issue is the widget showing 'Not Listening' even when music is playing. This usually means the refresh token has expired or was not saved correctly. Re-visit the /login endpoint on your Vercel deployment to regenerate a fresh token, then update the environment variable.

If the widget card fails to load entirely and shows a broken image, check that all three environment variables (Client ID, Client Secret, Refresh Token) are present in your Vercel project settings under Environment Variables. A missing variable causes the API to return a 500 error.

For CORS errors in local development, note that the widget is designed to run on Vercel, not locally — test changes by pushing to a preview deployment branch rather than running vercel dev.