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-p);
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')
  })
})

Mocking

• vi.mock() at file top for module mocks
• vi.mocked(fn).mockReturnValue(...) for typed mocks
• vi.clearAllMocks() in afterEach (always)

Queries

• Prefer screen.getByRole, screen.getByText, screen.getByTestId
• Never use container.querySelector
• data-testid format: ComponentName_ElementType

Makefile Targets

Per-Package (run from the package directory)

Each package has a Makefile with some or all of:

Root Makefile (run from monorepo root)

Running Tests Directly

# Single file
pnpm vitest app/src/organisms/__tests__/MyComponent.test.tsx

# Entire package
pnpm vitest protocol-designer/

# Watch mode
pnpm vitest --watch app/src/

# Specific project via Make
make test-js-app tests="src/organisms/__tests__/MyComponent.test.tsx"

Linting Specific Files

pnpm eslint path/to/file.tsx
pnpm stylelint path/to/file.module.css
pnpm prettier --check path/to/file.tsx
pnpm prettier --write path/to/file.tsx   # auto-fix

Event Handlers

import type { MouseEvent } from 'react'

// Named handlers for complex logic
const handleClick = (e: MouseEvent<HTMLButtonElement>): void => {
  e.preventDefault()
  onClick()
}
return <button onClick={handleClick}>Click me</button>

// Direct reference for simple cases
return <button onClick={onClick}>Click me</button>

// Bad — unnecessary wrapper
return <button onClick={() => onClick()}>Click me</button>

Always specify type on buttons in forms:

<button type="button" onClick={handleAttach}>Attach</button>
<button type="submit">Submit Form</button>

Constants & Magic Numbers

Extract all constants — avoid inline magic numbers:

// Good
const UNIT_MB = 1024 * 1024
const MAX_FILES = 5

export const FILE_SIZE_LIMITS = {
  pdf: 10 * UNIT_MB,
  csv: 2 * UNIT_MB,
} as const

// Bad
const sizeMB = Math.round(sizeLimit / (1024 * 1024))

Use object lookups for simple mappings instead of switch statements.

Component Architecture

Separate router logic from presentation for testability:

// Router-aware wrapper
function AppWithRouter() {
  const location = useLocation()
  return <AppContent isOnChatPage={location.pathname === '/chat'} />
}

// Pure presentation (easily testable)
function AppContent({ isOnChatPage }: { isOnChatPage: boolean }) {
  return <div>{!isOnChatPage ? <Footer /> : null}</div>
}

Common Pitfalls

• Do NOT use any — strict TypeScript is enforced
• Do NOT use default exports (except config files and stories)
• Do NOT use class components — functional only
• Do NOT use arrow functions for component definitions
• Do NOT use implicit truthiness for null checks — use explicit != null
• Do NOT import the full lodash package — use granular imports
• Do NOT use inline styles in components
• Do NOT use querySelector in tests
• Do NOT introduce new styled-components — use CSS Modules
• Do NOT import up the atomic design hierarchy (atoms ← molecules ← organisms ← pages)
• Do NOT skip afterEach(() => vi.clearAllMocks()) in test suites
• Do NOT use semicolons (Prettier removes them)
• Do NOT use console.log or debugger in committed code
• Do NOT omit curly braces for control statements — ESLint curly rule enforces braces for all if, else, for, while, and do blocks
• Do NOT use primitives (primitives are located in components/src/primitives) for new component - use HTML 5 tags and CSS Modules
• Do NOT use margins to create a layout in a component - use padding and gap
• Do NOT use a conditional statement for aria-label
• Do NOT use a nested ternary in non-component render code