How to Integrate Bolt.new with Spotify

Before writing any code, create a Spotify application in the Developer Dashboard. Go to developer.spotify.com/dashboard and log in with your Spotify account. Click 'Create App' and fill in a name (anything descriptive), description, and website URL (you can use your Bolt project URL or a placeholder). For Redirect URIs, add two entries now: `http://localhost:3000/api/spotify/callback` for local testing and a placeholder for your future deployed URL like `https://your-app.netlify.app/api/spotify/callback` — you can update this after deployment. After creating the app, click 'Settings' to find your Client ID. Click 'View Client Secret' to reveal the secret — copy both values. Your Client ID is safe to expose publicly (it identifies your app), but your Client Secret must never appear in client-side code. It will only be used in your Next.js API routes. For the API scopes, decide upfront which features you need. Public catalog access (search, albums, artists, playlists) requires no user scopes and uses Client Credentials. User features require specific scopes: `user-read-currently-playing` and `user-read-playback-state` for the Now Playing widget, `playlist-read-private` for private playlists, `user-top-read` for top artists and tracks. Requesting only the scopes you need reduces user friction during the authorization consent screen.

Client Credentials flow is the simpler of the two authorization flows and works perfectly in Bolt's WebContainer. You exchange your client ID and secret for an access token with no user interaction — the token is scoped to public catalog data only. This token expires after 3,600 seconds (1 hour), so your API route should cache it and refresh automatically. Create a token manager module that caches the current token in memory and fetches a new one when it expires. Then create a search API route that calls the Spotify search endpoint with your cached token. The Spotify search endpoint accepts a `q` parameter (the search query) and a `type` parameter specifying what to search (track, album, artist, playlist — comma-separated for multiple). All Spotify API calls from your Next.js API routes work in Bolt's WebContainer preview — outbound HTTP requests are fully supported. The preview cannot receive incoming webhooks or OAuth callbacks, but for read-only Spotify data lookups, the WebContainer is a complete development environment. Test your search endpoint in the preview before building the UI.

1// lib/spotify.ts
2interface SpotifyToken {
3  access_token: string;
4  expires_at: number;
5}
6
7let cachedToken: SpotifyToken | null = null;
8
9export async function getAccessToken(): Promise<string> {
10  if (cachedToken && Date.now() < cachedToken.expires_at - 60000) {
11    return cachedToken.access_token;
12  }
13
14  const clientId = process.env.SPOTIFY_CLIENT_ID!;
15  const clientSecret = process.env.SPOTIFY_CLIENT_SECRET!;
16  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
17
18  const response = await fetch('https://accounts.spotify.com/api/token', {
19    method: 'POST',
20    headers: {
21      'Authorization': `Basic ${credentials}`,
22      'Content-Type': 'application/x-www-form-urlencoded',
23    },
24    body: 'grant_type=client_credentials',
25  });
26
27  if (!response.ok) {
28    throw new Error(`Spotify token error: ${response.status}`);
29  }
30
31  const data = await response.json();
32  cachedToken = {
33    access_token: data.access_token,
34    expires_at: Date.now() + data.expires_in * 1000,
35  };
36
37  return cachedToken.access_token;
38}
39
40export async function searchTracks(query: string, limit = 20) {
41  const token = await getAccessToken();
42  const params = new URLSearchParams({
43    q: query,
44    type: 'track,artist',
45    limit: String(limit),
46  });
47
48  const response = await fetch(`https://api.spotify.com/v1/search?${params}`, {
49    headers: { 'Authorization': `Bearer ${token}` },
50  });
51
52  if (!response.ok) {
53    throw new Error(`Spotify search error: ${response.status}`);
54  }
55
56  return response.json();
57}
58
59export async function getPlaylist(playlistId: string) {
60  const token = await getAccessToken();
61  const response = await fetch(
62    `https://api.spotify.com/v1/playlists/${playlistId}?fields=id,name,description,images,tracks.items(track(id,name,artists,duration_ms,preview_url,album(images)))`,
63    { headers: { 'Authorization': `Bearer ${token}` } }
64  );
65  if (!response.ok) throw new Error(`Spotify playlist error: ${response.status}`);
66  return response.json();
67}

With the search API route working, build the React search interface. The UI centers around a debounced search input, a results grid showing album art and track metadata, and inline audio preview playback. Spotify provides 30-second MP3 preview clips for most tracks via the `preview_url` field — these work in standard HTML audio elements with no Spotify SDK required. Implement debouncing on the search input (300ms delay) to avoid firing API calls on every keystroke. Use React's `useState` and `useEffect` for the debounce pattern, or install the `use-debounce` package if available. The results grid shows album art (use the smallest image from `album.images` array for thumbnails), track name, artist names (comma-joined), and album name. For the audio preview player: use a single `<audio>` element managed by React ref — only one track plays at a time, and clicking a new track stops the current one. Show a play/pause toggle button on each track card, and a mini player at the bottom of the page showing the currently playing track with the album art and a progress bar. Note: preview_url is null for some tracks (particularly in certain regions or for very new releases). Handle this gracefully by hiding the play button for tracks without a preview URL.

1// app/api/spotify/search/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { searchTracks } from '@/lib/spotify';
4
5export async function GET(request: NextRequest) {
6  const query = request.nextUrl.searchParams.get('q');
7  if (!query || query.trim().length < 2) {
8    return NextResponse.json({ tracks: { items: [] } });
9  }
10
11  try {
12    const data = await searchTracks(query.trim());
13    return NextResponse.json(data);
14  } catch (error) {
15    console.error('Spotify search error:', error);
16    return NextResponse.json(
17      { error: 'Failed to search Spotify' },
18      { status: 500 }
19    );
20  }
21}

For user-specific Spotify data — currently playing, private playlists, listening history, playback controls — you need Authorization Code flow with user consent. This requires implementing three API routes: a login initiator that redirects to Spotify, a callback handler that exchanges the code for tokens, and a token refresh route for keeping sessions alive. The critical constraint: Bolt.new's WebContainer preview has a dynamic URL that changes between sessions and cannot be registered as a Spotify redirect URI. Authorization Code flow OAuth callbacks will not work in the Bolt preview. You must deploy to Netlify first, then register the deployed URL (`https://your-app.netlify.app/api/spotify/callback`) in your Spotify app settings. Store the refresh token in an HTTP-only cookie — this is more secure than localStorage and works correctly with Next.js server components. The refresh token is long-lived (until the user revokes access) and lets you get new access tokens without re-prompting the user. Store access tokens in memory (module-level cache or Redis for production) since they expire every hour. For PKCE (Proof Key for Code Exchange): Spotify supports PKCE as an alternative to client secret for the Authorization Code flow. PKCE is appropriate for pure client-side apps with no server. Since your Bolt app has Next.js API routes, use the standard Authorization Code flow with client secret on the server — it is more secure and better supported.

1// app/api/spotify/callback/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function GET(request: NextRequest) {
5  const { searchParams } = request.nextUrl;
6  const code = searchParams.get('code');
7  const state = searchParams.get('state');
8  const error = searchParams.get('error');
9
10  if (error) {
11    return NextResponse.redirect(new URL('/?error=spotify_denied', request.url));
12  }
13
14  const storedState = request.cookies.get('spotify_auth_state')?.value;
15  if (!state || state !== storedState) {
16    return NextResponse.redirect(new URL('/?error=state_mismatch', request.url));
17  }
18
19  const clientId = process.env.SPOTIFY_CLIENT_ID!;
20  const clientSecret = process.env.SPOTIFY_CLIENT_SECRET!;
21  const redirectUri = process.env.SPOTIFY_REDIRECT_URI!;
22  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
23
24  const tokenResponse = await fetch('https://accounts.spotify.com/api/token', {
25    method: 'POST',
26    headers: {
27      'Authorization': `Basic ${credentials}`,
28      'Content-Type': 'application/x-www-form-urlencoded',
29    },
30    body: new URLSearchParams({
31      grant_type: 'authorization_code',
32      code: code!,
33      redirect_uri: redirectUri,
34    }),
35  });
36
37  if (!tokenResponse.ok) {
38    return NextResponse.redirect(new URL('/?error=token_exchange_failed', request.url));
39  }
40
41  const tokens = await tokenResponse.json();
42  const response = NextResponse.redirect(new URL('/', request.url));
43
44  // Store refresh token in HTTP-only cookie (7 days)
45  response.cookies.set('spotify_refresh_token', tokens.refresh_token, {
46    httpOnly: true,
47    secure: true,
48    sameSite: 'lax',
49    maxAge: 7 * 24 * 60 * 60,
50    path: '/',
51  });
52
53  // Clear the state cookie
54  response.cookies.delete('spotify_auth_state');
55
56  return response;
57}

With both Client Credentials (search) and Authorization Code (user features) implemented, deploy to Netlify for full end-to-end testing of the OAuth flow. In Bolt.new, click the Deploy button, connect to Netlify via OAuth, and complete the deployment. Your app will get a `*.netlify.app` subdomain. After deployment, go to Netlify's dashboard → Site Configuration → Environment Variables and add: `SPOTIFY_CLIENT_ID`, `SPOTIFY_CLIENT_SECRET`, and `SPOTIFY_REDIRECT_URI` (set this to `https://your-site.netlify.app/api/spotify/callback`). Trigger a redeploy for the new environment variables to take effect. Now register the production callback URL in Spotify: go to developer.spotify.com/dashboard → your app → Settings → Redirect URIs → Add URI → enter your Netlify callback URL and save. You should now have both `http://localhost:3000/api/spotify/callback` and `https://your-site.netlify.app/api/spotify/callback` in the list. Test the full OAuth flow on the deployed site: visit your Netlify URL, click the Spotify login button, authorize the app, and confirm you are redirected back to your app with user data loading. The now-playing widget will show 'Nothing playing' if you are not listening to Spotify — open Spotify on your phone or desktop and start a song to verify the widget works. Note: during development in Bolt's WebContainer, outbound API calls to Spotify work (search, catalog browsing), but OAuth callbacks cannot reach the WebContainer's dynamic preview URL. This is a WebContainer limitation — always test OAuth on the deployed Netlify URL.

1# netlify.toml
2[build]
3  command = "npm run build"
4  publish = ".next"
5
6[[plugins]]
7  package = "@netlify/plugin-nextjs"
8
9[build.environment]
10  NODE_VERSION = "20"
11
12# Headers for security
13[[headers]]
14  for = "/*"
15  [headers.values]
16    X-Frame-Options = "DENY"
17    X-Content-Type-Options = "nosniff"