Building a local copy¶

The project repository contains the code underlying the lab.js library and the builder interface. To condense both into a single library file for distribution with studies, and an uploadable version of the builder, please follow these additional steps after downloading. You’ll need a local installation of node.js and yarn.

You’ll notice that many of the commands start with yarn – that’s because we use scripts as shortcuts for most build steps.

Downloading the code¶

The easiest way to create a local copy is by cloning the repository. If you use git, you can copy the following command:

git clone https://github.com/FelixHenninger/lab.js.git

If you’d prefer a direct download, that’s available too!

Bootstrapping the project¶

The library and builder interface are contained in the same repository because they share several pieces of code. Both are coordinated by Lerna, which can initialize all parts at once by running the following commands in the project directory:

yarn && yarn run bootstrap

Compiling the library¶

Changing to the packages/library directory and running

yarn

will install all dependencies for the lab.js library, whereafter

yarn run build:js

will output a transpiled version in the packages/library/dist directory. If you would like the transpiled output to be updated automatically as you make changes, yarn run watch:js will do that for you.

yarn run build:starterkit

will build the library with all its components (the basic HTML template, the stylesheet, and several other useful files), and assemble the result into a zip file for easier distribution. This is the bundle that is included with every release.

There are a few more commands available, which you can see by typing yarn run in the packages/library folder.

Working on the builder¶

The builder interface is created using Facebook’s create-react-app template, and follows the conventions instituted there. If you’re looking for details, their documentation provides more information than we ever could.

The main code is found in the packages/builder/src folder, where the components subdirectories contain all user-facing interface code, and logic holds the main application logic.

Please note that the builder requires a copy of the library to work, so please compile the library starterkit as described above before modifying the builder. With the library in place, please then navigate into the packages/builder directory. From there, typing

yarn start

will run the builder application in a local development server, and open it in a browser.

yarn run build

bundles all files necessary for deployment, and creates an optimized version of the application code in the packages/builder/build folder for you to upload to a local server.

Important

For the lab.js builder to work on a public server, it must be served over an encrypted connection (via HTTPS); please make sure that encryption is set up on the server you’re using.

Environment variables¶

During the build step, you can set several environment variables that customize the builder’s behavior.

PUBLIC_URL provides the URL at which the builder will run, e.g. https://labjs.felixhenninger.com
REACT_APP_EXAMPLE_PATH sets the URL from which the builder loads its repository of example studies. By default, this points to the tasks directory in the project repository, and thus the builder loads the example collection metadata from therein.
REACT_APP_TEMPLATE_PATH works just like the EXAMPLE_PATH above, but instead of loading examples, it loads the templates offered to users when they add new components. This path, too, is expected to contain a metadata JSON file that provides further information about the templates, like the one in the project repository.

Building the documentation¶

The library’s documentation is built using Sphinx, using the fabulous Read the Docs Theme. Both require a local python installation, as well as the pip package manager.

If you don’t have python on your system, please consider the Anaconda python distribution; if you’re only missing pip, you can install it on your system. Equipped with both, install the required Python modules:

pip install -r docs/requirements.txt

With everything at hand, you can run the following command from the project’s root directory:

yarn run build:docs

This will output the html documentation in the docs/_build subdirectory. Running yarn run watch:docs will update the documentation whenever you save changes.