# Multilingual Press Zone - Admin Panel

Modern Vanilla JavaScript admin panel with Webpack 5 build system.

## Features

- **Webpack 5**: Modern build system with code splitting
- **Babel**: ES6+ transpilation for broad browser support
- **SCSS**: Advanced styling with variables and nesting
- **PostCSS**: Autoprefixer for vendor prefixes
- **Code Splitting**: Automatic vendor and common chunk splitting
- **Source Maps**: Debug-friendly development builds
- **Minification**: Optimized production builds
- **Bundle Analysis**: Analyze bundle size and composition

## Prerequisites

- Node.js >= 18.0.0
- npm >= 9.0.0

## Installation

```bash
cd admin
npm install
```

## Build Scripts

### Development Build (with watch mode)
```bash
npm run dev
```
This starts webpack in development mode with watch enabled. Changes are automatically rebuilt.

### Production Build
```bash
npm run build
```
Creates optimized, minified production build in `dist/` directory.

### Watch Mode
```bash
npm run watch
```
Same as `npm run dev` - watches for file changes and rebuilds.

### Bundle Analysis
```bash
npm run analyze
```
Generates a visual report of bundle composition in `bundle-report.html`.

### Code Quality

```bash
# Lint JavaScript
npm run lint:js

# Format code
npm run format
```

## Directory Structure

```
admin/
├── dist/                  # Built assets (auto-generated)
│   ├── css/              # Compiled CSS files
│   └── js/               # Compiled JavaScript files
├── src/                  # Source files
│   ├── components/       # JavaScript components
│   ├── utils/            # Utility functions
│   ├── styles/           # SCSS stylesheets
│   │   └── main.scss    # Main stylesheet entry
│   └── main.js          # Main JavaScript entry
├── views/                # PHP template files
├── package.json          # Dependencies and scripts
├── webpack.config.js     # Webpack configuration
├── .babelrc             # Babel configuration
└── postcss.config.js    # PostCSS configuration
```

## Build Output

### Development Mode
- **Source Maps**: Enabled for debugging
- **Minification**: Disabled
- **CSS**: Injected via style-loader
- **File names**: `[name].js`, `[name].css`

### Production Mode
- **Source Maps**: Disabled
- **Minification**: Enabled (Terser for JS, cssnano for CSS)
- **CSS**: Extracted to separate files
- **File names**: `[name].[contenthash:8].js` for cache busting
- **Console removal**: `console.log` and `debugger` statements removed

## Code Splitting

The build system automatically splits code into optimized chunks:

1. **Runtime**: Webpack runtime code
2. **Vendor**: Third-party dependencies from `node_modules`
3. **Common**: Code shared between multiple entry points
4. **Entry**: Page-specific code

### Dynamic Imports

Use dynamic imports for code splitting:

```javascript
// Lazy load a component
const { Dashboard } = await import(/* webpackChunkName: "dashboard" */ './components/Dashboard');
```

## Path Aliases

The following aliases are configured for cleaner imports:

```javascript
import Component from '@/components/Component';     // src/components/Component.js
import util from '@utils/helper';                   // src/utils/helper.js
import '@styles/custom.scss';                       // src/styles/custom.scss
```

## WordPress Externals

The following WordPress globals are marked as externals (not bundled):

- `wp.i18n` - Internationalization
- `wp.apiFetch` - API requests
- `jQuery` - jQuery library

Use them like this:

```javascript
const { __ } = wp.i18n;
const apiFetch = wp.apiFetch;
```

## Browser Support

Target browsers (configured in browserslist):
- \> 1% market share
- Last 2 versions
- Not dead
- Not IE 11

## Performance Optimization

### Bundle Size Limits
- Max entry point size: 512 KB
- Max asset size: 512 KB

If these limits are exceeded, webpack will show warnings.

### Optimization Features
- Tree shaking (removes unused code)
- Minification (Terser for JS, cssnano for CSS)
- Code splitting (vendor, common, runtime chunks)
- Deterministic module IDs (better caching)
- Content hash in filenames (cache busting)

## Enqueuing in WordPress

The built assets should be enqueued in your PHP code:

```php
wp_enqueue_script(
    'multilingual-press-zone-admin',
    plugins_url('admin/dist/js/runtime.js', dirname(__FILE__)),
    ['wp-i18n', 'wp-api-fetch'],
    '1.0.0',
    true
);

wp_enqueue_script(
    'multilingual-press-zone-admin-vendor',
    plugins_url('admin/dist/js/vendor.js', dirname(__FILE__)),
    ['multilingual-press-zone-admin'],
    '1.0.0',
    true
);

wp_enqueue_script(
    'multilingual-press-zone-admin-main',
    plugins_url('admin/dist/js/main.js', dirname(__FILE__)),
    ['multilingual-press-zone-admin-vendor'],
    '1.0.0',
    true
);

wp_enqueue_style(
    'multilingual-press-zone-admin',
    plugins_url('admin/dist/css/main.css', dirname(__FILE__)),
    [],
    '1.0.0'
);
```

## Troubleshooting

### Build fails with "Cannot find module"
```bash
rm -rf node_modules package-lock.json
npm install
```

### Old code still loading after build
Clear browser cache and hard reload (Ctrl+Shift+R or Cmd+Shift+R).

### Webpack watch not detecting changes
Check that your file system supports file watching. On some systems (WSL, Docker), you may need to use polling:

Add to `webpack.config.js`:
```javascript
watchOptions: {
    poll: 1000,
    ignored: /node_modules/
}
```

## Development Workflow

1. Start watch mode: `npm run dev`
2. Make changes to source files in `src/`
3. Webpack automatically rebuilds
4. Refresh browser to see changes
5. Before committing: `npm run build` to verify production build works

## Next Steps

Week 3 remaining tasks:
- P1-29: Component architecture
- P1-30: API client with error handling
- P1-31: State management system
- P1-32: UI components library

## Resources

- [Webpack Documentation](https://webpack.js.org/)
- [Babel Documentation](https://babeljs.io/)
- [Sass Documentation](https://sass-lang.com/)
- [PostCSS Documentation](https://postcss.org/)