@kcroyweb/vite-plugin-wp-helper 0.1.0

package/LICENSE.md

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 KC Roy Web Services
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @kcroyweb/vite-plugin-wp-helper
+
+[![npm version](https://img.shields.io/npm/v/@kcroyweb/vite-plugin-wp-helper.svg)](https://www.npmjs.com/package/@kcroyweb/vite-plugin-wp-helper)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Coverage](https://git.kcroywebservices.com/packages/vite-plugin-wp-helper/badges/main/coverage.svg)](https://git.kcroywebservices.com/packages/vite-plugin-wp-helper/-/commits/main)
+
+Vite plugin to make WordPress block development possible with a regular JS/TS setup within vite.
+
+## Installation
+
+You can install the package using npm, pnpm, or yarn:
+
+```bash
+# npm
+npm install @kcroyweb/vite-plugin-wp-helper --save-dev
+
+# pnpm
+pnpm add -D @kcroyweb/vite-plugin-wp-helper
+
+# yarn
+yarn add @kcroyweb/vite-plugin-wp-helper --dev
+```
+
+## Usage
+
+Add the plugin to your `vite.config.js` or `vite.config.ts` file:
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite';
+import wpHelper from '@kcroyweb/vite-plugin-wp-helper';
+
+export default defineConfig({
+  plugins: [
+    wpHelper({
+      srcBlockDir: 'src/blocks',
+    }),
+  ],
+});
+```
+
+## How it Works
+
+This plugin is designed to simplify the build process for WordPress blocks within a Vite environment. It automates several tasks that are typically handled by `@wordpress/scripts`.
+
+During the build process (`vite build`), the plugin will:
+
+1.  Scan the `srcBlockDir` directory for any `block.json` files.
+2.  For each `block.json` found, it will build the corresponding `index.js`/`ts`, `editor.js`/`ts`, and `view.js`/`ts` entry points using Vite.
+3.  It automatically handles externalizing WordPress dependencies (like `@wordpress/blocks`, `react`, etc.) and maps them to the correct `wp` global variables.
+4.  It generates a `.asset.php` file for each JavaScript entry point, containing the dependency list and a version hash, which is required for enqueuing scripts in WordPress.
+5.  It processes `style.css` and `editor.css` files with PostCSS and places the output alongside the block's other assets.
+6.  The final compiled block assets and the updated `block.json` file are placed in the output directory.
+
+## Options
+
+### `srcBlockDir`
+
+-   **Type:** `string`
+-   **Required:** `true`
+
+The source directory where your WordPress blocks are located. The plugin will recursively search this directory for `block.json` files.
+
+### `outDir`
+
+-   **Type:** `string`
+-   **Default:** `'dist'`
+
+The output directory where the compiled block assets will be placed.
+
+## License
+
+This project is licensed under the ISC License.

package/dist/wp-helper.d.ts

@@ -0,0 +1,7 @@
+export default function wpHelper(options: {
+    srcBlockDir: string;
+    outDir?: string;
+}): {
+    name: string;
+    buildStart(): Promise<void>;
+};

package/dist/wp-helper.js

@@ -0,0 +1,180 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/wp-helper.ts
+var wp_helper_exports = {};
+__export(wp_helper_exports, {
+  default: () => wpHelper
+});
+module.exports = __toCommonJS(wp_helper_exports);
+var import_node_path = require("path");
+var import_node_fs = require("fs");
+var import_vite = require("vite");
+var import_postcss = __toESM(require("postcss"));
+var import_postcss_load_config = __toESM(require("postcss-load-config"));
+function wpHelper(options) {
+  if (!options.srcBlockDir) {
+    throw new Error("[vite-plugin-wp-helper] srcBlockDir is required");
+  }
+  const wpHandles = {
+    react: "wp-react",
+    "react-dom": "wp-react-dom",
+    "@wordpress/blocks": "wp-blocks",
+    "@wordpress/element": "wp-element",
+    "@wordpress/components": "wp-components",
+    "@wordpress/data": "wp-data",
+    "@wordpress/block-editor": "wp-block-editor",
+    "@wordpress/i18n": "wp-i18n",
+    "@wordpress/api-fetch": "wp-api-fetch",
+    "@wordpress/compose": "wp-compose",
+    "@wordpress/hooks": "wp-hooks"
+  };
+  const outDir = options.outDir ? (0, import_node_path.resolve)(options.outDir) : (0, import_node_path.resolve)("dist");
+  const findBlockJsonFiles = (dir, list = []) => {
+    if (!(0, import_node_fs.existsSync)(dir)) return list;
+    for (const file of (0, import_node_fs.readdirSync)(dir)) {
+      const full = (0, import_node_path.join)(dir, file);
+      const stat = (0, import_node_fs.statSync)(full);
+      if (stat.isDirectory()) findBlockJsonFiles(full, list);
+      else if (file === "block.json") list.push(full);
+    }
+    return list;
+  };
+  const extractDependencies = (chunk) => {
+    const deps = /* @__PURE__ */ new Set();
+    const scan = (v) => {
+      for (const [pkg, handle] of Object.entries(wpHandles)) {
+        if (v.includes(pkg)) deps.add(handle);
+      }
+    };
+    if (chunk.imports) chunk.imports.forEach(scan);
+    if (chunk.code) scan(chunk.code);
+    if (chunk.modules) Object.keys(chunk.modules).forEach(scan);
+    return [...deps].sort();
+  };
+  const generateAssetPhp = (deps) => `<?php
+return array(
+  'dependencies' => array(${deps.map((d) => `'${d}'`).join(", ")}),
+  'version' => '${Date.now()}',
+);
+`;
+  async function buildCss(input, output) {
+    const css = (0, import_node_fs.readFileSync)(input, "utf8");
+    const { plugins, options: options2 } = await (0, import_postcss_load_config.default)({}, process.cwd());
+    const result = await (0, import_postcss.default)(plugins).process(css, {
+      ...options2,
+      from: input,
+      to: output
+    });
+    (0, import_node_fs.writeFileSync)(output, result.css);
+    if (result.map) {
+      (0, import_node_fs.writeFileSync)(output + ".map", result.map.toString());
+    }
+  }
+  return {
+    name: "vite-plugin-wp-helper",
+    async buildStart() {
+      const blockJsonFiles = findBlockJsonFiles(options.srcBlockDir);
+      for (const blockJsonPath of blockJsonFiles) {
+        const blockDir = (0, import_node_path.dirname)(blockJsonPath);
+        const blockName = (0, import_node_path.basename)(blockDir);
+        const blockOutDir = (0, import_node_path.join)(outDir, "blocks", blockName);
+        (0, import_node_fs.mkdirSync)(blockOutDir, { recursive: true });
+        const rawBlockJson = JSON.parse((0, import_node_fs.readFileSync)(blockJsonPath, "utf8"));
+        const jsEntries = {
+          index: ["index.ts", "index.js"],
+          editor: ["editor.ts", "editor.js"],
+          view: ["view.ts", "view.js"]
+        };
+        for (const [key, files] of Object.entries(jsEntries)) {
+          const entry = files.map((f) => (0, import_node_path.join)(blockDir, f)).find((p) => (0, import_node_fs.existsSync)(p));
+          if (!entry) continue;
+          const outFile = `${key}.js`;
+          const result = await (0, import_vite.build)({
+            configFile: false,
+            optimizeDeps: { exclude: Object.keys(wpHandles) },
+            build: {
+              minify: false,
+              outDir: blockOutDir,
+              emptyOutDir: false,
+              rollupOptions: {
+                input: entry,
+                external: Object.keys(wpHandles),
+                output: {
+                  format: "iife",
+                  entryFileNames: outFile,
+                  globals: {
+                    react: "React",
+                    "react-dom": "ReactDOM",
+                    "@wordpress/blocks": "wp.blocks",
+                    "@wordpress/block-editor": "wp.blockEditor",
+                    "@wordpress/element": "wp.element",
+                    "@wordpress/i18n": "wp.i18n",
+                    "@wordpress/components": "wp.components",
+                    "@wordpress/data": "wp.data",
+                    "@wordpress/api-fetch": "wp.apiFetch",
+                    "@wordpress/compose": "wp.compose",
+                    "@wordpress/hooks": "wp.hooks"
+                  }
+                }
+              }
+            }
+          });
+          const chunk = result.output?.find((c) => c.isEntry);
+          if (chunk) {
+            const deps = extractDependencies(chunk);
+            (0, import_node_fs.writeFileSync)(
+              (0, import_node_path.join)(blockOutDir, outFile.replace(".js", ".asset.php")),
+              generateAssetPhp(deps)
+            );
+          }
+          if (key === "index") rawBlockJson.editorScript = `file:./${outFile}`;
+          if (key === "view") rawBlockJson.viewScript = `file:./${outFile}`;
+        }
+        const cssFiles = {
+          style: (0, import_node_path.join)(blockDir, "style.css"),
+          editorStyle: (0, import_node_path.join)(blockDir, "editor.css")
+        };
+        if ((0, import_node_fs.existsSync)(cssFiles.style)) {
+          await buildCss(cssFiles.style, (0, import_node_path.join)(blockOutDir, "style.css"));
+          rawBlockJson.viewStyle = "file:./style.css";
+        }
+        if ((0, import_node_fs.existsSync)(cssFiles.editorStyle)) {
+          await buildCss(cssFiles.editorStyle, (0, import_node_path.join)(blockOutDir, "editor.css"));
+          rawBlockJson.editorStyle = "file:./editor.css";
+        }
+        (0, import_node_fs.writeFileSync)(
+          (0, import_node_path.join)(blockOutDir, "block.json"),
+          JSON.stringify(rawBlockJson, null, 2)
+        );
+        console.log(`[wp-helper] Built block: ${blockName}`);
+      }
+    }
+  };
+}

package/dist/wp-helper.mjs

@@ -0,0 +1,156 @@
+// src/wp-helper.ts
+import { resolve, dirname, join, basename } from "path";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  statSync
+} from "fs";
+import { build as viteBuild } from "vite";
+import postcss from "postcss";
+import loadPostcssConfig from "postcss-load-config";
+function wpHelper(options) {
+  if (!options.srcBlockDir) {
+    throw new Error("[vite-plugin-wp-helper] srcBlockDir is required");
+  }
+  const wpHandles = {
+    react: "wp-react",
+    "react-dom": "wp-react-dom",
+    "@wordpress/blocks": "wp-blocks",
+    "@wordpress/element": "wp-element",
+    "@wordpress/components": "wp-components",
+    "@wordpress/data": "wp-data",
+    "@wordpress/block-editor": "wp-block-editor",
+    "@wordpress/i18n": "wp-i18n",
+    "@wordpress/api-fetch": "wp-api-fetch",
+    "@wordpress/compose": "wp-compose",
+    "@wordpress/hooks": "wp-hooks"
+  };
+  const outDir = options.outDir ? resolve(options.outDir) : resolve("dist");
+  const findBlockJsonFiles = (dir, list = []) => {
+    if (!existsSync(dir)) return list;
+    for (const file of readdirSync(dir)) {
+      const full = join(dir, file);
+      const stat = statSync(full);
+      if (stat.isDirectory()) findBlockJsonFiles(full, list);
+      else if (file === "block.json") list.push(full);
+    }
+    return list;
+  };
+  const extractDependencies = (chunk) => {
+    const deps = /* @__PURE__ */ new Set();
+    const scan = (v) => {
+      for (const [pkg, handle] of Object.entries(wpHandles)) {
+        if (v.includes(pkg)) deps.add(handle);
+      }
+    };
+    if (chunk.imports) chunk.imports.forEach(scan);
+    if (chunk.code) scan(chunk.code);
+    if (chunk.modules) Object.keys(chunk.modules).forEach(scan);
+    return [...deps].sort();
+  };
+  const generateAssetPhp = (deps) => `<?php
+return array(
+  'dependencies' => array(${deps.map((d) => `'${d}'`).join(", ")}),
+  'version' => '${Date.now()}',
+);
+`;
+  async function buildCss(input, output) {
+    const css = readFileSync(input, "utf8");
+    const { plugins, options: options2 } = await loadPostcssConfig({}, process.cwd());
+    const result = await postcss(plugins).process(css, {
+      ...options2,
+      from: input,
+      to: output
+    });
+    writeFileSync(output, result.css);
+    if (result.map) {
+      writeFileSync(output + ".map", result.map.toString());
+    }
+  }
+  return {
+    name: "vite-plugin-wp-helper",
+    async buildStart() {
+      const blockJsonFiles = findBlockJsonFiles(options.srcBlockDir);
+      for (const blockJsonPath of blockJsonFiles) {
+        const blockDir = dirname(blockJsonPath);
+        const blockName = basename(blockDir);
+        const blockOutDir = join(outDir, "blocks", blockName);
+        mkdirSync(blockOutDir, { recursive: true });
+        const rawBlockJson = JSON.parse(readFileSync(blockJsonPath, "utf8"));
+        const jsEntries = {
+          index: ["index.ts", "index.js"],
+          editor: ["editor.ts", "editor.js"],
+          view: ["view.ts", "view.js"]
+        };
+        for (const [key, files] of Object.entries(jsEntries)) {
+          const entry = files.map((f) => join(blockDir, f)).find((p) => existsSync(p));
+          if (!entry) continue;
+          const outFile = `${key}.js`;
+          const result = await viteBuild({
+            configFile: false,
+            optimizeDeps: { exclude: Object.keys(wpHandles) },
+            build: {
+              minify: false,
+              outDir: blockOutDir,
+              emptyOutDir: false,
+              rollupOptions: {
+                input: entry,
+                external: Object.keys(wpHandles),
+                output: {
+                  format: "iife",
+                  entryFileNames: outFile,
+                  globals: {
+                    react: "React",
+                    "react-dom": "ReactDOM",
+                    "@wordpress/blocks": "wp.blocks",
+                    "@wordpress/block-editor": "wp.blockEditor",
+                    "@wordpress/element": "wp.element",
+                    "@wordpress/i18n": "wp.i18n",
+                    "@wordpress/components": "wp.components",
+                    "@wordpress/data": "wp.data",
+                    "@wordpress/api-fetch": "wp.apiFetch",
+                    "@wordpress/compose": "wp.compose",
+                    "@wordpress/hooks": "wp.hooks"
+                  }
+                }
+              }
+            }
+          });
+          const chunk = result.output?.find((c) => c.isEntry);
+          if (chunk) {
+            const deps = extractDependencies(chunk);
+            writeFileSync(
+              join(blockOutDir, outFile.replace(".js", ".asset.php")),
+              generateAssetPhp(deps)
+            );
+          }
+          if (key === "index") rawBlockJson.editorScript = `file:./${outFile}`;
+          if (key === "view") rawBlockJson.viewScript = `file:./${outFile}`;
+        }
+        const cssFiles = {
+          style: join(blockDir, "style.css"),
+          editorStyle: join(blockDir, "editor.css")
+        };
+        if (existsSync(cssFiles.style)) {
+          await buildCss(cssFiles.style, join(blockOutDir, "style.css"));
+          rawBlockJson.viewStyle = "file:./style.css";
+        }
+        if (existsSync(cssFiles.editorStyle)) {
+          await buildCss(cssFiles.editorStyle, join(blockOutDir, "editor.css"));
+          rawBlockJson.editorStyle = "file:./editor.css";
+        }
+        writeFileSync(
+          join(blockOutDir, "block.json"),
+          JSON.stringify(rawBlockJson, null, 2)
+        );
+        console.log(`[wp-helper] Built block: ${blockName}`);
+      }
+    }
+  };
+}
+export {
+  wpHelper as default
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kcroyweb/vite-plugin-wp-helper",
+  "version": "0.1.0",
+  "description": "Vite plugin to make WordPress block development possible with a regular JS/TS setup within vite.",
+  "main": "dist/wp-helper.js",
+  "types": "dist/wp-helper.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/wp-helper.ts --format cjs,esm --external postcss --external postcss-load-config --external vite && tsc --emitDeclarationOnly --declaration --declarationDir dist --project tsconfig.json",
+    "test": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "vite",
+    "wordpress",
+    "vite-plugin"
+  ],
+  "author": "",
+  "license": "ISC",
+  "homepage": "https://git.kcroywebservices.com/packages/vite-plugin-wp-helper#readme",
+  "repository": {
+    "type": "git",
+    "url": "git@git.kcroywebservices.com:packages/vite-plugin-wp-helper.git"
+  },
+  "bugs": {
+    "url": "https://git.kcroywebservices.com/packages/vite-plugin-wp-helper/-/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0"
+  },
+  "packageManager": "pnpm@10.28.1",
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "@vitest/coverage-v8": "^4.0.18",
+    "jsdom": "^27.4.0",
+    "postcss": "^8.5.6",
+    "postcss-load-config": "^6.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  }
+}