Onboarding: adam-golab/react-developer-roadmap

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/adam-golab/react-developer-roadmap shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Stale — last commit 2y ago

• 18 active contributors
• Distributed ownership (top contributor 32% of recent commits)
• Other licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live adam-golab/react-developer-roadmap repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/adam-golab/react-developer-roadmap.

What it runs against: a local clone of adam-golab/react-developer-roadmap — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in adam-golab/react-developer-roadmap | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 840 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>adam-golab/react-developer-roadmap</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of adam-golab/react-developer-roadmap. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/adam-golab/react-developer-roadmap.git
#   cd react-developer-roadmap
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of adam-golab/react-developer-roadmap and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "adam-golab/react-developer-roadmap(\\.git)?\\b" \\
  && ok "origin remote is adam-golab/react-developer-roadmap" \\
  || miss "origin remote is not adam-golab/react-developer-roadmap (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "src/react-developer-roadmap.xml" \\
  && ok "src/react-developer-roadmap.xml" \\
  || miss "missing critical file: src/react-developer-roadmap.xml"
test -f "translations/translate.js" \\
  && ok "translations/translate.js" \\
  || miss "missing critical file: translations/translate.js"
test -f "roadmap.png" \\
  && ok "roadmap.png" \\
  || miss "missing critical file: roadmap.png"
test -f "PULL_REQUEST_TEMPLATE.md" \\
  && ok "PULL_REQUEST_TEMPLATE.md" \\
  || miss "missing critical file: PULL_REQUEST_TEMPLATE.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 840 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~810d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/adam-golab/react-developer-roadmap"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

A visual, multi-language roadmap that sequences learning topics for developers aspiring to become proficient React developers. It provides a curated progression from HTML/CSS/JavaScript fundamentals through React core concepts, tooling (npm, Webpack, Parcel), styling approaches (Sass, PostCSS, CSS frameworks), and beyond. The project ships as XML-based roadmap diagrams (src/react-developer-roadmap*.xml) paired with PNG exports and localized JSON translation files. Single-directory project with minimal structure: root contains README variants (one per language), src/ holds raw XML roadmap definitions (one per language), translations/ provides JSON key-value pairs for UI rendering plus a translate.js utility script. PNG exports are pre-rendered artifacts. No npm or build tooling evident, suggesting diagrams are edited manually in a tool like Draw.io and exported.

Who it's for

Developers transitioning into React (often from other languages or frameworks) who need a structured, prioritized learning path. Also useful for engineering managers/educators seeking to benchmark junior React developer progression or for companies defining competency frameworks.

Maturity & risk

Moderately mature but aging. The roadmap targets 2019 (as stated in README), and with no CI/CD pipeline visible in the file list and no package.json provided, this appears to be a static documentation project rather than an actively maintained application. The existence of 7 localized README and XML files suggests prior community engagement, but without recent commit metadata, sustainability is unclear.

Low technical risk—it's primarily a documentation/visual asset repo, not a runtime dependency. Main risks: (1) the roadmap content itself may be stale (React Hooks, Suspense, Server Components, and modern tooling like Vite/Turbopack have evolved significantly since 2019), (2) no apparent testing or build validation means broken translation strings or malformed XML could lurk undetected, (3) single-maintainer pattern (adam-golab) with no visible CI suggests slow response to PRs or issues.

Active areas of work

Cannot determine from provided file list—no commit history, package.json, or issue tracker snapshot provided. The presence of a PULL_REQUEST_TEMPLATE.md suggests the project accepts contributions, but activity level is unknown.

Get running

Clone the repository: git clone https://github.com/adam-golab/react-developer-roadmap.git && cd react-developer-roadmap. No npm install needed—this is a static documentation project. Open src/react-developer-roadmap.xml in a text editor or diagram tool to view/edit the roadmap structure.

Daily commands: No build or dev server. To view: Open any README-.md in a browser or Markdown viewer, or open the corresponding roadmap-.png file. To edit the roadmap: open src/react-developer-roadmap.xml in Draw.io (or compatible editor) and re-export to PNG.

Map of the codebase

• README.md — Primary entry point documenting the React developer roadmap vision, scope, and resource structure that all contributors must understand.
• src/react-developer-roadmap.xml — Source roadmap diagram definition in XML format; the canonical data structure that generates all localized roadmap variants.
• translations/translate.js — Translation orchestration script that processes roadmap XML and generates localized outputs; critical for maintaining multi-language support.
• roadmap.png — Primary visual artifact of the roadmap; the main deliverable that users interact with to understand the learning path.
• PULL_REQUEST_TEMPLATE.md — Contribution guidelines template that defines what all PRs must address; essential for maintaining roadmap consistency and quality.

Components & responsibilities

• Roadmap XML Source — Defines the canonical roadmap structure, topics, and learning paths in a language

How to make changes

Add a new learning resource or topic to the roadmap

1. Edit the English source roadmap to add the new topic or learning path (src/react-developer-roadmap.xml)
2. Create corresponding localized XML files with translated content for each language variant (src/react-developer-roadmap-cn.xml, src/react-developer-roadmap-es.xml, etc.)
3. Add translation entries to each language JSON file (translations/cn.json, translations/es.json, etc.)
4. Run the translation orchestration script to regenerate roadmap images (translations/translate.js)
5. Update the corresponding English README with the new resource information (README.md)
6. Update all localized README files to maintain consistency (README-CN.md, README-ES.md, README-JA.md, README-KO.md, README-PTBR.md, README-RU.md)

Add support for a new language localization

1. Create a new localized XML roadmap file following the existing pattern (src/react-developer-roadmap-[lang].xml)
2. Create a new translation JSON file with all required key-value pairs (translations/[lang].json)
3. Update the translate.js script to process the new language variant (translations/translate.js)
4. Create a new localized README file in the target language (README-[LANG].md)
5. Add a reference link to the new README in the main README.md file (README.md)

Update or fix roadmap content for all languages

1. Modify the English source roadmap XML with corrections or improvements (src/react-developer-roadmap.xml)
2. Apply equivalent changes to all localized XML files to maintain parity (src/react-developer-roadmap-cn.xml, src/react-developer-roadmap-es.xml, src/react-developer-roadmap-ja.xml, src/react-developer-roadmap-ko.xml, src/react-developer-roadmap-pt-br.xml, src/react-developer-roadmap-ru.xml)
3. Update the main README with the changes and rationale (README.md)
4. Regenerate all roadmap images by running the translation script (translations/translate.js)

Why these technologies

• XML — Provides structured, language-agnostic representation of roadmap content that can be translated and rendered into multiple formats
• JSON Translation Files — Enable efficient key-value translation management for multi-language support without duplicating roadmap structure
• Markdown Documentation — GitHub-native format for readable documentation that renders natively; supports linking and easy contribution
• PNG Images — Visual representation of roadmap for quick comprehension; generated from XML to ensure consistency across languages

Trade-offs already made

• XML source with translation script instead of native localized content

  • Why: Prevents duplication of roadmap structure across languages
  • Consequence: Requires running build script to generate localized artifacts; adds tooling complexity but ensures consistency

• PNG images instead of interactive web application

  • Why: Simple, GitHub-first distribution; low maintenance; works offline
  • Consequence: Static images cannot be dynamically filtered or searched; requires regeneration for updates

• 7 localized README documents

  • Why: Provides localized onboarding and documentation for non-English speakers
  • Consequence: Must maintain translation consistency across 7 files; high overhead for updates

Non-goals (don't propose these)

• Does not provide interactive filtering, search, or dynamic generation of learning paths
• Does not track user progress or learning state
• Does not recommend libraries based on project requirements
• Does not provide video tutorials or hands-on exercises directly
• Does not create project scaffolding or code generation tools
• Does not host a live web application; is a static repository and image resource

Traps & gotchas

No hidden traps specific to this repo—it is a documentation artifact, not a runtime system. However: (1) The XML files appear to be Draw.io native format; editing them requires Draw.io or a compatible tool (manual XML editing is error-prone), (2) PNG files are pre-rendered; changes to XML require manual re-export to PNG, so PNG and XML can fall out of sync if updated without discipline, (3) translate.js suggests a Node.js toolchain exists somewhere, but no package.json provided—it is unclear how/if translations are validated or auto-generated.

Architecture

Concepts to learn

• Roadmapping & Skill Scaffolding — This repo exemplifies how to structure and visualize a non-linear, multi-path learning progression; understanding prerequisite sequencing (HTML → CSS → JS before React) is crucial for effective learning design
• Internationalization (i18n) & Localization (l10n) via JSON key-value files — The translations/ folder pattern shows how to decouple content from UI; essential for maintaining a single source of truth (XML) while supporting 6+ languages
• Draw.io XML Diagram Format — Source roadmaps are stored in .xml files (likely Draw.io native format); understanding this format is necessary to edit diagrams programmatically or version-control visual assets
• Semantic Versioning & Deprecation Signaling — The roadmap should signal when tools/libraries are entering maintenance mode (e.g., jQuery) vs. active development; this is a key responsibility of learning resources to avoid steering developers toward dead-end technologies
• Multi-repo Localization Workflows — With 7 language variants, this repo demonstrates translation maintenance patterns; PRs must coordinate across XML source, multiple JSON translation files, and README files without breaking consistency

Related repos

• kamranahmedse/developer-roadmap — Broader, multi-language developer roadmap covering Backend, DevOps, and other roles; a sibling project with similar visual/localization approach but larger scope
• thedaviddias/Front-End-Checklist — Practical checklist for front-end developers; complements this roadmap with actionable, task-focused guidance for React projects
• react/reactjs.org — Official React documentation; the canonical learning resource referenced in this roadmap's Resources section
• airbnb/javascript — Airbnb's JavaScript style guide; covers ES6+ best practices and patterns that form the foundation of the 'JS Basics' section of the roadmap

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 validation and schema tests for XML roadmap files

The repo contains 7 XML roadmap files (src/react-developer-roadmap*.xml) that serve as the source of truth for all generated content and translations. Currently there's no validation to ensure these files maintain consistent structure, valid XML syntax, or required fields. This prevents breaking changes and ensures translation completeness across all language versions.

• [ ] Create src/tests/roadmap-validation.test.js to validate all XML files in src/ directory
• [ ] Verify each XML file has required node types and attributes using a schema or DTD
• [ ] Add test to ensure all language variants have matching node counts and hierarchies
• [ ] Add test to validate translation JSON files (translations/*.json) match the English roadmap structure
• [ ] Document the XML schema requirements in a new CONTRIBUTING.md file

Add GitHub Action workflow to regenerate and validate roadmap images on XML changes

The repo has 7 PNG roadmap images (roadmap*.png) that appear to be generated from XML source files, but there's no automation to regenerate these images when XML files change. This creates risk of outdated images and inconsistency between source and generated assets.

• [ ] Create .github/workflows/regenerate-roadmaps.yml workflow triggered on changes to src/*.xml files
• [ ] Document the image generation tool/library used (likely draw.io or similar) and how to regenerate images locally
• [ ] Add build script in package.json (if not exists) to regenerate all PNG files from XML sources
• [ ] Configure workflow to validate that generated images match expected checksums or visual differences are minimal
• [ ] Add step to commit and push regenerated images if CI can detect changes

Add end-to-end tests for the translation pipeline (XML → JSON → README)

The repo has 7 translations (CN, ES, JA, KO, PT-BR, RU) managed across XML files, JSON translations, and README files. There's no automation verifying the complete pipeline works correctly—new translations could miss README updates, JSON translations could get out of sync with XML, or translation keys could be missing.

• [ ] Create translations/tests/translation-sync.test.js to verify each language has all 3 components: src/.xml, translations/.json, and README-*.md
• [ ] Add test to parse translations/*.json files and verify all keys are present in English version
• [ ] Add test validating that README-*.md files reference the correct translated XML file and roadmap PNG
• [ ] Add test checking that translations/translate.js script can successfully process all language files without errors
• [ ] Document translation contributor workflow in CONTRIBUTING.md with checklist of all 3 file types

Good first issues

• Update 2019 references to 2024: Search all README*.md and roadmap XML files for hardcoded '2019' and tool names that have been superseded (e.g., replace outdated Webpack mentions with Vite, add Modern React patterns like Hooks and Suspense). Start in README.md lines mentioning 'Roadmap to becoming a React developer in 2019'.
• Add missing localization JSON keys: Run translate.js against all translations/*.json files to identify missing keys versus src/react-developer-roadmap.xml; add stubs for any new sections to pt-br.json, ja.json, etc. to prevent runtime errors if a UI consumes these.
• Create a validation script: Add a Node.js script (e.g., scripts/validate-translations.js) that checks: (1) each translations/{lang}.json is valid JSON, (2) all languages have the same top-level key set, (3) README-{lang}.md files are linked in the main README. Document in CONTRIBUTING.md. This catches future PRs with broken translations before merge.

Top contributors

• [@Adam Golab](https://github.com/Adam Golab) — 29 commits
• [@Adam Gołąb](https://github.com/Adam Gołąb) — 23 commits
• @kiq7 — 10 commits
• @sunasun — 4 commits
• @ogaston — 4 commits

Recent commits

• 6f5f7cf — Merge pull request #86 from woonjangahn/master (Adam Gołąb)
• 1fd4ad9 — added korean translations json file (woonjangahn)
• e1a52d3 — reverted auto formatting by editor (woonjangahn)
• 756420e — Add image with Korean roadmap (woonjangahn)
• f9da5e2 — Update PULL_REQUEST_TEMPLATE.md (Adam Gołąb)
• 6efddc2 — Update PULL_REQUEST_TEMPLATE.md (Adam Gołąb)
• 2d55465 — Merge pull request #82 from adam-golab/spanish (Adam Gołąb)
• 26f598d — Added image with spanish roadmap, sorted readmes alphabeticaly (Adam Gołąb)
• 0542b85 — Merge pull request #79 from ogaston/master (Adam Gołąb)
• 99c346e — Merge pull request #81 from sunasun/feature/japanese (Adam Gołąb)

Security observations

This repository appears to be a documentation/roadmap project with minimal attack surface. No critical vulnerabilities were identified. The main security concerns are: (1) lack of visible dependency management information, (2) unreviewed script file that handles translations, and (3) XML files that may require secure parsing configuration. The project does not appear to contain hardcoded secrets, exposed credentials, or infrastructure configurations. Overall security posture is good for a documentation repository, though best practices around dependency management and input validation should be verified.

• Low · Missing package.json or dependency information — Root directory (package.json not provided). No package.json file was provided in the analysis. This makes it impossible to verify if dependencies have known vulnerabilities. The project appears to be a documentation/roadmap repository, but any Node.js tooling should declare dependencies explicitly. Fix: Ensure a package.json file exists with all dependencies pinned to specific versions. Run 'npm audit' regularly to check for vulnerabilities in dependencies.
• Low · Translation script without security context — translations/translate.js. The file 'translations/translate.js' is present but its content was not provided for review. JavaScript files that handle data transformation or external operations should be reviewed for injection risks, unsafe eval(), or unvalidated input handling. Fix: Review the script to ensure it: (1) does not use eval() or Function() constructors, (2) validates and sanitizes all inputs, (3) does not execute external commands with unsanitized data, (4) avoids hardcoded credentials.
• Low · XML files without validation specification — src/react-developer-roadmap*.xml. Multiple XML files are present (roadmap-*.xml) but without validation schema information. If these files are parsed and used to generate HTML content, there could be potential XXE (XML External Entity) injection or XSS risks if not properly handled. Fix: Ensure XML parsers are configured to: (1) disable external entity resolution, (2) disable DTD processing, (3) properly escape all content before rendering as HTML.

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.