Onboarding: microsoft/Web-Dev-For-Beginners

Generated by RepoPilot · 2026-05-04 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 1w ago
• 5 active contributors
• MIT licensed
• CI configured
• ⚠ Small team — 5 top contributors
• ⚠ Concentrated ownership — top contributor handles 62% of commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

A structured 12-week, 24-lesson web development curriculum built by Microsoft Cloud Advocates that teaches JavaScript, CSS, and HTML through hands-on projects including a draggable terrarium (DOM manipulation), a browser extension that tracks carbon usage via the CO2Signal API (using webpack + axios), a space game, and an AI framework project using Python. It solves the problem of beginners lacking a project-grounded, sequenced path into frontend web development. The repo is a flat monorepo of numbered lesson folders (1-getting-started-lessons/, 2-js-basics/, 3-terrarium/, 10-ai-framework-project/, etc.), each containing a README.md lesson, assignment.md, images/, and solution/ subdirectories. The only buildable artifact is the browser extension project which has its own package.json with a webpack build pipeline and an axios HTTP dependency.

Who it's for

Absolute beginners to web development (students, career-changers, bootcamp candidates) who learn best by building real projects, and educators or curriculum designers who want a ready-made, open-source syllabus with quizzes, assignments, and solution code they can fork and adapt.

Maturity & risk

The repo has thousands of stars and contributors (badges visible in README), CI pipelines via GitHub Actions (.github/workflows/ includes link checking, stale issue management, and lock workflows), and multi-language translation automation. It is actively maintained as a curriculum resource rather than a production software library — stable and suitable for learning, but not a deployable software product.

The core curriculum content is low-risk as it is MIT-licensed and Microsoft-backed. The one real software dependency surface is the browser extension project under an implied extensions folder, which uses webpack ^5.105.4 and axios ^1.15.0 (both well-maintained). The CO2Signal API used in the carbon-trigger extension is an external third-party service that requires an API key and could break or change independently. Node >=18.0.0 and npm >=9.0.0 are hard engine constraints.

Active areas of work

Active work includes multi-language translation automation via a GitHub Action (CO-OP TRANSLATOR referenced in README), addition of an AI framework project (10-ai-framework-project/ with Python files app.py, app-chat.py, app-tools.py), and ongoing link validation via .github/workflows/links.yml. The Azure Static Web Apps deployment workflow (azure-static-web-apps-ashy-river-0debb7803.yml) suggests a hosted version of the curriculum site is actively maintained.

Get running

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

To work on the browser extension project:

cd <extension-directory-containing-package.json> npm install npm run build

For the AI project:

cd 10-ai-framework-project/code/python pip install -r requirements.txt # if present python app.py

Daily commands: For the browser extension: npm run watch (development with file watching) or npm run build (production bundle via webpack). Load the resulting dist/ folder as an unpacked extension in Chrome or Edge. For the AI Python project: python 10-ai-framework-project/code/python/app.py. Individual lesson HTML files can be opened directly in a browser — no server required for most lessons.

Map of the codebase

• 3-terrarium/solution/script.js — Core JavaScript implementation demonstrating DOM manipulation, closures, and drag-and-drop — the primary interactive project in the curriculum.
• 3-terrarium/solution/index.html — Main HTML entry point for the Terrarium project, showing proper semantic HTML structure and accessibility patterns taught throughout the course.
• 3-terrarium/solution/style.css — Primary CSS file demonstrating CSS Grid, Flexbox, and styling concepts that are core learning objectives for the CSS lessons.
• 10-ai-framework-project/code/python/app.py — Entry point for the AI framework project module, which represents the newest curriculum addition integrating AI tools with web development.
• 1-getting-started-lessons/README.md — Top-level orientation document for the getting-started section that defines the pedagogical structure all lessons follow.
• .github/workflows/links.yml — CI workflow that validates all hyperlinks across 600 files — critical for maintaining curriculum integrity across all lesson READMEs.
• .devcontainer/devcontainer.json — Defines the standardized development environment for all contributors and students, ensuring consistent tooling across the entire repo.

How to make changes

Add a New Lesson Module

1. Create a new numbered top-level directory following the existing naming convention (e.g., 11-new-topic/) with a README.md that includes lesson objectives, pre-lecture quiz, content, post-lecture quiz, and review. (1-getting-started-lessons/README.md)
2. Add a lesson README.md inside the new module directory, mirroring the structure of an existing lesson with sections: Introduction, Concept Explanation, Code Examples, and Knowledge Check. (3-terrarium/1-intro-to-html/README.md)
3. Create an assignment.md file in the new lesson directory that provides a concrete hands-on task students complete independently. (2-js-basics/1-data-types/assignment.md)
4. Add a solution/ subdirectory with working code and a solution README explaining the implementation decisions. (3-terrarium/solution/README.md)

Add a Translation for an Existing Lesson

1. Create a translations/ subdirectory inside the target lesson folder if it does not already exist. (3-terrarium/3-intro-to-DOM-and-closures/translations/README.es.md)
2. Copy the English README.md into the translations folder and rename it using the locale code suffix (e.g., README.fr.md, README.pt.md). (3-terrarium/3-intro-to-DOM-and-closures/translations/README.fr.md)
3. Translate the assignment file as well, following the same naming convention (e.g., assignment.fr.md). (3-terrarium/3-intro-to-DOM-and-closures/translations/assignment.fr.md)

Add a New Python AI Project Variant

1. Create a new Python script in the AI project code directory following the app-<feature>.py naming pattern. (10-ai-framework-project/code/python/app-tools.py)
2. Update the AI project README to document the new variant, its purpose, prerequisites, and how to run it. (10-ai-framework-project/README.md)
3. Add a corresponding solution README explaining the expected output and key learning points for the new variant. (10-ai-framework-project/solution/README.md)

Add a New GitHub Actions Workflow

1. Create a new YAML workflow file in .github/workflows/, following the patterns of existing workflows for trigger events and job structure. (.github/workflows/links.yml)
2. Reference the stale workflow as a pattern for time-based scheduled automation tasks. (.github/workflows/stale.yml)
3. Update the lock workflow if the new automation interacts with issue or PR lifecycle events. (.github/workflows/lock.yml)

Why these technologies

• Vanilla JavaScript — Teaches foundational web concepts without framework abstraction, ensuring students understand the DOM, events, and closures before moving to frameworks.
• Markdown (README.md) — GitHub renders Markdown natively, allowing the curriculum to be consumed directly in the browser without any build step or deployment.
• Python (AI module) — Industry-standard language for AI/ML tooling; used in lesson 10 to integrate with LLM frameworks accessible to beginners.
• Webpack (browser extension module) — Bundles the carbon-trigger extension code so it can be loaded as a Chrome/Edge extension with proper module resolution.
• GitHub Actions — Automates link validation, stale issue management, and PR locking — keeping a high-volume open-source curriculum repo maintainable.
• Dev Containers — Provides a reproducible environment via devcontainer.json so students using GitHub Codespaces get a consistent setup regardless of local OS.

Trade-offs already made

• No frontend framework (plain HTML/CSS/JS for projects)

  • Why: Target audience is absolute beginners who need to understand web primitives before abstractions.
  • Consequence: Projects are simpler but don't reflect modern production patterns; advanced students may need supplemental resources.

• Markdown-only curriculum (no CMS or database)

  • Why: Zero infrastructure cost, works natively on GitHub, and allows community contributions via standard PRs.
  • Consequence: No personalization, progress tracking, or interactive quizzes; learner experience is entirely self-directed.

• Flat directory structure per lesson (lesson + solution co-located)

  • Why: Keeps lesson content and reference implementation together
  • Consequence: undefined

Traps & gotchas

1. The carbon-trigger browser extension requires a free API key from CO2Signal (co2signal.com) — without it the extension silently fails. 2) Node >=18 and npm >=9 are enforced in package.json engines; older Node versions will error on install. 3) The webpack build outputs to a directory that must be manually loaded as an 'unpacked extension' in the browser — there is no auto-install step. 4) The .nojekyll file at root is required to prevent GitHub Pages from ignoring underscore-prefixed folders — removing it breaks the hosted site. 5) Python AI project dependencies are not listed in a requirements.txt in the visible file tree, so the exact packages needed (likely openai SDK) must be inferred from import statements in app.py.

Architecture

Concepts to learn

• Chrome Extension Manifest v3 — The carbon-trigger browser extension targets both Chrome and Edge using the WebExtensions API — understanding Manifest v3's service worker model vs. the older background page model is essential for the extension lesson.
• webpack Code Splitting and Bundling — The extension project uses webpack 5 with watch and build modes to bundle vanilla JS into extension-compatible output — understanding why a bundler is needed for browser extensions clarifies the build pipeline.
• CSS Grid and Flexbox Layout — The terrarium project (3-terrarium/2-intro-to-css/) uses CSS layout to position plants — understanding the difference between Grid (2D) and Flexbox (1D) is core to the CSS lessons.
• DOM Drag Events API — The terrarium project teaches DOM manipulation including making elements draggable using browser native drag events — a non-obvious API that differs from mouse event handling.
• GitHub Actions Workflow Triggers — The repo uses multiple workflow files including stale.yml, lock.yml, and links.yml each with different triggers (schedule, issues, push) — understanding trigger types is needed to maintain or extend the CI configuration.
• Dev Containers (devcontainer.json) — The .devcontainer/devcontainer.json enables one-click GitHub Codespaces setup — understanding this spec lets contributors know the expected development environment without local installation.
• Azure Static Web Apps — The curriculum is deployed via azure-static-web-apps-ashy-river-0debb7803.yml — Azure SWA's automatic PR preview environments and GitHub Actions integration are used to host the curriculum website.

Related repos

• microsoft/ML-For-Beginners — Microsoft's companion curriculum using the same 12-week, project-based format but for Machine Learning — same audience, same pedagogy, natural next step after this repo.
• microsoft/Data-Science-For-Beginners — Another Microsoft beginner curriculum in the same series, covering data science fundamentals with the same lesson/assignment/solution folder structure.
• microsoft/AI-For-Beginners — Directly relevant companion repo given the new 10-ai-framework-project/ section added to this curriculum.
• nickvdyck/webbundlr — Alternative static site bundler approach for web curriculum projects that avoids the webpack configuration complexity seen in the browser extension.
• freeCodeCamp/freeCodeCamp — The dominant alternative open-source web development curriculum — same target audience of beginners learning HTML/CSS/JS, different approach (interactive platform vs. GitHub-based lessons).

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Jest unit tests for the carbon-trigger-extension webpack build (package.json has no test runner)

The carbon-trigger-extension's package.json defines "test": "echo \"Error: no test specified\" && exit 1", meaning there are zero automated tests for the extension's JavaScript logic. The extension uses axios for API calls and webpack for bundling, so adding Jest with axios-mock-adapter would let contributors verify the carbon-usage fetch logic, DOM manipulation, and badge-update functions without a real browser. This is high-value because the extension is a complete, self-contained project students build end-to-end, and having tests models professional practice.

• [ ] Install jest, babel-jest, @babel/core, @babel/preset-env, and axios-mock-adapter as devDependencies in the extension's package.json
• [ ] Add a babel.config.js (or .babelrc) alongside the existing package.json so Jest can transpile ES modules used by the extension source files
• [ ] Create tests/carbonAPI.test.js that mocks axios and asserts the carbon-intensity fetch returns the correct region data structure
• [ ] Create tests/popup.test.js using jsdom (Jest's default env) to test that the badge color changes correctly based on intensity thresholds
• [ ] Update the test script in package.json from the placeholder echo to jest --coverage
• [ ] Add a .github/workflows/test-extension.yml workflow that runs npm ci && npm test on push/PR for the extension directory

Add missing translation files for lessons that have partial translation coverage (e.g. 3-terrarium/1-intro-to-html and 3-terrarium/2-intro-to-css lack a translations/ folder entirely)

Inspecting the file tree shows that 3-terrarium/3-intro-to-DOM-and-closures has a full translations/ directory with 9 language files (es, fr, hi, it, ja, ko, ms, pt, zh-tw), but 3-terrarium/1-intro-to-html and 3-terrarium/2-intro-to-css have no translations/ folder at all. This is an inconsistency that breaks the experience for non-English learners who can read lesson 3 but not lessons 1 or 2 of the same project. A contributor could port one language they know (e.g. Spanish) across the two missing lessons to establish the pattern.

• [ ] Create 3-terrarium/1-intro-to-html/translations/ directory and add README.es.md translated from the existing 3-terrarium/1-intro-to-html/README.md
• [ ] Create 3-terrarium/2-intro-to-css/translations/ directory and add README.es.md translated from 3-terrarium/2-intro-to-css/README.md
• [ ] Follow the exact front-matter and heading structure used in 3-terrarium/3-intro-to-DOM-and-closures/translations/README.es.md to keep consistency
• [ ] Update the main README.md of the repo (or the lesson README) to add a 'Translations' section linking to the new files, matching the pattern already used in lesson 3
• [ ] Open the PR with a checklist noting which languages are still missing so future contributors can pick up remaining languages (fr, hi, it, ja, ko, ms, pt, zh-tw)

Add a GitHub Actions link-checker workflow specifically for the new AI/10-ai-framework-project lessons which currently have no CI coverage

The repo already has .github/workflows/links.yml for link checking, but the 10-ai-framework-project/ directory (including 10-ai-framework-project/README.md, solution/README.md, and three Python source files) was clearly added recently and likely contains external links to Azure OpenAI docs, SDK references, and model endpoints that can rot

Good first issues

1. Add a requirements.txt to 10-ai-framework-project/code/python/ — no dependency file is visible, making the AI project hard to set up without reading source imports manually. 2) Add automated Jest or similar unit tests for the JavaScript examples in 2-js-basics/ — the package.json test script currently just echoes an error, meaning there is zero test coverage for lesson code. 3) Create a solution/ subdirectory for 10-ai-framework-project/ — the solution/README.md exists but the actual solution code appears missing based on the file tree, unlike earlier lessons which include solution code.

Top contributors

• @skytin1004 — 61 commits
• @leestott — 22 commits
• @dependabot[bot] — 14 commits
• @nishantpurohit04 — 1 commits
• @24f2000330 — 1 commits

Recent commits

• 5f22021 — Merge pull request #1795 from mitre88/fix-broken-flexbox-grid-link (leestott)
• f18abad — Update 3-terrarium/2-intro-to-css/assignment.md (leestott)
• 8c3040b — Merge pull request #1793 from microsoft/update-translations (leestott)
• b936bad — fix: replace broken flexbox-vs-grid link with MDN reference (nishantpurohit04)
• baec918 — chore(i18n): sync translations with latest source changes (chunk 1/1, 6 changes) (skytin1004)
• 2fae1b5 — chore(i18n): sync translations with latest source changes (chunk 1/1, 6 changes) (skytin1004)
• eeb49d1 — chore(i18n): sync translations with latest source changes (chunk 1/1, 6 changes) (skytin1004)
• fcd22d3 — chore(i18n): sync translations with latest source changes (chunk 1/1, 6 changes) (skytin1004)
• ecd784c — chore(i18n): sync translations with latest source changes (chunk 1/1, 6 changes) (skytin1004)
• c2abd5d — chore(i18n): sync translations with latest source changes (chunk 1/1, 6 changes) (skytin1004)

Security observations

• Medium · Outdated or Potentially Vulnerable axios Dependency — package.json -> dependencies -> axios. The project uses axios ^1.15.0. While this is a relatively recent version, axios has historically had vulnerabilities including SSRF (Server-Side Request Forgery) and prototype pollution issues in older versions. The caret (^) allows minor/patch updates which could introduce regressions, and the dependency should be pinned and audited. Fix: Pin the exact version of axios (e.g., '1.15.0' without the caret), run 'npm audit' regularly, and consider using automated dependency scanning tools like Dependabot or Snyk to monitor for new CVEs.
• Medium · webpack devDependency Version Pinning Risk — package.json -> devDependencies. webpack ^5.105.4 and webpack-cli ^5.1.4 use caret versioning, allowing automatic minor and patch upgrades. While devDependencies are not typically shipped to production, a compromised or malicious update in the build toolchain could introduce supply chain risks into the build output (the Chrome/Edge extension). Fix: Pin exact versions for devDependencies used in extension builds (e.g., '5.105.4' instead of '^5.105.4'). Use 'npm ci' instead of 'npm install' in CI pipelines to enforce lock file integrity. Regularly review and update the package-lock.json.
• Medium · Browser Extension with Network Access (axios) — Potential Data Exfiltration Risk — package.json, 5-browser-extension (inferred from dependency context). The package is described as a Chrome/Edge browser extension ('carbon-trigger-extension') that includes axios for HTTP requests. Browser extensions with network capabilities can pose a significant risk if the extension makes requests to third-party or attacker-controlled endpoints. Without reviewing manifest.json permissions and the actual request targets, there is a risk of overly broad host permissions or unvalidated URL construction that could enable SSRF or data leakage. Fix: Audit the browser extension manifest for minimum required permissions. Ensure all axios request URLs are hardcoded or strictly validated against an allowlist. Avoid using user-controlled input to construct request URLs. Review Content Security Policy (CSP) settings in the extension manifest.
• Low · No Subresource Integrity (SRI) or Content Security Policy Visible — 3-terrarium/solution, 2-js-basics (general lesson files). The repository is an educational web development project that teaches HTML, CSS, and JavaScript. Educational projects frequently include inline scripts or externally loaded resources without Subresource Integrity (SRI) hashes or proper Content Security Policy (CSP) headers. This could be modeled as insecure practice for learners following the curriculum. Fix: Add examples and guidance in lesson materials demonstrating SRI for external scripts/stylesheets and illustrate how to configure CSP headers. This reinforces secure coding practices for beginners.
• Low · Potential XSS Risk in Educational DOM Manipulation Examples — 3-terrarium/3-intro-to-DOM-and-closures/README.md and related solution files. The lesson '3-terrarium/3-intro-to-DOM-and-closures' explicitly introduces DOM manipulation. Educational code examples at this level often demonstrate innerHTML usage without sanitization to keep examples simple. If students replicate these patterns in real applications without understanding the XSS risk, it could lead to insecure implementations. Fix: Ensure that DOM manipulation examples in lesson materials use textContent or createElement rather than innerHTML where possible. When innerHTML is demonstrated, include explicit security warnings and guidance about sanitizing user input using libraries like DOMPurify.
• Low · AI Framework Code May Handle Sensitive Data Without Guidance — 10-ai-framework-project/code/python/app.py, app-chat.py, app-tools.py. The AI framework project (10-ai-framework-project) contains Python files including app-chat.py, app-tools.py, and app.py. These likely interact with AI APIs and may require API keys or tokens. Without reviewing the files directly, there is a risk that API keys are hardcoded or stored insecurely in the example code, which beginners may replicate. Fix: Ensure all API keys and secrets in example code are loaded from environment variables (e.g., using python-dotenv) and never hardcoded. Include a .env.example file and explicit documentation warning against committing secrets. Verify

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.