# Developer Getting Started

## Prerequisites

- **Node.js** 16+ and npm
- **PHP** 5.6+ (8.0+ recommended for development)
- **WordPress** local development environment (Local by Flywheel, wp-env, etc.)
- **Git**

## Setup

### 1. Clone the Repository

```bash
cd /path/to/wordpress/wp-content/plugins/
git clone <repo-url> ajaxpress
cd ajaxpress
```

### 2. Install Dependencies

```bash
npm install
```

This installs Solid.js, Vite, Tailwind CSS, and other build dependencies.

### 3. Build Assets

Build both admin and frontend bundles:

```bash
# Watch mode (recommended during development)
npm run admin      # Builds admin panel with file watching
npm run frontend   # Builds frontend JS with file watching

# Build deactivate script (one-time, no watch)
npm run deactivate
```

Run `admin` and `frontend` in separate terminal tabs for simultaneous development.

### 4. Activate the Plugin

In your WordPress admin, go to **Plugins** and activate AjaxPress.

## Development Workflow

### Editing Admin Panel

1. Start the admin watcher: `npm run admin`
2. Edit files in `src/admin/`
3. Vite rebuilds `public/js/admin.min.js` and `public/css/admin.min.css`
4. Refresh the AjaxPress settings page in WordPress admin

### Editing Frontend Engine

1. Start the frontend watcher: `npm run frontend`
2. Edit files in `src/frontend/`
3. Vite rebuilds `public/js/ajaxpress.min.js` and `public/css/ajaxpress.min.css`
4. Refresh your site's frontend

### Editing PHP

PHP changes take effect immediately -- no build step needed. Just refresh the page.

### Editing SCSS

SCSS files in `src/sass/` are imported by the Vite configs. Changes are picked up by the running watcher.

## Code Quality

### PHP Linting

```bash
npm run report
```

Runs PHP_CodeSniffer with WordPress coding standards. Output is written to `report.txt`.

The PHPCS configuration (`phpcs.xml`) enforces:
- WordPress coding standards
- PHP 5.6+ compatibility
- Text domain: `ajaxpress`
- Minimum WordPress version: 6.0

### Source Files vs. Built Files

**Never edit files in `public/js/` or `public/css/` directly.** These are generated outputs. Always edit source files in `src/`.

| Source | Output |
|--------|--------|
| `src/admin/` | `public/js/admin.min.js`, `public/css/admin.min.css` |
| `src/frontend/` | `public/js/ajaxpress.min.js`, `public/css/ajaxpress.min.css` |
| `src/admin/deactivate.js` | `public/js/deactivate.min.js` |

## Debugging

### PHP Debugging

Enable WordPress debug mode in `wp-config.php`:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

The `debug` flag is passed to the frontend via `window.ajaxpress_vars.debug`.

### JavaScript Debugging

Source maps are included in built files (`.map` files). Browser DevTools will show original source files.

Key global objects for inspection:
- `window.ajaxpress_vars` -- Frontend settings and state
- `window.ajaxpress_admin_vars` -- Admin settings and state
- `window.licenseStatus` -- License validation state

### Cloudflare Debugging

Check the `X-AjaxPress-Cache` response header:
- `HIT` -- Cached at edge
- `MISS` -- Fetched from origin
- `BYPASS` -- Skipped caching (check bypass rules)