npm package: @midkard/vite-plugin-wp-assetize
Description: Vite plugin to create wp php assets files.
Author: Dimenius Novus
Latest version: 1.0.1

# @dnt-theme/vite-plugin-wp-assetize

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Vite plugin that generates WordPress-compatible PHP asset files by analyzing JavaScript/TypeScript imports during the build process.

## Features

- 🔍 **Automatic Dependency Detection** - Scans your code for WordPress (`@wordpress/*`) and WooCommerce (`@woocommerce/*`) package imports
- 📦 **WordPress Integration** - Generates `.asset.php` files with proper dependency arrays and version hashes
- 🧩 **Block Development Support** - Special handling for WordPress blocks with `block.json` and `render.php`
- 🎯 **SHA-1 Version Hashing** - Automatic cache-busting with content-based hashes
- ⚡ **Vite Native** - Built specifically for Vite with ES Modules support

## Installation

```bash
npm install @dnt-theme/vite-plugin-wp-assetize --save-dev
# or
pnpm add -D @dnt-theme/vite-plugin-wp-assetize
# or
yarn add -D @dnt-theme/vite-plugin-wp-assetize
```

## Usage

### Basic Configuration

```typescript
// vite.config.ts
import wpAssetize from '@dnt-theme/vite-plugin-wp-assetize'

export default {
  plugins: [
    wpAssetize.assetize(path.resolve(__dirname, 'src'))
  ]
}
```

### With WordPress Externals

Use the provided `wpExternals` list for common WordPress package externalization:

```typescript
import wpAssetize, { wpExternals } from '@dnt-theme/vite-plugin-wp-assetize'

export default {
  plugins: [
    wpAssetize.assetize(path.resolve(__dirname, 'src'))
  ],
  build: {
    rollupOptions: {
      external: wpExternals
    }
  }
}
```

## How It Works

The plugin analyzes your source files during the Vite build process:

1. **Import Scanning** - Parses JS/TS/JSX/TSX files to find imports from `@wordpress/*` and `@woocommerce/*` packages
2. **Dependency Mapping** - Maps imports to WordPress script handles (e.g., `@wordpress/api-fetch` → `wp-api-fetch`)
3. **Asset File Generation** - Creates `.asset.php` files containing:
   - `dependencies` - Array of WordPress script handles
   - `version` - SHA-1 hash of the file content (first 20 chars)

### Generated Asset File Example

```php
<?php return ["dependencies" => ["wp-element","wp-api-fetch"], "version" => "a1b2c3d4e5f6g7h8i9j0"];
```

## WordPress Block Development

When the plugin detects an entry point in `src/blocks/{block-name}/`, it automatically:

- Generates `blocks/{block-name}/asset.php`
- Copies `block.json` to the output directory
- Copies `render.php` to the output directory

### Block Structure Example

```
src/
└── blocks/
    └── my-block/
        ├── index.tsx      # Entry point
        ├── block.json     # Block metadata
        └── render.php     # Server-side render
```

## Supported Packages

### WordPress Packages (`@wordpress/*`)

All WordPress packages are supported with automatic mapping to their global variables:

- `@wordpress/element` → `wp.element` (handle: `wp-element`)
- `@wordpress/api-fetch` → `wp.apiFetch` (handle: `wp-api-fetch`)
- `@wordpress/components` → `wp.components` (handle: `wp-components`)
- And many more...

### WooCommerce Packages (`@woocommerce/*`)

Full support for WooCommerce packages:

- `@woocommerce/components` → `wc.components` (handle: `wc-components`)
- `@woocommerce/data` → `wc.data` (handle: `wc-store-data`)
- `@woocommerce/blocks-checkout` → `wc.blocksCheckout` (handle: `wc-blocks-checkout`)
- And more...

### Other Libraries

- `react` → `React` (handle: `react`)
- `react-dom` → `ReactDOM` (handle: `react-dom`)
- `lodash` / `lodash-es` → `lodash` (handle: `lodash`)
- `jquery` → `jQuery` (handle: `jquery`)

## API

### `assetize(srcDir: string): Plugin`

Creates the Vite plugin instance.

**Parameters:**

- `srcDir` - Source directory path to scan for imports (e.g., `'src'`)

**Returns:**

- Vite plugin instance

### `wpExternals`

A curated list of common WordPress externals for use with Rollup's `external` option.

```typescript
import { wpExternals } from '@dnt-theme/vite-plugin-wp-assetize'

// Includes:
// - @wordpress/element
// - @wordpress/core-data
// - @wordpress/data
// - @wordpress/components
// - @wordpress/block-editor
// - react, react-dom, react/jsx-runtime
// - And all WooCommerce packages
```

## WordPress Integration

In your WordPress PHP code, use the generated asset files like this:

```php
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php' );

wp_register_script(
    'my-script',
    plugins_url( 'build/index.js', __FILE__ ),
    $asset_file['dependencies'],
    $asset_file['version'],
    true
);
```

## Requirements

- Node.js 22+
- Vite 5+

## License

[MIT](LICENSE)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## Support

- Issues: [GitLab Issues](https://gitlab.dn-ms.ru/dnt-theme/vite-plugin-wp-assetize/-/issues)
- Author: [Dimenius Novus](https://dn-ms.ru)