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
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
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
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.
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.
During the build step, you can set several environment variables that customize the builder’s behavior.
PUBLIC_URLprovides the URL at which the builder will run, e.g.
REACT_APP_EXAMPLE_PATHsets 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_PATHworks just like the
EXAMPLE_PATHabove, 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
JSONfile that provides further information about the templates, like the one in the project repository.
Building the documentation¶
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.