app

Opentrons Desktop App

Download | Support

overview

The Opentrons desktop application lets you use and configure your Opentrons personal pipetting robot. This directory contains the application's UI source code. If you're looking for support or to download the app, please click one of the links above.

This desktop application is built with Electron. You can find the Electron wrapper code in the app-shell directory.

developing

To get started: clone the Opentrons/opentrons repository, set up your computer for development as specified in the contributing guide, and then:

# change into the cloned directory
cd opentrons
# prerequisite: install dependencies as specified in project setup
make setup
# launch the dev server / electron app in dev mode
make -C app dev

At this point, the Electron app will be running with HMR and various Chrome devtools enabled. The app and dev server look for the following environment variables (defaults set in Makefile):

variable	default	description
NODE_ENV	production	Environment: production, development, or test
PORT	8090	Development server port
OT_APP_INTERCOM_ID	unset	Sets the Intercom application ID
OT_APP_MIXPANEL_ID	unset	Sets the Mixpanel application ID

Note: you may want to be running the Opentrons API in a different terminal while developing the app. Please see the contributing guide for API specific instructions.

stack and structure

The UI stack is built using:

• React
• Redux
• CSS modules
• Babel
• Webpack

Some important directories:

• app/src — Client-side React app run in Electron's renderer process
• API clients (see api/opentrons/server)
  • app/src/rpc - RPC API client
  • app/src/robot-api - HTTP API client
• app/webpack - Webpack configuration helpers

copy management

We use i18next for copy management and internationalization.

When adding any translatable copy strings, follow these conventions:

Choose a continuous chunk of target copy that composes a translatable unit. This should be all text in a paragraph, or sentence, but might only be 1 word (e.g. within a button).

1. Does the new copy belong within an existing translations namespace (e.g. 'robot_connection', 'robot_calibration', 'shared'...)?

   • if yes, add a new key-value pair to that file. The value should be the english copy string. The key should be a snake case string that describes this copy's purpose within the namespace.
   • if no, create a new namespace for this area of the application's functionality. Add a file titled [namespace].json to app/src/assets/localization/en/. Add a new key-value pair to that file. The value should be the english copy string. The key should be a snake case string that describes this copy's purpose within the namespace. Include the namespace in the i18n instance initialization function at app/src/i18n.js under the ns key of the options passed to the init fn ({...ns: [ 'new_namespace' ]...}). Import and export the new [namespace].json file from the manifest file at app/src/assets/localization/en/index.js

2. Does the copy include dynamic internal values, or embedded markup (e.g. "Hello {{user}}, click <a>here</a>.")?

   • if yes, use the Trans component from react-i18next docs here
   • if no, use useTranslation hook to retrieve the t function. docs here

Note: If a component utilizes both the Trans component and the useTranslation hook, be sure to pass the t function in as the t prop of the Trans component, that way the same namespace resolution order is maintained for all translation keys within that component.

testing

Tests for the App are run from the top-level along with all other JS project tests.

• make test-js - Run all JavaScript tests

Test tasks can also be run with the following arguments:

arg	default	description	example
watch	false	Run tests in watch mode	$ make test-unit watch=true
cover	!watch	Calculate code coverage	$ make test watch=true cover=true

building

If you'd like to build the Electron desktop app, see the app shell's build instructions.

The UI bundle can be built by itself with:

# default target is "clean dist"
make -C app
# build without cleaning
make -C app dist

The UI build process looks for the following environment variables:

variable	default	description
NODE_ENV	production	Build environment: production, development, or test
ANALYZER	unset	Launches the bundle analyzer

For example, if you wanted to analyze the production JS bundle:

ANALYZER=1 make -C app