Download the PHP package aslamhus/wordpress-hmr without Composer
On this page you can find all versions of the php package aslamhus/wordpress-hmr. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download aslamhus/wordpress-hmr
More information about aslamhus/wordpress-hmr
Files in aslamhus/wordpress-hmr
Package wordpress-hmr
Short Description HMR setup with webpack and wp-scripts for wordpress development and production
License MIT
Informations about the package wordpress-hmr
Wordpress Development setup with HMR and WP-Scripts
Introduction
This is an experimental package which allows you to develop wordpress themes with Webpack
and hot module replacement (HMR). It uses the wp-scripts
package in tandem with a custom enqueuing algorithm to enqueue assets in your theme.
Defining and enqueing assets is as simple as managing a single assets.json
file. This file contains the configuration for your assets, including the path to your scripts and styles, the hooks where they should be enqueued, and any conditions for enqueuing them.
Disclaimer
Currently, this package only supports HMR for a single entry point per page. This means that if you have multiple entry points on a single page, only the first entry point will be hot reloaded. This is a limitation of Webpack
and is not something that can be easily fixed.
Recommendations
Because of the entry point limitation, I recommend packaging your scripts into an editor and a screen script (this is also how Wordpress' wp-scripts
operates). You could also package your scripts into a single entry point and use dynamic imports to load your scripts on demand.
Potential Solutions to the Entry Point Limitation
- Use dynamic imports to load your scripts on demand.
- Package your scripts into an editor and a screen script.
- Add a script when the development server is started to combine all scripts into a single entry point.
- try creating multiple instances of the development server for each hook.
Build Process
This package is acts as a conditional enqueuing tool for your theme. While HMR may not be possible for multiple entry points, the build process still works seamlessly with multiple entry points and conditional enqueueing. You can define your assets in the assets.json
file and run npm run build
to generate the necessary asset files. Please see the Define your own assets for your theme section below for more information.
Why not just use wp-scripts
?
wp-scripts
is a great package for managing assets in your theme, but it lacks the ability to hot reload styles and scripts. While you can leverage hot module replacement in block development, it is not currently possible to do so for theme development. This package combines the power of wp-scripts
to manage asset dependencies with a dynamic enqueing algorithm to provide hot module replacement for your theme development.
Example
How does it work?
This package uses the assets you define in the assets.json
file to generate the necessary webpack configuration to build your assets. In development, each asset is enqueued dynamically using a path to a proxy development server. When you make changes to your assets, webpack will provide hot updates without requiring a reload (unless you change javascript). In production, the assets are statically enqueued with the correct path to your theme directory in an efficient and Wordpress compliant manner.
Styles
Styles are not enqueued separately with the wp_enqueue_style hook, but rather as imported dependencies in your javascript files. This allows us to use HMR for styles as well.
Conditional enqueuing
In the assets.json file you can specify conditions for enqueuing scripts. For example, you can specify that a script should only be enqueued on a specific page template or in the block editor. Conditional enqueuing can get complicated, so let's break it down with examples.
Example 1: Enqueue a script only on the block editor
In this example, we only want to enqueue a script in the block editor. We set the path to the script file as well as the extension. We don't need to specify a condition for this script, as it will be enqueued in the block editor by default.
Example 2: Enqueue a script only on the front end
Same as above, but we want to enqueue a script only on the front end. We use the wp_enqueue_scripts
hook to enqueue the script.
Example 3: Enqueue a script only on a specific page template
In this example, we only want to enqueue a script on a specific page template. We use the get_page_template_slug
function to get the page template slug and compare it to our custom template slug.
Example 4: Use a conditional argument that takes the result of a function as an argument
You can use a function as an argument by declaring the type in an array, followed by the function name, and then a list of optional arguments.
In this example, we only want to enqueue an asset on the about page. We need the id value of the current page to use the get_the_title
method. We can use the get_the_id
function to get the id of the current page.
This will evaluate to get_the_title(get_the_id()) === 'about'
.
Requirements
- Node.js
- MAMP / XAMPP / WAMP
Pre Installation
Setup your apache server
Example: MAMP
Create a local domain for your wordpress site. For example localhost.mysite
where
the document root is the public folder of your wordpress site project-root/public
-
Add the following virtual host configuration for your apache server (MAMP)
- Add the following to your
hosts
file (sudo nano /etc/hosts)
Install
Once you have completed the pre-installation instructions above, you are ready to install the package and its dependencies.
-
Install the package in the root directory of your project
-
Run the installer script. You can find installer.php file in the package's root directory (vendor/aslamhus/wordpress-hmr/installer.php). Move this file to the root directory of your project and run it on the command line.
The installer will create the following folders:
public
directory, with the latest version of wordpress installed. The installer will also prompt you to create a custom theme directory with the name you specify.resources
directory where all your theme files will reside. Webpack copies all the files from your resources folder to the current active theme.assets
directory where yourassets.json
file and css / scss files will reside.inc
directory where theenqueue-assets.php
andfunctions.php
file will reside.js
directory where your entry points will reside.style.css
file in the root of your theme directory with the template name of your custom theme.
-
Install
npm
dependencies. dThis will install the necessary webpack packages for development with HMR enabled. -
Rename
assets.sample.json
file toassets.json
and configure it with your development settings (see pre-installation instructions above for setting up your apache server and defining a local domain for your wordpress site)For more details on the
config
object properties, see the Define your own assets for your theme section below. -
Generate
wp-scripts
asset dependencies.Before we get started with development, we need
wp-scripts
to do some setup. Run the following command to generate the necessary asset files.NOTE: Our setup leverages
wp-scripts
in order to manage asset dependencies. Each asset specified in the wepback configuration will generate it's own asset file[filename].asset.php
which defines the asset's dependencies. For more information on thewp-scripts
package, see wp-scripts.
Develop with HMR
-
Start your local server.
-
Start the proxy (development) server
After you run the following command, Wordpress' installation prompt should appear when your proxy server opens the url. Follow the instructions to install wordpress.
- Once the install is complete, activate your custom theme in your wordpress site.
That's it! Try changing the src/js/screen.js
file and see the changes reflected in your browser. By default, the package adds two scripts to your theme, screen.js
and editor.js
. Each of these scripts is defined in the assets.json
file with conditions to enqueue them in the public facing area of your wordpress site nd editor respectively. Each script imports a correspdonding css file in your theme. Add more scripts or more css / scss files as you like. Try updating the css and see the changes reflected without a reload.
Build for production
Building is a very simple process, and leverages wp-scripts
to generate the necessary asset files. A little magic is performed by Aslamhus\WordpressHMR\EnqueueAssets
to create a static script which enqueues the assets in your theme, avoiding the performance overhead of enqueuing assets dynamically.
Troubleshooting the setup
-
If you have difficulty connecting to the database, try specifying the port number in the
DB_HOST
constant. Make sure this is the correct port based on your MAMP/XAMPP/WAMP setup. - Set your config env to development
Define your own assets for your theme
The assets.json
file is where you define your assets. It is a simple JSON file that contains the following properties:
config
- This is where you define the configuration for your assets.assets
- This is where you define your scripts. Each property of theassets
object is a hook where you want to enqueue your script. The value of each property is an array of script objects.
Config
handlePrefix
- This is the prefix for your asset handles. This is useful if you want to avoid conflicts with other plugins or themes.host
- This is the host of your local development server.port
- This is the port of your local development server.protocol
- This is the protocol of your local development server.theme
- This is the name of your theme directory, i.e. twentytwentyfour
Assets
An array of script objects. Each script object contains the following properties:
handle
- The handle of the script. This is the name that you will use to enqueue the script.hooks
- An array of hooks where the script will be enqueued.path
- The path to the script file.ext
- The file extension of the script file.condition
- a condition expression, which is an array of 3 elements. The first element is the function name, the second element is the function argument, and the third element is the expected value. If the condition is met, the script will be enqueued. For more on conditional enqueuing, see the Conditional enqueuing section below.
Adding a new asset
To add a new asset, simply add a new object to the assets
array in the assets.json
file. You will have to run npm run build
to generate the necessary asset files.
Let's add some styles to our theme which we only want to appear on our custom template, "My Custom Template".
-
Create a scss/css file in your
resources/assets/css
directory. For example,my-custom-template.scss
. -
Create a script in your
resources/js
directory that will import the scss file. For example,my-custom-template.js
. -
Add the following to your
assets.json
file: -
Run
npm run build
to generate the necessary asset files. - Restart your development server with
npm run start
. The styles should now be enqueued on the "My Custom Template" page.
You're done! Try changing the styles in your my-custom-template.scss
file and see the changes reflected in your browser only on pages that use the "My Custom Template" page template.
For a list of condition functions that you can use, see the Wordpress Conditional Tags.
Updating the child theme
By default, the package uses twentytwentyfour as the active theme. To use a different theme, you must do the following:
-
Change the active theme in wp-admin by going to
Appearance > Themes
and activating your custom theme. - Change the theme name in the
assets.json
files. The theme name should match the name of your theme directory, i.e. twentywentfour or twentytwentyone (see wp-content/themes).
A note on block theme hooks
When enqueuing assets for block themes, you will need to use the following hooks:
enqueue_block_editor_assets
- to load only in editor view
enqueue_block_assets
- loads both on frontend and editor view
Modifying the Webpack configurations
WARNING: You can set the webpack output
option to clean
the public folder before building, however if you have not defined the public folder correctly, you may end up deleting unintended files. Please test your configuration first before enabling clean
.
clean
is set to false by default to ensure that you do not accidentally delete files.
Directory Structure
The following files are required in your theme:
assets/assets.json
- This is where you define your assets.assets/assets.php
- This is where you load the assets.json file.inc/enqueue-assets.php
- This is where you enqueue your assets.
Contributing
If you would like to contribute to this package, please feel free to submit a pull request. I would love to hear your feedback and suggestions for improvement.