|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Repo shape |
| 6 | + |
| 7 | +Lerna + npm workspaces monorepo with ~38 packages under `packages/*`. Nx is used only for build caching (see `nx.json`). Node 24 / npm 11 (`.nvmrc`). Most packages are libraries built with Babel + Sass; the four apps (`code-studio`, `embed-widget`, `embed-chart`, `embed-grid`) are built with Vite. |
| 8 | + |
| 9 | +The web UI does not work standalone — it requires a `deephaven-core` server on port 10000 (override with `VITE_PROXY_URL` in `packages/<app>/.env.local`). For E2E, core must run with anonymous auth and `-Ddeephaven.application.dir=tests/docker-scripts/data/app.d` (see README's E2E section). |
| 10 | + |
| 11 | +## Common commands |
| 12 | + |
| 13 | +- `npm start` — build icons, then watch types and start dev servers (`code-studio` on :4000, `embed-widget` on :4010). |
| 14 | +- `npm run start:app` / `npm run start:embed-widget` — start a single dev server. |
| 15 | +- `npm run build` — full prod build: `build:necessary` → `types` → `build:packages` → `build:apps`. Always builds `@deephaven/icons` first because it generates SVGs other packages consume. |
| 16 | +- `npm run types` / `npm run watch:types` — `tsc --build` using project references. Top-level packages must be listed in the root `tsconfig.json` references for type emit to work. |
| 17 | +- `npm test` — Jest watch mode, filtered to files changed since `origin/main`. Press `p` to filter by name, `Shift+P` to toggle the `eslint`/`stylelint` jest projects. |
| 18 | +- `npm run test:unit` — runs `build:necessary`, then all unit tests across every package's `jest.config.cjs`. |
| 19 | +- `npm run test:lint` — runs ESLint and Stylelint as jest projects via `jest-runner-eslint` / `jest-runner-stylelint`. Faster than `lint:packages` when narrowed (`-- --changedSince origin/main`). |
| 20 | +- Single test: `npm run test:unit -- <pattern>` (matches filename or test name), or `npm run test:debug <pattern>` to attach a debugger. |
| 21 | +- `npm run e2e` / `npm run e2e:headed` — Playwright; requires `localhost:4000/ide/` reachable and core running. `npm run e2e:docker` builds a prod image and runs everything in docker. Snapshots are Linux-only — update CI snapshots with `npm run e2e:update-ci-snapshots`. |
| 22 | +- `DH_LOG_LEVEL=4 npm test` — enable `@deephaven/log` output in tests (suppressed by default in `jest.setup.ts`). |
| 23 | + |
| 24 | +## Architecture |
| 25 | + |
| 26 | +- **App entry points** all live in `packages/code-studio` (main UI), `packages/embed-widget` (single-widget embed), `packages/embed-chart`, `packages/embed-grid`. `code-studio` depends on nearly every other package and is the fastest way to see end-to-end effects. |
| 27 | +- **Rendering / layout stack:** `golden-layout` (low-level panel framework) → `dashboard` (panel state + APIs) → `dashboard-core-plugins` (concrete panel types: chart, grid, console, filter, linker) → `code-studio` wires plugins into the app shell. Plugins are registered via `@deephaven/plugin`. |
| 28 | +- **Data grids:** `grid` is a generic high-performance canvas grid; `iris-grid` is the Deephaven-aware grid that knows about the JS API (filters, totals rows, snapshots, etc.). `iris-grid` depends on `grid`. |
| 29 | +- **JS API integration:** `jsapi-types` (TypeScript types for the API delivered by core), `jsapi-shim` (re-exports the runtime API loaded from core), `jsapi-bootstrap` (React context + hooks like `useApi`, `useObjectFetcher`, `useWidget` that gate UI on API readiness), `jsapi-components` (React components that consume the API), `jsapi-utils` (framework-free helpers), `jsapi-nodejs` (Node loader for using the API server-side). |
| 30 | +- **State:** `redux` package owns the root store, reducer registry, middleware, and selectors. Other packages register reducers via `reducerRegistry`. `react-hooks` and `jsapi-bootstrap` provide React-side primitives. |
| 31 | +- **UI primitives:** `components` is the design system. It re-exports a curated subset of `@adobe/react-spectrum` from `components/src/spectrum` — the rest of the codebase **must not** import `@adobe/react-spectrum` directly (enforced by `no-restricted-imports` in the root ESLint config). Inside `components`, only `src/spectrum/**` and `src/theme/**` may import the spectrum package. |
| 32 | +- **No self-imports:** the same ESLint rule forbids a package from importing its own `@deephaven/<name>` alias — use relative paths within a package. |
| 33 | + |
| 34 | +## Test wiring |
| 35 | + |
| 36 | +- Unit tests resolve workspace packages from source via Jest `moduleNameMapper` (`^@deephaven/(?!icons|jsapi-types)(.*)$ → packages/$1/src`), so you don't need to rebuild dependencies between edits. `icons` and `jsapi-types` are exceptions and ship pre-built. |
| 37 | +- Each package has a thin `jest.config.cjs` that extends `jest.config.base.cjs`. Tests run under `jsdom` with `jest.setup.ts` mocking `matchMedia`, `ResizeObserver`, `IntersectionObserver`, fonts, etc. |
| 38 | +- The "dh-core" JS API is mocked globally via `__mocks__/dh-core` — most tests that touch the API use `@deephaven/test-utils` helpers and the mock proxy pattern (`TestUtils.createMockProxy<T>()`). |
| 39 | + |
| 40 | +## Conventions |
| 41 | + |
| 42 | +- **Conventional Commits are required for PR titles** (enforced by `conventional-pr-check.yml`). Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. Breaking changes use a `BREAKING CHANGE:` footer in the PR description — **do not** use the `!` shorthand. |
| 43 | +- Lerna versioning is conventional-commits driven; release notes and CHANGELOGs are generated automatically. |
| 44 | +- ESLint extends Airbnb + React; Prettier and Stylelint are wired through `@deephaven/prettier-config` and `@deephaven/stylelint-config`. Run `npm run test:lint` rather than calling eslint/stylelint directly so caching works. |
| 45 | +- New packages: copy `embed-widget` for an app, `components` for a library, then add to root `tsconfig.json` references if it needs to participate in `npm run types`. |
0 commit comments