Skip to content

Latest commit

 

History

History
267 lines (186 loc) · 8.22 KB

DEV.md

File metadata and controls

267 lines (186 loc) · 8.22 KB
Raw

Developer Guide

Setup Development Environment

Without Docker

This is a TypeScript project that uses React. You'll just need Node.js v16 and npm installed on your development machine. Although, this is sufficient to run, build, and test the project as a whole, you might need some extra tools for other development tasks.

You'll need tsc (TypeScript Compiler) to manually compile .ts files. You'll need ts-node (Node.js executable for TypeScript) to manually execute .ts scripts directly. Finally, you'll need an HTTP server like http-server (a HTTP server program), if you want to serve files manually.

Once npm is installed, to install the above, run

npm i -g http-server
npm i -g typescript
npm i -g ts-node

Note: Users on Linux and MacOS are required to add a sudo before these commands.

Check installation using

node -v && npm -v && tsc -v && ts-node -v && http-server -v

Output should look like

v16.14.0
8.3.1
Version 4.6.2
v10.6.0
v14.1.0

With Docker

This project development tools have been containerized using docker. Therefore, to use an execution sandbox, it requires docker to be installed on the development machine.

  1. Setup docker.

  2. Open a terminal 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:4-dev

    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 a second terminal, run

    docker attach musicblocks-4-dev

    The Alpine shell in the docker container named musicblocks-4-dev is spawned and standard input/output is connected to the terminal.

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

    node -v && npm -v && tsc -v && ts-node -v && http-server -v

    Output should look like

    v16.14.0
8.3.1
Version 4.6.2
v10.6.0
v14.1.0

  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

Commands

Note: This repository uses sugarlabs/musicblocks-v4-lib as an npm package which is published to the GitHub npm Registry of Sugar Labs. Before you install the dependencies you need to make sure that your GitHub Personal Access Token (PAT) is stored in your local system's npm configuration file .npmrc.

Note: Be sure to request permission for read: packages

Learn how to create a PAT.

Add your PAT to .npmrc using

echo "//npm.pkg.github.com/:_authToken=[YOUR_GITHUB_PERSONAL_ACCESS_TOKEN]" >> ~/.npmrc

After you are set-up, the steps you take depend on what you want to do:

  • Run a development server and test suites

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

      npm ci

    2. Run React scripts.

      • For unoptimized development serving, run

        npm run serve

        Visit localhost:5173 in a browser to view the web page served.

      • For generating a generic production build, run

        npm run build

      • For generating a production build under the subdirectory /musicblocks-v4/, run

        npm run build:gh

      • For serving the last production build (dist folder), run

        npm run preview

        Visit localhost:4173 in a browser to view the web page served.

      • For running unit tests, run

        npm run test:unit

      • For running E2E tests, run

        ## In 1 terminal
npm run build
npm run preview
## In another terminal
npm run test:e2e

      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.

  • Miscellaneous commands

    Note: This requires Node.js (Node.js Runtime), tsc (TypeScript Compiler), and ts-node (Node.js executable for TypeScript) to be installed. If you are using Docker, they'll be pre-installed in the container.

    • To launch the Node.js 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 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!