Skip to content

chore: add AGENTS.md with Cursor Cloud development instructions #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
ronros-elementor wants to merge 1 commit into
base: main
Choose a base branch
from
+35 −0
Draft

chore: add AGENTS.md with Cursor Cloud development instructions #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Agents

## Cursor Cloud specific instructions

### Overview
Elementor is a WordPress page builder plugin. The codebase is a monorepo with two main areas:
- **Root**: WordPress plugin (PHP + legacy JS/SCSS), built via Grunt + Webpack
- **`packages/`**: Turborepo-managed TypeScript micro-frontend packages (~47 packages: core apps, shared libs, build tools), built via tsup

### Prerequisites
- **Node.js 20.19** (see `.nvmrc`): `nvm use 20.19`
- **PHP >= 7.4** with extensions: `mbstring`, `xml`, `curl`, `zip`, `mysql`, `gd`, `bcmath`
- **Composer** for PHP dependency management

### Key commands
All standard dev commands are in `package.json` and documented in `CONTRIBUTING.md`. Key ones:
- `npm ci --ignore-scripts && composer install` — install all dependencies
- `npm run build:packages` — build turbo-repo packages (required before lint/test)
- `npx grunt styles` / `npx grunt scripts` — build legacy CSS/JS assets
- `npm run watch` — full dev mode with file watching (packages + styles + scripts)
- `npm run lint` — ESLint for root repo + packages lint (ESLint + tsc)
- `npm run test:jest` — Jest tests for main repo (691 tests)
- `npm run test:packages` — Jest tests for turbo-repo packages (2504 tests)
- `npm run wp-playground` — start WordPress Playground dev server on port 9400 (credentials: admin/password)

### Running the application locally
Use `npm run wp-playground` to start a WordPress Playground instance with Elementor mounted and activated. This is simpler than Docker-based `wp-env`. The server runs on `http://localhost:9400` with `admin`/`password` credentials.

### Gotchas
- `npm ci --ignore-scripts` is intentional — the repo uses npm workspaces and `--ignore-scripts` avoids running lifecycle hooks that may fail outside CI. Composer's `post-install-cmd` runs php-scoper and dump-autoload automatically.
- Turbo-repo packages must be built (`npm run build:packages`) before running root ESLint or Grunt webpack, since built package outputs are referenced.
- The `packages/` workspace has its own separate `lint` command (`npm run lint -w elementor-packages`) which runs both ESLint and TypeScript type checking concurrently.
- PHP tests (`npm run test:php`) require Docker with a MySQL container (via `docker-compose.yml`). They are not runnable without Docker.
- Playwright E2E tests require a running WordPress server and `npx playwright install chromium`.
- The `.husky/pre-commit` hook runs `lint-staged` with `NODE_OPTIONS=--max-old-space-size=8192`.