# Development and Build Instructions

This document provides detailed instructions for developers who want to contribute to or build Comments Press Zone from source.

## Table of Contents

- [Prerequisites](#prerequisites)
- [Directory Structure](#directory-structure)
- [Build Process](#build-process)
- [Development Workflow](#development-workflow)
- [File Organization](#file-organization)

## Prerequisites

Before building this plugin from source, ensure you have the following installed:

- **Node.js**: Version 14.x or higher
- **npm**: Version 6.x or higher (comes with Node.js)
- **Git**: For version control

To verify your installations:

```bash
node --version   # Should show v14.x or higher
npm --version    # Should show 6.x or higher
```

## Directory Structure

```
comments-press-zone/
├── admin/
│   ├── src-vanilla/        # Source files for admin panel (uncompiled)
│   │   ├── main.js         # Entry point
│   │   ├── state/          # State management
│   │   ├── components/     # UI components
│   │   ├── pages/          # Admin pages
│   │   ├── utils/          # Utility functions
│   │   └── css/            # Admin SCSS styles
│   ├── build/              # Compiled output (generated)
│   │   └── admin.js        # Minified admin bundle
│   ├── package.json        # Admin dependencies
│   └── webpack.config.js   # Webpack configuration
├── assets/
│   ├── scss/               # Frontend SCSS source files
│   │   ├── abstracts/      # Variables, mixins
│   │   ├── components/     # Component styles
│   │   ├── layout/         # Layout styles
│   │   └── frontend.scss   # Main entry point
│   ├── css/                # Compiled CSS (generated)
│   │   └── frontend.css    # Compiled from SCSS
│   └── js/                 # Frontend JavaScript (not compiled)
│       ├── frontend.js     # Main frontend script
│       └── components/     # Frontend components
├── includes/               # PHP backend code (not compiled)
├── templates/              # PHP templates (not compiled)
├── package.json            # Root dependencies
└── CONTRIBUTING.md         # This file
```

## Build Process

### First-Time Setup

1. **Clone the repository:**

```bash
git clone https://github.com/avi-ezra/comments-press-zone.git
cd comments-press-zone
```

2. **Install root dependencies:**

```bash
npm install
```

This installs the dependencies needed for CSS compilation (node-sass).

3. **Install admin panel dependencies:**

```bash
cd admin
npm install
cd ..
```

This installs webpack, babel, and other tools needed for admin JavaScript compilation.

### Building for Production

#### Build Everything (Recommended)

To compile all assets (CSS + Admin JavaScript) in one command:

```bash
# From plugin root directory
npm run build:css     # Compiles SCSS to CSS
cd admin && npm run build && cd ..  # Compiles admin JavaScript
```

#### Build CSS Only

If you've only modified SCSS files:

```bash
# From plugin root directory
npm run build:css
```

**What this does:**
- Compiles `assets/scss/frontend.scss` → `assets/css/frontend.css`
- Includes all SCSS partials (abstracts, components, layout)
- Generates minified CSS optimized for production

#### Build Admin JavaScript Only

If you've only modified admin panel JavaScript:

```bash
# From plugin root directory
cd admin
npm run build
cd ..
```

**What this does:**
- Compiles `admin/src-vanilla/**/*.js` → `admin/build/admin.js`
- Transpiles modern JavaScript (ES6+) to ES5 using Babel
- Bundles all modules using Webpack 5
- Generates minified, production-ready code
- Creates source maps for debugging

### Development Mode

For active development with file watching:

#### Watch CSS Changes

```bash
# From plugin root directory
npm run watch:css
```

This automatically recompiles CSS whenever you save SCSS files.

#### Watch Admin JavaScript Changes

```bash
# From admin directory
cd admin
npm run watch
```

This automatically recompiles JavaScript whenever you save files in `admin/src-vanilla/`.

## Development Workflow

### Recommended Workflow

1. **Start watchers** (optional, for faster feedback):

```bash
# Terminal 1: CSS watch (from plugin root)
npm run watch:css

# Terminal 2: Admin JS watch (from admin directory)
cd admin
npm run watch
```

2. **Make your changes:**
   - Edit SCSS files in `assets/scss/`
   - Edit admin JavaScript in `admin/src-vanilla/`
   - Edit frontend JavaScript in `assets/js/` (no build needed)
   - Edit PHP files in `includes/` or `templates/` (no build needed)

3. **Test your changes:**
   - Refresh your WordPress admin panel
   - Clear browser cache if styles don't update
   - Check browser console for JavaScript errors

4. **Before committing:**

```bash
# Build production assets
npm run build:css
cd admin && npm run build && cd ..

# Verify no errors in compilation
# Commit both source files AND compiled files
git add .
git commit -m "Your commit message"
```

### File Types and Build Requirements

| File Type | Location | Requires Build? | Build Command |
|-----------|----------|-----------------|---------------|
| PHP | `includes/`, `templates/` | ❌ No | N/A |
| Frontend JS | `assets/js/` | ❌ No | N/A |
| Admin JS | `admin/src-vanilla/` | ✅ Yes | `cd admin && npm run build` |
| SCSS | `assets/scss/` | ✅ Yes | `npm run build:css` |
| CSS | `assets/css/` | ❌ No (generated) | N/A |

**Important:** Always commit both source files AND compiled files to the repository. This ensures the plugin works out-of-the-box without requiring users to build it themselves.

## File Organization

### Source Files (Edit These)

**Admin Panel JavaScript:**
- `admin/src-vanilla/main.js` - Entry point
- `admin/src-vanilla/state/*.js` - State management
- `admin/src-vanilla/components/*.js` - Reusable components
- `admin/src-vanilla/pages/*.js` - Page-specific logic
- `admin/src-vanilla/utils/*.js` - Helper functions
- `admin/src-vanilla/css/*.scss` - Admin panel styles

**Frontend SCSS:**
- `assets/scss/frontend.scss` - Main entry point
- `assets/scss/abstracts/_variables.scss` - Color/spacing variables
- `assets/scss/components/*.scss` - Component-specific styles
- `assets/scss/layout/*.scss` - Layout and structure

**Frontend JavaScript:**
- `assets/js/frontend.js` - Main frontend entry point
- `assets/js/components/*.js` - Frontend components (Editor, Emoji picker, etc.)

**PHP Backend:**
- `includes/**/*.php` - All PHP business logic
- `templates/**/*.php` - Template files

### Generated Files (Don't Edit Directly)

**Compiled Assets:**
- `admin/build/admin.js` - Compiled from `admin/src-vanilla/`
- `assets/css/frontend.css` - Compiled from `assets/scss/`

These files are auto-generated during the build process. Any manual edits will be overwritten on the next build.

## Build Tools Configuration

### Webpack Configuration (Admin JavaScript)

Location: `admin/webpack.config.js`

**Key features:**
- Babel transpilation (ES6+ → ES5)
- Minification with Terser
- Source map generation
- Development and production modes

### SCSS Compilation

Location: `package.json` (scripts section)

**Key features:**
- SCSS → CSS compilation using node-sass
- Automatic imports from `assets/scss/`
- Production-ready output

## Troubleshooting

### Build Errors

**"Cannot find module"**
```bash
# Reinstall dependencies
rm -rf node_modules admin/node_modules
npm install
cd admin && npm install && cd ..
```

**SCSS compilation fails**
```bash
# Ensure node-sass is installed
npm install --save-dev node-sass
npm run build:css
```

**Webpack errors**
```bash
# Reinstall admin dependencies
cd admin
rm -rf node_modules
npm install
npm run build
```

### Common Issues

1. **Changes not appearing:** Clear browser cache and rebuild assets
2. **CSS not updating:** Run `npm run build:css` from plugin root
3. **Admin panel broken:** Rebuild admin JavaScript with `cd admin && npm run build`

## Contributing

When contributing code:

1. Fork the repository
2. Create a feature branch
3. Make your changes in source files (not compiled files)
4. Build production assets
5. Test thoroughly
6. Commit both source and compiled files
7. Submit a pull request

## Support

- GitHub Issues: https://github.com/avi-ezra/comments-press-zone/issues
- Website: https://press.zone

---

**Last updated:** 2026-02-05