Tour the Next.js starter

Hazel Home already has a product grid and eight pieces of furniture. The inventory comes from an array in the page component, so the storefront can run before we connect FastAPI. We'll start Next.js separately for this tour; in Lesson 2.1, vercel dev takes over starting both apps.

Outcome

Run the Next.js frontend and locate the mock inventory we will replace with a backend request.

Hands-on exercise 1.3

Start the frontend

Open a second terminal at the repository root. Leave the backend running on port 8000, then install and start Next.js:

cd starter/frontend
npm install
npm run dev

Open the local URL printed by Next.js, normally http://localhost:3000. The furniture grid should show all eight items. Next.js 16 requires Node.js 20.9 or later; use a current Node.js LTS release.

Find the mock data

Open starter/frontend/app/page.tsx. The mockItems array provides inventory to the Home component. Its Item type describes the same fields returned by FastAPI.

The page maps over that array to render the product cards. In Section 2, we'll keep the card markup and replace the data source with a request to the backend.

Inspect the project layout

From the repository root, the student project looks like this:

starter/
├── .gitignore
├── backend/
│   ├── main.py
│   ├── pyproject.toml
│   └── uv.lock
└── frontend/
    ├── app/
    │   ├── globals.css
    │   ├── layout.tsx
    │   └── page.tsx
    ├── package.json
    ├── next.config.ts
    ├── postcss.config.mjs
    └── tsconfig.json

Each application has its own dependency file and root directory. Next.js dependencies live in frontend/package.json, and Python dependencies live in backend/pyproject.toml. In the next lesson, we'll add starter/vercel.json to describe how these applications run as services in one Vercel project.

The shared page shell lives in frontend/app/layout.tsx. It imports the global stylesheet and renders the store header. Tailwind CSS v4 starts with @import "tailwindcss" in globals.css.

Try It

With both development servers running, open these URLs:

http://localhost:8000/api/items: inventory from FastAPI
http://localhost:3000: inventory rendered from Next.js mock data

Change an item's name in backend/main.py and refresh both. Only the API response changes at this stage because Next.js has not made a request to FastAPI. Restore the item name after checking.

Stop both development servers with Ctrl+C before continuing. In the next lesson, vercel dev -L starts both apps and supplies the service binding. Once Services is configured, we use that one command for local development.

Commit

If npm install created frontend/package-lock.json, save it from starter/:

git add frontend/package-lock.json
git commit -m "chore(frontend): lock Node dependencies"

If Git reports no changes, the lockfile is already current.

Troubleshooting

npm cannot find package.json: Run npm commands from starter/frontend/, where the frontend's dependency file lives.

Node version error: Run node --version and use a supported Node.js LTS release before reinstalling dependencies.

Port 3000 is busy: Next.js may choose another port. Use the URL printed in its terminal and stop that server before the Services lesson.

Done-When

The frontend loads and displays eight furniture items
You can locate mockItems in frontend/app/page.tsx
The backend and frontend run independently
Both development servers are stopped before the next lesson

Solution

From a terminal at the repository root:

cd starter/frontend
npm install
npm run dev

The starter's Home component renders mockItems until we connect the backend in Section 2.