|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Repository Overview |
| 6 | + |
| 7 | +DevExtreme is an enterprise UI component suite for Angular, React, Vue, and jQuery. This is a large-scale monorepo (pnpm workspaces + Nx 22) containing the core library, framework wrappers, demos, themes, and test suites. |
| 8 | + |
| 9 | +**Required tooling:** Node.js 24.15.0, pnpm 11.5.1. |
| 10 | + |
| 11 | +## Setup |
| 12 | + |
| 13 | +```bash |
| 14 | +pnpm install --frozen-lockfile |
| 15 | +``` |
| 16 | + |
| 17 | +Always use `--frozen-lockfile`. CI enforces it. |
| 18 | + |
| 19 | +## Build |
| 20 | + |
| 21 | +The `dev` script is run manually in WebStorm (not by agents). It runs a Gulp watch build with hot reload and starts the QUnit test server on port 20060: |
| 22 | + |
| 23 | +```bash |
| 24 | +# From packages/devextreme — run manually, not via agent |
| 25 | +pnpm run dev |
| 26 | +``` |
| 27 | + |
| 28 | +This is a long-running process. **Agents should not run it.** If a build is needed to verify a change, ask the developer to confirm when the dev build succeeds. |
| 29 | + |
| 30 | +For a one-shot dev build (e.g., before running Jest tests in CI-like fashion): |
| 31 | +```bash |
| 32 | +pnpm nx build:dev devextreme |
| 33 | +``` |
| 34 | + |
| 35 | +If builds behave unexpectedly, clear the Nx cache: `rm -rf .nx/cache` |
| 36 | + |
| 37 | +## Tests |
| 38 | + |
| 39 | +### Jest unit tests (from `packages/devextreme`) |
| 40 | + |
| 41 | +```bash |
| 42 | +pnpm run test-jest # All JSDOM tests |
| 43 | + |
| 44 | +# Single file/pattern — invoke Jest directly. |
| 45 | +# Note: this repo currently uses Jest 29.x, where the flag is --testPathPattern (singular). |
| 46 | +pnpm exec jest --no-coverage --runInBand --selectProjects jsdom-tests --testPathPattern "<pattern>" |
| 47 | + |
| 48 | +# Watch mode for a single file/pattern: |
| 49 | +pnpm exec jest --watch --no-coverage --selectProjects jsdom-tests --testPathPattern "<pattern>" |
| 50 | +``` |
| 51 | + |
| 52 | +Example: `pnpm exec jest --no-coverage --runInBand --selectProjects jsdom-tests --testPathPattern "js/__internal/grids/data_grid/ai_assistant/commands/__tests__/summary.test.ts"` |
| 53 | + |
| 54 | +Jest tests for grid components live under `js/__internal/grids/` — typically in `__tests__/` subdirectories alongside the source (in `grid_core/`, `data_grid/`, and `tree_list/`). |
| 55 | + |
| 56 | +### QUnit tests (legacy, browser-based) |
| 57 | + |
| 58 | +QUnit tests are not written for new code but used to verify existing grid behavior after refactoring. To run them: |
| 59 | + |
| 60 | +1. Ensure `pnpm run dev` is running (started manually in WebStorm) |
| 61 | +2. Open `http://localhost:20060/` in browser |
| 62 | +3. Navigate to the relevant module (e.g., `DevExpress.ui.widgets.dataGrid`) |
| 63 | +4. Run the tests — errors appear on the page |
| 64 | + |
| 65 | +**Agents should not run QUnit tests.** Ask the developer to run the relevant module and report results. |
| 66 | + |
| 67 | +## Lint Commands |
| 68 | + |
| 69 | +**From `packages/devextreme`:** |
| 70 | +```bash |
| 71 | +pnpm run lint # All linting |
| 72 | +pnpm run lint-js # JS only |
| 73 | +pnpm run lint-ts # TS only |
| 74 | +pnpm run lint-dts # .d.ts files |
| 75 | + |
| 76 | +pnpm run lint-js -- --fix # Auto-fix |
| 77 | +pnpm run lint-ts -- --fix |
| 78 | +``` |
| 79 | + |
| 80 | +Pre-commit hooks (Husky + lint-staged) run automatically on `git commit`. |
| 81 | + |
| 82 | +## Architecture |
| 83 | + |
| 84 | +### Package Layout |
| 85 | + |
| 86 | +``` |
| 87 | +packages/ |
| 88 | + devextreme/ # Core library — JS/TS source, QUnit tests, build scripts |
| 89 | + js/ui/ # Public entry points: .d.ts API definitions + reexports from __internal |
| 90 | + js/viz/ # Public entry points for visualizations |
| 91 | + js/core/ # Public entry points for core utilities |
| 92 | + js/data/ # Public entry points for data layer |
| 93 | + js/__internal/ # All implementation code lives here |
| 94 | + grids/ # Grid components (DataGrid, TreeList, etc.) |
| 95 | + devextreme-angular/ # Angular wrapper (GENERATED — do not edit src/) |
| 96 | + devextreme-react/ # React wrapper (GENERATED — do not edit src/) |
| 97 | + devextreme-vue/ # Vue wrapper (GENERATED — do not edit src/) |
| 98 | + devextreme-scss/ # SCSS themes |
| 99 | + devextreme-metadata/ # Metadata that drives wrapper generation |
| 100 | + testcafe-models/ # TestCafe page object models |
| 101 | +
|
| 102 | +apps/ |
| 103 | + demos/ # Technical demos (Angular, React, Vue, jQuery) |
| 104 | +
|
| 105 | +e2e/ |
| 106 | + testcafe-devextreme/ # E2E tests |
| 107 | +``` |
| 108 | + |
| 109 | +The folders under `js/` (except `__internal/`) contain only the public API surface — `.d.ts` type definitions and reexports. All actual implementation is in `js/__internal/`. |
| 110 | + |
| 111 | +### Framework Wrappers |
| 112 | + |
| 113 | +Framework wrappers (`devextreme-angular/src/`, `devextreme-react/src/`, `devextreme-vue/src/`) are **entirely generated** — do not edit `src/` directly. |
| 114 | + |
| 115 | +When updating public API in `js/ui/*.d.ts`, regenerate afterward: |
| 116 | +```bash |
| 117 | +pnpm run regenerate-all # from repo root — requires .NET SDK 8.0.x |
| 118 | +cd packages/devextreme |
| 119 | +pnpm run update-ts-reexports |
| 120 | +pnpm run update-ts-bundle |
| 121 | +pnpm run lint-dts |
| 122 | +``` |
| 123 | + |
| 124 | +Do not edit directly: |
| 125 | +- `packages/devextreme-angular/src/**/*` (except templates) |
| 126 | +- `packages/devextreme-react/src/**/*` (except templates) |
| 127 | +- `packages/devextreme-vue/src/**/*` (except templates) |
| 128 | +- `packages/devextreme/js/__internal/core/localization/default_messages.ts` |
| 129 | +- `packages/devextreme/js/__internal/core/localization/cldr-data/**/*` |
| 130 | + |
| 131 | +## Code Style Conventions |
| 132 | + |
| 133 | +These rules apply to `packages/devextreme/js/**/*.d.ts` (see `.github/instructions/API_conventions.instructions.md`): |
| 134 | + |
| 135 | +- **Acronym casing:** Treat acronyms as regular words — `parseHtml`, `testDom`, `createJsonParser`. Exception: `AI` is always fully capitalized (`AIIntegration`, `aiOptions`). |
| 136 | +- **JSDoc @type:** Omit `@type` when the TypeScript annotation already declares the type. |
| 137 | + |
| 138 | +Use comments sparingly. Only comment complex code. |
| 139 | + |
| 140 | +## Localization Files |
| 141 | + |
| 142 | +Files under `**/localization/messages/**/*.json` are managed by a dedicated team. **Never suggest translations, alternative phrasings, or language changes.** Only flag critical JSON syntax errors. |
| 143 | + |
| 144 | +## CI Checks on PRs |
| 145 | + |
| 146 | +| Workflow | What it runs | |
| 147 | +|------------------------|-----------------------------------------------------------------------| |
| 148 | +| `default_workflow.yml` | `nx run-many -t lint,test` on most packages | |
| 149 | +| `lint.yml` | TS, JS, .d.ts, text linting; checks generated reexports are up-to-date | |
| 150 | +| `build_all.yml` | Full production build (requires .NET 8.0.x) — CI only | |
| 151 | +| `wrapper_tests.yml` | Angular/React/Vue wrapper tests + regeneration check | |
| 152 | +| `qunit_tests.yml` | Legacy QUnit tests | |
| 153 | +| `testcafe_tests.yml` | E2E accessibility and component tests | |
| 154 | + |
| 155 | +**Common CI failure fixes:** |
| 156 | +- *"Generated code is outdated"* → run `pnpm run regenerate-all` from repo root |
| 157 | +- *"Reexports outdated"* → run `pnpm run update-ts-reexports` from `packages/devextreme` |
| 158 | +- *Lint errors* → run `pnpm run lint-js -- --fix` or `pnpm run lint-ts -- --fix` |
0 commit comments