HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-10 19:20:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
80d3da4c72
jsPsych/docs/developers/configuration.md
bjoluc bb89baef40 Update developers/configuration docs
2021-10-01 15:25:26 +02:00

6.9 KiB
Raw Blame History

Configuring the jsPsych development environment

Setup

JsPsych is written using TypeScript, a superset of JavaScript that adds static typing, but compiles to plain JavaScript. The TypeScript compiler itself is written in JavaScript and can be run by Node.js, a runtime to execute JavaScript code without a web browser. Node.js comes with a package manager called NPM (Node Package Manager) that can install JavaScript libraries to run on your machine, such as TypeScript and other build tools for jsPsych. In order to work on code in the jsPsych or the jspsych-contrib repository, it is recommended that you follow the steps below to set up your development environment.

Install Node.js

The jsPsych development setup requires Node.js >= v14 to be installed on your machine. We recommend that you install version 16 since it includes version 7 of NPM (required for the workspaces feature that the jsPsych repositories use). If you are bound to Node.js v14, make sure to install NPM v7 manually (via npm install -g npm@7).

Clone the repository and install the dependencies

Clone either the jsPsych repository or the jspsych-contrib repository by running

git clone https://github.com/jspsych/jsPsych.git && cd jsPsych

or

git clone https://github.com/jspsych/jspsych-contrib.git && cd jspsych-contrib

in a terminal.

Then run npm install. This will create a node_modules directory and install all the dependencies into it that are required to build and test jsPsych.

!!! attention It is important that npm install is only run in the root directory of the repository (due to the NPM workspaces feature). If you accidentally ran npm install anywhere else, remove the node_modules directory and the package-lock.json file that were created at that location and run npm install in the root directory again.

!!! info If you are running npm install in the core jsPsych repository, this will also execute the build chain for all packages in the jsPsych repository. This step may take a few minutes. If you would like to use that time efficiently, consider reading the following two sections to know what's happening.

Repository structure

A Node.js package is a directory that contains a package.json file describing it. Most importantly, a package.json file lists other packages that the package depends on. The jsPsych and jspsych-contrib repositories use NPM workspaces. That means, running npm install in the repository root will install the dependencies for all packages in the packages directory. The core jsPsych library and every jsPsych plugin or extension is laid out as an individual package. These packages are published to the NPM registry where they can be downloaded by NPM or any CDN (such as unpkg).

Build chain and build artifacts

JsPsych comes with a build chain (specified in the @jspsych/config package) that can be executed by running npm run build in a package's directory. The build chain will read the package (starting at its src/index.ts file) and create the following build artifacts in the package's dist directory:

  • index.js This file contains everything from index.ts, but as plain JavaScript and bundled in a single file (i.e. without importing files from the same package). It is used by bundlers like webpack.

  • index.cjs Like index.js, but using the old CommonJS standard to support backwards-compatible tools like the Jest testing framework.

  • index.browser.js This file, like index.js, contains the entire package as plain JavaScript, but this time wrapped in a function so that it can be included directly by browsers using the <script> tag. For plugins or extensions, the default export of a module (i.e. whatever statement comes after export default in the index.ts file) is assigned to a global variable. The name of this global variable is specified in the package's rollup.config.mjs file, as a parameter to the makeRollupConfig() function. Hence, for instance, including the index.browser.js file from the plugin-html-keyboard-response package would assign the HtmlKeyboardResponsePlugin class to the global jsPsychHtmlKeyboardResponse variable. Because the code in index.browser.js looks very similar to the index.ts code but is fully supported by modern web browsers, all examples in the examples directory reference the index.browser.js files so users can also modify the source code directly without running the build chain.

  • index.browser.min.js There are different versions of the JavaScript language specification and not all web browsers and browser versions support all JavaScript features. That's why the jsPsych build chain uses Babel to translate the source files into code that a majority of web browsers can understand. The result of this operation is index.browser.min.js. It behaves just like index.browser.js, but adds support for older browsers by substituting new JavaScript features using older ones. Because this is the recommended build artifact for production usage (and is automatically served by unpkg), the code in index.browser.min.js is also processed by Terser to reduce its size and speed up experiment loading times.

  • *.js.map When debugging code in a browser (especially index.browser.min.js, which is not easily readable due to Terser and Babel), it is important to be able to read the original source code in the debugger. For every build artifact, there is a .map file which contains a mapping of the generated code to the original source code. Browsers automatically read these .map files and display the original code in their debuggers instead of the generated one.

  • *.d.ts The .d.ts files contain the TypeScript type definitions that would otherwise be lost during compilation to plain JavaScript. They are read by Typescript and editors when a package is imported into another TypeScript project.

Testing

Automated code testing for jsPsych is implemented with Jest.

To run the tests, install Node and npm. Run npm install in the root jsPsych directory. Then run npm test. You can also run npm test in the directory of the package that you would like to test. For example, if you are developing tests for the html-keyboard-response plugin you can run npm test in /packages/plugin-html-keyboard-response.

Tests for the core jsPsych library are located in /packages/jspsych/tests.

Tests for plugins and extensions are located in the /src folder of the corresponding package. Test files for plugins and extensions are named index.spec.ts.

There are helper functions for testing in /packages/jspsych/tests/utils.ts. We recommend looking at other test files to observe conventions for testing.