Build a Spotify Clone with Claude Code

Use Claude Code CLI to build a queue feature for a music app.

Introduction

30 Second Summary

You know how Spotify lets you queue up songs so the next track is always ready? Building a feature like that usually takes hours of reading docs and writing code.

In this project, you will use Claude Code to add a queue feature to a Spotify-style music app called NextSound. You'll work entirely in your terminal, having a conversation with an AI that reads, plans, edits, and runs code for you.

What You'll Build

You'll have a music app running in your browser where you can add songs to a queue, see what's playing next, and remove tracks. All built without writing a single line of code yourself.

By the end of this project, you'll have:

  • A running Spotify-style music app you can interact with in your browser.
  • A queue sidebar where you can add songs, see what's playing next, and remove tracks.
  • A complete feature built entirely through conversation, without writing code manually.
  • Secret Mission: Create a CLAUDE.md project memory file so Claude Code remembers your project's architecture across sessions.

Are there any prerequisites?

This project assumes you already have a Claude Pro subscription and Claude Code installed and authenticated on your Mac. If you don't have Claude Code yet, visit the Anthropic docs to set it up before starting.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters for how you work with code.

Set Up Git and Node.js

Claude Code runs terminal commands for you, from cloning repositories to installing packages to starting servers. For it to do any of this, your machine needs two tools: Git for downloading code and Node.js for running JavaScript projects.

In this step, you'll install both tools and confirm Claude Code is ready to go.

In this step, get ready to:
  • Install and verify Git on your machine.
  • Install and verify Node.js (the JavaScript runtime).
  • Confirm Claude Code is working in your terminal.
Install Git
  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Terminal (macOS/Linux) or PowerShell (Windows) and press Enter to open it.
  • Check if Git is already installed by running this command:
git --version

✔️ I see a version number

You'll see something like git version 2.39.3. The exact number doesn't matter for this project. Git is ready to go.

ⓧ Command not found or install prompt

Git isn't installed yet. Follow the instructions for your operating system:

macOS

macOS may show a dialog asking to install the command line developer tools. This is normal.

  • Click Install in the dialog that appeared.
  • Wait for the installation to complete (this can take a few minutes).
  • If no dialog appeared, trigger it manually by running:
xcode-select --install
  • Once it finishes, close your terminal and open a new one, then run the version check again:
git --version

You should now see a version number printed.

Windows

  • Open git-scm.com/download/win in your browser.
  • Download the standalone installer (64-bit version).
  • Run the installer and accept the default settings at each step.
  • Close PowerShell completely, then open a new PowerShell window.
  • Run the version check again:
git --version

You should now see a version number printed.

Linux

  • Install Git using your package manager by running:
sudo apt install git

If you're on Fedora or RHEL, use sudo dnf install git instead.

  • Once it finishes, run the version check again:
git --version

You should now see a version number printed.

Still not seeing a version number?

Close your terminal completely and open a new window. Some installations require a fresh session to pick up the new PATH entries.

On macOS, if the Xcode dialog never appeared, try xcode-select --install manually. On Windows, make sure you selected the option to add Git to your PATH during installation.

help me troubleshoot why git --version is not working after installation

Install Node.js

Node.js is the JavaScript runtime that powers the NextSound music app. The project requires version 18 or higher.

  • Check if Node.js is already on your machine by running:
node --version

✔️ I see version 18 or higher

If you see v18.x.x or above (like v24.18.0), Node.js is ready. Skip ahead to the next substep.

  • Confirm npm is also available by running:
npm --version

You should see a version number printed. Both tools are good to go.

ⓧ I see an older version

Your installed Node.js is below version 18. You'll need to upgrade it.

  • Open nodejs.org/en/download in your browser.
  • Download the LTS installer for your operating system (.pkg for macOS, .msi for Windows).
  • Run the installer and follow the prompts.
  • Close your terminal completely, then open a fresh terminal window.
  • Verify the upgrade by running:
node --version

You should now see v24.18.0 or a similar version 18+ number.

  • Also confirm npm is available:
npm --version

You should see a version number printed.

Still seeing the old version after installing?

The most common cause is running the check in the same terminal window you had open before the install. Close all terminal windows and open a brand new one.

If it still shows the old version, the old Node.js path may be taking priority. Run which node (macOS/Linux) or where.exe node (Windows) to see which binary your terminal is using.

help me figure out why my terminal is still showing an old Node.js version after I installed the latest LTS

ⓧ Command not found

Node.js is not installed on your machine. You'll install the current LTS version.

  • Open nodejs.org/en/download in your browser.
  • Download the LTS installer for your operating system (.pkg for macOS, .msi for Windows, or use NodeSource for Linux).
  • Run the installer and follow the prompts.
  • Close your terminal completely, then open a fresh terminal window.
  • Verify the installation by running:
node --version

You should see v24.18.0 or a similar version 18+ number.

  • Also confirm npm is available:
npm --version

You should see a version number printed.

Verify Claude Code is working

Your prerequisites say Claude Code is already installed and authenticated. Let's confirm it's ready before we rely on it for the rest of this project.

  • Confirm Claude Code is installed by running:
claude --version

You should see a version number printed.

Now for the real test. What do you think will happen when you start an interactive Claude Code session? Will it ask you to log in, or drop you straight into a prompt?

  • Start an interactive Claude Code session by running:
claude
  • Claude Code will show a workspace security check asking if you trust this folder. Select Yes, I trust this folder to continue.

You should see the Claude Code interactive prompt with the model name displayed. Authentication is working.

  • Exit the session for now by typing:
/exit

Seeing 'command not found' for claude?

This means Claude Code is not installed or not in your terminal's PATH. Since this project assumes Claude Code is already set up, revisit the installation steps from Anthropic's documentation.

If the command works but the session asks you to authenticate, follow the on-screen prompts to sign in with your Claude Pro account.

help me get Claude Code working in my terminal

Your environment is locked in:

  • You have Git for cloning repositories
  • Node.js for running JavaScript
  • Claude Code for building features through conversation

Next up, you'll put all three to work by cloning the NextSound codebase and exploring it with Claude Code.

Clone and Explore the Codebase

You have all the tools installed, but no project to work with yet. Time to get the starter code on your machine.

Claude Code can clone repositories, read files, and explain unfamiliar code. In this step, you'll use it to download the NextSound music app and understand how it's structured.

In this step, get ready to:
  • Clone the NextSound starter repository to your Desktop.
  • Ask Claude Code to explain the app's structure and purpose.
  • Identify the key components that handle songs and playback.
Clone the repository with Claude Code

You'll use Claude Code to clone the NextSound repository from GitHub. No Git syntax to remember. Just plain English.

  • In your terminal, move to your Desktop by running this command:
cd ~/Desktop
  • Start a Claude Code interactive session by running:
claude

You'll see the Claude Code prompt appear, showing the current model and your working directory. You may also see a greyed-out suggested command. Ignore the suggestion and type your own prompt.

  • Clone the NextSound repository by typing this into your Claude Code session:
Clone the repository at https://github.com/nextwork-projects/nextsound.git into this directory

What happens when you send this prompt?

Claude Code reads your request and decides it needs to run a git clone command. Before running it, Claude Code asks for your permission.

You'll see a prompt like "Claude wants to run: git clone..." with options to accept or reject. Press Yes to approve the command. Claude Code then downloads the repository to your Desktop.

Once the clone finishes, you should see output confirming the repository was cloned successfully.

  • Exit your Claude Code session by typing:
/exit
  • Navigate into the cloned project folder in your Terminal by running:
cd nextsound
  • Confirm you're in the right folder by running:
ls

You should see files like package.json, tsconfig.json, and a src folder listed in the output. This confirms the repository cloned correctly.

  • Start a new Claude Code session inside the project by running:
claude

Claude Code now launches inside the nextsound directory. This gives it full visibility into the project files when you ask questions.

Clone failed or folder not found?

  • If the clone failed with a network error, check your internet connection and try the prompt again in a new Claude Code session.
  • If cd nextsound says "No such file or directory", make sure you were on the Desktop when you started Claude Code. Run ls ~/Desktop to check if the nextsound folder exists there.
  • Help me troubleshoot why my repository didn't clone correctly with Claude Code.
Explore the codebase

You're inside the project with Claude Code running. Instead of opening files one by one, ask it to summarize the whole thing.

  • Ask Claude Code to explain the project by typing this prompt:
Explain this web app to me. How are the files organized? What does this web app do? Please be concise, max 4 sentences.

What does this prompt do?

Claude Code reads through the project's files to understand the structure. It looks at package.json for dependencies, config files for the build setup, and source files for the application logic.

The "max 4 sentences" constraint keeps the answer focused. Without it, Claude Code might write paragraphs of detail you don't need yet.

  • Read Claude Code's response. It should explain that NextSound is a React/TypeScript music discovery app built with Vite, using Redux Toolkit for state management.

Getting a very long response?

If Claude Code ignores the "max 4 sentences" instruction and writes a long explanation, that's fine. The key information you're looking for is the tech stack (React, TypeScript, Vite, Redux Toolkit) and that it's a music app.

You can always run /clear to reset the conversation and try a more specific prompt.

Dig deeper into key components

You now know what the app is. The next question is which specific files you'll be working near when you build the queue feature. Let Claude Code map that out for you.

Before you ask, think: which parts of a music app handle displaying songs and controlling playback?

  • Ask Claude Code about the key components by typing:
What components handle displaying songs and playing music? Show me the key files involved.

What does this response tell you?

Claude Code navigates the codebase and identifies the React components responsible for rendering song tiles and managing the audio player. It shows you file paths and explains what each component does.

You should now see a clear breakdown of the components that handle songs and playback.

Claude Code not reading files?

  • Make sure you started your Claude Code session from inside the nextsound folder. If you started it from the Desktop, Claude Code won't see the project files. Exit with /exit, run cd ~/Desktop/nextsound, and start again with claude.
  • If Claude Code asks for permission to read files, approve it. It needs file access to answer questions about the code.
  • Help me get Claude Code to read my project files and explain the codebase.

You've got a mental map of the codebase. Next up, you'll run the app and see it in your browser before adding any new features.

Run the App Locally

In the last step, you used Claude Code to explore and understand the NextSound codebase. Now it's time to see the app running in your browser.

Running the app first gives you a "before" snapshot. When you add the queue feature later, you'll know exactly what changed.

In this step, get ready to:
  • Install dependencies and start the dev server.
  • Confirm the app is running in your browser.
Install dependencies and run the dev server

The NextSound app needs its packages installed before it can run. Claude Code can handle both the install and the server startup in one go.

  • In your Claude Code session, type the following prompt:
Install the project dependencies and start the development server.

What does Claude Code do with this prompt?

Claude Code interprets your request and runs the appropriate commands. It will run npm install to download all the packages listed in package.json, then run npm run dev to start the Vite development server.

When Claude Code asks for permission to run these commands, approve them.

  • Watch the terminal output. You should see http://localhost:5173 appear once the dev server is ready.

Session seems stuck or hanging?

Long-running commands like dev servers can sometimes cause Claude Code's session to wait indefinitely. If your session appears frozen for more than 30 seconds after npm run dev, press Ctrl+C to interrupt it.

Then open a new terminal tab (Cmd+T on macOS, Ctrl+Shift+T on Windows/Linux), navigate to your project with cd ~/Desktop/nextsound, and run npm run dev directly. You can return to your Claude Code session in the original tab afterwards.

help me fix my Claude Code session hanging on npm run dev

View the app in your browser

The dev server is running. Time to see what the app looks like before you make any changes.

  • Hold Cmd (macOS) or Ctrl (Windows/Linux) and click the http://localhost:5173 link in the terminal output to open it in your browser.
  • If that doesn't work, open your browser manually and paste http://localhost:5173 into the address bar.

You should now see the NextSound music app.

The first photo below showcases the hero section at the top of the webpage.

And the second photo below showcases song tiles with album artwork.

Why establish a baseline?

You're about to add a queue feature to this app. Seeing the current state means you'll immediately notice when your new feature appears. If something looks broken later, you'll know it wasn't there before you made changes.

🙋‍♀️ Seeing a blank page or error?

Check your terminal for red error messages. If you see node_modules related errors, the install may not have completed. Run npm install again in a separate terminal tab, then restart the server with npm run dev.

Make sure the URL is exactly http://localhost:5173 with no extra characters or slashes.

help me troubleshoot why the NextSound app isn't loading in my browser

Your app is up and running. Next up, you'll use Claude Code to plan and build a brand new queue feature for NextSound.

Plan and Build the Queue Feature

Your NextSound app plays music and displays song tiles, but there's no way to line up songs you want to hear next. A queue feature is what turns a basic music player into something you'd actually use day-to-day.

In this step, you'll describe the feature you want to Claude Code, review its plan, then let it build the whole thing across multiple files.

In this step, get ready to:
  • Plan the queue feature by describing requirements to Claude Code.
  • Have Claude Code implement the plan across multiple files.
  • Verify the queue feature works in your browser.
Plan the feature with Claude Code

Before writing any code, you describe what you want the feature to do. This gives Claude Code clear requirements to work from and gives you a chance to review its approach before any files change.

  • In your Claude Code session, type the following prompt to describe the queue feature you want:
Plan a change with me. I'd like to add a queue feature to our music web app. The goal is to let users manage their upcoming songs in a dedicated area. Key requirements: 1) Add an Add to Queue button on each song tile that opens a panel from the right-hand side showing the queue as a vertical list. 2) Users should be able to add songs to this queue panel. 3) Show the currently playing song prominently. 4) Allow users to reorder or remove songs from the queue. 5) Make it easily accessible but not intrusive. 6) Please use only the packages and versions already defined in package.json. Don't make any changes yet, just give me the plan.

What does this prompt do?

This prompt follows a professional pattern: describe the goal, list specific requirements, and explicitly ask for a plan before any changes happen.

The last line is critical. Saying "Don't make any changes yet" prevents Claude Code from jumping straight into editing files. You get to review the approach first.

  • Read the plan Claude Code proposes.

Claude Code's should outline which files it will create or modify, what components it will build, and how the state management will work.

The first photo includes Context, Architecture, Queue operations and Audio player changes.

Next up, the output continues with UI and Known issues to fix as part of this work.

Lastly, the same output has Verification section.

What should I see in the plan?

Claude Code typically proposes creating a new Redux Toolkit slice for queue state, a new sidebar component, and modifications to the existing song tile components. The exact details vary, but it should mention all five requirements from your prompt.

If the plan looks incomplete or misses a requirement, tell Claude Code what's missing. You can ask it to revise before moving on.

Implement the plan

Once you've reviewed the plan and it covers your requirements, it's time to let Claude Code do the building.

  • Tell Claude Code to implement the plan by typing:
This plan looks good. Please implement it now.

What happens next?

Claude Code starts building. It reads existing files, creates new ones, and edits components to wire everything together. You'll see it working through the plan in your terminal.

Approve any permission requests by pressing y or Enter.

  • Watch the terminal as Claude Code creates and modifies files. It typically takes 30-60 seconds to implement the full feature.
  • Approve each permission request as it appears.

✔️ Claude Code finished and moved on

You're all set. Move on to verifying the feature below.

ⓧ Claude Code asked what to do next

Claude Code may finish implementing and ask what you'd like to do next with options like committing the changes, trying it yourself, or something else.

  • Type 2 and press Enter to try it yourself first.
Verify the feature in your browser

Claude Code has finished implementing. Before you look at the result, think about what you expect to see based on your requirements.

  • Before you refresh, predict: what new UI elements should appear on the page based on the five requirements you gave Claude Code?
  • Refresh your browser at http://localhost:5173.

In the first photo, in the webpage view, you should see "Add to Queue" buttons on each song tile. Click one of them to add the song to the queue.

Below, you should see the songs you queued up when clicked on the queue icon in the right corner. The added songs should be reflected there.

Don't see the Add to Queue buttons?

If the dev server stopped during implementation, ask Claude Code to restart it by typing: "Start the dev server again." Then refresh your browser.

If the page loads but buttons are missing, Claude Code may still be implementing. Check your terminal for activity. Wait for Claude Code to finish and show its completion message before refreshing.

If you see errors in the browser console or a blank page, don't worry. Copy any error message you see. The next step covers exactly how to debug with Claude Code.

Why aren't my Add to Queue buttons showing up after Claude Code finished implementing?

Your queue feature is live. Next up, you'll learn how to debug and polish it by giving Claude Code targeted feedback.

Debug and Iterate

Your queue feature is live in the browser. AI-generated code often works on the first try, but it rarely works perfectly. Small errors, visual quirks, or edge cases are completely normal.

In this step, you'll practice the most important skill for working with Claude Code: giving it targeted feedback to go from "mostly working" to "exactly right."

In this step, get ready to:
  • Fix any browser or terminal errors by pasting error messages to Claude Code.
  • Polish visual issues by describing what looks wrong and what you want instead.
  • Confirm the full queue feature works end-to-end.

✔️ My app works with no errors

If your queue feature is working correctly with no red errors in the browser console and no visual issues, skip ahead to the "Confirm everything works" section below.

ⓧ I'm seeing errors or visual problems

This is completely normal with AI-generated code. Follow the steps below to fix errors and visual issues.

Fix any errors

The queue feature Claude Code built in the last step may have runtime errors. These show up as red error messages in your browser console or in your terminal output.

  • Switch to your browser showing the NextSound app at http://localhost:5173.
  • Open the browser console by pressing Cmd+Option+J (macOS) or Ctrl+Shift+J (Windows).
  • Look for any red error messages in the console, and check your terminal for errors too.

If you see an error, copy the full error message. You'll paste it directly into your Claude Code session so it can diagnose and fix the issue.

  • Return to your Claude Code session in the terminal and type a prompt like this:
I'm getting this error: [paste your error message here]. Can you explain why this happens and fix it?

Why paste the full error message?

Error messages contain the exact file name, line number, and failure reason. When you paste the full message, Claude Code can jump straight to the problem instead of guessing. The more specific your input, the more accurate the fix.

  • After Claude Code proposes fixes and asks for permission to edit files, approve them.
  • Refresh your browser to confirm the error is gone from the console.

Still seeing errors after the fix?

Copy the new error message and paste it into your Claude Code session again. Sometimes fixing one issue reveals another underneath. Each round of pasting and fixing gets you closer to a clean console.

If Claude Code's responses seem confused or circular, start a fresh conversation by typing /clear and try again with the error message.

Help me debug errors in my Claude Code queue feature

Fix visual issues

Even when the code runs without errors, the visual result might look off. Wrong colours, unreadable text, or broken layouts are common when AI generates styling for a dark-themed app.

  • Refresh your browser and open the queue sidebar by clicking an Add to Queue button on any song tile.
  • Look at the sidebar carefully. Can you read all the text? Are icons visible? Does the layout look tidy?

A common issue with dark-themed apps is black text on a dark background. If you spot this or any other visual problem, describe it specifically to Claude Code.

  • In your Claude Code session, describe the visual issue. Be specific about what's wrong and what you want instead:
The queue sidebar text is black on a dark background and hard to read. Can you make all text and icons in the queue sidebar white?

What makes a good visual feedback prompt?

Name the exact element ("queue sidebar text"), describe what's wrong ("black on a dark background"), and state what you want ("make it white"). Vague requests like "fix the styling" give Claude Code too little to work with.

The more precisely you describe the gap between what you see and what you want, the fewer rounds of iteration you'll need.

  • Approve Claude Code's file edits when prompted.
  • Refresh your browser and check the sidebar again. The text and icons should now be clearly visible against the dark background.

Still seeing visual problems?

Keep iterating. Describe each remaining issue one at a time. For example: "The remove button is too small to click" or "The song titles are overlapping each other."

Help me describe visual issues to Claude Code effectively

Confirm everything works

Now that errors are fixed and the visuals look right, it's time to test the full queue feature from end to end. This is your final check before calling the feature complete.

Before you test, do you expect the whole queue to work smoothly, or might an edge case be hiding?

  • Refresh your browser at http://localhost:5173.
  • Click Add to Queue on three different songs.
  • Open the queue sidebar and verify all three songs appear in the list.
  • Check that the currently playing song shows prominently at the top of the sidebar.
  • Remove one song from the queue and confirm it disappears from the list.
  • Verify the remaining songs stay in the correct order.

If any part of this flow doesn't work as expected, describe the issue to Claude Code and ask for a fix.

  • If Claude Code's responses feel off-track or repetitive, type /clear to start a fresh conversation, then re-describe the issue.

What does /clear do?

The /clear command starts a fresh conversation with an empty context. Your project files stay untouched and Claude Code keeps its project-level memory, but the conversation history resets. Use it when responses seem confused or circular.

Once the full flow works smoothly, your queue feature is complete. You can add songs, see them queued up, see what's currently playing, and remove tracks you don't want.

Feature still not working after multiple attempts?

Type /clear to reset the conversation. Then give Claude Code a summary of the full problem and what you've tried so far in a single message. A fresh start with full context often produces better results than a long back-and-forth.

If the dev server stopped at any point, ask Claude Code to "start the dev server again" and it will run npm run dev for you.

Help me get my queue feature working end-to-end

Secret mission

Create a CLAUDE.md Project Memory File

Every time you start a new Claude Code session, it starts fresh with no memory of your past conversations. What if you could give it persistent project memory so it's immediately productive every time you return? In this mission, you'll create a CLAUDE.md file that makes Claude Code remember your project's architecture, conventions, and the queue feature you just built.

Clean Up Your Resources

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely locally, so there are no ongoing costs.

Resources you used:

  • Running development server at http://localhost:5173 (free, local only).
  • Cloned nextsound repository on your Desktop.

Keep everything running

No action needed. Choose this if you're still actively building or want to keep experimenting with Claude Code and the queue feature.

  • Your dev server will keep running until you close the terminal window.
  • To restart it later, open a terminal and run:
cd ~/Desktop/nextsound && npm run dev
  • On Windows PowerShell, use:
cd ~\Desktop\nextsound; npm run dev
  • Git and Node.js remain installed on your machine for future projects.

Pause - I'll come back to this later

Shut down the running process to free up your terminal. Your project files stay on your machine for when you're ready to return.

  • In the terminal where the dev server is running, press Ctrl+C to stop the server.
  • Your project folder at ~/Desktop/nextsound (macOS/Linux) or ~\Desktop\nextsound (Windows) remains intact with all your changes.
  • When you're ready to resume, open a terminal and run:
cd ~/Desktop/nextsound && npm run dev
  • On Windows PowerShell, use:
cd ~\Desktop\nextsound; npm run dev

Delete - I don't want to use this again

Remove all project files and start fresh. This permanently deletes the queue feature you built and your CLAUDE.md file.

  • Stop the dev server by pressing Ctrl+C in the terminal where it's running.
  • Delete the project folder by running:

macOS

rm -rf ~/Desktop/nextsound
  • Confirm it's gone by running:
ls ~/Desktop | grep nextsound

You should see no output, confirming the folder has been removed.

Windows

Remove-Item -Recurse -Force ~\Desktop\nextsound
  • Confirm it's gone by running:
Test-Path ~\Desktop\nextsound

You should see False, confirming the folder has been removed.

Linux

rm -rf ~/Desktop/nextsound
  • Confirm it's gone by running:
ls ~/Desktop | grep nextsound

You should see no output, confirming the folder has been removed.

Nice Work!

Nice Work!

You just built a fully functional queue feature for a Spotify clone without writing a single line of code yourself. Everything happened through conversation with an AI coding assistant in your terminal.

You've learned how to:

  • Used Claude Code to explore and understand an unfamiliar codebase in seconds, navigating files and summarizing architecture through conversation.
  • Built a queue feature for a Spotify clone entirely through AI conversation in the terminal, going from plan to working implementation without opening an editor.
  • Learned to debug and iterate with Claude Code using error messages and visual descriptions to refine AI-generated code until it worked exactly right.
  • Secret Mission: Created a CLAUDE.md project memory file that gives Claude Code persistent context about your project's architecture and conventions across sessions.

Ready to quiz yourself?