DEV Community: Alex Standiford

Make Webpack Configuration Easy With wordpress/scripts

Alex Standiford — Fri, 09 Jul 2021 19:27:33 +0000

I believe the single-biggest barriers to entry for modern Javascript development are the build tools that are necessary to use it effectively. It’s all a black box, breaks with vague error messages, that ultimately lead you down a tunnel of “google and pray”. Unless you’ve spent a lot of time with Webpack, it’s hard to troubleshoot when it inevitably breaks. (and seriously, who freaking has time to learn all the idiosyncrasies of Webpack?)

But even with that, the benefits vastly outpace the drawbacks. When Javascript build tools work, they work beautifully – compiling your scripts down to the smallest size, ensuring that it works on all web browsers, and in the case of WordPress, even automatically enqueuing dependent scripts that are a part of WordPress core.

Thankfully, WordPress has its own Webpack configuration that is built specifically to make developing in WordPress easier. It includes all of the babel configurations, and build tools you need to compile WordPress-specific Javascript as effectively as possible. This amazing, time-saving, godsend utility is an NPM package, and it is called @wordpress/scripts. It’s not perfect, and you’ll still find yourself occasionally scratching your head wondering “what the hell is this error?” but, in the grand scheme of things I’ve found that I’m a lot less frustrated when using this package. It usually just works, and that feels pretty solid.

How to Set Up @wordpress/scripts

Regardless of if you’re working with a theme or a plugin, the process is the same – install the package using NPM. Go to the root directory of your plugin, or theme, and run:

npm install @wordpress/scripts –save-dev

Setting Up package.json

Once installed, you need to add some scripts to your package.json file. At minimum, you’re going to need build and start. Your JSON would look something like this:

{
  "name": "plugin_name_replace_me",
  "version": "1.0.0",
  "description": "Plugin Description Replace Me",
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
  },
  "devDependencies": {
    "@wordpress/scripts": "15.0"
  },
  "author": "",
  "license": "ISC"
}

The example above is the package.json used in the Underpin plugin boilerplate, but it would work in just about any plugin or theme. The key part is the scripts object:

"scripts": {
  "build": "wp-scripts build",
  "start": "wp-scripts start"
}

Your scripts object may have additional scripts, and that’s fine. All this does is register command line scripts that can be ran inside the directory that contains this package.json file.

Create Your Javascript File

Now that your package.json is all-set, it’s time to create your Javascript file. This file is going to be what @wordpress/scripts uses to create the actual Javascript file that the site will be used by your browser. By default,
this script file must be placed inside ./src/index.js, but this can be customized to be something else if-needed. More on that later.

Using Build and Start

For example, if you run npm run start it will actually run the start command inside the @wordpress/scripts package. Conversely, if you run npm run build, it will run the build command inside the @wordpress/scripts package. There are a handful of other useful commands, such as linters and translation compilation built into this command, but we’re not going to cover those in this post. You can see them in the @wordpress/scripts documentation.

Both build and start will compile your Javascript and your CSS/SCSS into something all web browsers can read, but each one does this a little differently.

Start

npm run start will create an un-minified version of your script, and include a map file so that you can easily debug your scripts. Without this map file, you’d get vague errors that point to the wrong file because the browser wouldn’t otherwise know where these errors are.

When start is ran, it will continue to run in the background, and automatically regenerate your scripts and styles when the files are changed. This is perfect for when you’re still building your scripts and styles, since it runs quietly in the background, and automatically regenerates everything for you.

Build

start‘s priority is to help you while you’re developing, but because of this your script files will be way bigger than you’d want them to be on your live site (we’re talking megabytes people_, megabytes!_). This is where build comes in.

npm run build will create the absolute smallest file sizes it can generate by minifying scripts, and optimizing their contents. This is ideal for when you’re ready to use these themes on a live site (production). Unlike start, this command will generate your scripts and styles one time, instead of running in the background. The scripts and styles generated by build will look garbled. With variable names minified, and everything compressed to a single line of code, so you don’t want to use this when developing. Instead, you’ll want to run this as a step in your deployment process.

Enqueuing Your Scripts

After you run either build or watch, a compiled version of your script will be located inside the build directory.
Now you have to instruct WordPress when to add this script to your site’s head tag. In WordPress this is done by
“enqueuing” the script.

Basic WordPress Enqueue Script Example

To enqueue your script, you have to first register it, and then enqueue it at the right time. If you’re using Underpin, that would look like this:

plugin_name()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => plugin_name()->js_url() . 'index.js',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Script'
        ]
] );

The example above instructs Underpin to:

Register a new script called test, where the JS URL is build/index.js. Underpin’s js_url() method defaults to the build in your plugin or theme.
Automatically enqueue this script on the front-end. This is done inside the Enqueue_Script middleware. You can learn more about how script middleware works here.

If you wanted to-do this without Underpin, it would look more like this:

wp_register_script( 'test', plugin_dir_url( __FILE__ ) . 'build/index.js' );

add_action( 'wp_enqueue_scripts', function(){
    wp_enqueue_script( 'test' );
} );

Automatically Setting Script Dependencies

A key feature of @wordpress/scripts is
the dependency-extraction-webpack-plugin. This wonderful, glorious, amazing Webpack loader will automatically detect if your script has imported any WordPress core library, and will remove it from your compiled script. This keeps your script as small as possible, and also ensures that your script doesn’t somehow clash with another plugin’s script.

The problem, however, is that by doing this, your script won’t work unless all of the these imported scripts are loaded before your script is loaded. This means, that you would have to manually enqueue every single script you imported, as well as any script those scripts imported, too. As you can imagine, this would be a nightmare to
maintain.

To work around this, dependency-extraction-webpack-plugin will automatically generate a PHP file with an array of all of the dependencies your script. This array can be passed directly to your registered script, and it will automatically enqueue all of the necessary scripts just before your script automatically.

And the best part? This happens when your script is compiled using either build or watch, and when it’s all set-up it works seamlessly. You won’t even notice that these scripts are not included in your file.

The generated file will be compiled inside your build directory along with your script. It’s just a matter of using that PHP file when you register your script.

With Underpin, that looks something like this:

plugin_name()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => plugin_name()->js_url() . 'index.js',
        'name'        => 'test',
        'description' => 'The description',
    'deps'        => plugin_name()->dir() . 'build/index.asset.php', // path to dependency file generated by webpack
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Script' // Enqueue the script on the front-end
        ]
] );

The key change is the deps argument. deps can be an array of registered script handles, or a path fo a PHP file. If the path to the asset file exists, it will automatically set the dependencies from the file.

Without Underpin, this can also be done but requires a bit of extra logic:

// Check to see if the file exists.
$deps_file = plugin_dir_path(__FILE__) . 'build/index.asset.php';

// Set default fallback to dependencies array
$deps = [];

// If the file can be found, use it to set the dependencies array.
if ( file_exists( $deps_file ) ) {
    $deps_file = require( $deps_file );
    $deps      = $file['dependencies'];
}

// Register script
wp_register_script( 'test', plugin_dir_path( __FILE__ ) . 'build/index.js', $deps );

// Enqueue the script later-on
add_action( 'wp_enqueue_scripts', function(){
    wp_enqueue_script( 'test' );
} );

How to Customize Your Webpack Configuration

@wordpress/scripts includes a default Webpack configuration, but this can be overridden with your own webpack configuration. This is done by adding a webpack.config.js file in the root directory of your plugin or theme. When this is added, @wordpress/scripts will automatically use your Webpack config instead of the one that comes with @wordpress/scripts.

You could add your 100% custom Webpack config to this file, and completely override the configuration that comes with @wordpress/scripts, but at that point, there’s not much point in using @wordpress/scripts. Instead, I find that it makes a lot more sense to extend the config that comes with @wordpress/scripts, and modify the parts you need to modify, instead. The Underpin plugin boilerplate accomplishes this like so:

/**
 * WordPress Dependencies
 */
const defaultConfig = require( '@wordpress/scripts/config/webpack.config.js' );

module.exports = {
    ...defaultConfig,
    ...{
        // Add any overrides to the default here.
    }
}

The above example uses Javascript’s spread operator to take the default Webpack configuration included in @wordpress/scripts, and override sections of the configuration with your own customized config. This allows you to change the parts you want, and still use @wordpress/scripts to its fullest potential.

Create Custom Entrypoints With @wordpress/scripts

By default, @wordpress/scripts will allow you to create a single entrypoint file – src/index.js, but what happens if you want to create multiple Javascript files? Maybe you need to have one script for an admin interface, and another for the front-end of the site. Using the method above, you can override the entry configuration of your Webpack config, and instruct @wordpress/scripts to create two files, instead.

Here is an example of the webpack.config.js file that is used in our WordPress plugin development course:

/**
 * External Dependencies
 */
const path = require( 'path' );

/**
 * WordPress Dependencies
 */
const defaultConfig = require( '@wordpress/scripts/config/webpack.config.js' );

module.exports = {
    ...defaultConfig,
    ...{
        entry: {
            admin: path.resolve( process.cwd(), 'src', 'admin.js' ),
            "beer-admin": path.resolve( process.cwd(), 'src', 'beer-admin.js' ),
            "beer-list": path.resolve( process.cwd(), 'src', 'beer-list.css' ),
        },
    }
}

Using Javascript’s spread operator, this configuration extends the default @wordpress/scripts configuration object and replace the entry configuration. Instead of creating the default index.js file, this instructs Webpack to create three files:

build/admin.js will be created from src/admin.js
build/beer-admin.js will be created from src/beer-admin.js
build/beer-list.css will be created from src/beer-list.css

From there, you would need to enqueue the styles and scripts for each item just like you did in the example above.

Conclusion

@wordpress/scripts simplifies working with Webpack, and makes it possible to create custom Gutenberg blocks, allow you to utilize core WordPress libraries like the awesome ApiFetch library. It can be extended, manipulated, and changed to suit your needs, and it can ensure that your scripts don’t conflict with other scripts. Once you get the hang of it, you’ll never want to go back to a world where you don’t have this tool at your disposal. Underpin has theme and plugin boilerplates that includes this library, and sets everything up to extend this compilation tool quickly.

Looking for more WordPress Resources?

Join WP Dev Academy’s Discord server, and become a part of a growing community of WordPress developers.

API Fetch – The WordPress Library You Didn’t Know You Needed

Alex Standiford — Sun, 04 Jul 2021 14:14:27 +0000

One of my favorite WordPress packages that nobody seems to talk about right now is @wordpress/apiFetch. This library works kind-of like your traditional fetch library, only it’s built into WordPress, plays nice with backwards compatibility, and is capable of using middleware to transform some, or all of the REST API calls that it receives.

There are many people who go fully headless with GraphQL, Gatsby and the like, but I prefer a semi-headless approach to WordPress. This allows me to use WordPress plugins to their full potential, but still make use of the REST API when I can. One of the key pieces of this approach is making extensive use of the apiFetch library.

Setting Up api-fetch

api-fetch is a built-in package that you can install just like any other NPM package, but it’s best to instead require the packaged up API Fetch library as a dependency. This will minimize conflicts with other plugins that are also using api-fetch.

To use it, you just need to add it to your list of dependencies on your registered script. If you’re using Underpin, that would look like this:

plugin_name()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
    'deps'        => [ 'wp-api-fetch', 'wp-polyfill' ],
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Script'
        ]
] );

If you wanted to-do this without Underpin, it would look more like this:

wp_register_script( 'test', 'path/to/script/src', ['wp-api-fetch', 'wp-polyfill'] );

add_action( 'wp_enqueue_scripts', function(){
    wp_enqueue_script( 'test' );
} );

This is okay, but it’s way better If you’re extending wordpress/scripts‘ Webpack configuration. This is because you can actually use import statements inside your Javascript for any @wordpress package, just like as-if you had installed the NPM package.

WordPress has a truly magical Webpack loader that will actually extract the WordPress-specific dependencies, and generate the dependencies array as a PHP file. You can then require this file, and it will automatically set your script dependencies for you. That way you can just write your JS as you were, and it will automatically update the dependency array for you.

This is way easier once you get it set-up. You can see how Underpin sets up a Webpack config for these sorts of things in Underpin’s plugin boilerplate.

Once you get that all-set, you can instead use this file to set dependencies. With Underpin, that would look like this:

plugin_name()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
    'deps'        => plugin_name()->dir() . 'build/test.asset.php', // path to dependency file generated by webpack
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Script' // Enqueue the script on the front-end
        ]
] );

Without Underpin, it can be done but requires a bit of extra logic:

// Check to see if the file exists.
$deps_file = plugin_dir_path(__FILE__) . 'path/to/file';

// Set default fallback to dependencies array
$deps = [];

// If the file can be found, use it to set the dependencies array.
if ( file_exists( $deps_file ) ) {
    $deps_file = require( $deps_file );
    $deps      = $file['dependencies'];
}

// Register script
wp_register_script( 'test', 'path/to/script/src', $deps );

// Enqueue the script later-on
add_action( 'wp_enqueue_scripts', function(){
    wp_enqueue_script( 'test' );
} );

Using api-fetch

Like I mentioned earlier, API fetch works a lot like the regular fetch API, but the syntax is a little different. Let’s say you wanted to get a list of posts via REST. It would look something like this:

apiFetch( {
    path: '/wp/v2/posts'
} );

This would return aJavascript Promise, much like how the normal Fetch API, however, unlike Fetch, this will return a parsed object instead of a response object after the promise resolves.

The example above doesn’t do anything with the object, however. There’s two primary methods to use the response for this. One is with the then statement, or async/await. Then is a little simpler to set up, but I find that async/await is easier to read.

Using then:

apiFetch( {
    path: '/wp/v2/posts'
} ).then( ( posts ) => /** do something with the posts **/ );

Using async/await:

const posts = await apiFetch( {
    path: '/wp/v2/posts'
} );

// Do something with your posts

Middleware

Okay, so this is all fine and dandy, but what’s the point of using this library when you can just use fetch and accomplish the same thing? The answer? Middleware.

apiFetch middleware allows you to automatically run a callback function, and mutate the request on every apiFetch call. This allows you to do some really cool things. api-fetch comes with three “built-in” middlewares that you can set up using a method.

createRootURLMiddleware will Automatically set the root REST API url so you only have to pass the relative path in your requests. This is important because the REST API URL can differ from WordPress install to WordPress install (don’t get me started with multisite)
createNonceMiddleware allows you to automatically authenticate a logged in user with a nonce.
createPreloadingMiddleware will allow you to preload REST API requests so that they load instantly instead of making another request on the server when that request is called on the front-end. (More on this later)

These can be set up inside Javascript directly, but it is common to load these as an inline script just after the script is enqueued using wp_add_inline_script, like so:

// Add a nonce to all requests
wp_add_inline_script(
    'test' // Script handle to add after
    'apiFetch.use( apiFetch.createNonceMiddleware( '. wp_create_nonce( 'wp_rest' ) .' ) )', // Javascript to inject after the script. This will add the nonce header to all rest requests on the apiFetch object.
);

// Set the root URL for all requests
wp_add_inline_script(
    'test' // Script handle to add after
    'apiFetch.use( apiFetch.createRootURLMiddleware( '. get_rest_url() .' ) )', // Javascript to inject after the script. This will add the nonce header to all rest requests on the apiFetch object.
);

Preloading Middleware

The first two built-in middlewares have a fairly obvious use-case – most REST requests need at least one of these in-order for the site to work consistently. Prior to middleware, this was done using wp_localize_script, and even at that time it was necessary to pass one, or both of these things in every request.

Preloading, however, is a bit different, and is defionitely not something that should be used in most cases, but there are times where it makes a lot of sense to use.

What does Preloading Middleware do?

Preloading middleware accepts a Javascript object where the object keys are specific WordPress REST API endpoints, and the values are the corresponding result of that particular endpoint. When this middleware is set, apiFetch will automatically check to see if the provided REST endpoint has been pre-loaded. If it has, it will use the preloaded response instead of making another fetch request.

When Should This Be Used?

I find the best time to use this feature is when you have had to retrieve the same data on the server as what will need to be retrieved on the actual site. For example – a WordPress request on the front-end always runs the page’s query when loading the content. If you’re using a semi-headless approach, and are ultimately using REST to fetch the post content after the site is loaded, you’re essentially forcing WordPress to fetch that data from the database twice. That kind-of sucks!

But you can, however, use a method similar to what we did above to preload the REST API data that has already been retrieved by the database. Something like this will take advantage of the object cache, and allow your web app to instantly have access to the posts instead of waiting for another request to complete. It’s a win-win because you’re taking advantage of data that has already been retrieved from the database, and reducing your requests on page load.

add_action('wp_enqueue_scripts', function(){
    // Preload the fetch data

    $current_page = get_query_var( 'paged' ) ?? 1; // Get the current page, and use page 1 as the default.
    $request = new \WP_REST_Request( $type, $endpoint ); // Instantiate a fake REST request.
    $request->set_query_params( ['page' => $current_page ); // Set current page
    $response = rest_do_request( $request ); // Run the REST request.

    $preloaded_data = [
        'wp/v2/posts?page=' . $current_page => $response->get_data()
    ];

    wp_add_inline_script(
        'test' // Script handle to add after
        'apiFetch.use( apiFetch.createPreloadingMiddleware( '. wp_json_encode( $preloaded_data ) .' ) )', // Javascript to inject after the script. This will add the nonce header to all rest requests on the apiFetch object.
    );
} );

Make Your Own Middleware

The sky is the limit with this. In some plugins, I’ve loaded in my own custom cache solution that automatically caches the REST API response, passed-in required params for different authentication methods, all kinds of things. Creating your own middleware is as simple as doing something like this:

apiFetch.use( ( options, next ) => {
    // Do things, like manipulate the provided options
    return next( options );
} );

This could be done either in your Javascript, or inside of PHP using the method detailed with other middlewares above.

Conclusion

api-fetch is an awesome little fetch utility that I use all the time when working in a RESTful manner with WordPress. It’s a powerful utility that has been tried and tested on tons and tons of sites, on different browsers, and in different contexts. When used correctly, it can make working with WordPress’s REST API a lot easier. When I look at this method, and reflect on the times before the REST API, I can’t help but chuckle. It’s so much easier now, provided you know how it works.

Looking for more WordPress Resources?

Join WP Dev Academy’s Discord server, and become a part of a growing community of WordPress developers.

Create a Custom Gutenberg Block Plugin with Underpin

Alex Standiford — Fri, 02 Jul 2021 14:23:40 +0000

This tutorial covers how to set up a custom Gutenberg block plugin in WordPress using Underpin. This plugin can hold all of your site’s custom Gutenberg blocks, and allows you to bring your custom blocks with you when you change themes in the future.

Install Underpin

If you haven’t already, the first thing you need to-do is actually install Underpin on your site. Underpin uses Composer to handle its dependencies, and it can be loaded in as a Must-Use plugin, or directly inside of your plugin. It really just depends on where you have Composer set up on your site. I like to install it as a mu-plugin for personal sites, and directly inside the plugin when I’m building a plugin that is intended to be distributed. In this lesson, I’ll assume you’re going to use it as a must-use plugin.

If you already have Underpin installed, you can skip this entirely.

Inside the wp-content directory, create a new directory called mu-plugins. If mu-plugins already exists, then skip this step.

Now create a composer.json file inside the mu-plugins directory. Most of this is the default settings for a composer.json file, the key difference is that extra.installer-paths is tweaked to force wordpress-muplugins to simply be installed directly in the vendor directory. This is necessary because Underpin is considered a mu-plugin by Composer, and will install in an improper directory, otherwise.

{
    "name": "wpda/muplugin",
    "type": "plugin",
    "require": {},
    "extra":{
        "installer-paths": {
          "vendor/{$vendor}/{$name}": ["type:wordpress-muplugin"]
    }
    }
}

Next, create a new PHP file inside the mu-plugins directory. It can named be whatever you want it to be. WordPress will automatically include this file, and run it on every page load. This happens really early in WordPress’s runtime so there are some limitations to this, but for our needs it’s perfect.

Use this code to include composer’s autoloader. This will automatically install and set up Underpin so you can use it anywhere else. This includes any plugins custom to this site, or your theme. Essentially, this makes Underpin as close to core functionality as possible. The only caveat is you have to remember to upload the mu-plugins directory to your live site.

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// Load Underpin, and its dependencies.
$autoload = plugin_dir_path( __FILE__ ) . 'vendor/autoload.php';

require_once( $autoload );

Now, let’s install Underpin. Open up your command-line, navigate to your site’s mu-plugins directory, and then run this command:

composer require underpin/underpin

Booya! You now have Underpin installed. Now, let’s use it in a plugin.

Set Up The Gutenberg Block Plugin

A fundamental practice of WordPress is to create WordPress plugins for each piece of custom functionality for your site. This allows you to enable/disable these plugins as-needed, and potentially re-use the plugin on other sites in the future.

We’re going to use Underpin’s plugin boilerplate to help set up this plugin quickly. This plugin does a few key things for us:

It sets up our Underpin plugin instance
It comes with a WordPress-ready Webpack config
It sets up the file headers that WordPress needs in-order to recognize the file as a plugin

To use this, navigate to wp-content/plugins and clone the boilerplate. Then you’ll need to-do a few find/replaces in the boilerplate.

Replace plugin-name-replace-me with custom-blocks (it can be whatever you want, just make sure spaces use dashes, and it’s all lowercase)
Replace Plugin Name Replace Me with Custom Blocks (Again, whatever you want just has to use spaces and Title Case)
Replace plugin_name_replace_me with custom_blocks (Same thing applies here, but you should use snake_case)
Replace Plugin_Name_Replace_Me with Custom_Blocks (using Upper_Snake_Case)

At this point, your plugin’s bootstrap.php file should look something like this:

<?php
/*
Plugin Name: Custom Blocks
Description: Plugin Description Replace Me
Version: 1.0.0
Author: An awesome developer
Text Domain: custom_blocks
Domain Path: /languages
Requires at least: 5.1
Requires PHP: 7.0
Author URI: https://www.designframesolutions.com
*/

use Underpin\Abstracts\Underpin;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Fetches the instance of the plugin.
 * This function makes it possible to access everything else in this plugin.
 * It will automatically initiate the plugin, if necessary.
 * It also handles autoloading for any class in the plugin.
 *
 * @since 1.0.0
 *
 * @return \Underpin\Factories\Underpin_Instance The bootstrap for this plugin.
 */
function custom_blocks() {
    return Underpin::make_class( [
        'root_namespace'      => 'Custom_Blocks',
        'text_domain'         => 'custom_blocks',
        'minimum_php_version' => '7.0',
        'minimum_wp_version'  => '5.1',
        'version'             => '1.0.0',
    ] )->get( __FILE__ );
}

// Lock and load.
custom_blocks();

Set Up The Loaders

With Underpin, everything is registered using an Underpin loader. These loaders will handle actually loading all of the things you need to register. Everything from scripts, to blocks, even admin pages, can all be added directly using Underpin’s loaders. Loaders make it so that everything uses an identical pattern to add items to WordPress. With this system, all of these things use nearly exact same set of steps to register.

To build a Gutenberg block, we need to add at least two loaders, but you usually end up needing three.

A block loader
A script loader
A style loader (optional)

Create the Gutenberg Block Loader

First things first, install the block loader. In your command line, navigate to your mu-plugins directory and run this command:

composer require underpin/block-loader

This will install the loader necessary to register blocks in Underpin. Now that it’s installed, you can register your block by chaining custom_blocks like so:

// Registers block
custom_blocks()->blocks()->add( 'my_custom_block', [
    'name'        => 'My Custom Block',                       // Names your block. Used for debugging.
    'description' => 'A custom block specific to this site.', // Describes your block. Used for debugging
    'type'        => 'custom-blocks/hello-world',             // See register_block_type
    'args'        => [],                                      // See register_block_type
] );

Let’s break down what’s going on above.

custom_blocks() actually retrieves this plugin’s instance of Underpin
blocks() Retrieves the loader registry for this instance of Underpin
add() actually adds this block to the registry

Behind the scenes, Underpin will automatically create an instance of Block, which then automatically runs register_block_type using the provided args and type.

At this point, your plugin’s bootstrap.php will look like this:

<?php
/*
Plugin Name: Custom Blocks
Description: Plugin Description Replace Me
Version: 1.0.0
Author: An awesome developer
Text Domain: custom_blocks
Domain Path: /languages
Requires at least: 5.1
Requires PHP: 7.0
Author URI: https://www.designframesolutions.com
*/

use Underpin\Abstracts\Underpin;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Fetches the instance of the plugin.
 * This function makes it possible to access everything else in this plugin.
 * It will automatically initiate the plugin, if necessary.
 * It also handles autoloading for any class in the plugin.
 *
 * @since 1.0.0
 *
 * @return \Underpin\Factories\Underpin_Instance The bootstrap for this plugin.
 */
function custom_blocks() {
    return Underpin::make_class( [
        'root_namespace'      => 'Custom_Blocks',
        'text_domain'         => 'custom_blocks',
        'minimum_php_version' => '7.0',
        'minimum_wp_version'  => '5.1',
        'version'             => '1.0.0',
    ] )->get( __FILE__ );
}

// Lock and load.
custom_blocks();

// Registers block
custom_blocks()->blocks()->add( 'my_custom_block', [
    'name'        => 'My Custom Block',                       // Names your block. Used for debugging.
    'description' => 'A custom block specific to this site.', // Describes your block. Used for debugging
    'type'        => 'custom-blocks/hello-world',             // See register_block_type
    'args'        => [],                                      // See register_block_type
] );

Create the Gutenberg Block Script

Next up, install the script loader. In your command line, navigate to your mu-plugins directory and run this command:

composer require underpin/script-loader

Exactly like blocks, this will install the loader necessary to register scripts in Underpin. With it, you can register scripts like so:

custom_blocks()->scripts()->add( 'custom_blocks', [
    'handle'      => 'custom-blocks',                                // Script Handle used in wp_*_script
    'src'         => custom_blocks()->js_url() . 'custom-blocks.js', // Src used in wp_register_script
    'name'        => 'Custom Blocks Script',                         // Names your script. Used for debugging.
    'description' => 'Script that loads in the custom blocks',       // Describes your script. Used for debugging.
] );

Let’s break down what’s going on above.

custom_blocks() actually retrieves this plugin’s instance of Underpin
scripts() Retrieves the loader registry for this instance of Underpin
add() actually adds this script to the registry
custom_blocks()->js_url() is a helper function that automatically gets the javascript url for this plugin. This is configured in the custom_blocks function directly, and defaults to build

Behind the scenes, Underpin will automatically create an instance of Script, which then automatically runs wp_register_script using the arguments passed into the registry.

Enqueuing the Script

Now that the script is registered, you actually have to enqueue the script as well. We could manually enqueue the script, but instead we’re going to use Underpin’s Middleware functionality to automatically enqueue this script in the admin area.

custom_blocks()->scripts()->add( 'custom_blocks', [
    'handle'      => 'custom-blocks',                                // Script Handle used in wp_*_script
    'src'         => custom_blocks()->js_url() . 'custom-blocks.js', // Src used in wp_register_script
    'name'        => 'Custom Blocks Script',                         // Names your script. Used for debugging.
    'description' => 'Script that loads in the custom blocks',       // Describes your script. Used for debugging.
    'middlewares' => [
        'Underpin_Scripts\Factories\Enqueue_Admin_Script',             // Enqueues the script in the admin area
    ],
] );

Your bootstrap.php file should now look something like this:

<?php
/*
Plugin Name: Custom Blocks
Description: Plugin Description Replace Me
Version: 1.0.0
Author: An awesome developer
Text Domain: custom_blocks
Domain Path: /languages
Requires at least: 5.1
Requires PHP: 7.0
Author URI: https://www.designframesolutions.com
*/

use Underpin\Abstracts\Underpin;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Fetches the instance of the plugin.
 * This function makes it possible to access everything else in this plugin.
 * It will automatically initiate the plugin, if necessary.
 * It also handles autoloading for any class in the plugin.
 *
 * @since 1.0.0
 *
 * @return \Underpin\Factories\Underpin_Instance The bootstrap for this plugin.
 */
function custom_blocks() {
    return Underpin::make_class( [
        'root_namespace'      => 'Custom_Blocks',
        'text_domain'         => 'custom_blocks',
        'minimum_php_version' => '7.0',
        'minimum_wp_version'  => '5.1',
        'version'             => '1.0.0',
    ] )->get( __FILE__ );
}

// Lock and load.
custom_blocks();

// Registers block
custom_blocks()->blocks()->add( 'my_custom_block', [
    'name'        => 'My Custom Block',                       // Names your block. Used for debugging.
    'description' => 'A custom block specific to this site.', // Describes your block. Used for debugging
    'type'        => 'underpin/custom-block',                 // See register_block_type
    'args'        => [],                                      // See register_block_type
] );

custom_blocks()->scripts()->add( 'custom_blocks', [
    'handle'      => 'custom-blocks',                                // Script Handle used in wp_*_script
    'src'         => custom_blocks()->js_url() . 'custom-blocks.js', // Src used in wp_register_script
    'name'        => 'Custom Blocks Script',                         // Names your script. Used for debugging.
    'description' => 'Script that loads in the custom blocks',       // Describes your script. Used for debugging.
    'middlewares' => [
        'Underpin_Scripts\Factories\Enqueue_Admin_Script',             // Enqueues the script in the admin area
    ],
] );

Create the Blocks Javascript File

First, you need to modify your webpack.config.js to create a new entry file. It should look like this:

/**
 * WordPress Dependencies
 */
const defaultConfig = require( '@wordpress/scripts/config/webpack.config.js' );

/**
 * External Dependencies
 */
const path = require( 'path' );

module.exports = {
    ...defaultConfig,
    ...{
        entry: {
            "custom-blocks": path.resolve( process.cwd(), 'src', 'custom-blocks.js' ) // Create "custom-blocks.js" file in "build" directory
        }
    }
}

This instructs Webpack to take a JS file located in your plugin’s src directory, and compile it into build/custom-blocks.js. From here, we need to create a new file in the src directory called custom-blocks.js.

Now we have to register the block in our Javascript, as well. This will allow us to customize how this block behaves in the Gutenberg editor. In this lesson, we’re going to just create a very simple “Hello World” block.

// Imports the function to register a block type.
import { registerBlockType } from '@wordpress/blocks';

// Imports the translation function
import { __ } from '@wordpress/i18n';

// Registers our block type to the Gutenberg editor.
registerBlockType( 'custom-blocks/hello-world', {
    title: __( "Hello World!", 'beer' ),
    description: __( "Display Hello World text on the site", 'beer' ),
    edit(){
        return (
            <h1 className="hello-world">Hello World!</h1>
        )
    },
    save() {
        return (
            <h1 className="hello-world">Hello World!</h1>
        )
    }
} );

Okay, so what’s going on here?

We’re importing registerBlockType so we can use it in this file
We’re also importing __ so we can make translate-able strings
We are running registerBlockType to register our “Hello World” block to the editor.

Now run npm install and npm run start. This will create two files in your build directory:

custom-blocks.js – This is your compiled Javascript file that gets enqueued by Underpin’s script loader.
custom-blocks-asset.php – This asset file tells WordPress what additional scripts need enqueued in-order for this script to work properly.

You will notice that we did not install @wordpress/blocks or @wordpress/i18n. That’s not a mistake. Since these are internal WordPress scripts, we need to tell WordPress to enqueue those scripts before our script. Fortunately, WordPress and Underpin make this pretty easy to-do.

Update Underpin Script to include

Back in bootstrap.php, update your script’s add function to include a deps argument. Since this argument is a path, it will automatically require the file, and use it to tell WordPress which scripts need enqueued. Since Webpack automatically generates this file for us, we no-longer need to worry about adding dependencies every time we want to use a WordPress library.

custom_blocks()->scripts()->add( 'custom_blocks', [
    'handle'      => 'custom-blocks',                                          // Script Handle used in wp_*_script
    'src'         => custom_blocks()->js_url() . 'custom-blocks.js',           // Src used in wp_register_script
    'name'        => 'Custom Blocks Script',                                   // Names your script. Used for debugging.
    'description' => 'Script that loads in the custom blocks',                 // Describes your script. Used for debugging.
    'deps'        => custom_blocks()->dir() . 'build/custom-blocks.asset.php', // Load these scripts first.
    'middlewares' => [
        'Underpin_Scripts\Factories\Enqueue_Admin_Script',                       // Enqueues the script in the admin area
    ],
] );

From your admin screen, if you navigate to posts>>Add New, you will find that you can use a new block called “Hello World”, which will simply display “Hello World” In gigantic letters on the page.

With this script, you can create as many blocks as you need by simply creating another registerBlockType call, and registering the block though Underpin using custom_blocks()->blocks()->add.

Create the Gutenberg Block Stylesheet (Optional)

Stylesheets need a bit of extra thought in-order for them to work-as expected. Normally, you would simply enqueue the script much like you enqueue a script. The catch is that this stylesheet also needs to be used in the block editor in-order to accurately display the block output. Let’s get into how to set that up.

Just like everything else with Underpin, the first step is to install the appropriate loader, the register the style.

In your mu-plugins directory, run:

composer require underpin/style-loader

From there, register a style in your bootstrap.php file:

custom_blocks()->styles()->add( 'custom_block_styles', [
    'handle'      => 'custom-blocks',                                        // handle used in wp_register_style
    'src'         => custom_blocks()->css_url() . 'custom-block-styles.css', // src used in wp_register_style
    'name'        => 'Custom Blocks Style',                                  // Names your style. Used for debugging
    'description' => 'Styles for custom Gutenberg blocks',                   // Describes your style. Used for debugging
] );

Then, update webpack.config.js to include custom-block-styles.css, like so:

/**
 * WordPress Dependencies
 */
const defaultConfig = require( '@wordpress/scripts/config/webpack.config.js' );

/**
 * External Dependencies
 */
const path = require( 'path' );

module.exports = {
    ...defaultConfig,
    ...{
        entry: {
            "custom-blocks": path.resolve( process.cwd(), 'src', 'custom-blocks.js' ), // Create "custom-blocks.js" file in "build" directory
            "custom-block-styles": path.resolve( process.cwd(), 'src', 'custom-block-styles.css' )
        }
    }
}

Next, update your registered block to use the style to specify the stylesheet to be used with this block like so:

// Registers block
custom_blocks()->blocks()->add( 'my_custom_block', [
    'name'        => 'My Custom Block',                       // Names your block. Used for debugging.
    'description' => 'A custom block specific to this site.', // Describes your block. Used for debugging
    'type'        => 'custom-blocks/hello-world',             // See register_block_type
    'args'        => [                                        // See register_block_type
        'style' => 'custom-blocks',                             // Stylesheet handle to use in the block
    ],
] );

That will update your block to enqueue the stylesheet in the block editor automatically, and will reflect the styles in the stylesheet. This will work both on the actual site and the block editor.

With the style set as-such:

.hello-world {
    background:rebeccapurple;
}

You’ll get this in the block editor, and the front end:

Use Server-Side Rendering (Optional)

This is all fine and dandy, but there’s one problem with how this is built – what happens if a theme needs to change the markup of our block? Or, what if, for some reason, it makes more sense to use PHP to render this block instead of Javascript?

A fundamental problem with blocks is that it will hardcode the saved block result inside of the WordPress content. In my opinion, it’s better to render using server-side rendering. This tells WordPress that, instead of saving the HTML output, to instead create a placeholder for the block, and just before the content is rendered, WordPress will inject the content from a PHP callback. This allows you to update blocks across your site quickly just by updating a PHP callback whenever you want.

Call me old fashioned, but I think that’s a lot more maintain-able, and thankfully it’s pretty easy to-do.

First, update your registered block so that save returns null. This instructs the editor to simply not save HTML, and just put a placeholder there instead.

// Registers our block type to the Gutenberg editor.
registerBlockType( 'custom-blocks/hello-world', {
    title: __( "Hello World!", 'beer' ),
    description: __( "Display Hello World text on the site", 'beer' ),
    edit(){
        return (
            <h1 className="hello-world">Hello World!</h1>
        )
    },
    save: () => null
} );

Now, if you specify a render_callback in your registered block arguments, it will use the callback instead of what was originally in the save callback.

// Registers block
custom_blocks()->blocks()->add( 'my_custom_block', [
    'name'        => 'My Custom Block',                       // Names your block. Used for debugging.
    'description' => 'A custom block specific to this site.', // Describes your block. Used for debugging
    'type'        => 'custom-blocks/hello-world',             // See register_block_type
    'args'        => [                                        // See register_block_type
        'style' => 'custom-blocks',                             // Stylesheet handle to use in the block
        'render_callback' => function(){
            return '<h1 class="hello-world">Hey, this is a custom callback!</h1>';
        }
    ],
] );

Now if you look in your editor, you’ll still see “Hello World”, because that’s what the Javascript’s edit method returns, however, if you save and look at the actual post, you’ll find that the actual post will show “Hey, this is a custom callback” instead. This is because it’s using PHP to render the output on the fly. Now, if you change the content of the render_callback, it will automatically render this output.

Going Further – Use Underpin’s Template System

What happens if you have a WordPress theme, and you want to actually override the render callback? A good way to approach this is to use Underpin’s built-in Template loader system. This system allows you to specify file locations for PHP templates that render content, and also has baked-in support for template overriding by themes.

Underpin’s template system is a PHP trait. It can be applied to any class that needs to output HTML content. The tricky part is, we haven’t made a class yet, have we?

…Have we?

Well, actually, we have. Every time we run the add method in WordPress, it automatically creates an instance of a class, and it uses the array of arguments to construct our class for us. However, now, we need to actually make the class ourselves so we can apply the Template trait to the class, and render our template. So, next up we’re going to take our registered block, and move it into it’s own PHP class, and then instruct Underpin to use that class directly instead of making it for us.

First up, create a directory called lib inside your plugin directory, and then inside lib create another directory called blocks. Inside that, create a new PHP file called Hello_World.php. Underpin comes with an autoloader, so the naming convention matters here.

├── lib
│   └── blocks
│       └── Hello_World.php

Inside your newly created PHP file, create a new PHP class called Hello_World that extends Block, then move all of your array arguments used in your add method as parameters inside the class, like so:

<?php

namespace Custom_Blocks\Blocks;


use Underpin_Blocks\Abstracts\Block;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

class Hello_World extends Block {

    public $name        = 'My Custom Block';                       // Names your block. Used for debugging.
    public $description = 'A custom block specific to this site.'; // Describes your block. Used for debugging
    public $type        = 'custom-blocks/hello-world';             // See register_block_type

    public function __construct() {
        $this->args        = [                                        // See register_block_type
            'style' => 'custom-blocks',                                 // Stylesheet handle to use in the block
            'render_callback' => function(){
                return '<h1 class="hello-world">Hey, this is a custom callback!</h1>';
            }
        ];
        parent::__construct();
    }

}

Then, replace the array of arguments in your add callback with a string that references the class you just created, like so:

// Registers block
custom_blocks()->blocks()->add( 'my_custom_block', 'Custom_Blocks\Blocks\Hello_World' );

By doing this, you have instructed Underpin to use your PHP class instead of creating one from the array of arguments. Now that we have a full-fledged PHP class in-place, we can do a lot of things to clean this up a bit, and use that template Trait I mentioned before.

Add use \Underpin\Traits\Templates to the top of your PHP class, and add the required methods to the trait as well, like so:

<?php

namespace Custom_Blocks\Blocks;


use Underpin_Blocks\Abstracts\Block;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

class Hello_World extends Block {
    use \Underpin\Traits\Templates;

    public $name        = 'My Custom Block';                       // Names your block. Used for debugging.
    public $description = 'A custom block specific to this site.'; // Describes your block. Used for debugging
    public $type        = 'custom-blocks/hello-world';             // See register_block_type

    public function __construct() {
        $this->args        = [                                        // See register_block_type
            'style' => 'custom-blocks',                                 // Stylesheet handle to use in the block
            'render_callback' => function(){
                return '<h1 class="hello-world">Hey, this is a custom callback!</h1>';
            }
        ];
        parent::__construct();
    }

    public function get_templates() {
        // TODO: Implement get_templates() method.
    }

    protected function get_template_group() {
        // TODO: Implement get_template_group() method.
    }

    protected function get_template_root_path() {
        // TODO: Implement get_template_root_path() method.
    }

}

Now, we’re going to fill out each of these functions. get_templates should return an array of template file names with an array declaring if that template can be manipulated by a theme, or not, like so:

public function get_templates() {
    return ['wrapper' => [ 'override_visibility' => 'public' ]];
}

get_template_group should return a string, that indicates what the template sub directory should be called. In our case, we’re going to make it hello-world.

protected function get_template_group() {
    return 'hello-world';
}

get_template_root_path should simply return custom_blocks()->template_dir(), as we don’t need to use a custom template directory or anything.

protected function get_template_root_path() {
    return custom_blocks()->template_dir();
}

Finally, we have the option to override the template override directory name into something specific to our own plugin. Let’s do that, too:

protected function get_override_dir() {
    return 'custom-blocks/';
}

With these three items in-place, you can now create a new file in templates/hello-world called wrapper.php. Inside your theme, this template can be completely overridden by adding a file in custom-blocks/hello-world called wrapper.php. Let’s start by adding our template in the plugin file.

The first thing your template needs is a header that checks to make sure the template was loaded legitimately. You don’t want people to load this template outside of the intended way, so you must add a check at the top level to make sure it was loaded properly, like so:

<?php

if ( ! isset( $template ) || ! $template instanceof \Custom_Blocks\Blocks\Hello_World ) {
    return;
}

?>

Underpin automatically creates a new variable called $template and assigns it to the class that renders the actual template. So inside your template file $template will always be the instance of your registered block. This allows you to create custom methods inside the block for rendering purposes if you want, but it also gives you access to rendering other sub-templates using $template->get_template(), plus a lot of other handy things that come with the Template trait. As you can see above, this also provides you with a handy way to validate that the required file is legitimate.

Now, simply add the HTML output at the bottom, like this:

<?php

if ( ! isset( $template ) || ! $template instanceof \Custom_Blocks\Blocks\Hello_World ) {
    return;
}

?>
<h1 class="hello-world">Hey, this is a custom callback, and it is inside my template!</h1>

From there, go back into your Hello_World class, and update the render callback to use your template. This is done using get_template, like so:

public function __construct() {
        $this->args = [                         // See register_block_type
            'style'           => 'custom-blocks', // Stylesheet handle to use in the block
            'render_callback' => function () {
                return $this->get_template( 'wrapper' );
            },
        ];
        parent::__construct();
    }

This instructs the render_callback to use get_template, which will then retrieve the template file you created. If you look at your template’s output, you’ll notice that your h1 tag changed to read “Hey, this is a custom callback, and it is inside my template!”.

Now, go into your current theme, create a php file inside custom-blocks/hello-world called wrapper.php. Copy the contents of your original wrapper.php file, and paste them in. Finally, change the output a little bit. When you do this, the template will automatically be overridden by your theme.

Conclusion

Now that you have one block set-up, it’s just a matter of registering new blocks using Underpin, and inside your Javascript using registerBlockType. If necessary, you can create a block class for each block, and use the template system to render the content.

This post barely scratches the surface of what can be done with Underpin, the template loader, and Gutenberg. From here, you could really flesh out your block into something more than a trivial example. If you want to go deeper on these subjects, check out my WordPress plugin development course, where we create a block much like how I describe it here, and then build out a fully-functional Gutenberg block, as well as many other things.

Looking for more WordPress Resources?

Join WP Dev Academy’s Discord server, and become a part of a growing community of WordPress developers.

Headless WordPress is Overrated: A Case for The Nearly-Headless Web App

Alex Standiford — Fri, 02 Jul 2021 14:05:26 +0000

Over the last few years, I’ve built a number of fully headless WordPress websites with the REST API and React. I loved how fast the end result is, and if done correctly, how powerful and extend-able you could eventually make page creation. Plus it just feels nice. Loading transitions, and the general behavior just makes your website feel fresh, and modern. It provides a polish that even the fastest non-headless sites can’t quite achieve.

I avoid creating headless WordPress websites. It creates a lot of extra overhead, which creates more bugs, and ultimately ends up making the site much harder to maintain. I typically stick to the basics – fast hosting, and aggressive caching.

Headless WordPress kind-of sucks. You give up a lot of help from WordPress in-search of an app experience. I have found myself frequently dreaming “what if I could have it both ways?”

The Problem With Headless

One problem with fully-headless WordPress is routing. Behind the scenes, WordPress has a lot of logic built-in to handle routing, and with a headless approach you have to build something to handle that on the front end. Ultimately, you’re re-inventing the wheel, and it takes a lot of extra time to build.

Another problem with headless WordPress quickly becomes apparent the moment you try to use most WordPress plugins. The ugly truth is that you usually have to re-invent a lot of things just to get the plugin working properly. For example, try to create and use a Gravity Forms form, and then use it in a React app. You can’t really do it without re-building the form’s render, validation, and submission logic on the front-end. That’s a lot of extra overhead to maintain. This example is something as simple as adding a form to a website. Imagine how complex things get when you look at things like integrating e-commerce tools, like Easy Digital Downloads, or WooCommerce.

Re-Thinking “Headless WordPress”

I knew when I committed to upgrading my personal theme, I wanted it to be a fast, and have an app feel, but I didn’t want to completely sacrifice all of the natural capabilities that WordPress plugins offer. This site, for example, uses LifterLMS for its courses, and it would have taken a lot of extra time to rewrite all of those course templates from-scratch.

I also wanted to use this tech for our premium clients at DesignFrame. Because of that, we needed a way to maximize compatibility with WordPress’s native features, and ensure that plugins remain compatible with whatever we build.

So, with that, here’s the key parameters of this approach:

The theme had to be compatible with other plugins without re-building a bunch of custom logic in the process.
Other developers should be able to pick up and work with the theme with a minimal learning curve.
The site needs to just work with WordPress’s block editor without needing any changes to the theme.

These parameters immediately revealed a couple technical truths:

The HTML markup needs to be rendered inside WordPress. This ensures that plugins can render their output in the same way they do with any other theme.
The app needs to rely on WordPress for routing, and needs to handle any custom page from any plugin without fail.

Neither of these things fit the description of headless WordPress.

Enter Our Nearly Headless Web App

I like to call this a nearly headless app. Partially because it makes sense – the app still relies on the server to get started, but once the server provides the initial load, the app can usually take it from there. But let’s be real, I just wanted an excuse to put John Cleese in my blog post.

Here’s the gist:

The system uses AlpineJS for rendering. It’s light, fairly easy to understand, and it plays exceptionally nice with PHP server-side rendering.
Most of the theme is is loaded around HTML template tags. These tags get populated by WordPress’s REST responses for post content.
The system makes judicious use of session storage. This drastically reduces the number of REST API calls, and keeps the site running fast.

How Nearly Headless WordPress Works

The site is loaded just like any regular ol’ WordPress site. The key difference is “the loop” is replaced by a template tag, which uses Alpine’s x:forEach loop to actually render the loop. It looks something like this:

 `
/**
 * Index Loop Template
 *
 * @author: Alex Standiford
 * @date  : 12/21/19
 * @var $template \Theme\Templates\Index
 */

if ( ! theme()->templates()->is_valid_template( $template ) ) {
    return;
}

?>

<div class="loop">
    <template x-for="( post, index ) in posts" :key="index">
        <div>
            <template x-if="'post' === getParam(index, 'type')">
                = theme()->templates()->get_template( 'post', 'post' ); ?>
            template>
            <template
                x-if="'page' === getParam(index, 'type') || 'course' === getParam(index, 'type') || 'lesson' === getParam(index, 'type')">
                = theme()->templates()->get_template( 'page', 'page' ); ?>
            template>
        div>
    template>
div>`

I’m using Underpin’s template system in the example above, but you could just as easily do this with get_template_part() instead of get_template().

Once the page loads, AlpineJS fires up, and renders the content using the REST API. Since the initial endpoint is preloaded, it grabs the data from the cache, loops through the content, and renders the result. The REST response is also saved in session storage (more on that later).

Behind the scenes, the app scans the entire rendered page for internal site links, gathers them up, and sends them to a custom REST endpoint. This endpoint takes the URLs, retrieves the post object associated with each one, and returns them to the app. The app takes these objects and puts them in session storage for later use.

When a link is clicked, the app intercepts the event, and checks to see if the post for that link is stored in session storage. If it is, it re-renders the page using the data from session storage, and pushes the URL to the browser’s history. If the page content isn’t stored in session storage, it simply loads the link using the default behavior.

Key Benefits

Your Website Works Less

Because most of the content ultimately gets loaded from the session storage, the app has all of the information needed to render content without contacting the server. This takes a lot of strain off of the server by reducing the number of requests a visitor makes when exploring your website. Not only does this mean your site will run faster, it also means your site will be able to handle more concurrent visitors without slowing down.

Faster Experience On Slow Networks

Another benefit of the nearly headless WordPress app is how much better this app performs on a slow network. I spend a lot of time in the boonies, so I’m painfully aware of how much an optimized website can improve a person’s experience. The initial load won’t be any better than a normal site, but when it loads, the rest of the content is fetched in another request. Once that loads, the site will load instantly, even though the network is slow.

In fact, in testing, I was able to load the initial page, turn on my iPhone’s airplane mode, and still navigate most of the site as-if I had a lightning fast connection.

> .@DFS_Web’s website redesign will make it possible to visit any page without an internet connection shortly after the first page is loaded. This makes this site FAST even if your internet connection is slow. pic.twitter.com/keOxyMU8cq
>
> — Alex Standiford (@alexstandiford) December 9, 2020

Problem Pages Can Bypass the App

The app only instant-loads if the content is in the session storage. This means that you can “disable” the app on pages that, for whatever reason, need to run through a WordPress request when visited. This theme includes settings page that makes it possible to add a list of pages to explicitly force to load in this manner.

This makes it possible to fallback to a more-traditional theme load on pages that somehow conflict with the app. That gives us a way to quickly fix pages that are behaving unexpectedly without needing to make any immediate changes to the theme.

This allows me to quickly put a quick-fix to problems that crop up, and then implement the necessary upgrades to the theme to fix the conflicts and re-activate the app on that page.

This also allows us to completely disable headless WordPress when it’s convenient from a technical standpoint. Some pages would require a lot of extra work to re-build using REST. For example, a cart page on a website that uses an e-commerce solution would require a significant rewrite of the template because these plugins expect a traditional request to occur when the page is visited.

Caveats

This system avoids most problems that headless apps create, however, in its current form, it has a few gotchas. Fortunately, these issues have been relatively easy to fix, and can often be avoided altogether by simply disabling the app for the pages that are impacted.

Scripts and styles are probably the biggest headache that comes with any method that renders with Javascript, and this system is no exception. Any plugin that enqueues a custom script or style on the front end will not work if the page is loaded with the cache. This is because most plugins only load scripts and styles on pages that need the scripts. This can usually be avoided by forcing any page that utilizes these plugins to load without the cache. That will force the site to load the site normally, which usually makes everything work as-expected.

In my build, Gravity Forms still didn’t work, even when the page with the form was loaded normally. This was because Gravity Form’s script fired before Alpine rendered the content. This caused Gravity Form to fail.

To get around this, I had two options:

Force all pages that have a Gravity Form to load without Alpine, using a traditional loop. Easy, but not as nice.
Modify how Gravity Forms renders its forms to use Alpine + Gravity Forms REST API. Harder, but nicer.

For this specific problem, I opted to spend a few hours getting Gravity Forms working with Alpine. Since I’m still using WordPress to do my rendering, I didn’t have to re-do the rendering portion, just had to modify it a little to use Alpine’s event handles. This ended up being significantly easier than what I’ve had to-do in React, where I had to also re-create the forms in JSX. I didn’t have to re-invent the rendering, just had to get submissions working, and it took a lot less effort to achieve.

Conclusion

When I started working on this, I knew that there would be a little more overhead than a basic theme, and a lot less overhead than a site builder. The goal, however, was to minimize the overhead enough to make it a plausible option for our premium clients. This approach offers a lot of performance gains without adding a lot of extra overhead in the process, and most-importantly, provides a traditional-loading safety net for pages that are being naughty.

Looking for more WordPress Resources?

Join WP Dev Academy’s Discord server, and become a part of a growing community of WordPress developers.

Introducing Underpin - A Modern WordPress Framework

Alex Standiford — Thu, 20 May 2021 21:28:04 +0000

Over the years, I have built dozens and dozens of WordPress plugins. Some have been GPL plugins shared publicly, but most have been custom plugins for clients. I started out much like most other WordPress developers, building ever-improving homemade boilerplates. It started simple enough - nothing more than a collection of handy functions that I always wanted in my plugins. Over time, it expanded into a bootstrap file that sets up the plugin, set up constants, and all of the other things that you will find in pretty much any major WordPress plugin today.

Over time, I tinkered, built, re-built, and re-imagined my little plugin boilerplate into a full-blown WordPress framework, that I use on all of my client sites, and all of my distributed plugins.

WordPress Isn't a Framework

WordPress 'aint perfect. It does a lot of things "old skool", and wasn't really designed to make building web applications easy. Instead, it has always been focused on making its core as extendable as possible, and simply stays out of your way so you can go on to build what you want.

In my opinion, I think this is great. I think WordPress's staying power has come from the fact that it just does not give a damn about how you build your stuff. If you hook into the right action, it'll do whatever you want.

But this does not make plugin development particularly efficient in WordPress. If you're starting from scratch, you're literally starting with a blank PHP file in a plugin directory. There's a lot of extra setup that comes with doing pretty much everything in WordPress that you don't find in actual frameworks.

Over time, you will also find that WordPress is missing some key things that most plugins will need as they mature, such as plugin upgrade routines.

In fact, WordPress has a lot of shortcomings that many plugins have to eventually overcome:

Troubleshooting their plugin on a live customer site
Building robust, extendable admin pages
Making your plugin extendable without taking on tons of technical debt in the process
Using consistent code practices across add-ons
Handling upgrade routines, and database upgrades
Keeping technical debt managed, and under-control

These are a few of the challenges that I have had to overcome in my own plugins, and Underpin tackles each one of them.

Using Underpin

Underpin takes everything that is done in WordPress, and converts it into a consistent syntax. In other words, the process to create a widget is pretty much identical to how you would register a custom post type. Things as seemingly different as creating scripts, and creating admin pages, even use the same exact steps.

Install the appropriate loader via Composer
Register the item using the loader's add function.

Registering a custom post type could look like this:

// Register custom Post Type
underpin()->custom_post_types()->add( 'example_type', [
    'type' => 'example-type', // see register_post_type
    'args' => [ /*...*/ ] // see register_post_type
] );

Registering a widget could look something like this:

// Register widget
underpin()->widgets()->add( 'hello-world-widget', [
    'name'                => underpin()->__( 'Hello World Widget' ),                               // Required. The name of the widget.
    'id_base'             => 'widget_name',                                                        // Required. The ID.
    'description'         => underpin()->__( 'Displays hello to a specified name on your site.' ), // Widget description.
    'widget_options'      => [                                                                     // Options to pass to widget. See wp_register_sidebar_widget
        'classname' => 'test_widget',
    ],
    'get_fields_callback' => function ( $fields, \WP_Widget $widget ) {                            // Fetch, and set settings fields.
        $name = isset( $fields['name'] ) ? esc_html( $fields['name'] ) : 'world';

        return [
            new \Underpin\Factories\Settings_Fields\Text( $name, [
                'name'        => $widget->get_field_name( 'name' ), // See WP_Widget get_field_name
                'id'          => $widget->get_field_id( 'name' ),   // See WP_Widget get_field_id
                'setting_key' => 'name',                            // Must match field name and field ID
                'description' => underpin()->__( 'Optional. Specify the person to say hello to. Default "world".' ),
                'label'       => underpin()->__( 'Name' ),
            ] ),
        ];
    },
    'render_callback'    => function ( $instance, $fields ) {                                      // Render output
        $name = ! empty( $fields['name'] ) ? esc_html( $fields['name'] ) : 'world';

        echo underpin()->__( sprintf( 'Hello, %s!', $name ) );
    },
] );

Behind the scenes, each of these items do all of the things necessary to register their respective items. It uses all of the information you provide to build when the time is right.

Debugging With Underpin

Underpin comes with a PSR3 compatible logging utility. This utility will write error logs to a file, or you can extend it to do something else if your plugin needs something else.

This logger is used throughout Underpin, and is something that you could use as you build your own plugin, as well.

plugin_name_replace_me()->logger()->log(
    'error',             // Error type.
    'unique_error_code', // Error code
    'Human readable error message',
    ['arbitrary' => 'data', 'that' => 'is relevant', 'ref' => 1]
);

Not only does this optionally save certain events to the log, it also https://github.com/Underpin-WP/debug-bar-extension with Query Monitor and Debug Bar debug plugins. All Underpin events automatically get added to these logs. This allows you to troubleshoot problems on a live site, and begin to make sense of what's going on.

Settings Fields

Full-Site editing is coming, but for now we still need a way to create admin pages using WordPress's HTML markup. If you've ever worked with this system, you know - there be dragons.

To help make this easier, Underpin has a set of HTML input classes that make it possible to sanitize, save, and render HTML on admin pages. These fields are capable of natively using all of the markup that WordPress expects, or a bare-minimum set of markup for places that do not work inside of a table.

A basic text field would look like this:

$text_field = new \Underpin\Factories\Settings_Fields\Text( $name, [
    'name'        => $widget->get_field_name( 'name' ), // See WP_Widget get_field_name
    'id'          => $widget->get_field_id( 'name' ),   // See WP_Widget get_field_id
    'setting_key' => 'name',                            // Must match field name and field ID
    'description' => underpin()->__( 'Human Readable Description' ),
    'label'       => underpin()->__( 'Field Name' ),
] );

// Render the field
echo $text_field->place();

With these fields, you can create entire settings pages using the exact same add syntax discussed above. The example below would render an admin page in WordPress, complete with support for saving the field to an option.

// Register the option to use on the settings page. See Underpin_Options\Abstracts\Option
underpin()->options()->add( 'example_admin_options', [
    'key'           => 'example_option', // required
    'default_value' => [
        'test_setting' => 'Hello world',
    ],
    'name'          => 'Example Admin Page',
    'description'   => 'Settings manged by Example Admin Page',
] );

// Register the admin page
underpin()->admin_pages()->add( 'example-admin-page', [
    'page_title' => underpin()->__( 'Example Admin Page' ),
    'menu_title' => underpin()->__( 'Example' ),
    'capability' => 'administrator',
    'menu_slug'  => 'example-admin-page',
    'icon'       => 'dashicons-admin-site-alt',
    'position'   => 5,
    'sections'   => [
        [
            'id'          => 'primary-section',
            'name'        => underpin()->__( 'Primary Section' ),
            'options_key' => 'example_admin_options',
            'fields'      => [
                'test_setting' => [
                    'class' => 'Underpin\Factories\Settings_Fields\Text',
                    'args'  => [ underpin()->options()->pluck( 'example_admin_options', 'test_setting' ), [
                        'name'        => 'test_setting',
                        'description' => underpin()->__( 'Optional. Specify the person to say hello to. Default "world".' ),
                        'label'       => underpin()->__( 'Name' ),
                    ] ],
                ],
            ],
        ],
    ],
] );

Plugin Extend-ability

The loader pattern provided by Underpin makes it possible to extend WordPress core, and you can use the exact same technology to make your own plugin extendable. This can be done by registering your own custom loader registries to your WordPress plugin.

In fact, the process to add a loader uses the exact same syntax as adding literally anything else. The only difference here is that you have to also create the Loader_Registry class to reference.

I'm not going to get into this too deep in this post, but you can see how it all works in the custom post type loader source code. This particular bit of functionality is really the heart and soul of Underpin, and an entire post could be easily written on it.

Here's an example of how a loader is registered in an upcoming course I'm working on:


        /**
         * Setup Colors
         */
        underpin()->loaders()->add( 'colors', [
            'registry' => 'Beer_List\Loaders\Colors', 
        ] );

Now, if I wanted to add a new color to the registry, I would do this:

underpin()->colors()->add( 'color_id', [/** Args to register the color **/] );

Behind the scenes, this would create a new instance of your Color class, and store it for later use.

That color class could be accessed at any time with:

$color = underpin()->colors()->get( 'color_id' );

This could also be done by anyone extending the plugin.

Upgrade Routines & Batch Tasks

Like anything else, Underpin has a custom loader that handles the admin interface, script, and batch actions needed to make an upgrade routine work. Like everything else, this is a pre-built loader that can be installed and used like this:

\Underpin\underpin()->batch_tasks()->add( 'example-batch', [
    'description'             => 'A batch task that does nothing 20 times',
    'name'                    => 'Batch Task Example',
    'tasks_per_request'       => 50,
    'stop_on_error'           => true,
    'total_items'             => 1000,
    'notice_message'          => 'Run the most pointless batch task ever made.',
    'button_text'             => 'LETS GO.',
    'capability'              => 'administrator',
    'batch_id'                => 'example-batch',
    'task_callback'           => '__return_null', // The callback that iterates on every task
    'finish_process_callback' => '__return_null', // The callback that runs after everything is finished
    'prepare_task_callback'   => '__return_null', // The callback that runs before each task
    'finish_task_callback'    => '__return_null', // The callback that runs after each task
  ] );

Distributing Underpin

One big thing that stops most developers from using dependencies in their WordPress plugin is that there's usually no easy way to prevent plugin conflicts with other plugins that also use the system. Underpin resolves that problem with a rename compiler.

This compiler is a basic find/replace script that replaces all mention of the word underpin throughout the plugin with a word of your choice. Everything in Underpin that can cause a conflict has been intentionally prefixed with underpin to make it possible to do this rename.

This means that you can use Underpin in its entirety in your WordPress plugin, and run the script to compile Underpin so it is safe to be distributed with other plugins that also use Underpin.

If you don't need to distribute your plugin, and are using Underpin on a single website, it usually makes sense to install it as a mu-plugin. This removes the need to do any compilation, and also ties all of your plugins to a single installation of underpin.

Conclusion

There is so much more about Underpin that hasn't been discussed here, and I expect I'll be publishing more content over time. In the meantime, if you think you'd like to learn more about Underpin, check out the GitHub organization containing all of the current loaders, as well as Underpin's core.

PR's, discussions, and questions are always welcome.

Looking for more WordPress Resources?

Join WP Dev Academy’s Discord server, and become a part of a growing community of WordPress developers.

Create Your Own WordPress Menu API

Alex Standiford — Wed, 06 Jan 2021 19:45:09 +0000

What We’ll Be Doing

We’re going to create 3 REST API endpoints, designed to allow us to get our menus in a couple of different ways.

Get a single menu by its ID
Get a single menu by its name (slug)
Get a single menu by its theme location

We’re going to create a single class, NavMenu, to handle these functions.

I should mention that one limitation this build has is that it doesn’t provide a way to filter results by the
parent. I didn’t use submenus in my personal build of my site, so I didn’t bother adding this functionality. Children
menu items will show up with this build, but you will have to filter out the results with Javascript’s array.filter()
method, or just build that directly into the endpoint via an extra argument, or something like that. I’m sure there’s a
better database query that can be run to only get the results where the parent is X, but that’s outside of the scope of
this lesson.

Build Your NavMenu Class

In my experience, it’s generally easier to create the class that will handle the functionality first, and then build the static methods that will be used as the api callbacks later. Create a new file called NavMenu.php and drop it in your plugin. Be sure to include it in your core plugin file!

<?php
/**
 * Gets a nav menu
 * @author: Alex Standiford
 * @date : 1/13/18
 */

namespace asmenus\lib\app;

class NavMenu{

 public function __construct($menu_name_or_id{
    $this->menus = wp_get_nav_menu_items($menu_name_or_id);
 }

}
?>

We’ll start simple, and grab the list of menu items using wp_get_nav_menu_items() Luckily, this function will work with
either a menu name, or a menu ID, which makes our constructor pretty simple for now.

Also note that we are using a namespace called asmenus\lib\app. This helps to reduce the probability of name collisions
with our code and other plugins, and is why I didn’t name the class something like ASNavMenu.

Right now, if we run var_dump(new asmenus\lib\app\NavMenu($menu_name_or_id)); where you replace $menu_name_or_id
with a valid menu name or ID, it will dump out all of the relevant information related to the items in that menu.

Create a Way To Get a Menu By its Location

Now that we have a way to get the menu by the menu ID and the menu slug, we need to create a way to get a menu by its
location. With a little digging, I discovered that the menu locations and their correlated menu IDs are stored in the
database as a theme mod. To access that, we just need to add a method to our class.

<?php
/**
 * Gets a nav menu
 * @author: Alex Standiford
 * @date : 1/13/18
 */

namespace asmenus\lib\app;

class NavMenu{

 public function __construct($menu_name_or_id){
    $this->menus = wp_get_nav_menu_items($menu_name_or_id);
 }

 /**
 * Gets the menu ID from the specified location
 *
 * @param $location
 *
 * @return mixed
 */
 public function getMenuIdFromLocation($location){
    $locations = get_theme_mod('nav_menu_locations');

    return $locations[$location];
 }

}
?>

Here, we added a new method, getMenuIdFromLocation. This method uses get_theme_mod returns an associative array, with
the menu IDs keyed by the menu location. So, by passing a $location parameter, we can get the desired menu ID.

Now, we just need to use this function in our constructor.

<?php
/**
 * Gets a nav menu
 * @author: Alex Standiford
 * @date : 1/13/18
 */

namespace asmenus\lib\app;

class NavMenu{

 public function __construct($menu_name_or_id, $type = 'menu'){
    if($type == 'location') $menu_name_or_id = $this->getMenuIdFromLocation($menu_name_or_id);

    $this->menus = wp_get_nav_menu_items($menu_name_or_id);
 }

 /**
 * Gets the menu ID from the specified location
 *
 * @param $location
 *
 * @return mixed
 */
 public function getMenuIdFromLocation($location){
    $locations = get_theme_mod('nav_menu_locations');

    return $locations[$location];
 }

}
?>

On our constructor, we add an optional second argument, $type, which if the type is set to 'location', our
constructor will use the getMenuIdFromLocation to get the correct menu ID based on the provided location in our first
argument, $menu_name_or_id.

Right now, if we run var_dump(new asmenus\lib\app\NavMenu($menu_location,'location')); where you replace
$menu_location with a valid menu location, it will dump out all of the relevant information related to the items in
that menu.

Create the REST API Callback Functions

Now that our class is capable of getting our menu details, let’s create our functions that will be used by our rest
endpoints when our endpoint is visited.

<?php
/**
 * Gets a nav menu
 * @author: Alex Standiford
 * @date : 1/13/18
 */

namespace asmenus\lib\app;

class NavMenu{

 public function __construct($menu_name_or_id, $type = 'menu'){
    if($type == 'location') $menu_name_or_id = $this->getMenuIdFromLocation($menu_name_or_id);

    $this->menus = wp_get_nav_menu_items($menu_name_or_id);
 }

 /**
 * Gets the menu ID from the specified location
 *
 * @param $location
 *
 * @return mixed
 */
 public function getMenuIdFromLocation($location){
    $locations = get_theme_mod('nav_menu_locations');

    return $locations[$location];
 }


 /**
 * Callback function to get the menu by name/id via the REST API
 *
 * @param \WP_REST_Request $request
 *
 * @return array|\WP_Error
 */
 public static function getMenuFromApi(\WP_REST_Request $request){
    $name_or_id = $request->get_param('name') ? $request->get_param('name') : (int) $request->get_param('id');
    $self = new self($name_or_id);

    return $self->menus;
 }

}
?>

We’ll start with the first method, which will handle getting the menu regardless of if it is a name or an id. As you can
see, this is a static method (in other words, we can access it without instantiating our class first), and the first
parameter is type-hinted with \WP_REST_Request. If you’re
using a namespace, be sure to remember to add the \ beforehand, otherwise it won’t work.

$name_or_id is set with a ternary operator – which allows us to get the argument regardless of if it is a name or an
id. You could have built this out as two separate methods, but I felt this was cleaner.

Our Completed Class

Now, we just need to repeat this process with a second static method that will get the menu by location.

<?php
/**
 * Gets a nav menu
 * @author: Alex Standiford
 * @date : 1/13/18
 */

namespace asmenus\lib\app;

class NavMenu{

 public function __construct($menu_name_or_id, $type = 'menu'){
    if($type == 'location') $menu_name_or_id = $this->getMenuIdFromLocation($menu_name_or_id);

    $this->menus = wp_get_nav_menu_items($menu_name_or_id);
 }

 /**
 * Gets the menu ID from the specified location
 *
 * @param $location
 *
 * @return mixed
 */
 public function getMenuIdFromLocation($location){
    $locations = get_theme_mod('nav_menu_locations');

    return $locations[$location];
 }


 /**
 * Callback function to get the menu by slug/id via the REST API
 *
 * @param \WP_REST_Request $request
 *
 * @return array|\WP_Error
 */
 public static function getMenuFromApi(\WP_REST_Request $request){
    $name_or_id = $request->get_param('name') ? $request->get_param('name') : (int) $request->get_param('id');
    $self = new self($name_or_id);

    return $self->menus;
 }


 /**
 * Callback function to get the menu by location via the REST API
 *
 * @param \WP_REST_Request $request
 *
 * @return array|\WP_Error
 */
 public static function getMenuByLocationFromApi(\WP_REST_Request $request){
    $location = $request->get_param('location');
    $self = new self($location, "location");

    return $self->menus;
 }

}
?>

The only difference here is that when we instantiated the class, we set the second parameter to 'location'. This tells
our constructor to look up the ID based on the location provided

Register Our Endpoints

Now that our class is built out, we just need to register our endpoints. This should not be added to NavMenu.php,
instead this should be either placed in the core plugin file, or in a separate file that is included afterward. In the
example below, I put them in the core plugin file.

<?php
/**
Plugin Name: WordPress Menu REST API Endpoints
Description: Creates RESTful endpoints for WordPress menus
Version: 1.0
Author: Alex Standiford
Author URI: http://www.alexstandiford.com
**/

if(!defined('ABSPATH')) exit;

require_once(plugin_dir_path(__FILE__).'NavMenu.php');


/**
 * Registers our api endpoints
 */
add_action('rest_api_init', function(){
 /**
 * Gets a single menu by ID
 */
 register_rest_route('asmenus/v1', '/menu/(?P<id>[\d]+)', [
    'methods' => ['GET'],
    'callback' => 'asmenus\lib\app\NavMenu::getMenuFromApi',
 ]);

 /**
 * Gets a single menu by slug
 */
 register_rest_route('asmenus/v1', '/menu/(?P<name>[\w-_]+)', [
    'methods' => ['GET'],
    'callback' => 'asmenus\lib\app\NavMenu::getMenuFromApi',
 ]);

 /**
 * Gets a single menu by its theme location
 */
 register_rest_route('asmenus/v1', '/menu/location/(?P<location>[\w-_]+)', [
    'methods' => ['GET'],
    'callback' => 'asmenus\lib\app\NavMenu::getMenuByLocationFromApi',
 ]);
});

?>

To register our endpoints, we hook into 'rest_api_init', and register our routes in the callback, using
register_rest_route. Notice that our callbacks have the namespace prepended to them, and that we are setting the
method for these endpoints to GET.

Voila! When you visit any of the endpoints, you should now get an array of objects containing all of the information
about each menu item. From here, you could build out some React/Angular components that loop through and build your menu.

Looking for more WordPress Resources?

Join WP Dev Academy’s Discord server, and become a part of a growing community of WordPress developers.

Batch Video Editing With Node.JS

Alex Standiford — Wed, 06 Jan 2021 19:29:10 +0000

Over at DesignFrame, one of my clients hosts videos on their own site. In order to ensure that these videos will play correctly on all devices, I have been manually converting these videos using Cloudconvert. It's a very handy tool, but the process can be tedious when you have a lot of files to deal with, and it doesn't (at least to my knowledge) handle generating screenshots of your videos for you.

So, in-order to upload the videos to their website, my (admittedly awful) workflow looked something like this:

Take each video, and use cloudconvert to create ogv, webm, and mp4 versions of each video
Open the video and save a screenshot at a good place
Upload each version of each video to their server
Publish the video with the screenshot

This wasn't too bad, but as a programmer, doing manual, repetitive tasks makes my skin crawl, so I started looking into ways to automate this. I've been playing with creating small CLI applications with Node.js using commander lately, and decided that this would be an excellent place to start.

What's nice about starting with a CLI-based solution is that it allows me to spend most of my time focusing on the back-end instead of building out some kind of interface. If you build correctly, it should be easy to set up what you've built with an interface.

Here's what the script does:

Add 3 commands accessible from my terminal's command line: run, screenshots, and videos
Take all of the files in a specified directory, and convert the videos to ogv, webm, and mp4
Automatically generate 6 screenshots of each video at different intervals throughout.
Save the results of each video in a converted files directory, with each video title as the sub directory.

The nice thing about setting it up with Node is that, if the conversion job warrants it, you can spin up a cpu-optimized droplet on DigitalOcean, upload the files, and make the conversion quickly, and then destroy the droplet. This is way faster than doing it on your local machine, and since the droplet is usually destroyed in 1-2 hours you're going to spend very little money to get the job done. This isn't a requirement, of course; The script runs perfectly fine on a local machine - the conversion will just take longer.

Completed Project Files

You can get the completed project files here.

Project Structure

I set the project up to use 3 files.

index.js - The entry point for our program. This is where we configure our CLI commands
FileConverter.js - Handles the actual conversion of a single file.
MultiFileConverter.js - Gathers up videos from a directory, creates instances of FileConverter, and runs the conversion.

Setting Up Your Project

Here is the resulting package.json file that I'm using for this project:

    {
      "name": "video-converstion-script",
      "version": "1.0.0",
      "description": "Converts Videos",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "bin": {
        "asconvert": "./index.js"
      },
      "author": "",
      "license": "ISC",
      "dependencies": {
        "@ffmpeg-installer/ffmpeg": "^1.0.15",
        "@ffprobe-installer/ffprobe": "^1.0.9",
        "commander": "^2.16.0",
        "fluent-ffmpeg": "^2.1.2",
        "junk": "^2.1.0"
      }
    }

Here's a list of each dependency and a brief description of their role in this project

@ffmpeg-installer/ffmpeg - sets up the binaries needed to convert the videos and create screenshots
@ffprobe-installer/ffprobe - sets up the binaries needed to convert the videos and create screenshots
commander - Super awesome tool that allows us to build out a CLI from our Node.js application.
fluent-ffmpeg - Allows us to interface with ffmpeg using Node
junk - A nice little library that makes it easy to filter out junk files from our directory. This will keep us from trying to convert a .DS_Store file, or something like that.

Note that we also have set the bin object. This allows us to associate our CLI command asconvert with our index.js file. You can change asconvert to whatever you want, just keep in mind that you will need to use whatever you call asconvert instead of what I call it in this post.

Place JSON above into your package.json file, and run npm install. Once you do that, you'll also need to run npm link. This will connect the bin configuration to your terminal so you can run your commands directly from the command line.

Setting up our Index file

Before we can start messing with our system, we need to set up some commander commands. This will allow us to test, debug, and tinker with our javascript from the terminal. We will be adding multiple commands later, but for now, let's simply add the run command. The code below is a basic example, and should respond with "hello world!' in your terminal.

#!/usr/bin/env node

/**
 * Allows us to run this script as a cli command
 */
const program = require('commander');

/**
 * Sets up the command to run from the cli
 */
program
 .version('0.1.0')
 .description('Convert Video Files From a Directory');

/**
 The run command
 */
program
 .command('run')
 .description('Converts the files in the files-to-convert directory of this project')
 .action(() =>{
 console.log('hello world!');
//We will put our actual command here.
 });

program.parse(process.argv);

Once you add this, you should be able to run asconvert run from your terminal and you should get "hello world!" back. Superkewl!

Set Up the MultiFileConverter Class

Now that we've got some simple command line things set up, let's start working on the good stuff.

Create a new file called MultiFileConverter.js and add the following code.

/**
 * Parses file names
 */
const path = require('path');

/**
 * converts files from a directory
 */
class MultiFileConverter{
 constructor(args = {}){
 //Set the argument object
 const defaults = {
 directory: false,
 formats: false
 };
 this.args = Object.assign(args, defaults);

 //Construct from the args object
 this.formats = this.args.formats;
 this.directory = this.args.directory === false ? `${path.dirname(require.main.filename)}/files-to-convert/` : this.args.directory;
 }
}

module.exports = MultiFileConverter;

This basic setup will allow us to pass an object of arguments to our constructor, which will merge with default arguments and build everything we'll need to complete the conversions.

Connect The Converter to the CLI

Once you do this, we need to set up our CLI command to use this object. Go back to your index.js file and create an instance of this class, like so.

#!/usr/bin/env node
/**
 * Allows us to run this script as a cli command
 */
const program = require('commander');

const MultiFileConverter = require('./lib/MultiFileConverter');

/**
 * Sets up the command to run from the cli
 */
program
 .version('0.1.0')
 .description('Convert Video Files From a Directory');

/**
 The run command
 */
program
 .command('run')
 .description('Converts the files in the files-to-convert directory of this project')
 .action(() =>{
 const converter = new MultiFileConverter();
 console.log(converter);
 });

program.parse(process.argv);

If you run the command now, the converter object should be displayed in the terminal.

I personally organize my js files inside a lib directory. You can put your files wherever you want, just make sure your include paths are correct.

Get the List of FileConverter objects

The primary purpose of the MultiFileConverter class is to batch-convert files in the directory. In order to do that, we are going to loop through the files in the directory and construct an array of FileConverter objects from each file. We'll let the FileConverter object handle the actual conversion and other file-specific things.

I like to delay processes that have the potential to be time-consuming until I absolutely need them. That way I can construct the class without going through the time-consuming bits every time. To do this, I often create a getter method, like this:

/**
 * Constructs the files object
 * @returns {*}
 */
getFiles(){
 if(this.files) return this.files;
 this.files = [];
 const files = fs.readdirSync(this.directory, {});
 //Loop through and construct the files from the specified directory
 files.filter(junk.not).forEach((file) =>{
 this.files.push(new FileConverter(this.directory + file, false, this.formats));
 });

 return this.files;
}

You'll notice the first line checks to see if the class already has a files array set. If it does, it simply returns that array. Otherwise, it goes through and builds this array. This allows us to use getFiles() throughout the class without re-building the array every time.

A lot is happening in this method. Let's break it down.

Check to see if the files array exists. If it does, it returns the value
Reads the specified directory and returns an array of files
Filters out junk files, and then loops through the filtered array.
Inside the loop, we push a new instance of FileConverter and pass the arguments into the the files array.
Return the files in the object

Update your MultiFileConverter class to include a couple of required libraries, and add the getFiles() class. You should end up with something like this:

/**
 * Node File system
 */
const fs = require('fs');

/**
 * Parses file names
 */
const path = require('path');

/**
 * Allows us to filter out junk files in our results
 */
const junk = require('junk');

/**
 * Handles the actual file conversion of individual files
 * @type {FileConverter}
 */
const FileConverter = require('./FileConverter');

/**
 * converts files from a directory
 */
class MultiFileConverter{
 constructor(args = {}){
 //Set the argument object
 const defaults = {
 directory: false,
 formats: false
 };
 this.args = Object.assign(args, defaults);

 //Construct from the args object
 this.formats = this.args.formats;
 this.directory = this.args.directory === false ? `${path.dirname(require.main.filename)}/files-to-convert/` : this.args.directory;
 }

 /**
 * Constructs the files object
 * @returns {*}
 */
 getFiles(){
 if(this.files) return this.files;
 this.files = [];
 const files = fs.readdirSync(this.directory, {});
 //Loop through and construct the files from the specified directory
 files.filter(junk.not).forEach((file) =>{
 this.files.push(new FileConverter(this.directory + file, false, this.formats));
 });

 return this.files;
 }
}

module.exports = MultiFileConverter;

Set Up the FileConverter Class

Now that we are looping through our files, it's time to build a basic instance of the FileConverter class so our files array builds properly.

 /**
 * Parses file names
 */
const path = require('path');

/**
 * Node File system
 */
const fs = require('fs');

/**
 * Handles the actual file conversion
 */
const ffmpegInstaller = require('@ffmpeg-installer/ffmpeg');
const ffprobePath = require('@ffprobe-installer/ffprobe').path;
const ffmpeg = require('fluent-ffmpeg');
ffmpeg.setFfmpegPath(ffmpegInstaller.path);
ffmpeg.setFfprobePath(ffprobePath);

/**
 * Converts files and takes screenshots
 */
class FileConverter{

 constructor(inputPath, outputPath = false, formats = false){
 this.formats = formats === false ? ['ogv', 'webm', 'mp4'] : formats.split(',');
 this.file = path.basename(inputPath);
 this.format = path.extname(this.file);
 this.fileName = path.parse(this.file).name;
 this.conversion = ffmpeg(inputPath);
 this.outputPath = outputPath === false ? `${path.dirname(require.main.filename)}/converted-files/${this.fileName}` : `${outputPath}/${this.fileName}`;
 }
}

module.exports = FileConverter;

You'll notice that we are constructing some useful data related to the file and its impending conversion, but we don't actually do the conversion step yet. This simply sets the file up. We'll add the actual conversion in a separate method.

Test It Out

We now have all 3 of our files all set up and connected. We haven't started the actual conversion process yet, but if we make a change to our command action we can check to make sure everything is working as-expected.

If you haven't yet, now would be a good time to create 2 directories in the root of your project. converted-files and files-to-convert. Add a few video files in your files-to-convert directory.

Modify your commander action in your index.js file so that it logs the result of the getFiles() method. If all went well, you should get a big ol' array of objects.

#!/usr/bin/env node
/**
 * Allows us to run this script as a cli command
 */
const program = require('commander');

const MultiFileConverter = require('./lib/MultiFileConverter');

/**
 * Sets up the command to run from the cli
 */
program
 .version('0.1.0')
 .description('Convert Video Files From a Directory');

/**
 The run command
 */
program
 .command('run')
 .description('Converts the files in the files-to-convert directory of this project')
 .action(() =>{
 const converter = new MultiFileConverter();
 console.log(converter.getFiles());
 });

program.parse(process.argv);

Convert Videos

Whew. All this effort and we haven't even started converting videos yet. Let's change that.

Add a new method, called getVideos() to your MultiFileConverter.js file.

/**
 * Loops through and converts files
 */
getVideos(){
 return this.getFiles().forEach(file => file.convert());
}

This iddy biddy method simply loops through our files array and runs the convert method on each FileConverter object. Of course, we have to actually create the convert method on the FileConverter object for this to work, so let's do that now.

Add a new method, called convert() to your FileConverter.js file.

/**
 * Converts the file into the specified formats
 */
convert(){
 fs.mkdir(this.outputPath,() =>{

 //Loop through file formats
 this.formats.forEach((fileFormat) =>{
 //Check to see if the current file format matches the given file's format
 if(`.${fileFormat}` !== this.format){
 //Start the conversion
 this.conversion.output(`${this.outputPath}/${this.fileName}.${fileFormat}`)
 .on('end', () => console.log(`${this.file} has been converted to a ${fileFormat}`))
 .on('start', () =>{
 console.log(`${this.fileName}.${fileFormat} conversion started`);
 })
 }

 //If the file format matches the file's format, skip it and let us know.
 else{
 console.log(`Skipping ${this.fileName} conversion to ${fileFormat} as this file is already in the ${fileFormat} format.`);
 }
 });

 this.conversion.run();
 });
}

Here's the real meat and potatoes of the build. A lot is happening here, so let's break it down.

Creates a directory named after the original video we're converting. This will hold all files generated for this video.
Loops through each file format specified for this conversion.
In the loop, we check to see if the current file format matches the format of the video we're converting. If they match, the converter skips that conversion and moves on to the next format. This keeps us from needlessly converting an .mp4 to another .mp4.
If the formats are different, we queue up the converter using the specified format.
Once we've looped through all of the formats we're converting to, we run the actual converter.

Test It Out

We have now set up the actual converter. Let's see if it works as expected.

Modify your commander action in your index.js file to use the getVideos() method, like so.

#!/usr/bin/env node
/**
 * Allows us to run this script as a cli command
 */
const program = require('commander');

const MultiFileConverter = require('./lib/MultiFileConverter');

/**
 * Sets up the command to run from the cli
 */
program
 .version('0.1.0')
 .description('Convert Video Files From a Directory');

/**
 The run command
 */
program
 .command('run')
 .description('Converts the files in the files-to-convert directory of this project')
 .action(() =>{

 });

program.parse(process.argv);

You should see a message for each video, stating that the conversion started for each format. It will also let you know if it skipped one of the conversions, and why. This will take a long time to convert, and since we're just testing, cancel the command (CTRL+C on a Mac) after about 20 seconds. Check your converted-files directory and see if the video conversion started to run.

Generate Screenshots

Sweet! Now that we have videos converting, let's get generate some screenshots while we're at it. The process of adding screenshots is very similar.

Add a new method, called getScreenshots() to your MultiFileConverter.js file.

/**
 * Loops through and generates screenshots
 */
getScreenshots(){
 return this.getFiles().forEach(file => file.getScreenshots());
}

This works just like getVideos(), only it runs getScreenshots method on each FileConverter object instead. Again, we need to create the convert method on the FileConverter object for this to work.

Add a new method, called getScreenshots() to your FileConverter.js file.

/**
 * Creates 6 screenshots taken throughout the video
 */
getScreenshots(){
 this.conversion
 .on('filenames', filenames => console.log(`\n ${this.fileName} Will generate 6 screenshots, ${filenames.join('\n ')}`))
 .on('end', () =>{
 console.log(`\n Screenshots for ${this.fileName} complete.\n`)
 })
 .screenshots({
 count: 6,
 timestamps: [2, 5, '20%', '40%', '60%', '80%'],
 folder: this.outputPath,
 filename: `${this.fileName}-%s.png`
 })

}

This method is a bit simpler than getVideos(). We simply chain the screenshots() method (included in our ffmpeg library) and pass some arguments. Our arguments instruct ffmpeg to create 6 screenshots at 2 seconds, 5 seconds, and at 20%, 40%, 60%, and 80% of the video. Each file is saved inside the same directory as our converted videos are saved.

Test It Out

Let's make sure that we can generate screenshots.

Modify your commander action in your index.js file to use the getScreenshots() method, like so.

#!/usr/bin/env node
/**
 * Allows us to run this script as a cli command
 */
const program = require('commander');

const MultiFileConverter = require('./lib/MultiFileConverter');

/**
 * Sets up the command to run from the cli
 */
program
 .version('0.1.0')
 .description('Convert Video Files From a Directory');

/**
 The run command
 */
program
 .command('run')
 .description('Converts the files in the files-to-convert directory of this project')
 .action(() =>{
const converter = new MultiFileConverter();
return converter.getScreenshots();
 });

program.parse(process.argv);

You should see a message for each video, listing off the screenshots that will be created. This will take a some time to convert, and since we're just testing, cancel the command (CTRL+C on a Mac) after about 20 seconds. Check your converted-files directory and see if the screenshots started to generate.

Generate Everything

Now that we have a way to generate screenshots and convert our videos, we need to make one more method in our MultiFileConverter.js file. This method will run both the convert() method and the getScreenshots() method.

We are creating a third method to do both of these because it allows us to loop through the files once, instead of twice, and as such is more efficient than running getVideos() and then getScreenshots() separately.

Add this method to your MultiFileConverter class.

/**
 * Runs the complete converter, converting files and getting screenshots
 */
runConverter(){
 return this.getFiles().forEach((file) =>{
 file.convert();
 file.getScreenshots();
 });

Create Commands

Now that we have everything needed, let's create our 3 commands we talked about earlier - asconvert videos, asconvert screenshots, and asconvert run

/**
 * Sets up the command to run from the cli
 */
program
 .version('0.1.0')
 .description('Convert Video Files From a Directory');

program
 .command('run')
 .description('Converts the files in the files-to-convert directory of this project')
 .action(() =>{
 const converter = new MultiFileConverter();
 return converter.runConverter();
 });

/**
 * Sets up the command to run from the cli
 */
program
 .command('screenshots')
 .description('Gets a screenshot of each video')
 .action(() =>{
 const converter = new MultiFileConverter();
 return converter.getScreenshots();
 });

/**
 * Sets up the command to run from the cli
 */
program
 .command('videos')
 .description('Gets conversions of each video')
 .action(() =>{
 const converter = new MultiFileConverter();
 return converter.getVideos();
 });

program.parse(process.argv);

You can now run any of those 3 commands, and convert videos, create screenshots, or do both at the same time.

Closing Remarks

There are a couple of things that could improve this tool.

I'm sure someone who knows Docker better than I could put it in some kind of container to make this EZPZ to set up/tear down on a server
The directory that houses the videos is a part of the project. With further configuration you could set this up so that the videos are pulled directly from Google Drive, or something like that. I didn't have a need for that, but it would be pretty slick.

All in all, it was a fun little build, and I'm sure it will save me some time in the future.

If you are using this, I'd love to hear about how it worked for you, and why you needed it. Cheers!