Installation Guide

Before You Start

This one's genuinely easy to run. No database, no environment variables, no API keys. Two things on your machine and you're done:

1. Node.js 20 or newer. Grab it from nodejs.org — take the LTS build, not "Current". Once installed, open your terminal and type node -v. If it prints something like v20.11.0 or higher, you're good. If it prints v16 or v18, upgrade. Next.js 16 will refuse to start on old Node and the error message isn't friendly about it.
2. A code editor. VS Code, whatever you already use.

npm comes bundled with Node, so you don't install it separately.

Step 1 — Open the project folder

Unzip whatever you downloaded. Open that folder in VS Code, then open the built-in terminal with Ctrl + backtick (Cmd + backtick on Mac). Make sure the terminal path ends with the project folder name and not your Downloads folder — this trips up more people than you'd expect.

Step 2 — Install dependencies

npm install

This pulls Next.js, React, Tailwind, Zustand and Framer Motion. Takes two to four minutes on decent internet. You might see a few yellow warnings scroll past — ignore those, they're normal. Red errors are the ones that matter.

Step 3 — Run it

npm run dev

Wait for the line that says it's ready, then open http://localhost:3000 in Chrome.

Step 4 — Confirm it's actually working

The app opens on the Sorting module. Do this:

1. Press play. The bars should start swapping and the pseudocode panel on the right should highlight a different line as it goes.
2. Drag the timeline slider backwards. The bars should jump back to that earlier state instantly, no stutter.
3. Click Pathfinding in the left rail, generate a maze, run A*. You should see the search expand outward and then a final path light up.
4. Copy the URL, paste it into a new tab. Same algorithm, same dataset, same settings. That's the shareable state working.

All four pass? You're done. Go write your report.

Building for submission or hosting

npm run build
npm run start

Run the build before your viva, not during it. If there's a lint or type issue it surfaces here, and you don't want to discover that with your examiner watching. npm run lint checks the code separately.

Common Issues

"Port 3000 is already in use"

Something else is sitting on that port — usually another dev server you forgot to close. Either kill it, or just run on a different port:

npm run dev -- -p 3001

Then open localhost:3001 instead.

npm install fails halfway or throws weird module errors

Almost always a broken partial install from a dropped connection. Delete the mess and start clean:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

On Windows, delete the node_modules folder and package-lock.json manually in File Explorer, then run npm install again.

The app loads but nothing animates

Check the browser console (F12). If you see an error about MAX_STEPS, you've set the array size too high for the algorithm you picked — Bubble Sort on 2,000 elements blows past the 200,000 step cap. Bring the array size down and it'll run.

Saved mazes and settings disappear

You're probably in an incognito window. localStorage gets wiped when incognito closes. Use a normal window.

Still stuck?

Send us a screenshot of the terminal output — the full red block, not a crop. Nine times out of ten it's the Node version and we'll spot it in ten seconds.