opentrons / rules

---
description: Monorepo environment setup, teardown, and troubleshooting for JS and Python
alwaysApply: true
---

# Monorepo Setup, Teardown & Troubleshooting

All commands run from the **monorepo root** unless noted otherwise.

## Node.js Version Management

**Required:** Node.js >= 22.22.0 (`.nvmrc`: `22.22.0`), pnpm 10.32.1.

Before running any `node`, `pnpm`, or `make` command, ensure the correct Node version is active. The user may use **nvm**, **nvs**, or **asdf**:

```bash
# nvm (most common)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && nvm use

# nvs
export NVS_HOME="$HOME/.nvs"
[ -s "$NVS_HOME/nvs.sh" ] && . "$NVS_HOME/nvs.sh" && nvs use auto

# asdf
[ -s "$HOME/.asdf/asdf.sh" ] && . "$HOME/.asdf/asdf.sh"
```

If `node --version` already shows a valid version, skip sourcing. Always verify before running shell commands.

## Python Version

Robot-stack Python projects use **Python 3.12** (`OT_VIRTUALENV_VERSION` in `scripts/python.mk`). The `OT_PYTHON` env var (default: `python`) selects the interpreter.

Standalone Python projects (`opentrons-ai-server/`, `e2e-testing/`, `analyses-snapshot-testing/`, `scripts/static-deploy/`) use **uv** for dependency management instead of pipenv. See their dedicated rules for details.

## Root Makefile — Quick Reference

### Setup (install dependencies)

| Target | Description |
| --- | --- |
| `make setup` | Install all JS and Python dependencies |
| `make setup-js` | Setup all JS projects (pnpm install) |
| `make setup-py` | Setup all robot Python packages (pipenv/uv per project) |

### Teardown (uninstall dependencies)

| Target | Description |
| --- | --- |
| `make teardown` | Teardown Python then JS (order matters) |
| `make teardown-js` | Clean JS build output, remove all `node_modules` |
| `make teardown-py` | Teardown all robot Python packages |

### Clean (remove build artifacts only)

| Target | Description |
| --- | --- |
| `make clean` | Clean JS and Python build output |
| `make clean-js` | Clean JS build output (includes `clean-ts`) |
| `make clean-py` | Clean Python build output |
| `make clean-ts` | Remove TypeScript declaration output (`tsc --build --clean`) |

### Test

**Prefer scoped tests.** When changes are in a specific package or directory, run tests only for that area rather than the entire repo. This is faster and gives more relevant feedback.

```bash
# Best: run tests for just the files near your changes
pnpm vitest protocol-designer/src/step-forms/
make test-js-protocol-designer tests="src/step-forms/"

# For Python, run from the project directory
cd api && make test  # or: make -C api test
```

**Full-repo targets** (use only when changes span multiple packages):

| Target | Description |
| --- | --- |
| `make test` | Run all JS and Python tests |
| `make test-js` | Run all JS tests (Vitest) |
| `make test-js-<project>` | Run tests for one JS project (e.g., `make test-js-protocol-designer`) |
| `make test-py` | Run all robot Python tests (pytest) |

Pass options: `make test-js-<project> tests="src/path" test_opts="--reporter=verbose"`

### Frontend Lint & Format — Always Use These Three

All frontend (TS/TSX/JS/CSS) lint and format commands run from the **monorepo root** via these three Make targets. Do not call ESLint, Prettier, or Stylelint directly.

```bash
make format-js    # Prettier auto-format (all TS/TSX/JS/MD/JSON)
make lint-js      # ESLint + Prettier check (run after format-js to confirm clean)
make lint-css     # Stylelint check for all CSS Modules
```

Run `format-js` first to auto-fix, then `lint-js` and `lint-css` to verify nothing remains.

### Lint & Type-Check (full reference)

| Target | Description |
| --- | --- |
| `make lint-js` | ESLint + Prettier check |
| `make lint-js-eslint` | ESLint only |
| `make lint-js-prettier` | Prettier only |
| `make lint-css` | Stylelint all CSS |
| `make lint-json` | ESLint for JSON files |
| `make lint-py` | Lint all robot Python projects (ruff + mypy) |
| `make check-js` / `make build-ts` | TypeScript type-check (`tsc --build`) |
| `make circular-dependencies-js` | Check for circular imports (madge) |

### Format (auto-fix, full reference)

| Target | Description |
| --- | --- |
| `make format-js` | Prettier auto-format |
| `make format-py` | ruff format for all robot Python projects |
| `make format-css` | Stylelint auto-fix |

### opentrons-ai-server Lint & Format

`opentrons-ai-server/` is a standalone Python project with its own Makefile. Run from inside that directory:

```bash
make format   # ruff format + ruff check --fix + prettier for MD/JSON
make lint     # ruff format --check + ruff check + mypy
```

## Standalone Python Projects

These projects have their **own** `Makefile` and use **uv** (not pipenv). They are NOT covered by root `make setup-py` / `make teardown-py`:

| Project | Directory | Setup Command |
| --- | --- | --- |
| AI Server | `opentrons-ai-server/` | `make setup` (runs `uv sync`) |
| E2E Testing | `e2e-testing/` | `make setup` (runs `uv sync`) |
| Analyses Snapshot Testing | `analyses-snapshot-testing/` | `make setup` (runs bootstrap script; Python 3.12) |
| Static Deploy | `scripts/static-deploy/` | `make setup` (runs `uv sync`) |

Run their setup from within their own directory.

## Troubleshooting

### Stale or Broken node_modules

```bash
make teardown-js && make setup-js
```

### Pnpm Cache Corruption

```bash
pnpm cache delete && make setup-js
```

### TypeScript Build Artifacts Out of Sync

```bash
make clean-ts    # remove declaration output
make build-ts    # rebuild
```

### Python Virtual Environment Issues

```bash
make teardown-py && make setup-py
```

For standalone uv projects, run `make teardown && make setup` from within that project's directory.

### Wrong Node Version

```bash
node --version   # should show v22.22.0+
```

If wrong, re-source the version manager (see Node.js section above) or install the correct version:

```bash
nvm install       # reads .nvmrc
# or
nvs add auto
# or
asdf install nodejs
```

### "Module not found" Errors in JS

Usually means `pnpm` hasn't been run:

```bash
make setup-js
```

If a specific package is missing, try:

```bash
make teardown-js && make setup-js
```

### Port Conflicts for Dev Servers

```bash
lsof -i :<port>          # find the process
kill -9 <pid>            # kill it
```

### Nuclear Option — Full Reset

When nothing else works, tear down and rebuild everything:

```bash
make teardown && make setup
```

This removes all `node_modules`, Python venvs, and build output, then reinstalls from scratch.