mirror of
https://github.com/jspsych/jsPsych.git
synced 2025-05-10 19:20:55 +00:00
99 lines
7.1 KiB
Markdown
99 lines
7.1 KiB
Markdown
# Configuring the jsPsych development environment
|
|
|
|
## Setup
|
|
|
|
JsPsych is written using [TypeScript](https://www.typescriptlang.org/), 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](https://nodejs.org/en/), 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](https://nodejs.org/en/) 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
|
|
|
|
```sh
|
|
git clone https://github.com/jspsych/jsPsych.git && cd jsPsych
|
|
```
|
|
|
|
or
|
|
|
|
```sh
|
|
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](https://www.npmjs.com/) where they can be downloaded by NPM or any CDN (such as [unpkg](https://unpkg.com/)).
|
|
|
|
## 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 `import`ing files from the same package).
|
|
It is used by bundlers like [webpack](https://webpack.js.org/).
|
|
|
|
* **`index.cjs`**
|
|
Like `index.js`, but using the old CommonJS standard to support backwards-compatible tools like the [Jest](https://jestjs.io/) 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](https://babeljs.io/) 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](https://terser.org/) 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](https://jestjs.io/).
|
|
|
|
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`. If you want to run one file from the root directory, using the aforementioned example, you can run `npm test -- /packages/plugin-html-keyboard-response/src/index.spec.ts`.
|
|
|
|
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.
|