Skip to content

AGENTS.md

Latest commit

 

History

History
61 lines (45 loc) · 2.68 KB

AGENTS.md

File metadata and controls

61 lines (45 loc) · 2.68 KB
Raw

Mendix Web Widgets

Monorepo of official Mendix pluggable web widgets. pnpm workspaces + Turbo.

Conventions

  • TypeScript strict, React functional components + hooks
  • Mendix Pluggable Widgets API: EditableValue, ActionValue, ListValue, DynamicValue
  • Check ActionValue.canExecute before execute()
  • Render loading/empty states until values are ready
  • SCSS for styling, prefer Atlas UI classes, BEM-like naming with widget prefix
  • Conventional commits enforced: type(scope): description
  • Semver + CHANGELOG.md per package for pluggable widgets and modules, not for shared packages
  • Changelogs for users: include only widget behavior, not implementation details
  • Changelogs added during development, version bumps only at release time
  • Jest + RTL for unit tests (src/*/tests/.spec.ts)
  • Playwright for E2E (e2e/*.spec.js)

E2E Test Rules (Playwright)

  • docs/requirements/e2e-test-guidelines.md — Full rules + template

Development Setup

  • Node >=24, pnpm 10.x
  • Set MX_PROJECT_PATH to Mendix project dir for live reload
  • Run pnpm start inside widget package for dev build

Constraints

  • Never modify dist/, generated files, or lockfiles
  • OpenSpec specs/changes are PER-PACKAGE — never create them at the monorepo root. Always cd packages/<type>/<name> before any openspec new/init/archive. The root openspec/ directory is off-limits (enforced by .claude/hooks/validate-openspec-path.sh).
  • XML property keys: lowerCamelCase, must match TypeScript props exactly
  • Don't override core Atlas UI classes
  • Prefer tree-shakable imports for new dependencies

Documentation

Essential reading (consult for any widget work):

  • docs/repo-layout.md — To understand the repository
  • docs/widget-scripts.md - How to build/test/lint packages
  • docs/requirements/tech-stack.md — Full technology stack
  • docs/requirements/frontend-guidelines.md — CSS/SCSS/Atlas UI guidelines
  • docs/requirements/app-flow.md — Widget lifecycle and Studio Pro integration
  • docs/requirements/backend-structure.md — Data flow and Mendix runtime
  • docs/requirements/project-requirements-document.md — Goals and scope

Reference (consult on demand for specific tasks):

  • docs/requirements/implementation-plan.md — New widget guide + PR template
  • docs/requirements/widget-to-module.md — Widget-to-module conversion guide
  • docs/requirements/e2e-test-guidelines.md — E2E test reliability rules + template

Agent-Specific Instructions

  • Claude Code — See CLAUDE.md for hooks and auto-imported documentation
  • GitHub Copilot — See .github/copilot-instructions.md for PR review guidelines
  • Cursor / Windsurf — Use docs/requirements/ files as rule sources (YAML frontmatter compatible)