Onboarding: RaspberryPiFoundation/blockly

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/RaspberryPiFoundation/blockly 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

GO — Healthy across the board

• Last commit 1d ago
• 9 active contributors
• Distributed ownership (top contributor 42% of recent commits)
• Apache-2.0 licensed
• CI configured
• ⚠ 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 RaspberryPiFoundation/blockly repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/RaspberryPiFoundation/blockly.

What it runs against: a local clone of RaspberryPiFoundation/blockly — 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 RaspberryPiFoundation/blockly | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>RaspberryPiFoundation/blockly</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of RaspberryPiFoundation/blockly. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/RaspberryPiFoundation/blockly.git
#   cd blockly
#
# 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 RaspberryPiFoundation/blockly and re-run."
  exit 2
fi

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

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/RaspberryPiFoundation/blockly"
  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

Blockly is a visual programming editor library that transforms code into interlocking graphical blocks, allowing users to program without syntax knowledge. It's a web-based editor (primary JavaScript/TypeScript) maintained by the Raspberry Pi Foundation that generates executable code from block-based visual representations, with support for multiple target languages (Python, PHP, Dart, Lua, JavaScript). Monorepo structure: packages/blockly/ is the core library with blocks/ subdirectory (blocks.ts, lists.ts, logic.ts, loops.ts, math.ts, procedures.ts) defining block categories. appengine/ contains a deployable reference implementation. Build outputs to blockly_compressed.js. Architecture separates block definitions (XML-based block specs) from code generators (language-specific transpilation) and the visual editor runtime.

Who it's for

Educators and developers building programming learning environments for beginners, plus maintainers/contributors adding language support, block definitions, and editor features. Users integrate Blockly into their own web apps via the npm package to teach programming fundamentals without syntax barriers.

Maturity & risk

Highly mature and actively maintained. The project is a monorepo (packages/blockly) with 5.4M lines of code, comprehensive CI/CD pipelines (.github/workflows/ for browser tests, builds, and deployments), Apache-2.0 licensed, and published to npm as 'blockly'. Recent commit activity and multiple active workflows indicate ongoing maintenance from the Raspberry Pi Foundation.

Low risk for production integration. Large established codebase with extensive test automation (browser_test.yml), conventional commit enforcement (commitlint.config.mjs), and semantic versioning via publish.yml. Main risk: broad scope (supports 6 target languages and multiple block types) means API surface is large; contributors must understand the transpilation layer for multiple languages. No obvious single-maintainer dependency based on CODEOWNERS presence.

Active areas of work

Active development across multiple areas: CI/CD pipeline refinement (assign_reviewers.yml, conventional-label.yml), deployment automation to Google App Engine (appengine_deploy.yml), documentation generation (deploy-docusaurus.yml), and dependency management (dependabot.yml for automated updates). Pull request template and contributing guide in .github/ indicate structured review process.

Get running

git clone https://github.com/RaspberryPiFoundation/blockly.git
cd blockly
npm install
npm run build
npm test

Daily commands: From package.json root scripts: npm run build --ws builds all packages, npm test --ws runs tests, npm run lint --ws lints, npm run format:check --ws checks formatting. Dev server likely runs from packages/blockly/ with a build tool (exact command not visible in provided config, check packages/blockly/package.json).

Map of the codebase

• packages/blockly/blocks/blocks.ts: Core block definition file; defines fundamental block categories and structure for all visual programming constructs
• package.json: Root monorepo config with npm workspaces; orchestrates build/test/lint for all packages including blockly core
• .github/workflows/browser_test.yml: Automated browser-based test pipeline ensuring visual editor functions correctly across browsers
• packages/blockly/appengine/main.py: Reference implementation of Blockly deployed to Google App Engine; shows how to integrate the library
• .github/CONTRIBUTING.md: Contributor guidelines; necessary read before submitting PRs to understand commit conventions and review process
• commitlint.config.mjs: Enforces conventional commits format across all commits; critical for understanding contribution standards

How to make changes

Start here for common changes: (1) New block types → packages/blockly/blocks/ (add to blocks.ts or category file like math.ts); (2) Code generation for a language → look for language-specific generator files (not visible in snippet, likely in packages/blockly/generators/); (3) Documentation → MDX files (900K of them); (4) Block definitions → blocks/ directory uses TypeScript block specs; (5) Editor UI customization → investigate .prettierrc.js and renderer plugins mentioned in README (blockly-samples repo).

Traps & gotchas

No obviously hidden traps in the provided data, but: (1) The appengine/ directory suggests some deployment targets Google Cloud specifically; check deployment docs if integrating elsewhere. (2) The blockly package is published to npm but depends on code generation for multiple languages (Python, PHP, Dart, Lua) — adding language support requires understanding the generator plugin system not visible in this file list. (3) .npmrc and .prettierignore suggest specific npm registry or publishing config; check these if publishing or installing from private sources. (4) Block definitions in packages/blockly/blocks/ are TypeScript — changes require TypeScript knowledge and must rebuild (npm run build).

Concepts to learn

• Code Generation / Transpilation — Blockly's core function: blocks must be converted to executable code in Python, PHP, Dart, Lua, or JavaScript. Understanding the generator pattern is essential for adding language support or debugging code output.
• Block Serialization (XML/JSON) — Blockly programs are serialized as XML or JSON (visible in appengine/storage.js/storage.py); contributors need to understand how to save, load, and transmit block workspaces between client and server.
• Plugin Architecture — Blockly is extended via plugins (themes, renderers, custom fields, block definitions); the blockly-samples repo and copilot-instructions.md indicate this is how custom features are added without modifying core.
• Abstract Syntax Tree (AST) — Blocks represent an AST that is traversed during code generation; understanding AST traversal and statement/expression semantics is critical for fixing generator bugs or adding new block types.
• Type Safety in Visual Programming — Block categories (logic, math, loops, procedures, lists) enforce programming concepts; type checking between block inputs/outputs prevents invalid program structures at the visual level, not the code level.
• Monorepo / Workspace Management — This is a monorepo using npm workspaces; understanding npm run <cmd> --ws and package.json workspaces array is essential for building, testing, and publishing the entire project coherently.
• Conventional Commits — commitlint.config.mjs enforces conventional commit format (feat:, fix:, docs:, etc.) for all PRs. This is non-negotiable for this project; commits not following the format will be rejected.

Related repos

• RaspberryPiFoundation/blockly-samples — Official companion repo with plugins, examples, and codelabs for extending Blockly with custom fields, themes, renderers, and integrations
• google/blockly — Original Blockly project (now a fork/previous source); Raspberry Pi Foundation maintains this as an active fork with additional features and support
• microsoft/MakeCode — Competing visual programming editor built on Blockly; shows how educators can customize and deploy Blockly for specific curricula (Python, JavaScript targets)
• MIT-RAISE/runtimeServer — Example of a backend that consumes Blockly-generated code and executes it in a sandboxed runtime environment

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 comprehensive unit tests for core/block.ts and core/block_svg.ts

The Block and BlockSvg classes are fundamental to Blockly's rendering and behavior. These files likely contain complex state management and DOM manipulation logic that needs robust test coverage. The browser_test.yml workflow exists but specific unit test files for these core modules are not visible in the file structure, making this a high-value addition for preventing regressions.

• [ ] Create tests/core/block.test.ts covering Block instantiation, field management, and state changes
• [ ] Create tests/core/block_svg.test.ts covering SVG rendering, positioning, and animation logic
• [ ] Add test utilities for mocking workspace and connection objects in tests/core/test_helpers.ts
• [ ] Integrate new tests into the existing browser_test.yml workflow if not already included
• [ ] Document testing patterns in CONTRIBUTING.md for core module tests

Add GitHub Action workflow for TypeScript type checking and strict mode validation

The repo uses TypeScript extensively (blocks/.ts, core/.ts) and has eslint/prettier configured, but there's no dedicated CI workflow visible for strict TypeScript compilation checks. Adding a workflow to validate tsconfig.json settings, catch type errors, and enforce strict null checks would prevent subtle bugs and improve code quality across the monorepo.

• [ ] Create .github/workflows/typescript-check.yml that runs 'npm run build' with --noEmit flag
• [ ] Verify tsconfig.json in packages/blockly has strict: true enabled
• [ ] Add step to check for any 'any' type usage in core and blocks directories (per any_aliases.ts pattern)
• [ ] Configure workflow to fail on compilation errors and report to PR status checks
• [ ] Document TypeScript requirements in .github/CONTRIBUTING.md

Create integration tests for block flyout inflation and rendering pipeline

The file core/block_flyout_inflater.ts suggests complex logic for dynamically creating and rendering block templates. There's no visible test coverage for the full pipeline from block definition to rendered UI. Integration tests would validate the interaction between block.ts, block_svg.ts, and block_flyout_inflater.ts under realistic conditions.

• [ ] Create tests/integration/flyout_inflation.test.ts with test fixtures for various block types
• [ ] Add tests for flyout inflation with blocks from all categories (lists.ts, math.ts, logic.ts, etc.)
• [ ] Test SVG rendering correctness and DOM structure after inflation
• [ ] Add performance benchmarks for large flyout rendering (optional but valuable)
• [ ] Update browser_test.yml to include integration tests in CI pipeline

Good first issues

• Add TypeScript type definitions or documentation comments to packages/blockly/blocks/procedures.ts, which handles function/procedure blocks but lacks inline documentation compared to other category files.
• Create integration test examples in packages/blockly/appengine/ demonstrating how to save/load block XML and generate code for each supported language (Python, PHP, Dart, Lua) — appengine/storage.js exists but examples are sparse.
• Expand .github/CONTRIBUTING.md with concrete examples of adding a new block type (pick one of the category files like math.ts or loops.ts) and submitting a PR, since contributors must understand the block spec format.

Top contributors

• @grega — 42 commits
• @gonfunko — 30 commits
• @maribethb — 17 commits
• @translatewiki — 5 commits
• @github-actions[bot] — 2 commits

Recent commits

• 1e002dd — chore: Localisation updates from https://translatewiki.net (#9809) (translatewiki)
• a7fb78a — chore: Localisation updates from https://translatewiki.net (#9780) (translatewiki)
• 6af2190 — chore: Localisation updates from https://translatewiki.net (#9769) (translatewiki)
• a65a88b — chore: Localisation updates from https://translatewiki.net (#9750) (translatewiki)
• f80253f — fix: Make the undo/redo API more ergonomic (#9573) (gonfunko)
• 0344397 — Merge pull request #9671 from grega/docs (grega)
• 172adb5 — chore(docs): handle hoisted node_modules in Mocha tests (grega)
• 50ea876 — chore(docs): isolate type_definitions from docs related types (grega)
• 593d877 — chore(docs): fix eslint version inconsistency between packages (grega)
• 50445ed — Localisation updates from https://translatewiki.net. (#9716) (translatewiki)

Security observations

The Blockly codebase demonstrates reasonable security practices with Dependabot integration and organized structure. However, several areas require attention: (1) XSS vulnerabilities are the primary concern given the visual editor's nature of rendering user-controlled blocks and comments, (2) Security headers are not visibly configured, (3) Input validation and sanitization in clipboard/comment operations need verification, (4) Dependency management could be more proactive. The monorepo structure and use of TypeScript provide some type-safety benefits. Recommend conducting a focused security audit on DOM manipulation, clipboard operations, and data serialization, implementing comprehensive CSP policies, and establishing regular security testing in the CI/CD pipeline.

• Medium · Monorepo Dependency Version Overrides — package.json - overrides field. The root package.json uses 'overrides' to enforce specific versions of eslint (9.36.0) and prettier (3.6.2) across the monorepo. While this ensures consistency, it may override security patches in transitive dependencies if not regularly updated. No automatic security update mechanism is visible. Fix: Implement automated dependency scanning with tools like Dependabot (already configured in .github/dependabot.yml), ensure regular updates to override versions, and establish a security patch review process. Consider using npm audit regularly in CI/CD.
• Medium · Potential XSS Risk in Visual Programming Editor — packages/blockly/core/block_svg.ts, packages/blockly/core/bubbles/, packages/blockly/core/comments/comment_editor.ts. The codebase contains visual block manipulation and rendering logic (block_svg.ts, bubbles components, comment_editor.ts). Without visible sanitization in the file structure, there's potential for XSS vulnerabilities if user-generated content or block definitions are rendered without proper escaping. Fix: Conduct a code review of DOM manipulation, ensure all user-controlled content is properly sanitized using DOMPurify or similar library, use textContent instead of innerHTML where possible, implement Content Security Policy (CSP) headers, and add XSS-focused security tests.
• Medium · Missing Security Headers Documentation — packages/blockly/appengine/app.yaml, packages/blockly/appengine/main.py. No evidence of security header configuration (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the visible files. The appengine deployment configuration (app.yaml) is present but content not shown. Fix: Configure security headers in app.yaml or the Python application. Implement at minimum: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X-XSS-Protection, and Strict-Transport-Security for HTTPS deployments.
• Low · Clipboard Operations Require Validation — packages/blockly/core/clipboard/block_paster.ts, packages/blockly/core/clipboard/workspace_comment_paster.ts. The clipboard functionality (packages/blockly/core/clipboard/) handles pasting of blocks and comments. Without visible input validation, there's potential for malformed data injection. Fix: Implement strict schema validation for clipboard data before processing, validate block definitions and comment structures, implement bounds checking on deserialized objects, and add fuzzing tests for clipboard operations.
• Low · Storage Implementation Review Needed — packages/blockly/appengine/storage.js, packages/blockly/appengine/storage.py. The codebase includes storage modules (storage.js, storage.py in appengine). Without code visibility, potential issues include insecure data storage, lack of encryption, or improper session handling. Fix: Review storage implementations for: encrypted at-rest data, secure session tokens, proper access controls, input validation, SQL injection prevention (if using databases), and compliance with data protection regulations.
• Low · Workspace Comment Functionality - Injection Risk — packages/blockly/core/comments/comment_view.ts, packages/blockly/core/comments/comment_editor.ts. Comment rendering and editing functionality may be vulnerable to injection attacks if user comments are not properly sanitized before display. Fix: Ensure all comment text is sanitized before rendering, use text nodes instead of HTML parsing for user content, implement rich text editing safely with a vetted library, and add validation for comment length and character sets.

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.