Find Your Way Around Your Project

In the last lesson you ran one command and got a real app at https://web.localhost. This lesson maps it out. You won't write code yet.

The whole point in one line: once you can name the right folder, your prompts go from "how do I make a page in Next.js?" to "edit the home page", and the second kind works far more reliably.

What you're actually looking at

The page at https://web.localhost is a demo the template ships with: buttons, cards, sliders and toggles, the ready-made building blocks (shadcn/ui) you'll use later. It's a placeholder, not your home page.

Open the project in your editor: code . from inside the project folder. Click through the folders in the sidebar as they come up.

The project is a monorepo

Your project is a monorepo: many related pieces in one repository. Skim the top level:

my-website/
├─ apps/
│  └─ web/                  # your website — the thing at web.localhost
├─ packages/
│  ├─ ui/                   # shared UI components (buttons, cards…), reused everywhere
│  ├─ api/                  # your backend/API (you'll meet this in later lessons)
│  ├─ env/                  # environment variables, kept typed and tidy
│  └─ typescript-config/    # shared TypeScript settings
├─ scripts/                 # one-off maintenance scripts (e.g. upgrading deps)
├─ package.json             # root settings + the list of workspaces above
├─ biome.jsonc              # lint & format rules
└─ turbo.json               # the task runner that ties it all together

Two folders matter to you right now. The agent owns the rest; you'll rarely touch a config file by hand.

• apps/web: your website, the thing running at web.localhost. Almost everything you build next lives here.
• packages/ui: shared UI components, the buttons and cards from the demo. Every app in the repo pulls from here.

Later you'll add a Telegram bot and a desktop app, and they all reuse the same packages/ui as the website. Fix a button once and it's fixed everywhere: bot, website, desktop. Mild overkill for a one-page site, but you won't have to rewire anything when you grow.

Inside the web app: the App Router

Open apps/web/src, where your website's code lives:

apps/web/
└─ src/
   ├─ app/                  # your pages live here (the "App Router")
   │  ├─ page.tsx           #   the home page        →  shows at  /
   │  └─ layout.tsx         #   the frame around every page
   └─ components/           # pieces specific to this app
      └─ providers.tsx      #   app-wide setup (theme, etc.)

Next.js uses the App Router. Its one rule:

Folders inside app/ become pages, and the folder path becomes the URL.

app/page.tsx            →   /            (your home page)
app/about/page.tsx      →   /about
app/blog/page.tsx       →   /blog

To add an About page, you (or the agent) make a folder app/about/ with a page.tsx inside it, and /about exists. No routing setup, no list of pages to register.

Two filenames are special inside app/:

• page.tsx: what a visitor sees at that URL.
• layout.tsx: the frame around every page: shared fonts, the header and footer you'll add later, dark mode. Edit it once, every page changes.

The line that draws the demo

Open apps/web/src/app/page.tsx. It's tiny:

import { Demo } from "@workspace/ui/components/demo";

const Page = () => (
  <div className="flex min-h-svh items-center justify-center">
    <Demo />
  </div>
);

export default Page;

That's the whole home page. <Demo /> is the wall of buttons you saw, and you'll replace that line next lesson with your own content. Don't change anything yet.

The @ shortcuts

Those @ names in the import are shortcuts to places in the repo, so files don't reference each other with long ../../../ paths:

• @workspace/ui/... is the shared packages/ui toolbox: the demo, the buttons, the cards.
• @/... is this app's own src folder (apps/web/src), so @/components/... belongs to the web app only.

Where your stuff goes

Keep this table handy:

Let the agent give you the tour

Start your agent inside the project and try a prompt or two:

Walk me through this project like I'm new to it. What's in apps/web vs packages/ui,
and which file draws the page I see at web.localhost?

and

What does apps/web/src/app/layout.tsx do, in plain English?

or if you want to learn more:

Explain in simple language how nextjs 16 app router works.

Asking the agent to explain your code, not code in the abstract, is one of the most useful habits in this course.

What's next

Next you'll replace that <Demo /> with your own content, your name and your title, built from components you create yourself, and add a second page.