Get it spinning.

SpotLive is a single component plus a tiny API route that turns your Spotify activity into a live widget on your site. This page is the entire manual — under five minutes if you have your dev console open.

Requirements

Node 18 or later, a Next.js App Router project, and a premium Spotify developer account. Pages Router is not supported.

01Install with CLI

The fastest path. One command scaffolds the component, the API route, and walks you through the OAuth flow.

terminalzsh

$ npx spotlive init

That single command will:

Detect next in your package.json and confirm App Router layout
Drop SpotLive.tsx into components/spotlive/
Add a route handler at app/api/spotify/route.ts
Open your browser for the Spotify OAuth consent flow and write the resulting refresh token to .env.local

02Spotify credentials

You'll need three values from the Spotify developer console. SpotLive's CLI opens the right pages automatically, but here's the manual path:

Go to developer.spotify.com/dashboard and create an app.
Copy the Client ID and Client Secret.
Add http://127.0.0.1:8888/callback as a Redirect URI.
Run npx spotlive init — the CLI opens the browser OAuth consent flow and prints your refresh token.

Keep secret

The client secret and refresh token are server-only. Never expose them with a NEXT_PUBLIC_ prefix or in client-side code.

03Environment variables

After npx spotlive init your .env.local will contain:

.env.localenv

# SpotLive
SPOTIFY_CLIENT_ID=a1b2c3d4e5f6...
SPOTIFY_CLIENT_SECRET=x9y8z7w6v5u4...
SPOTIFY_REFRESH_TOKEN=AQDxyz...truncated

SPOTIFY_CLIENT_ID

From your Spotify app's settings page.

SPOTIFY_CLIENT_SECRET

From the same page, behind a "show client secret" toggle. Treat it like a password.

SPOTIFY_REFRESH_TOKEN

Generated by the CLI's OAuth flow. SpotLive uses it to mint short-lived access tokens.

04Using the component

Import it anywhere in your App Router pages:

app/page.tsxtsx

import { SpotLive } from "@/components/spotlive/SpotLive";

export default function Home() {
  return (
    <main>
      {/* vinyl variant, fixed to the right */}
      <SpotLive variant="vinyl" position="right"/>

      {/* player card, inline */}
      <SpotLive variant="player"/>
    </main>
  );
}

05Props reference

Prop	Type	Default	Notes
variant	"vinyl" \| "player"	"player"	Visual style. Vinyl spins; player shows a card.
pollInterval	number	10000	Polling interval in ms. Lower = more API calls.
position	"left" \| "right"	"right"	Fixed position side (vinyl variant only).

06The API route

SpotLive ships its own route handler at /api/spotify. The handler:

reads your env vars,
exchanges the refresh token for a short-lived access token (cached in memory),
calls /v1/me/player/currently-playing,
normalizes the response into the payload below.

GET /api/spotifyjson

{
  "isPlaying": true,
  "title": "Dreams",
  "artist": "Fleetwood Mac",
  "albumArt": "https://i.scdn.co/image/…",
  "progress": 42031,
  "duration": 254000
}

07Troubleshooting

"Failed to refresh access token"

Your refresh token is wrong or has been revoked. Re-run npx spotlive init to go through the OAuth flow again and replace SPOTIFY_REFRESH_TOKEN in .env.local.

The widget shows "off-air" while I'm clearly playing music

Spotify only returns a current track if a device is active. Open the Spotify desktop or mobile app — even briefly — and the next poll will pick it up.

I deployed and nothing shows up

You forgot to set the three env vars in your hosting provider. Local .env.localdoesn't ship with your bundle. Add SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET, and SPOTIFY_REFRESH_TOKENin your provider's environment settings.

See it spinning →

Open demo

Install guide