{"id":23148200,"url":"https://github.com/mrottow/vite-wordpress","last_synced_at":"2025-07-22T14:05:27.953Z","repository":{"id":267228845,"uuid":"900598781","full_name":"mrOttoW/vite-wordpress","owner":"mrOttoW","description":"A Vite 6 configuration for block \u0026 traditional WordPress development with HMR \u0026 Vite DevServer integration \u0026 WP Interactivity API support.","archived":false,"fork":false,"pushed_at":"2024-12-26T05:40:58.000Z","size":1703,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-05T10:52:44.125Z","etag":null,"topics":["vite","vite-plugin","vitejs","wordpress","wordpress-development"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrOttoW.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-09T05:46:24.000Z","updated_at":"2025-06-18T21:13:31.000Z","dependencies_parsed_at":"2024-12-16T07:27:54.798Z","dependency_job_id":null,"html_url":"https://github.com/mrOttoW/vite-wordpress","commit_stats":null,"previous_names":["mrottow/vite-wordpress"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/mrOttoW/vite-wordpress","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrOttoW%2Fvite-wordpress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrOttoW%2Fvite-wordpress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrOttoW%2Fvite-wordpress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrOttoW%2Fvite-wordpress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrOttoW","download_url":"https://codeload.github.com/mrOttoW/vite-wordpress/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrOttoW%2Fvite-wordpress/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266507366,"owners_count":23940055,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["vite","vite-plugin","vitejs","wordpress","wordpress-development"],"created_at":"2024-12-17T17:09:40.453Z","updated_at":"2025-07-22T14:05:27.943Z","avatar_url":"https://github.com/mrOttoW.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://vitejs.dev/\"\u003e\n    \u003cimg width=\"200\" height=\"200\" hspace=\"10\" src=\"https://raw.githubusercontent.com/mrOttoW/vite-wordpress/ef6f4b84aa9da549e9908d8c21513d53dfe020bc/vite-logo.svg\" alt=\"vite logo\" /\u003e\n  \u003c/a\u003e\n  \u003ch1\u003e⚡️Vite 6 Config for Traditional WordPress Development\u003c/h1\u003e\n  \u003cp\u003e\nProviding an opinionated \u0026 \"Go To\" Vite configuration for building WordPress blocks \u0026 traditional WordPress development with WP Interactivity API support and HMR \u0026 Vite DevServer integration.\n\u003c/p\u003e\n  \u003cimg alt=\"NPM Downloads\" src=\"https://img.shields.io/npm/d18m/vite-wordpress\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/v/release/mrOttoW/vite-wordpress\" alt=\"GitHub release\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/dependency-version/vite-wordpress/peer/vite\" alt=\"npm peer dependency version\" /\u003e\n  \u003cimg alt=\"Node Current\" src=\"https://img.shields.io/node/v/vite-wordpress\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/last-commit/mrOttoW/vite-wordpress\" alt=\"GitHub last commit\"/\u003e\n  \u003cimg src=\"https://img.shields.io/npm/l/vite-wordpress\" alt=\"licence\" /\u003e\n\u003c/div\u003e\n\n## Features\n\n- Compiles and outputs JavaScript, CSS, and other assets directly into WordPress-ready formats.\n- Glob options to configure input paths.\n- Complete Vite development server \u0026 HMR (Hot Module Replacement) integration.\n- JSX/React code supported in `.js` files instead of using `.jsx`.\n- Support for WP Interactivity API blocks.\n  - Scripts with `@wordpress/interactivity` imports will be compiled as modules.\n  - The Vite development server will enable HMR for WP Interactivity API blocks.\n- Automatically externalizes WordPress globals like `wp` and libraries like `React` to reduce bundle sizes.\n  - Includes a preset of globals for wp dependencies and other common libraries in WordPress like react, react-dom, jquery, lodash etc.. (see src/globals.ts) with option to add additional globals.\n  - Uses `rollup-plugin-external-globals` plugin under the hood to ensure that globals are not imported for non-modules in compiled files but are instead defined externally.\n- Paths in (block).json files like `file:./index.js` will be resolved with hashed file names when `manifest` is enabled.\n- Automatically reloads PHP files during development.\n- Preserved folder structure in the output directory.\n- Use vite `development` mode to compile unminified with sourcemaps (sourcemaps are also included during `serve` command)\n- All configurations can be overridden using Vite's default configuration options.\n\n## Installation\n\nInstall the plugin via npm:\n\n```bash\nnpm install --save-dev vite-wordpress\n```\n\nor yarn\n\n```bash\nyarn add -D vite-wordpress\n```\n\n## Usage\n\n### Basic Setup\n\nAdd the plugin to your `vite.config.js` (no other Vite configurations needed):\n\n```javascript\nimport { ViteWordPress } from 'vite-wordpress';\n\nexport default {\n  plugins: [\n    ViteWordPress({\n      base: '/wp-content/plugins/my-plugin',\n      input: ['main.js'],\n    }),\n  ],\n};\n```\n\nSee all options \u003ca href=\"#options\"\u003ehere\u003c/a\u003e.\n\n## Example Project Structure\n\n```\nproject-root/\n├── src/\n│   ├── js\n│   │   └── main.js\n│   ├── css\n│   │   └── main.pcss\n│   └── blocks\n│       └── example-block\n│           ├─ style.pcss (imported into index.js)\n│           └─ index.js\n├── build/\n│   ├── js\n│   │   └── main.js\n│   ├── css\n│   │   └── main.css\n│   └── blocks\n│       └── example-block\n│           ├─ index.css\n│           └─ index.js\n├── vite.config.js\n└── package.json\n```\n\nVite config for the given example.\n\n```javascript\nimport { ViteWordPress } from 'vite-wordpress';\n\nexport default {\n  plugins: [\n    ViteWordPress({\n      base: '/wp-content/plugins/my-plugin',\n      input: ['js/*.js', 'css/*.pcss', 'blocks/*/*.js'],\n    }),\n  ],\n};\n```\n\nProject examples (WordPress plugins) can be found here:\n\n- Dynamic block: https://github.com/mrOttoW/vite-wordpress-plugin-block-example\n- WP Interactivity API block: https://github.com/mrOttoW/vite-wordpress-plugin-interactivity-block-example\n\n## Dev Server \u0026 HMR\n\n\u003cimg hspace=\"10\" src=\"https://raw.githubusercontent.com/mrOttoW/vite-wordpress/refs/heads/main/vite-hmr.gif\" alt=\"vite hmr\" style=\"border-radius: 10px;\" /\u003e\n\nInstall the `vite-wordpress-php` composer package.\n\n```bash\ncomposer require mrottow/vite-wordpress\n```\n\nThe `vite-wordpress` node package can be used in hand with the \u003ca href=\"https://github.com/mrOttoW/vite-wordpress-php\"\u003evite-wordpress-php\u003c/a\u003e composer package to\nintegrate Vite's development server and HMR into WordPress, as well as manage the manifest file (if enabled), which can be used by simply adding\nthe following into your plugin or theme.\n\n```php\n(new ViteWordPress\\DevServer())-\u003eregister();\n```\n\nAside to the integration, `vite-wordpress` exposes the plugin's configurations \u0026 a map of the latest build on the development server which is used by `vite-wordpress-php`\nto automatically detect all enqueued scripts and template paths from the project through hooks and resolves these to source files served by the development\nserver. It updates script tags from these specific scripts to use as modules and injects Vite's client to enable HMR (Hot Module Replacement).\n\nIt's compatible with a traditional setup with `vite-wordpress` without the need for a manifest (non-hashed) but also works well with a manifest.\n\nYou can read more about this on the \u003ca href=\"https://github.com/mrOttoW/vite-wordpress-php#readme\"\u003erepository's README\u003c/a\u003e page.\n\n## Asset File \u0026 Cache busting\n\nUse https://github.com/mrOttoW/vite-php-asset-file to include a hash, manage dependencies identified in the code, and handle imported CSS assets.\n\nExample project structure:\n\n```\nproject-root/\n├── src/\n│    ├─ custom-slider.pcss (imported into custom-slider.js)\n│    └─ custom-slider.js\n├── build/\n│    ├─ custom-slider.css\n│    ├─ custom-slider.js\n│    └─ custom-slider.asset.php\n...\n```\n\nExample of registering and enqueueing the asset file based on the given example within a theme.\n\n```php\n\n  $asset_file = require get_stylesheet_directory() . 'build/custom-slider.asset.php';\n\n  wp_register_script(\n    'my-custom-slider',\n    get_stylesheet_directory_uri() . 'build/custom-slider.js',\n    $asset_file['dependencies'],\n    $asset_file['version'],\n  );\n\n  foreach ( $asset_file['assets'] as $css_handle =\u003e $css_path ) {\n    wp_register_style(\n      $css_handle,\n      get_stylesheet_directory_uri() . \"build/{$css_path}\",\n      [],\n      $asset_file['version']\n    );\n  }\n\n  wp_enqueue_script('my-custom-slider')\n\n```\n\nAlternatively you can use the manifest and hashed file names for cache busting.\n\n## Manifest \u0026 Hash\n\nThe `manifest` enabler in the plugin will add the manifest file but also add hash to file names.\n\n```diff\nexport default {\n  plugins: [\n    ViteWordPress({\n        base: '/wp-content/plugins/my-plugin',\n        input: ['main.js'],\n+       manifest: true\n    }),\n  ],\n};\n\n```\n\nYou can use the Manifest Resolver from \u003ca href=\"https://github.com/mrOttoW/vite-wordpress-php#manifest-resolver\"\u003evite-wordpress-php\u003c/a\u003e to handle reading and accessing the Vite manifest file and additionally integrates it into the dev server.\n\n#### Example using the facade:\n\n```php\n\nuse ViteWordPress\\DevServer;\nuse ViteWordPress\\Manifest;\n\n$manifest = Manifest::create( 'absolute/path/to/manifest.json' ); // Also works with a PHP manifest file.\n\n// When using the dev server you need to include the manifest.\n( new DevServer( $manifest ) )-\u003eregister();\n\n// Enqueue scripts hook.\nadd_action( 'wp_enqueue_scripts', function () {\n\t$file_name = Manifest::get_file( 'app.js' );\n\n\twp_enqueue_script( 'my-app', get_stylesheet_directory() . \"build/{$file_name}\" );\n} );\n```\n\n### block.json\n\n`vite-wordpress` ensures that JSON files are emitted as assets instead of being converted into JavaScript files.\nThis keeps the `block.json` file readable and compatible with functions like `register_block_type()` in WordPress.\nIt is also crucial for the `block.json` file to retain its original name to remain accessible in WordPress,\npreventing it from being hashed when the `manifest` option is enabled.\n\nAdditionally, all URLs found in the `block.json` file will automatically be resolved to their corresponding hashed filenames.\n\nFor example the following `block.json` configurations:\n\n```json\n{\n  \"editorScript\": \"file:./index.js\",\n  \"editorStyle\": \"file:./index.css\",\n  \"style\": \"file:./style.css\",\n  \"render\": \"file:./render.php\",\n  \"viewScript\": \"file:./view.js\"\n}\n```\n\nWill include the hashed file names after compilation.\n\n```json\n{\n  \"editorScript\": \"file:./index.BFKxLtHH.js\",\n  \"editorStyle\": \"file:./index.BvpkZCOy.css\",\n  \"style\": \"file:./style.WLomad7Q.css\",\n  \"render\": \"file:./render.Aelou6by.php\",\n  \"viewScript\": \"file:./view.BQK8SocZ.js\"\n}\n```\n\n### manifest.php\n\nThe following plugin also allows you to generate a PHP manifest file that is compatible with the DevServer:\n\nhttps://github.com/mrOttoW/vite-php-manifest\n\n## WP Interactivity API\n\n`vite-wordpress` also provides out-of-the-box support for development with the\n\u003ca href=\"https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/\" target=\"_blank\"\u003eWP Interactivity API\u003c/a\u003e.\nAny scripts that import `@wordpress/interactivity` (e.g., view scripts) will be compiled as modules, allowing them to\nbe resolved by the \u003ca href=\"https://make.wordpress.org/core/2023/11/21/exploration-to-support-modules-and-import-maps/\" target=\"_blank\"\u003eWordPress import map\u003c/a\u003e.\n\nAdditionally, `vite-wordpress` ensures that the development server ignores these static imports, allowing them to be resolved by WordPress rather than by Vite.\nThis will prevent errors from Vite's internal `vite:import-analysis` plugin failing the resolve import.\n\nA project example (WordPress plugin) can be found here:\nhttps://github.com/mrOttoW/vite-wordpress-plugin-interactivity-block-example\n\n## Asset Callers\n\nLet's say you have the following project:\n\n```\nproject-root/\n├── classes/\n│   ├── Plugin.php\n│   ├── Helpers.php\n│   ├── Fonts.php\n│   └── Integration.php\n├── templates/\n│   ├── table.php\n│   ├── button.php\n│   └── card.php\n├── src/\n│   ├── js\n│   │   └── main.js\n│   ├── css\n│   │   └── main.pcss\n│   └── assets/\n│       ├── svg/\n│       │   ├── star.svg\n│       │   └── coffee.svg\n│       ├── images/\n│       │   ├── background.png\n│       │   └── logo.png\n│       └── fonts/\n│           └── arial.woff\n├── vite.config.js\n....\n```\n\nAnd you have various PHP functions that retrieve asset files from the `assets` folder, used across different template files or classes like:\n\n```php\n\u003c?php\n  echo Helpers::get_image('logo.png');\n  echo Helpers::get_svg('coffee.svg');\n  echo $fonts-\u003eget_font('arial.woff')\n```\n\nYou can use the following plugin to identify and emit assets referenced in PHP functions or callers during the build process. This ensures that Vite compiles only the assets used throughout the project:\n\nhttps://github.com/mrOttoW/vite-php-asset-callers\n\nThe plugin parses PHP code to locate embedded assets, such as image files, SVGs, fonts, or other resources. It then processes and emits these assets for compilation in the final bundle.\n\n## Options\n\n### `outDir`\n\n_Type:_ `string`\n\n_Default:_ `'build'`\n\nDirectory for output files.\n\n---\n\n### `srcDir`\n\n_Type:_ `string`\n\n_Default:_ `'src'`\n\nDirectory for source files.\n\n---\n\n### `base`\n\n_Type:_ `string`\n\n_Default:_ `''`\n\n_Example:_ `'/wp-content/themes/my-theme'`\n\nSets the base public path for generating URLs for assets in CSS/JS. If set, it will be appended with the `outDir` during the `build` command (e.g., `/wp-content/themes/my-theme/{outDir}`).\n\nThis is also used to link source files to build files during development.\n\n---\n\n### `input`\n\n_Type:_ `string[]`\n\n_Default:_ `[]`\n\nList of input files relative to `srcDir` with glob options.\n\n---\n\n### `css`\n\n_Type:_ `string`\n\n_Default:_ `'pcss'`\n\nCSS extension used for uncompiled files.\n\n---\n\n### `manifest`\n\n_Type:_ `boolean | string`\n\n_Default:_ `false`\n\nGenerate a manifest file. Accepts `true`, `false`, or a custom path (this will also add a hash to all compiled files).\n\n---\n\n### `preserveDirs`\n\n_Type:_ `boolean`\n\n_Default:_ `true`\n\nPreserve folder structure in the output. If set to `false`, all files are flattened into a single directory.\n\n---\n\n### `globals`\n\n_Type:_ `object`\n\n_Default:_ `{}`\n\nMaps module names to global variables to mark them as external dependencies (in addition to preset globals).\n\n---\n\n### `alias`\n\n_Type:_ `object`\n\n_Default:_ `{}`\n\nDefine path aliases.\n\n---\n\n### `target`\n\n_Type:_ `string | string[] | false`\n\n_Default:_ `'es2017'`\n\nEsbuild target.\n\n---\n\n### `wrapper`\n\n_Type:_ `boolean`\n\n_Default:_ `true`\n\nEnable or disable code wrappers for JavaScript chunks.\n\n---\n\n### `banner`\n\n_Type:_ `string | function`\n\n_Default:_ `document.addEventListener('DOMContentLoaded', () =\u003e {'use strict';`\n\nCode wrapper banner to prepend to output JS files.\n\n---\n\n### `footer`\n\n_Type:_ `string | function`\n\n_Default:_ `});`\n\nCode wrapper footer to append to output JS files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrottow%2Fvite-wordpress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrottow%2Fvite-wordpress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrottow%2Fvite-wordpress/lists"}