codemirror-blocks

codemirror-blocks is a project to make programming languages editable using visual blocks.

About this repository

This repository contains the code for all the packages maintained by the codemirror-blocks team, including the core codemirror-blocks library, and various language modules that implement block editors for individual languagues using the core library. Documentation for individual packages can be found in their respective directories:

• codemirror-blocks - the core library used to make block editors. Start here if you'd like to implement a new block editor for a programming language of your choice.
• wescheme-blocks - a block editor for the wescheme programming language.

Contributing Changes

To contribute changes to any of the packages in this repository, you'll need to setup a development environment.

Dev Environment

To get your dev environment up and running, follow these steps.

1. Clone the repository onto your local machine

2. Install dependencies with npm

   npm install
   

   Note: This repository uses npm workspaces, so you'll need to use npm v7 or later.

3. build the library and generate type declarations

   npm run build --workspaces
   npm run build-types --workspaces --if-present
   

4. run tests to confirm everything is setup correctly. This will run all tests in all sub-packages

   npm run test
   

Development Workflow

At any given time, you'll probably be working in only one of the repo's sub-packages. Each package provides it's own set of npm scripts to help with the build/test process. You can either run these scripts from the repository root and specify which package you are working on with --workspace=<package-name> or you can run the scripts from that packages directory without the --workspace setting. The following assumes you are doing the latter.

CMB is written in a combination of typescript and javascript, with some language extensions (like jsx syntax) that are handled by babel. As such, before any code can actually be executed, it must be transpiled to javascript. The easiest way to do this during development is to run each of the following commands in their own terminal:

1. Continuously transpile code from the src/ directory to the lib/ directory with babel:

   npm run build-watch
   

2. Continuously run typechecks and generate type declaration files in lib/ with typescript:

   npm run build-types-watch
   

3. With these two processes running, you can then start the development server in yet another terminal with:

   npm start
   

   then open http://localhost:8080 in your browser to see CMB running on a web page. This web page just executes the example javascript from example/ediotor-example.js, but will automatically update whenever any code is changed.

4. Finally, you can also run tests continuously whenever code is changed. This should always be done from the repository root to make sure you don't inadvertantly break an API that another package is depending on.

   npm run test-watch
   

Coverage reports can be generated by passing the --coverage flag to the test command:

npm test -- --coverage

The reports will be written to the .coverage/ directory.