Quickstart: JavaScript runtime

PsyCloud experiments execute in a browser runtime — a JavaScript engine that loads a compiled Study Bundle and runs its trials, screens, and timing. You rarely hand-write that runtime code: you author a study (in Studio, the Python or R SDK, or the CoffeeScript DSL), the CLI compiles it to a bundle, and the runtime plays it back.

This quickstart is the local development loop for that runtime: serve a study from source, watch it reload as you edit, and build a standalone HTML file when you are done.

1. Install dependencies

   Copy

   git clone https://github.com/bbuchsbaum/psycloud
   cd psycloud
   npm install

   This makes the psycloud command available via node bin/psycloud (and the npm run serve wrapper below).

2. Serve an example with live reload

   The repo ships runnable examples under examples/canonical/. Serve the minimal keypress study:

   Copy

   node bin/psycloud serve examples/canonical/hello-keypress/coffee/author.coffee

   The dev server starts on http://localhost:3333, opens your browser, and rebuilds on every save. Use -p to pick another port and --no-open to skip launching a browser.

3. Run once, without the watch loop

   To play a study a single time (handy in scripts or CI):

   Copy

   node bin/psycloud run local examples/canonical/hello-keypress/coffee/author.coffee

   run local accepts an authoring script (.coffee / .ts); run on its own also accepts an already-compiled bundle.json or bundle.zip.

4. Build a standalone HTML file

   When you want a single file you can host anywhere or hand to a participant offline:

   Copy

   node bin/psycloud build examples/canonical/hello-keypress/coffee/author.coffee -o experiment.html

   Assets are inlined by default; pass --separate to keep JS/CSS as sidecar files and --minify to compress.

Choosing a build size

serve and build accept -b <type> to control how much of the runtime is bundled: minimal, standard, full, or auto (the default, which picks the smallest bundle that covers the components your study actually uses). Start with auto.

How the pieces fit

Next