TOPSPOT

Generate clean Topster-style album boards from your Spotify taste.

TOPSPOT connects to Spotify, reads your Top Tracks, aggregates them by album, and exports a share-ready PNG with album covers on the left and a compact ranked album list on the right. It is built for people who want a fast, beautiful Topster3-style collage without manually dragging covers around.

Live demo: https://topspot.shiroppu.workers.dev

Why TOPSPOT

Most music collage tools either require manual input or rank tracks instead of albums. TOPSPOT is album-first:

• One album appears only once.
• Album covers come directly from Spotify.
• Rankings prioritize albums with more tracks in your Spotify Top Tracks.
• The final image is made for social sharing: black canvas, tight cover grid, monospaced list, no UI controls in the export.

Features

• Spotify OAuth with PKCE
• Reads Spotify Top Tracks across:
  • Past 4 weeks
  • Past 6 months
  • Long term
• Album-level aggregation
• Multiple Topster layouts:
  • Classic 7 x 7
  • Dense 10 x 5
  • Poster 6 x 8
• Manual data refresh
• Login/logout with local token clearing
• PNG export
• Spotify cover proxy for CORS-safe image export
• Adjustable exported list font size
• Braun-inspired industrial interface:
  • black main canvas
  • warm paper panels
  • restrained red/yellow/green control colors
  • square, physical-feeling controls
  • dense but readable tool layout

Tech Stack

• Next.js App Router
• React
• TypeScript
• Next.js API Routes
• Spotify Web API
• html-to-image for PNG generation
• OpenNext Cloudflare adapter
• Cloudflare Workers

How Ranking Works

Spotify's Top Tracks API does not expose exact play counts. TOPSPOT ranks albums with available Spotify data:

1. Albums with more tracks in your Top Tracks rank higher.
2. Ties are broken by summed track popularity.
3. Remaining ties use the highest individual track rank.

If a selected range does not have enough unique albums to fill a layout, TOPSPOT supplements with albums from the other ranges while still deduplicating albums.

Local Setup

Install dependencies:

npm install

Create .env.local:

NEXT_PUBLIC_SPOTIFY_CLIENT_ID=your_spotify_client_id
NEXT_PUBLIC_SPOTIFY_REDIRECT_URI=http://127.0.0.1:4175/callback

Start the local app:

npm run dev

Open:

http://127.0.0.1:4175

Spotify App Setup

Create an app in the Spotify Developer Dashboard, then add redirect URIs for the environments you use.

Local:

http://127.0.0.1:4175/callback

Cloudflare demo:

https://topspot.shiroppu.workers.dev/callback

Required scope:

user-top-read

Cloudflare Deployment

This project is configured for Cloudflare Workers through OpenNext.

Build for Cloudflare:

npm run upload

Deploy:

npm run deploy

Preview locally with Wrangler:

npm run preview

Main Cloudflare files:

• wrangler.jsonc
• open-next.config.ts
• public/_headers

Project Structure

app/
  api/
    cover/                  Spotify cover proxy
    spotify/token/          PKCE token exchange and refresh
    spotify/top-tracks/     Top Tracks proxy with pagination
  callback/                 Spotify OAuth callback page
  page.tsx                  Main generator UI
  globals.css               Braun-inspired interface and poster layout

Privacy

TOPSPOT does not ask for your Spotify password. Authentication happens through Spotify OAuth / PKCE.

Tokens are stored locally in the browser so the app can refresh Spotify data during your session. Logging out clears local TOPSPOT token storage.

Roadmap Ideas

• Custom titles and captions
• Drag-and-drop album reordering
• More Topster templates
• Artist-level and genre-level boards
• Saved presets
• Custom domain deployment

License

MIT