# Web Dev for Beginners — User Guide

## 1. Quick Start

**Web Dev for Beginners** is a free, open source, 24-lesson web development curriculum created by Microsoft Cloud Advocates. It teaches HTML, CSS, and JavaScript fundamentals through seven hands-on projects — a terrarium, a typing game, a browser extension, a space shooter, a banking app, an AI chat client, and a memory card game.

**Key features:**

- 24 structured lessons across 12 weeks of self-paced learning
- Seven complete, buildable projects with starter code and solutions
- Pre- and post-lesson quizzes via a dedicated Vue 3 quiz app
- Sketchnote visual summaries for every lesson
- Available in 50+ languages through community translations
- No frameworks required for core lessons — vanilla HTML/CSS/JS throughout
- Advanced projects introduce React/Next.js, Vue 3, Express, and LangChain

**Prerequisites:**

- A modern web browser (Chrome, Edge, Firefox, or Safari)
- A text editor (Visual Studio Code recommended)
- Git installed locally
- Node.js ≥ 10 (for project solutions that use npm)

**Get started in 2 minutes:**

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

Open `1-getting-started-lessons/1-intro-to-programming-languages/README.md` in your editor and begin the first lesson.

> [!TIP]
> Each lesson folder contains a `README.md` with the lesson content, a `solution/` directory with the completed code, and links to pre- and post-lesson quizzes. Start with the README, attempt the assignment, then compare against the solution.

**What to try next:**

- Browse the full curriculum outline in the root README
- Jump to a specific project: `3-terrarium/`, `6-space-game/`, or `7-bank-project/`
- Run the quiz app locally (see Installation below)

---

## 2. Installation

### System Requirements

| Requirement | Minimum | Recommended |
|---|---|---|
| **OS** | Any (Windows, macOS, Linux) | Any |
| **Node.js** | 10+ | 18+ |
| **npm** | 6+ | 9+ |
| **Python** | 3.8+ (AI projects only) | 3.11+ |
| **Disk space** | ~200 MB (clone) | ~500 MB (with node_modules) |
| **Browser** | Any modern browser | Chrome or Edge (DevTools lessons) |

### Clone the Repository

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

```text
Cloning into 'Web-Dev-For-Beginners'...
```

> [!IMPORTANT]
> The repository contains 13,000+ files due to translations and images. The initial clone may take several minutes on slower connections. Use `git clone --depth 1` for a shallow clone if you only need the latest content.

### Running Individual Projects

Each project is self-contained. Navigate to the project's solution directory and follow its setup instructions.

**Terrarium (vanilla JS — no install needed):**

Open `3-terrarium/solution/index.html` directly in your browser.

**Typing Game (vanilla JS — no install needed):**

Open `4-typing-game/solution/index.html` directly in your browser.

**Space Game (local server):**

```bash
cd 6-space-game/solution
npm install
npm start
```

```text
Starting up http-server, serving ./
Available on:
  http://127.0.0.1:5000
```

Open `http://localhost:5000` in your browser.

**Browser Extension (webpack build):**

```bash
cd 5-browser-extension/solution
npm install
npm run build
```

```text
webpack compiled successfully
```

Load the `dist/` folder as an unpacked extension in your browser's extension manager.

**Bank Project — API server:**

```bash
cd 7-bank-project/api
npm install
npm start
```

```text
Server started on port 5000
```

Then open `7-bank-project/solution/index.html` in your browser.

**Memory Game (Next.js + React):**

```bash
cd memory-game
npm install
npm run dev
```

```text
▲ Next.js (turbopack)
- Local: http://localhost:3000
```

**Quiz App (Vue 3 + Vite):**

```bash
cd quiz-app
npm install
npm run dev
```

```text
VITE vX.X.X ready
➜ Local: http://localhost:5173/
```

> [!NOTE]
> The quizzes are also hosted online at `https://ff-quizzes.netlify.app/web/` — you do not need to run the quiz app locally to complete the curriculum.

**AI Chat Project (Python backend):**

```bash
cd 9-chat-project/solution/backend/python
python -m venv venv
source ./venv/bin/activate   # Windows: venv\Scripts\activate
pip install openai fastapi uvicorn python-dotenv
python api.py
```

```text
INFO:     Uvicorn running on http://0.0.0.0:5000
```

Then serve the frontend:

```bash
cd 9-chat-project/solution/frontend
npx http-server -p 8000
```

**AI Framework Project (LangChain):**

```bash
cd 10-ai-framework-project/code/python
pip install -qU "langchain[openai]"
export GITHUB_TOKEN=your_token_here
python app.py
```

### Post-Install Verification

After cloning, verify that lesson content loads correctly:

```bash
ls 1-getting-started-lessons/
```

```text
1-intro-to-programming-languages/  2-github-basics/  3-accessibility/  README.md
```

For projects with `package.json`, verify dependencies install without errors:

```bash
cd 7-bank-project/api && npm install && echo "OK"
```

```text
added 55 packages in 3s
OK
```

> [!WARNING]
> Several projects use `npx http-server` on port 5000. If you run multiple projects simultaneously, you will encounter port conflicts. Stop the previous server before starting a new one, or change the port with `-p <port>`.

---

## 3. Configuration

The curriculum projects require minimal configuration. Most lessons work by opening HTML files directly in a browser.

### Environment Variables

| Variable | Project | Purpose | Required? |
|---|---|---|---|
| `PORT` | Bank Project API | Server listen port (default: `5000`) | No |
| `GITHUB_TOKEN` | AI Framework Project | GitHub Models API authentication | Yes (AI lessons only) |

### Browser Extension Configuration

The Carbon Trigger browser extension (`5-browser-extension/`) requires:

1. An API key from CO2 Signal
2. A region/country code (e.g., `US`, `DE`, `FR`)

These are entered through the extension's popup form and stored in `localStorage`.

### Bank Project Client Configuration

The bank app client (`7-bank-project/solution/app.js`) connects to the API at `http://localhost:5000/api` by default. This is defined as the `serverUrl` constant in the source — if you run the API on a different port, update this value.

### Chat Project Configuration

The chat frontend (`9-chat-project/solution/frontend/app.js`) connects to a hardcoded `BASE_URL`. Update this to your backend URL (default expects a GitHub Codespace URL or `http://localhost:5000`).

> [!TIP]
> For the AI-powered projects (lessons 9 and 10), you can use GitHub Codespaces with a built-in `GITHUB_TOKEN` for the simplest setup — no local token configuration needed.

See the Admin Guide for full configuration reference across all projects.

---

## 4. Core Usage

### Curriculum Structure

The curriculum is organized into 10 topic sections containing 24 lessons total:

| Section | Lessons | Topic | Project |
|---|---|---|---|
| **1. Getting Started** | 1–3 | Programming languages, GitHub, accessibility | — |
| **2. JS Basics** | 4–7 | Data types, functions, decisions, arrays/loops | — |
| **3. Terrarium** | 8–10 | HTML structure, CSS layout, DOM manipulation | Virtual terrarium with draggable plants |
| **4. Typing Game** | 11 | Event-driven programming | Speed typing game |
| **5. Browser Extension** | 12–14 | Browser APIs, forms, localStorage, async | Carbon usage tracker extension |
| **6. Space Game** | 15–20 | Canvas, OOP, collision detection, scoring | Space shooter game |
| **7. Bank Project** | 21–24 | HTML templates, routing, forms, state management | Single-page banking app + REST API |
| **8. Code Editor** | 25 | Editor extensions, debugging, customization | — |
| **9. Chat Project** | — | AI integration, fetch API, chat UI | AI chat client + Python backend |
| **10. AI Framework** | — | LangChain, tool calling, multi-turn chat | LLM-powered Python apps |

### Navigating Lessons

Each lesson directory follows a consistent structure:

```text
{section}/{lesson-number}-{topic}/
├── README.md           ← Lesson content (start here)
├── assignment.md       ← Hands-on assignment
├── solution/           ← Complete working code
├── images/             ← Lesson diagrams and screenshots
└── translations/       ← Translated versions
```

1. Read the lesson `README.md` from start to finish
2. Take the pre-lesson quiz (linked at the top of each README)
3. Follow the coding exercises in the lesson
4. Complete the assignment in `assignment.md`
5. Compare your work against the `solution/` directory
6. Take the post-lesson quiz

### Working Through Projects

#### Terrarium Project (Lessons 8–10)

Build an interactive virtual terrarium where users drag and drop plant elements.

**What you learn:** HTML structure, CSS positioning, DOM event handling with closures.

**Running the solution:**

Open `3-terrarium/solution/index.html` in your browser. Drag any of the 14 plant elements to rearrange them.

The project teaches the closure pattern — each plant element gets its own `dragElement()` function scope that tracks position state (`pos1` through `pos4`) via pointer events.

#### Typing Game (Lesson 11)

Build a speed typing game that measures words-per-minute accuracy.

**What you learn:** Event listeners, DOM manipulation, timer logic.

**Running the solution:**

Open `4-typing-game/solution/index.html` in your browser. Click Start, then type the displayed quote. The game highlights the current word and reports your completion time in seconds.

#### Browser Extension (Lessons 12–14)

Build a Chrome/Edge extension that displays carbon intensity data for electricity usage by region.

**What you learn:** Browser extension architecture (manifest, popup, background scripts), `localStorage`, async API calls with axios, webpack bundling.

**Running the solution:**

```bash
cd 5-browser-extension/solution
npm install
npm run build
```

1. Open `chrome://extensions/` (Chrome) or `edge://extensions/` (Edge)
2. Enable "Developer mode"
3. Click "Load unpacked" and select the `dist/` folder
4. Click the extension icon, enter your CO2 Signal API key and region
5. View your region's carbon intensity and fossil fuel percentage

> [!NOTE]
> The extension calls the CO2 Signal API at `https://api.co2signal.com/v1/latest`. You need a free API key from their website. The extension icon color changes based on carbon intensity: green (low) → yellow → brown → dark brown (high).

#### Space Game (Lessons 15–20)

Build a complete space shooter with canvas rendering, object-oriented game entities, collision detection, scoring, and end conditions.

**What you learn:** HTML5 Canvas API, ES6 classes and inheritance, the pub/sub pattern via `EventEmitter`, game loop with `requestAnimationFrame`, sprite-based rendering.

**Running the solution:**

```bash
cd 6-space-game/solution
npm install
npm start
```

Open `http://localhost:5000`. The game features:

| Control | Action |
|---|---|
| `W` / `ArrowUp` | Move up |
| `S` / `ArrowDown` | Move down |
| `A` / `ArrowLeft` | Move left |
| `D` / `ArrowRight` | Move right |
| `Space` | Fire laser |
| `Shift` | Special attack |
| `P` | Pause/resume |
| `F` | Toggle fullscreen |

The settings dialog configures difficulty (`easy`, `normal`, `hard`, `insane`), graphics quality (`low`, `medium`, `high`, `ultra`), volume levels, and control scheme.

> [!TIP]
> The progressive lesson structure builds the game incrementally. Each lesson folder (`1-introduction/` through `6-end-condition/`) has both a `solution/` (complete up to that lesson) and a `your-work/` (starter template) directory. Use `your-work/` to code along, then compare against `solution/`.

#### Bank Project (Lessons 21–24)

Build a full single-page banking application with account creation, login, transaction management, and state persistence.

**What you learn:** Client-side routing with URL hash, HTML templates, form validation, REST API interaction, `localStorage` state management, cross-tab sync.

**Running the solution:**

Terminal 1 — start the API:

```bash
cd 7-bank-project/api
npm install
npm start
```

The client app also works standalone using `localStorage` for data persistence — the API server is optional and demonstrates server-side concepts.

**Bank app features:**

- Create accounts with username, description, currency, and initial balance
- Login with username
- View account dashboard with formatted balance and transaction history
- Add transactions (deposits and withdrawals) with date, description, and amount
- Currency formatting with `Intl.NumberFormat` (supports any ISO 4217 currency code)
- Cross-tab synchronization via the `storage` event
- Schema migration scaffolding for future data format changes

#### Chat Project (AI Integration)

Build an AI-powered chat interface with a Python FastAPI backend and a JavaScript frontend.

**What you learn:** `fetch` API, JSON request/response handling, async/await, HTML escaping for security, typing indicators.

See the Installation section for backend and frontend setup. The chat UI sends messages to a `/hello` endpoint and displays AI responses with timestamps.

> [!WARNING]
> The chat project requires either a GitHub Codespace environment (which provides a `GITHUB_TOKEN` automatically) or a manually configured personal access token. Without authentication, the backend API calls will fail.

#### AI Framework Project (LangChain)

Explore LLM integration patterns using LangChain with GitHub Models.

**What you learn:** Basic LLM invocation, multi-turn conversation with system/human messages, tool calling with TypedDict schemas.

Three Python scripts demonstrate progressively advanced patterns:

| Script | Pattern | Description |
|---|---|---|
| `app.py` | Basic invocation | Send a single prompt, print the response |
| `app-chat.py` | Multi-turn chat | System persona + conversation history |
| `app-tools.py` | Tool calling | Define `add` and `joke` tools, let the LLM choose and invoke them |

#### Memory Game (Bonus Project)

A card-matching memory game built with React 19 and Next.js 16.

**What you learn:** React hooks (`useState`, `useEffect`, `useCallback`), component state management, CSS Grid layout with Tailwind CSS.

```bash
cd memory-game
npm install
npm run dev
```

Open `http://localhost:3000`. Set a grid size (even numbers 2–10), then click cards to find matching pairs. Matched pairs turn green; the game announces victory when all pairs are found.

#### Quiz App

A Vue 3 single-page application hosting the pre- and post-lesson quizzes for the entire curriculum.

```bash
cd quiz-app
npm install
npm run dev
```

Navigate to `http://localhost:5173/`. The app provides routes for each quiz (`/quiz/:id`) and an About page.

---

## 5. Common Tasks

### Starting a New Lesson

1. Navigate to the lesson directory (e.g., `2-js-basics/1-data-types/`)
2. Open `README.md` in your editor or on GitHub
3. Click the pre-lesson quiz link at the top
4. Read through the lesson content, following code examples
5. Complete the assignment in `assignment.md`
6. Take the post-lesson quiz
7. Check `solution/` if you get stuck

### Opening Projects Without a Local Server

For projects that are purely client-side (terrarium, typing game, bank client), open the `index.html` file directly:

```bash
# macOS
open 3-terrarium/solution/index.html

# Windows
start 3-terrarium/solution/index.html

# Linux
xdg-open 3-terrarium/solution/index.html
```

### Using the "Your Work" Starter Templates

The Space Game lessons provide `your-work/` directories alongside `solution/`:

```bash
cd 6-space-game/3-moving-elements-around/your-work
npm install
npm start
```

Code along with the lesson, adding features to the starter template. Compare with `solution/` to verify your implementation.

### Viewing Lessons in a Different Language

Translations live in `translations/{language-code}/`. For example, to read lessons in Japanese:

```bash
ls translations/ja/
```

```text
1-getting-started-lessons/  2-js-basics/  3-terrarium/  ... 7-bank-project/
```

Open the translated `README.md` in any lesson directory.

> [!NOTE]
> Translation completeness varies by language. Some translations are auto-generated via Azure AI Co-op Translator. The English version in the root directories is the canonical source.

### Generating a PDF of the Curriculum

The repository includes a `docsify-to-pdf` configuration:

```bash
npm install
npx docsify-to-pdf
```

```text
Output: pdf/readme.pdf
```

> [!WARNING]
> The PDF generation tool converts the docsify sidebar structure to PDF. It requires Puppeteer (bundled via `docsify-to-pdf@0.0.5`) and a Chromium installation. The output covers the sidebar-defined content, not necessarily every lesson file.

### Building the Browser Extension for Production

```bash
cd 5-browser-extension/solution
npm run build
```

The webpack configuration bundles `src/index.js` and its dependencies (including axios) into a `dist/` directory ready for extension store submission.

### Adding a Transaction in the Bank App

1. Start the bank API server (`cd 7-bank-project/api && npm start`)
2. Open the bank client in your browser
3. Register a new account (username, description, currency, initial balance)
4. Log in with your username
5. Click "Add Transaction"
6. Enter the date, description, and amount (positive for deposits, negative for withdrawals)
7. The balance updates automatically with locale-aware currency formatting

### Running the AI Tool-Calling Example

```bash
cd 10-ai-framework-project/code/python
pip install -qU "langchain[openai]" requests
export GITHUB_TOKEN=your_github_pat
python app-tools.py
```

```text
TOOL CALL: Here's a animals joke!
CONTENT:
```

The script defines `add` and `joke` tools as `TypedDict` classes. The LLM receives the tool schemas, decides which to call based on the prompt, and the script executes the selected function locally.

---

## 6. Troubleshooting

### Diagnostic Decision Tree

```text
Problem with the curriculum?
├── Can't clone the repo? → Check git and network access
├── npm install fails? → Check Node.js version (≥10 for bank API, ≥18 for memory game)
├── Project won't start? → Check if port 5000 is already in use
├── Browser extension not loading? → Run npm run build first, then load dist/
├── AI projects fail? → Check GITHUB_TOKEN is set
└── Quiz links broken? → Use https://ff-quizzes.netlify.app/web/ instead
```

### Error: `EADDRINUSE: address already in use :::5000`

**Cause:** Another process (or another project from this curriculum) is already using port 5000. Multiple projects default to this port.

**Solution:**

1. Stop the other server process
2. Or change the port: `PORT=5001 npm start` (for the bank API)
3. Or for http-server projects: `npx http-server -c-1 -p 5001`

**Prevention:** Run only one project server at a time, or assign different ports to each.

### Error: `Missing carbon intensity or fossil fuel data`

**Cause:** The CO2 Signal API returned incomplete data for the selected region, or the API key is invalid.

**Solution:**

1. Verify your CO2 Signal API key is correct
2. Try a different region code (e.g., `DE` for Germany, `FR` for France)
3. Check if the API is operational at `https://api.co2signal.com/v1/latest?countryCode=DE`

**Prevention:** Some regions have limited data coverage. European countries generally have the most reliable data.

### Error: `Network response was not ok`

**Cause:** The chat project frontend cannot reach the backend API at the configured `BASE_URL`.

**Solution:**

1. Verify the Python backend is running on port 5000
2. Update `BASE_URL` in `9-chat-project/solution/frontend/app.js` to match your backend URL
3. If not using Codespaces, ensure CORS is not blocking the request

**Prevention:** Start the backend before the frontend. Use `http://localhost:5000` as the `BASE_URL` for local development.

### Bank App: Account Data Lost After Refresh

**Cause:** The client solution stores all data in the browser's `localStorage`. Data persists across refreshes within the same browser and origin.

**Solution:**

1. Check `localStorage` in DevTools → Application → Local Storage
2. Look for the `accounts` and `savedAccount` keys
3. Ensure you are opening the same origin (protocol + host + port)

**Prevention:** The bank client supports cross-tab sync — changes in one tab automatically reflect in others via the `storage` event.

### Space Game: Blank Canvas / No Sprites Loading

**Cause:** Opening the HTML file directly (`file://`) without a local server. The game loads sprite images that may be blocked by browser security policies on `file://` origins.

**Solution:**

```bash
cd 6-space-game/solution
npm install
npm start
```

Always use the local HTTP server (`http://localhost:5000`) for the space game.

### npm Install Fails With Version Errors

**Cause:** Node.js version is too old. The browser extension and memory game require Node.js ≥ 18.

**Solution:**

```bash
node --version
```

If below v18, upgrade Node.js. The bank API works with Node.js ≥ 10, but newer projects require ≥ 18.

> [!CAUTION]
> The `package-lock.json` files are committed with specific lockfile versions. Using a significantly older npm version may produce dependency resolution errors. Use the Node.js LTS version for best compatibility.

### GitHub Issues — Link Checker Report Failures

The repository's automated link checker (issues #1712–#1717) periodically flags broken links in lesson content, typically pointing to external resources that have moved or been taken down.

**Solution:** If you encounter a broken link in a lesson, check the corresponding GitHub issue for status. You can also open a new issue or pull request to fix it.

---

## 7. FAQ

**Q: Do I need to complete the lessons in order?**

The curriculum is designed as a 12-week sequential course, but each project section (terrarium, space game, bank project, etc.) is largely self-contained. The JS Basics section (lessons 4–7) provides foundational knowledge used by all subsequent projects — complete those first, then jump to any project that interests you.

**Q: Can I use this curriculum for a classroom or workshop?**

Yes. The repository is MIT licensed. Each lesson includes teaching files in `teaching-files/`, sketchnote visual summaries in `sketchnotes/`, and quizzes suitable for classroom assessment. The `lesson-template/` directory provides a structure for creating additional lessons.

**Q: Where are the quizzes hosted?**

The quizzes are available at `https://ff-quizzes.netlify.app/web/`. You can also run them locally using the Vue 3 quiz app in `quiz-app/`. Each lesson README links directly to its pre- and post-lesson quizzes.

**Q: Do I need an API key for the main curriculum?**

No. The core 24 lessons (sections 1–8) require no API keys or external services. Only the AI-focused projects (sections 9 and 10) require a `GITHUB_TOKEN` for the GitHub Models API.

**Q: What programming languages does this curriculum teach?**

Primarily JavaScript (vanilla ES6+), with HTML and CSS fundamentals. Advanced projects use Python (AI/chat backend), Vue 3 (quiz app), and React/Next.js (memory game). The core lessons assume no prior programming experience.

**Q: How do I contribute translations?**

Translations are organized under `translations/{language-code}/`, mirroring the English lesson structure. Translations are also partially generated using Azure AI Co-op Translator. Open a pull request against the repository to contribute.

**Q: Why do some links in the lessons point to Microsoft Learn?**

Several lessons are cross-published on Microsoft Learn as interactive modules. The links provide an alternative way to consume the same content with a built-in code playground and progress tracking.

> [!TIP]
> The GitHub repository is the canonical source for the most up-to-date lesson content. Microsoft Learn versions may lag behind recent updates.

**Q: Can I run the projects in GitHub Codespaces?**

Yes. The repository works well in Codespaces. This is especially convenient for the AI projects, as Codespaces automatically provides a `GITHUB_TOKEN` environment variable.

**Q: What is the `Git-Basics/` directory?**

It contains supplementary material on Git fundamentals — branching, merging, and collaboration workflows. It supports lesson 2 (GitHub Basics) in the Getting Started section.

---

_Generated May 2026 from microsoft/Web-Dev-For-Beginners at 1db4ae0. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._