Music Blocks (v4)

A complete overhaul of Music Blocks — a visual, interactive programming environment for exploring music, art, and logic, designed for learners of all ages.

Tech Stack

Music Blocks (v4) is a client-side rendered web application written in TypeScript and React. It is structured as a monorepo using npm workspaces, managed by Lerna.

Stack

Tooling

Quality

Project Status

This project stalled for an extended period. Most of the code written during that phase has reached a dead end, and the effort is being restarted from a cleaner foundation.

Active

Package	Notes
modules/masonry	Graphical project builder — brick geometry, layout, and rendering

Archived

All other packages (modules/engine.old, modules/program, modules/runtime, modules/code-builder, modules/editor, modules/singer, modules/painter, modules/menu, lib/*) are remnants of the previous effort and are not being carried forward.

Development

Monorepo Structure

This repository is a monorepo using npm workspaces, managed by Lerna. It is organized into three layers:

• app/ — the main application package
• modules/ — feature modules (e.g. editor, painter, singer, masonry)
• lib/ — shared libraries used across modules (e.g. events, transport, components)

The root of the repository is not a runnable package. It holds global configuration: workspace definitions, shared tsconfig, ESLint and Prettier config, and shared dev dependencies.

• Dev dependencies should generally be installed at the root level, unless they are specific to a single sub-package.
• Production dependencies belong in the individual sub-package that uses them.

When working on a specific feature or fix, navigate to the relevant sub-package directory. Changes to shared tooling, config, or anything cross-cutting belong at the root level.

Setup

You will need Node.js v24 or later and npm 11 or later. All other dependencies (TypeScript, tsx, etc.) are installed locally as part of the project via npm ci — no global installs are required.

nvm (Node Version Manager) is recommended for managing Node.js and npm versions. It lets you install and switch between versions easily, and ensures you are running the version this project expects.

Verify your environment:

node -v
npm -v

Expected output (or later):

v24.0.0
11.0.0

Commands

Install all dependencies from the repository root first:

npm ci

If you are working within a specific sub-package, you can run the scripts directly from that package's directory instead.

The commands below are run from the root and delegate to the relevant sub-package scripts via Lerna.

Command	Description
npm run serve	Start development server at localhost:5173
npm run build	Generate a production build
npm run build:gh	Production build for GitHub Pages (base: /musicblocks-v4/)
npm run preview	Serve the last production build at localhost:4173
npm run test	Run all tests
npm run check	TypeScript type-check across all packages
npm run lint	Lint all files

Editor

Visual Studio Code is recommended, or any VS Code-based editor such as Cursor or Antigravity IDE.

Recommended extensions: ESLint, Prettier, markdownlint, SVG, and Tailwind CSS.

Contributing

All skill levels are welcome. Browse issues labeled good first issue to find a beginner-friendly starting point, or follow the project board to track ongoing work and see what is being planned. Unassigned issues are free to pick up; if an issue has an assignee, comment to check whether it is still active. Feel free to ask for clarification directly on the issue before starting.

For general questions and discussion, visit the discussions tab.

See full contributing guide for code standards, commit format, and the pre-submit checklist.