Week 5 · Day 30 of 91

Vite and the development server

TypeScript, Packages, and Tooling

Objective

Use a build tool without treating it as magic.

TypeScript is similar to design-rule checking: it catches invalid connections before runtime but cannot prove system behavior.

development server
entry points and modules
production build output

Why this matters

Yesterday you learned to read the file that describes a project. Today you generate a real one and refuse to treat any part of it as magic. A build tool is the thing that stands between the files you write and the files a browser downloads, and beginners who never look inside it spend years frightened of their own project folder. By the end of the hour you will have a running development server, a production build you can list on disk, and a written map saying what each generated file is for.

What a build tool is for

On Day 25 you opened an HTML file and the browser ran your script. That works until it doesn't. Three things break the simple approach:

Modules. Browsers can load ES modules over http://, but not from a file:// path, so a project split into modules needs a server even on your own machine.
Languages the browser does not speak. From tomorrow you write TypeScript. No browser runs TypeScript. Something must convert it first.
Many small files are slow to fetch. Thirty modules means thirty network requests. For production you want a few large files instead.

Vite (pronounced "veet") solves all three. It is one tool wearing two hats: a development server while you work, and a bundler that produces the files you deploy. It is a devDependency — a bench instrument, not a part of the shipped product.

The development server

A development server is a program that runs on your own machine, serves your project's files over http://localhost, and updates the page as you edit. That is the whole definition: a local environment that serves and updates your project files.

You met localhost and ports on Day 5. Vite's default is port 5173, so the address is http://localhost:5173/. Start it with npm run dev and it keeps running until you press Ctrl+C.

The updating part has a name: HMR, hot module replacement. When you save a file, Vite works out which module changed and pushes just that module into the already-running page, without a full reload. Saving a CSS file restyles the page while your form still has text in it.

The development server does not create files. Nothing is written to disk while it runs — it transforms modules in memory as the browser asks for them, which is why starting it is nearly instant no matter how large the project grows.

The dev server is a powered bench rig

On the bench, the board sits in a test jig: probe points exposed, jumpers accessible, a supply you can turn down when something smells hot. Tuning a value there takes seconds. The development server is that jig — instrumented, fast to change, and deliberately not what you ship. The production build is the potted unit in the enclosure: no probe points, smaller, and the only version a customer ever sees.

Entry points and modules

An entry point is the one file a tool starts reading from. Everything reachable from it by import is part of the project; everything else is not.

For Vite the entry point is index.html, which is unusual and worth understanding. Vite reads your HTML and looks for <script type="module" src="...">:

<body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
</body>

From /src/main.ts it follows every import — other TypeScript modules, CSS files, even images — and builds a module graph: the tree of everything that file needs, and everything those files need in turn.

import './style.css'
import viteLogo from './assets/vite.svg'
import { setupCounter } from './counter.ts'

Notice that importing CSS and an image is not JavaScript behaviour — plain Node cannot do it. Vite handles those imports itself, and the image import gives you back a URL string you can put in src="...". That is the build tool doing work on your behalf, and it is the first place to look when an import behaves in a way plain JavaScript would not explain.

Following the wiring from the plug

To find out what a machine contains, you start at the mains inlet and trace every wire until you run out of wire. Anything you never reached is not part of the machine. The entry point is the inlet; the module graph is what tracing found.

Production build output

npm run build produces the files you deploy. In the TypeScript template the script is two commands joined by &&, which means "run the second only if the first succeeded":

"build": "tsc && vite build"

tsc is the TypeScript compiler, here running purely as a type check — it reports type errors and writes nothing. Only if it is clean does vite build bundle. So a type error fails your build before a single output file is produced.

vite v8.2.0 building client environment for production...
✓ 9 modules transformed.
dist/index.html                  0.45 kB │ gzip: 0.29 kB
dist/assets/vite-BF8QNONU.svg    8.70 kB │ gzip: 1.60 kB
dist/assets/hero-CLDdwZDr.png   13.05 kB
dist/assets/index-CsUDhMuy.css   4.10 kB │ gzip: 1.46 kB
dist/assets/index-Na4_thdC.js    4.49 kB │ gzip: 2.02 kB

✓ built in 317ms

Everything lands in a folder called dist (short for "distribution"). Three details are worth naming:

Your many modules became one .js file and one .css file. That is bundling.
The filenames contain random-looking strings like index-Na4_thdC.js. That is a content hash: change the file's contents and the name changes. It lets browsers cache a file forever and still pick up your next release, because the next release has a different name.
dist is generated, never edited, and never committed. The Vite template's .gitignore already lists it.

npm run preview serves the built dist folder locally so you can check the real output before deploying. It is not the development server: no HMR, and it will not notice source edits.

Walkthrough

Scaffold the project that will hold the rest of this week's work.

cd ~/fullstack-journey
npm create vite@latest inventory-ts -- --template vanilla-ts
cd inventory-ts
npm install

The -- separates npm's own arguments from the ones passed to the scaffolding tool. "vanilla" means no framework — plain modules, like your Week 4 app. Now list what you were given:

ls -A

.gitignore  index.html  package.json  public  src  tsconfig.json

Your exact list may differ slightly by Vite version; map what you got, not what this page shows. Start the server:

npm run dev

  VITE v8.2.0  ready in 312 ms

  ➜  Local:   http://localhost:5173/

Open that URL. Now edit src/counter.ts — change Count is ${counter} to Clicks: ${counter} — and save. The page updates without you reloading it. That is HMR, and it is the single most convincing demonstration that the server is doing real work.

Stop the server with Ctrl+C and build:

npm run build
ls dist

assets  favicon.svg  icons.svg  index.html

Open dist/index.html in your editor. The <script> tag no longer points at /src/main.ts — it points at the hashed bundle in dist/assets/. That single line is the clearest proof of what a build tool does.

Checkpoint

You should be able to say which files you write, which files Vite generates, and which of the two npm run dev and npm run build writes to disk. (Only build does.)

How to use AI today

Today's mode is reviewer: you already have something concrete, and you ask for criticism of it. A useful review produces specific, actionable findings backed by evidence — "this file is only referenced from index.html, so deleting it breaks the favicon" — not praise, not a rewrite. If a reply is complimentary or vague, the review failed; ask again for defects and evidence.

Reviewer mode, after you have written your own file map

"Review the generated Vite files and tell me which are essential, optional, or safe to delete." Write your own guess for each file first. Then check every claim the AI makes by deleting the file, running npm run build, and putting it back. A claim you did not test is a rumour.

Your turn

Build the deliverable: a running project plus a generated-file map.

Scaffold and install as in the walkthrough, then confirm npm run dev serves the page.
Create notes/vite-map.md inside the project.
For every file and folder in ls -A, write one line: what it is, who reads it, and whether you wrote it or a tool generated it. Cover at minimum index.html, package.json, tsconfig.json, .gitignore, src/, and public/.
Trace the module graph by hand. Start at index.html, note which script it loads, open that file, and list its imports. Write the chain in your map.
Prove the entry point matters: comment out the <script type="module"> line in index.html, reload, and record what you see. Restore it.
Run npm run build, then ls dist and ls dist/assets. Add a section to your map explaining each output file and where its hashed name came from.
Run npm run preview and confirm the built site works. Note the port it reports — it is not
Run git init, then git status. Confirm node_modules and dist do not appear, and say why. Commit the project.

You are done when

Someone could read vite-map.md, delete your whole project except src/, index.html, package.json and tsconfig.json, and rebuild a working app from your description.

Common pitfalls

Editing files in dist. They are overwritten by the next build. Every real change goes in src/ or index.html.
Expecting the dev server to write files. It transforms in memory. If you are looking for output on disk, you wanted npm run build.
Closing the terminal and wondering why localhost died. The server is a running process, as on Day 5. Closing its terminal stops it.
"Port 5173 is in use". An old dev server is still running. Stop it with Ctrl+C in its terminal, or let Vite pick the next free port and use the URL it actually printed.

Verify it yourself

Open today's reference, the Vite Getting Started guide, and find its sections on scaffolding and on the vite build command.

The guide names the folder vite build writes to, and says the option that changes it. Find both and record them.
This lesson said the entry point is index.html. Find where the guide says the same thing, and note the reason it gives for that choice being different from older bundlers.

Add both answers to vite-map.md and commit. Correcting a lesson with something you looked up is the habit this course keeps asking for.

The hour

0–5 min Recall

Without notes, state yesterday’s main idea and one unresolved question.
5–20 min Learn

Read only the listed concept notes and official reference sections needed today.
20–48 min Build

Create a vanilla TypeScript Vite project and identify what each generated file does.
48–55 min Explain and verify

Run the result, inspect evidence, and explain the data/control flow in your own words.
55–60 min Quiz and commit

Complete the quiz, record one lesson, and commit the verified change when applicable.

What to hand in

Deliverable

A running project plus a generated-file map.

Working with AI today

AI as skeptical reviewer

Provide existing work and ask for concrete defects, risks, missing tests, and unsupported assumptions—not praise.

Review the generated Vite files and tell me which are essential, optional, or safe to delete.

References

Vite: Getting started

Explain-back gate

Pass the quiz above to unlock completion.

I can explain: Use a build tool without treating it as magic.
I can identify the input, output, state change, and failure cases in today’s code.
I reviewed any AI-generated change and can justify why it is correct.

Quiz + explain-back checks required.