Run with vercel dev

So far, Hazel Home requires two terminals and two URLs. That was useful while we inspected each app, but it does not resemble the Vercel deployment we are building.

vercel dev reads the project the way Vercel does in production. It serves Next.js at / and sends /api/* requests to FastAPI, all from http://localhost:3000. We can develop against the same route structure that we plan to deploy.

Outcome

Run both apps together under http://localhost:3000 using vercel dev, and confirm the FastAPI routes are reachable on the same origin as the Next.js app.

Hands-on exercise 2.1

Stop the old dev servers

Stop the terminals running fastapi dev and npm run dev. From this point on, one vercel dev process will serve the project.

Link the project

Current Vercel CLI guidance separates project linking from local development. From the starter/ root, start the link flow:

vercel link

The CLI asks which Vercel project this directory belongs to:

? Set up and deploy "starter"? yes
? Which scope do you want to deploy to? Your Name
? Link to existing project? No
? What's your project's name? hazel-home
? In which directory is your code located? ./

Choose your scope, create the hazel-home project, and keep ./ as the code directory. The CLI stores the link under .vercel/.

Before running a project command, verify the resolved owner and project:

vercel project inspect --non-interactive

Check that the output names the scope and hazel-home project you selected. If it points somewhere else, stop and rerun vercel link with the intended --project and --scope values.

Run vercel dev

Start the local Vercel development server:

vercel dev

Vercel detects Next.js from package.json and installs the Python dependencies declared in pyproject.toml. When the local server is ready, the CLI prints:

> Ready! Available at http://localhost:3000

What vercel dev is doing

The CLI reads your project structure the same way Vercel does at deploy time. Next.js runs as the main app on /. Anything under /api/* routes to your FastAPI app at api/index.py. Both come from one local server on port 3000.

Confirm the frontend

Open http://localhost:3000. Next.js still renders the Hazel Home inventory from mock data, now through the Vercel development server.

Confirm the backend

Open http://localhost:3000/api/items. The FastAPI JSON comes back:

[
  {"id": 1, "name": "Fernwood Sectional", "category": "Seating", "price": 2499.0, "in_stock": true},
  ...
]

The response now comes from http://localhost:3000/api/items instead of the standalone FastAPI server on port 8000. The /api/items path matches the production route we will use later.

Trace the request

We changed the development server rather than either application. A request now follows this path:

http://localhost:3000/api/items → api/index.py → FastAPI /api/items

The frontend and API share an origin, so browser requests between them do not require CORS configuration. Vercel will use the same path-based split when we deploy in Section 3.

What about CORS?

A browser request to a backend on another origin would require that backend to return the appropriate CORS headers. Hazel Home serves both parts from one origin, so its architecture does not need that configuration.

Try It

With vercel dev running, both endpoints should be reachable through localhost:3000:

curl http://localhost:3000/api

{"message": "Hazel Home Furniture API"}

curl http://localhost:3000/api/items | head -c 100

[{"id":1,"name":"Fernwood Sectional","category":"Seating","price":2499.0,"in_stock":true}

Both responses should arrive through port 3000.

Commit

Running vercel dev creates local project metadata in .vercel/. The starter's .gitignore excludes that directory, so there is nothing to commit in this lesson.

Troubleshooting

vercel link offers an unrelated existing project: Choose "No" and create a fresh hazel-home project for the course.

Project inspection shows the wrong scope: Run vercel link --help, then relink with explicit --project and --scope values. Inspect the project again before continuing.

/api/items returns 404 or "Not Found": The FastAPI routes need to match the full path. Open starter/api/index.py and confirm the routes are defined as @app.get("/api") and @app.get("/api/items"), not just / and /items.

Port 3000 is already in use: Another process (like a lingering npm run dev) is holding the port. Kill it with lsof -ti:3000 | xargs kill and try vercel dev again.

Python dependencies not installed: If /api/items throws a Python import error, vercel dev didn't pick up pyproject.toml. Run pip install "fastapi[standard]" from starter/ and restart vercel dev.

Done-When

vercel dev runs without errors from starter/
http://localhost:3000 loads the furniture listing page
http://localhost:3000/api/items returns the FastAPI JSON
Both work in the same browser tab with no CORS errors

Solution

cd starter
vercel link
vercel project inspect --non-interactive
vercel dev

The starter already has the project structure that vercel dev expects.