---
title: "Run with vercel dev"
description: "Replace the two-terminal dev workflow with a single command that serves the Next.js frontend and FastAPI backend from the same origin. This is the setup that mirrors how Vercel runs both in production."
canonical_url: "https://vercel.com/academy/python-on-vercel/run-with-vercel-dev"
md_url: "https://vercel.com/academy/python-on-vercel/run-with-vercel-dev.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-05-10T14:21:34.244Z"
content_type: "lesson"
course: "python-on-vercel"
course_title: "Python on Vercel"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Run with vercel dev

# Run with vercel dev

Two terminals, two ports, two dev servers. That's fine for exploring each app in isolation, but it's about to become a problem. When the Next.js frontend tries to fetch from `http://localhost:8000` in the next lesson, the browser will block the request. Different origins, CORS, all that.

You could fix that by adding CORS middleware. And if your backend and frontend really did live on different domains in production, you'd have to. But they don't. In production on Vercel, Next.js and FastAPI share one domain. So the cleanest fix is to make local dev match production: one URL, same origin.

That's what `vercel dev` does.

## 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.

## Fast Track

1. Stop the two dev servers from Section 1
2. From `starter/`, run `vercel dev`
3. Visit `http://localhost:3000` and `http://localhost:3000/api/items`

## Hands-On

### Stop the old dev servers

Kill the two terminals running `fastapi dev` and `npm run dev`. You won't need them from here on. One process handles both.

### Run vercel dev

From the `starter/` root:

```bash
vercel dev
```

The first time, the CLI prompts you to link the directory to a Vercel project:

```
? 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? ./
```

Accept the defaults. Vercel detects Next.js from `package.json` and Python from `pyproject.toml`. A few seconds later:

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

One URL. Both apps behind it.

\*\*Note: 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`. You'll see the Hazel Home furniture listing with mock data, same as before. The page is being rendered by Next.js running through `vercel dev`, but the output is identical.

### Confirm the backend

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

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

Same data, different URL. Instead of `http://localhost:8000/api/items` from the standalone FastAPI server, the endpoint is now `http://localhost:3000/api/items`, served through `vercel dev`.

### Notice what just happened

The FastAPI code didn't change. The Next.js code didn't change. Only the way we run things changed. And now:

- Both apps answer at `http://localhost:3000`
- There's no cross-origin request because there's no second origin
- CORS isn't something we have to configure because it isn't something that applies

This is the same routing behavior that will happen when we deploy to Vercel in Section 3. Local dev now matches production, and we didn't have to touch a line of application code.

\*\*Note: What about CORS?\*\*

If your backend lived on a different domain from your frontend (say, a
separate FastAPI instance on a VPS), you'd need CORS middleware to allow the
cross-origin request. Because our backend lives in the same project as the
frontend, we don't. Worth knowing CORS exists so you can reach for it when
the architecture calls for it.

## Try It

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

```bash
curl http://localhost:3000/api
```

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

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

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

Both apps, one URL.

## Troubleshooting

**`vercel dev` asks to link to an existing project:** If you've deployed either app before in a different configuration, the CLI may try to link to an existing project. Answer "No" and let it create a fresh one for this course.

**`/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

```bash
cd starter
vercel dev
```

No code changes. The starter files already have the structure `vercel dev` expects.


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)