ODC Instruments Template

A template repository for building data-collection instruments for the Open Data Capture platform. Forms live in lib/forms and interactive tasks live in lib/interactive, with each instrument in its own directory containing an index.ts entrypoint.

Use this repository as a starting point: click Use this template on GitHub (or copy the files), then replace the example instrument in lib/forms/EXAMPLE_FORM with your own.

What is an instrument?

An instrument is the unit of data collection in Open Data Capture — it defines what the user sees, what data is produced, and how that data is validated. See the instruments documentation for a full overview.

Getting started

There are two paths through this section, depending on your experience:

• For developers — a quick reference if you already have Node.js and pnpm installed.
• For beginners — a step-by-step walkthrough from a brand-new computer, assuming no prior knowledge.

For developers

Installation

This repo uses pnpm. Install dependencies with:

pnpm install

You can setup an agents file with the following command:

pnpm exec instrument-guidelines --file CLAUDE.md

Adding an instrument

Create a new directory under lib/forms (or lib/interactive) and add an index.ts that default-exports the result of defineInstrument. See lib/forms/EXAMPLE_FORM/index.ts for a minimal, fully-typed starting point.

Serving an instrument

Use serve-instrument to preview an instrument locally. Pass the instrument's directory as the target:

pnpm exec serve-instrument lib/forms/EXAMPLE_FORM

The dev server runs on port 3000 by default; override it with -p <number>.

Linting

Type-check and lint the instruments with:

pnpm lint

For beginners (from scratch)

New to programming? No problem. These steps take you from a brand-new computer all the way to a running preview of an instrument, assuming no prior knowledge. You'll install a few free tools, then copy and paste a handful of commands.

A few terms you'll see below:

• Terminal — a text window where you type commands instead of clicking buttons. We'll use the one built into the code editor (VS Code) because it automatically opens "inside" your project folder.
• Node.js — the program that runs the JavaScript/TypeScript code in this project.
• pnpm — the tool that downloads the other pieces of code (the "dependencies") this project needs.

Pick your operating system and follow the steps in order.

Windows

1. Get the project files. At the top of this page on GitHub, click the green Use this template button → Create a new repository to make your own copy. (If you just want to try it out, click Code → Download ZIP instead, then unzip the file to a folder you'll remember, such as your Desktop.) Installing Git is optional — the ZIP route needs no extra tools.

2. Install a code editor (VS Code). Download it from code.visualstudio.com, run the installer, and accept the defaults. VS Code is where you'll read, edit, and run the project.

3. Install Node.js. Go to nodejs.org and click the big LTS download button (LTS means the stable, recommended version). Run the downloaded .msi installer and click through it, accepting all the defaults.

4. Open the project in VS Code. Start VS Code, then choose File → Open Folder… and select the project folder from step 1.

5. Open a terminal. In VS Code's menu, choose Terminal → New Terminal. A text panel appears at the bottom — it's already pointed at your project folder.

6. Install everything and run an instrument. Type these commands one at a time, pressing Enter after each:

   corepack enable
   pnpm install
   pnpm exec serve-instrument lib/forms/EXAMPLE_FORM

   (corepack enable sets up pnpm and only needs to be run once.)

7. View it. Open your web browser and go to http://localhost:3000. You should see the example instrument. To stop the preview, click in the terminal and press Ctrl + C.

macOS

1. Open the Terminal. Press Cmd + Space, type Terminal, and press Return. The Terminal is a text window where you type commands instead of clicking buttons — you'll run the rest of these steps here by pasting in each command and pressing Return.

2. Install Homebrew. Homebrew is a tool that installs other software for you. Copy the command below from brew.sh, paste it into the Terminal, and press Return:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   Follow the on-screen prompts (it may ask for your password). When it finishes, it may print a couple of Next steps commands to run so the brew command works — copy and run those too, then close and reopen the Terminal.

3. Install Git and a code editor. Git downloads the project files; VS Code is where you'll read and edit them. Install both with Homebrew:

   brew install git
   brew install --cask visual-studio-code

4. Download the project. This copies the project to your computer and moves you into its folder:

   git clone https://github.com/DouglasNeuroInformatics/ODC_Instruments_Template.git
   cd ODC_Instruments_Template

   (If you made your own copy with Use this template on GitHub, clone that repository's URL instead.)

5. Install nvm and Node.js. nvm (Node Version Manager) installs the version of Node.js this project needs. Install nvm by following the official instructions at github.com/nvm-sh/nvm, then close and reopen the Terminal and cd ODC_Instruments_Template again. Now install Node:

   nvm install
   nvm use

   (This reads the project's .nvmrc file and installs the right Node.js version.)

6. Install everything and run an instrument:

   corepack enable
   pnpm install
   pnpm exec serve-instrument lib/forms/EXAMPLE_FORM

   (corepack enable sets up pnpm and only needs to be run once.)

7. View it. Open your web browser and go to http://localhost:3000. You should see the example instrument. To stop the preview, click in the Terminal and press Control + C. To edit the project, open VS Code and choose File → Open Folder…, then select the ODC_Instruments_Template folder.

Linux

These steps assume you're comfortable opening a terminal. Make sure git is installed (e.g. sudo apt install git on Debian/Ubuntu, or your distribution's equivalent).

1. Download the project with git clone, then move into its folder:

   git clone https://github.com/DouglasNeuroInformatics/ODC_Instruments_Template.git
   cd ODC_Instruments_Template

   (If you made your own copy with Use this template on GitHub, clone that repository's URL instead.)

2. Install a code editor (VS Code). Optional but recommended — install it from code.visualstudio.com or your distribution's package manager.

3. Install nvm (Node Version Manager). Follow the official instructions at github.com/nvm-sh/nvm, then close and reopen your terminal and cd ODC_Instruments_Template again so the nvm command becomes available.

4. Install the right Node.js version. From inside the project folder, run:

   nvm install
   nvm use

   This reads the project's .nvmrc file and installs the Node.js version it expects.

5. Install everything and run an instrument:

   corepack enable
   pnpm install
   pnpm exec serve-instrument lib/forms/EXAMPLE_FORM

   (corepack enable sets up pnpm and only needs to be run once.)

6. View it. Open your web browser and go to http://localhost:3000. Press Ctrl + C in the terminal to stop the preview.

Once you've done this once, you can re-run an instrument any time with pnpm exec serve-instrument <directory>, and the For developers reference above is your day-to-day quick reference.

Examples

Browse live examples of instruments on our playground: https://playground.opendatacapture.org