HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-10 11:10:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

finish the remaining sections in configuration.md

Browse Source
This commit is contained in:
bjoluc 2021-09-21 11:33:11 +02:00
parent ddb42ed89c
commit 82cb4428d3
1 changed files with 55 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
docs/developers/configuration.md
View File

@ -5,38 +5,81 @@
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 repository, it is recommended that you follow the steps below to set up your development environment.
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 repository uses).
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
In a terminal, run:
Clone either the jsPsych repository or the jspsych-contrib repository by running
```sh
git clone https://github.com/jspsych/jsPsych.git
cd jsPsych
npm install
```
The latter command will install all the dependencies that are required to build and test jsPsych.
or
```sh
git clone https://github.com/jspsych/jspsych-contrib.git
```
in a terminal.
Then navigate into the repository's directory via `cd jsPsych` or `cs jspsych-contrib`.
Finally, 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.
Afterwards, it will run the build chain for all packages in the jsPsych repository.
!!! info
Depending on your system, this step will take some time.
If you would like to use that time efficiently, consider reading the section below to know what's happening.
The build step will 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
TODO describe the steps and artifacts, and how to run it / use the 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:
There are different versions of the JavaScript language specification and not all web browsers and browser versions support all JavaScript features.
That's why jsPsych uses a build chain to translate the source files into code that a majority of web browsers can understand.
* **`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