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:

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

Clone the Repository

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

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):

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

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

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

Browser Extension (webpack build):

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

webpack compiled successfully

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

Bank Project — API server:

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

Server started on port 5000

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

Memory Game (Next.js + React):

cd memory-game
npm install
npm run dev

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

Quiz App (Vue 3 + Vite):

cd quiz-app
npm install
npm run dev

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):

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

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

Then serve the frontend:

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

AI Framework Project (LangChain):

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:

ls 1-getting-started-lessons/

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

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

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

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

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:

Navigating Lessons

Each lesson directory follows a consistent structure:

{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:

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:

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

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

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:

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:

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.

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.

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:

# 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/:

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:

ls translations/ja/

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:

npm install
npx docsify-to-pdf

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

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

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

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

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:

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:

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.