Get Started

This guide walks you through cloning the Unwrap frontend, installing it, and running it locally. By the end, you'll have the dev server running with mock data and a passing test suite.

For a quickstart, see the README on github. This page is an expanded version with explanations and troubleshooting.

INFO

If you're an end user looking to use Unwrap, see the User Guide instead.

Prerequisites

Tool	Version	Why
Node.js	24 LTS or newer	Vite 8 and Vitest 4 require Node ≥ 24.
npm	11+	Ships with Node 24. (Yarn or pnpm also work, but npm is what CI uses.)
git	any recent version	Cloning the repo and the Husky hooks both need it.

Check your versions

node --version   # should print v24.x.x or higher
npm --version    # should print 11.x.x or higher
git --version

If node is older, use nvm (macOS/Linux) or nvm-windows to install Node 24.

1. Clone the repository

git clone https://github.com/thebrndt/unwrap-client.git
cd unwrap-client

2. Install dependencies

npm install

This does two things:

1. Installs all packages listed in package.json.
2. Runs the prepare script, which sets up Husky git hooks. From now on, every commit will run lint-staged (ESLint + Prettier) on staged files.

   If npm install fails on the prepare step

   Husky tries to write to .husky/. If you're inside a directory that isn't a git repo (e.g. you downloaded a zip instead of cloning), prepare will fail. Re-clone with git clone and try again.

3. Configure environment variables

Copy the example file:

cp .env.example .env

In development, you can leave every value empty as MSW intercepts all API calls and serves mock data, no backend is required. The variables only matter in specific situations:

Variable	When to set it
VITE_API_URL	When you want to point the frontend at a real backend instead of MSW.
VITE_USE_MOCKS	Set to "true" if you want MSW to keep running in a production build (e.g. for a demo deploy).
VITE_PLAYWRIGHT	Set to "true" only when running Playwright. Disables MSW so Playwright can route requests itself.

For the why behind each variable and how Vite bakes them into the bundle at build time, see src/config/env.ts.

import.meta.env vs process.env

Unwrap is a Vite-bundled SPA. All env vars are accessed via import.meta.env.VITE_* in browser code. They are statically baked into the bundle at build time meaning changing a value requires a rebuild, not a server restart. process.env only works in Node-runtime files like vite.config.ts.

4. Start the dev server

npm run dev

Open http://localhost:5173 in your browser, or whatever development server runs.

What you should see

• The terminal prints VITE v8.x.x ready in N ms and Local: http://localhost:5173/.
• The browser console logs [MSW] Mocking enabled. confirming the mock service worker registered correctly.
• The app loads on the Login page. (You're not authenticated, so protected routes redirect you here.) If any of the above is missing, jump to Troubleshooting.

5. Verify your setup

Run the test suite once to confirm everything is wired up:

npm run test:run

You should see all tests pass with output ending in something like:

Test Files  XX passed
     Tests  XXX passed
  Duration  X.XXs

Watch mode while developing

npm run test:run runs tests once and exits. While developing, use npm run test instead as Vitest defaults to watch mode and re-runs affected tests on save.

Troubleshooting

Port 5173 is already in use

Vite automatically picks the next available port (5174, 5175, etc.) and prints the new URL. Use whatever it says. If you want to free 5173, find and kill the process holding it:

# macOS / Linux
lsof -ti:5173 | xargs kill -9

[MSW] Failed to register a Service Worker

The MSW service worker file lives in public/mockServiceWorker.js. If it's missing or out of date with your installed MSW version, regenerate it:

npx msw init public/ --save

Then refresh the browser.

npm or nvm not found after installing nvm

nvm may not have loaded in your current terminal. Run the following to load it manually, or close and reopen your terminal:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"