3. Build Tools

Quizzera makes use of a variety of build tools to help faciliate working with the various frontend and backend parts of the project.

Vagrant and Ansible, mentioned in the ‘Getting Started’ guide, are two of those tools. In this document, we will go over a few others that are primarily used by developers while working on the code itself - not just for deployment.

3.1. Gulp

Gulp is a task runner for JavaScript. It works very well when dealing with frontend assets, especially with React and Babel.

In Quizzera, it is used to manage Browserify, the build/bundling tool, alongside Babel’s JSX transpiler. In addition, Gulp compiles and minifies our SASS files into CSS bundles.

gulpfile.js

All of the Gulp task definitions are located in a central gulpfile.js, which is in the project root directory.

Currently, no files are ‘watched’ - watched files will automatically run the appropriate compilation task when changed. However, this puts a strain on the machine running the VM, especially because the files have to be synced beforehand.

To run all of the Gulp tasks, which will prepare all of the static files (JSX and CSS alike), run $ gulp all.

3.2. Compiling & Bundling JSX

JSX files can be compiled using the bundle, external, and questions tasks. However, these compile different assets.

3.2.1. Gulp: bundle

The bundle task will bundle all of the JSX files defined in Django apps. However, it will only search the apps defined in the configuration file.

The search paths are defined as such: for an app named app, it will compile the JSX files found in the ./app/static/react/app/ directory - this is similar to how Django structures app-specific templates/static files.

The bundled code is placed in the ./app/static/app/js/ folder, matching how Django expects static files to be structured.

To compile only a single app’s JSX files, which will be faster, you can provide the app name with the --app or -a option. For example, to compile the core app’s JSX only:

$ gulp bundle --app core
$ gulp bundle -a core

3.2.2. Gulp: questions

The questions task will bundle the JSX files for each question module. It will traverse the question module search path (defined in the configuration filee) and for each directory that appears to be a question, compile the JSX file and bundle it.

For a question SortingQuestion, the JSX file expected is questions/q/SortingQuestion/SortingQuestion.jsx. The bundle is outputted to questions/static/questions/js/bundle/SortingQuestion.js.

To compile only a single question’s JSX files, you can provide the question name with the --question or -q option. For example, to compile the SortingQuestion question’s JSX only:

$ gulp questions --question SortingQuestion
$ gulp questions -q SortingQuestion

3.2.3. Gulp: external

The external task will bundle external dependencies - those defined in the package.json file.

Separating External Dependencies

Because these dependencies are expected to be shared among all (or most) bundles, they are excluded from all other bundles.

By separating the external dependencies, page-specific bundle sizes can be significantly decreased. In addition, because external dependencies will not change often, the external bundle can be effectively cached among all pages for longer durations of time.

The external dependencies bundle is automatically added to every page.

By running $ gulp external, the dependencies are bundled and sent to the static JS folder shared among all apps, which is the default quizzera/static/quizzera/js/bundle folder.

3.3. Compiling SASS

The sass task bundles our SASS/SCSS files into CSS.

To bundle the SASS files for all Django apps (specified in the configuration file), run $ gulp sass.

To compile only a single app’s SASS files, you can provide the app name with the --app or -a option. For example, to compile the core app’s SASS only:

$ gulp sass --app core
$ gulp sass -a core
note:Currently, question-specific SASS/CSS is not supported. Support will be added in the future.