Opentrons Typescript

Opentrons Monorepo — TypeScript Conventions

Node.js, Pnpm, Python setup, teardown, and troubleshooting are in the always-apply monorepo-setup rule.

Monorepo Structure

Pnpm workspaces monorepo with 15 TypeScript packages. No Lerna/Nx/Turbo — uses Pnpm workspaces + TypeScript project references.

Packages

Dependency Graph

shared-data is the foundation. Nothing should import "up" the tree:

shared-data
├── step-generation
├── components
├── api-client → react-api-client
└── discovery-client
↓
protocol-visualization (scaffold; depends on components + shared-data + step-generation)
↓
app, protocol-designer, labware-library, opentrons-ai-client (leaf apps)

TypeScript Configuration

All packages extend tsconfig-base.json:

• Target/Module: ESNext
• Strict: true (no any, strict null checks)
• JSX: preserve (Vite handles transform)
• Declarations: emitDeclarationOnly, composite for project references
• Module resolution: node

Each package defines rootDir: "src", outDir: "lib", and references its dependencies.

Code Style (Prettier)

Enforced by Prettier with @ianvs/prettier-plugin-sort-imports:

• No semicolons
• Single quotes (double quotes in JSX)
• Trailing commas: ES5
• Print width: 80, Tab width: 2
• Line endings: LF

Import Conventions

Order (auto-sorted by Prettier plugin)

1. React imports (import { useState } from 'react')
2. Third-party packages
3. @opentrons/* packages
4. Package-local absolute imports (/app/*, /protocol-designer/*, /ai-client/*)
5. Relative imports
6. import type (type-only imports, same sub-ordering)
7. Asset imports (images, CSS)

Cross-Package Imports

Use the @opentrons/ scope. These resolve to source via Vite aliases in dev/test:

import { Flex, SPACING } from '@opentrons/components'
import { getPipetteSpecsV2 } from '@opentrons/shared-data'

import type { PipetteName } from '@opentrons/shared-data'

Intra-Package Absolute Imports

Each app has a path alias (configured in tsconfig + Vite):

• app/ → /app/*
• protocol-designer/ → /protocol-designer/*
• opentrons-ai-client/ → /ai-client/*

// Good — absolute import within app
import { useRobot } from '/app/resources/robots'

// Bad — deep relative paths across features
import { useRobot } from '../../../resources/robots'
// Acceptable — relative for nearby files in the same feature
import { utils } from './utils'

No Default Exports

ESLint enforces import/no-default-export. Always use named exports. Exceptions: config files (vite.config.mts, *.stories.tsx).

Lodash

Import individual functions only:

// Good — imports a specific function
import mapValues from 'lodash/mapValues'

// Bad — imports entire library
import { mapValues } from 'lodash'

Type Imports

Always use import type for type-only imports:

import type { LabwareDefinition2 } from '@opentrons/shared-data'

React Component Patterns

Function Declarations (not arrows)

interface MyComponentProps {
  title: string
  onClose: () => void
}

export function MyComponent({ title, onClose }: MyComponentProps): JSX.Element {
  return <div>{title}</div>
}

• Named function declarations, not arrow functions, for components
• Props interface named <ComponentName>Props
• Always destructure props in the function signature

Atomic Design Hierarchy

Components are organized as atoms/ → molecules/ → organisms/ → pages/. Custom ESLint rule opentrons/no-imports-up-the-tree-of-life prevents importing up the hierarchy:

• atoms must NOT import from molecules, organisms, or pages
• molecules must NOT import from organisms or pages
• organisms must NOT import from pages

Application Boundaries (app/ specific)

The app package separates Desktop and ODD (On-Device Display) UIs. ESLint rule opentrons/no-imports-across-applications prevents cross-contamination between /Desktop/, /ODD/, and shared code.

Component Library (@opentrons/components)

Do not use primitives from the shared component library when you create a new component from zero. Primitives are located in components/src/primitives. Use primitives if you update an existing component or fix an existing component for layout and common UI:

import {
  COLORS,
  DIRECTION_COLUMN,
  Flex,
  Icon,
  SPACING,
  StyledText,
} from '@opentrons/components'

Hooks

• useSelector / useDispatch from react-redux
• useTranslation from react-i18next for i18n
• Custom hooks prefixed with use*
• Never call hooks conditionally
• ESLint enforces react-hooks/rules-of-hooks (error) and react-hooks/exhaustive-deps (warn)

Styling

CSS Modules (preferred for new code)

• File: <componentname>.module.css (lowercase, no separators)
• Classes: snake_case (enforced by Stylelint: /^[a-z0-9_]+$/)
• Use CSS custom properties from the design system (spacing, colors, typography, border-radius)
• Use clsx for conditional classes
• Never use inline styles in components (only in *.stories.tsx)

styled-components (legacy)

Some packages still use styled-components@5.3.6. Do not introduce new styled-components — use CSS Modules for new code.

Design System Tokens

/* Spacing */
padding: var(--spacing-8);
gap: var(--spacing-16);

/* Colors */
color: var(--grey-60);
background: var(--white);

/* Typography */
font-size: var(--font-size-13);
font-weight: var(--font-weight-semi-bold);

/* Border radius */
border-radius: var(--border-radius-8);

/* Width/height — use explicit rem values, NOT variables */
width: 15rem;

Testing

Framework

• Vitest 2.1.9 (not Jest) — vi.fn(), vi.mock(), vi.mocked()
• @testing-library/react 16.3.0 — screen, fireEvent, renderHook
• @testing-library/user-event 14.6.1
• vitest-when 0.5.0 for conditional mocking
• jsdom test environment (global vitest.config.mts)

Test File Structure

FeatureOrComponent/
├── index.tsx (or module.ts)
└── **tests**/
└── FeatureName.test.tsx

renderWithProviders

React component tests MUST use renderWithProviders (wraps Redux Provider + QueryClientProvider + optional i18n), not plain render:

import { renderWithProviders } from '/app/__testing-utils__'  // or /protocol-designer/__testing-utils__
import { i18n } from '/app/i18n'
import type { ComponentProps } from 'react'

const render = (props: ComponentProps<typeof MyComponent>) => {
  return renderWithProviders(<MyComponent {...props} />)[0]
}

describe('MyComponent', () => {
  let props: ComponentProps<typeof MyComponent>

  beforeEach(() => {
    props = { /* defaults */ }
  })

  afterEach(() => {
    vi.clearAllMocks()
  })

  it('renders the button', () => {
    render(props)
    expect(screen.getByRole('button')).toBeInTheDocument()
  })

  it('renders the text', () => {
    render(props)
    screen.getByText('Opentrons Flex')
  })
})