Installing a development server.
See Getting Started.
Running in development mode
The easiest way to start the app in development and debugging mode with livereload is with
Testing is done with Mocha and Karma.
npm run test
npm run test-headless
npm run test-browsers
Tests can be run in watch mode for TDD workflows with.
npm run test-watch-client
npm run test-watch-server
Support for debugging in VSCode is provided. For instructions see [./#debugging-test-watch-mode-in-vscode](Debugging test watch mode in VSCode) below.
Debugging test watch mode in VSCode
- Go to VSCode's "Run and Debug" panel
- Select "Test client (watch + debug)" or "Test server (watch + debug)"
- Click the play button
Optionally, you can add a keyboard shortcut to select launch tasks:
- Open the keyboard shortcuts settings (cmd+k cmd+s on Mac, ctrl+k ctrl+s on other OSes)
- Search for
- Click the + button to add your preferred keybinding keybinding
Launch a test form
Enketo Express needs an OpenRosa-compliant server to obtain forms and submit data too. For development you can conveniently use any public or local server for this with the API.
For example to use your https://kobotoolbox.org or https://ona.io account "ali", the server_url to use in API calls is
An API call to get the Enketo webform url for a form called "TestForm" can thus be made like this:
curl --user enketorules: -d "server_url=https://kc.kobotoolbox.org/ali&form_id=TestForm" http://localhost:8005/api/v2/survey
Once you have the Enketo webform URL can start development on a feature or bug.
Another convenient way for some subset of development work is to put your XForm on any webserver (local, public), and use a preview url with a query parameter, e.g.:
http://localhost:8005/preview?xform=http://example.org/myform.xml (officially, the query parameter should be URL encoded, though for development use this is often fine).
Release a new version
Documentation is auto-generated and should be re-built for each new release. Do not commit updated documentation in non-release commits. The process to follow for each release that includes various helpful checks is:
- Check Dependabot alerts for vulnerabilities
- Update dependencies:
npm audit fix
- Make sure tests pass:
npm run test
- Beautiful code:
npm run beautify
- Build documentation:
npm run build-docs
- Bump the version tag in
package.jsonfile (we follow semantic versioning)
- Merge all your changes to
- Add git tag of new version