/musicblocks-v4

A complete overhaul of the original Music Blocks

Primary LanguageTypeScriptGNU Affero General Public License v3.0AGPL-3.0

Music Blocks (v4)

A complete overhaul of Music Blocks.

Contributing

Please visit the discussions tab at the top of the repository to follow the planning progress.

A prototype is being built currently. It'll be in the musicblocks-v4-lib repository. For updates, follow the develop branch and the feature branches that branch out of it. All initial development shall take place in that repository. The said branch repository shall contain the core (engine) of the Music Blocks v4 application. A bundle shall be built there, which shall serve as the core of this application; this repository shall contain the user-end client which is to communicate with the said core through a broker module.

The said repository has been added here as a submodule "musicblocks-v4-lib". Look out for issues in the issues tab of the repository.

Tech Stack

Music Blocks v4 shall be built using React 17 (with hooks) and TypeScript 4. In addition, SCSS shall be used for styling. Webpack has been configured to transpile and bundle the source code, for deployment on a web browser.

Setup Development Environment

This project is containerized using docker. Therefore, it requires docker to be installed on the development machine.

  1. Setup docker.

  2. Open a teminal and navigate to working directory (where the source code will reside).

  3. Git Clone (additional installation of Git required on Windows) this repository using

    git clone https://github.com/sugarlabs/musicblocks-v4.git

  4. Build docker image and launch docker network.

    Note: A built initial development image has been published to Sugar Labs GitHub Container Registry (GHCR), which can be pulled directly, so you don't have to build it again. Pull using

    docker pull ghcr.io/sugarlabs/musicblocks:initial

    Nagivate inside the project directory and launch the docker network using

    docker-compose up -d

    or (for Docker v1.28 and above)

    docker compose up -d

    If you haven't pulled the image from the GitHub Container Registry (GHCR), it'll first build the image using the Dockerfile, then launch the docker network. If an image already exists locally, it'll not be rebuilt. To force a rebuild from the Dockerfile before launching the docker network, add the --build flag.

  5. In another terminal, run

    docker attach musicblocks

  6. The Linux Debian 10.7 (buster) shell in the docker container named musicblocks is spawned and standard input/output is connected to the terminal.

    Node (Node.js Runtime), npm (Node Package Manager), tsc (TypeScript Compiler), and ts-node (Node executable for TypeScript) should be installed. Check using

    node --version && npm --version && tsc --version && ts-node --version

    Output should look like

    v14.15.3
6.14.10
Version 4.1.3
v9.1.1

  7. To shut down the docker network, run (in the terminal where you ran docker-compose up -d or docker compose up -d)

    docker-compose down

    or (for Docker v1.28 and above)

    docker compose down

  8. To install all the dependencies (in package.json), run

    npm ci

  9. To spawn a HTTP Server (uses Python 3's http.server), run

    npm run serve

    This is spawned on 0.0.0.0:80 inside the container, but mapped to localhost:5001 on host. Visit localhost:5001 in a browser to view the webpage served.

  10. Run React scripts.

    • For unoptimized development serving, run

      npm start

      This is spawned on 127.0.0.1:3000 inside the container, but mapped to localhost:5000 on host. Visit localhost:5000 in a browser to view the webpage served.

    • For testing, run

      npm run test

    • For generating a production build, run

      npm run build

    Note: If you're running using Docker Desktop on Windows or Mac, you might experience longer execution times for these scripts. This happens due to cross-file-system communication. Duration varies across machines; duration primarily depends on hard drive read/write speed.

  11. Miscellaneous commands.

    • To launch the Node runtime, run

      node

    • To run a JavaScript file, say file.js, run

      node file.js

    • To transpile a TypeScipt file, say file.ts, to JavaScript, run

      tsc file.ts

      This transpilation produces file.js.

    • To run a TypeScript file directly, say file.ts, run

      ts-node file.ts

Editor

All code is just plain text, so it doesn't really matter what you use to edit them. However, using modern, feature-rich IDEs/text-editors like Atom, Brackets, WebStorm, Sublime Text, Visual Studio Code, etc. makes life way easier. These come with a directory-tree explorer, and an integrated terminal, at the very least, while having support for plugins/extensions to expand their functionality.

Some (non-exhaustive) benefits of using these are syntax highlighting, warning/error annotations, formatting, auto-refactoring, tons of customizable keyboard shortcuts, etc.

Visual Studio Code (VSCode) is currently the most-popular code editor for reasons like being lightweight, cleaner, large marketplace of extensions, integrated Source Control features, debugger, remote explorer support, Regular Expression (regex) based find/replace, etc.

In fact, a workspace configuration file for vscode.vscode/settings.json has already been added. Recommended extensions for this project are Babel JavaScript, Docker, ESLint, Git Graph, GitLens, markdownlint, Prettier, SCSS IntelliSense, and SVG.

All that, however, shouldn't necessarily stop you from using Emacs, Nano, or Vim, if that's your poison :D. Happy coding!