If you’ve been following my blog or WordPress development for some time now, you’d know by now that the Gutenberg project contains a number of hidden gems that you, as a JavaScript developer or a WordPress developer can benefit from in your own standalone applications or WordPress plugins.

One of these hidden gems is the keyboard shortcuts package, a utility package that allows you to do all sort of things related to keyboard shortcuts, between adding keyboard shortcuts, removing keyboard shortcuts, updating them and more.

As a standalone package.

Like any package in the gutenberg package, it’s distributed as a standalone npm package that you can consume and use in any React application. Here’s a basic example (Full example available on Stackblitz):

import { ShortcutProvider, useShortcut, store } from '@wordpress/keyboard-shortcuts';
import { useState, useEffect } from '@wordpress/element';
import { useDispatch } from '@wordpress/data';

function MyCounter() {
  const [ count, setCount ] = useState( 0 );
  const { registerShortcut } = useDispatch( store );

  useEffect( () => {
    registerShortcut( {
      name: 'mycounter/increment',
      description: 'Increment the counter',
      keyCombination: {
        character: 'i'
      } 
    } );
  }, [] );

  useShortcut( 'mycounter/increment', () => {
    setCount( count + 1 );
  } );

  return (
    <div>
      Count: { count }
    </div>
  );
}

function App() {
  return (
    <ShortcutProvider>
      <MyCounter />
    </ShortcutProvider>
  );
}

So to use the package, first, you need to wrap your React application in a ShortcutProvider. (The shortcuts will only work if the active element is inside the shortcut provider in the DOM tree)

The next step is to register your shortcuts using the registerShortcut action. This function call declares the existence of your shortcut in your shortcuts store, providing the keyboard combination used to trigger the shortcut behavior and some additional metadata, like a description and a category.

It’s a good practice to register all your shortcuts when initially rendering your application component.

That said, for the shortcuts to actually perform any action, we need to define their callbacks, and we do so using the useShortcut react hook, the first argument being the shortcut name and the second the function that is called when the key combination is pressed.

Note: The reason registering shortcuts and using shortcuts are separate is because some shortcuts are contextual to specific actions but the application always need to know about the existence of a shortcut during its lifecycle. For instance, all shortcuts can be rendered in a help panel but all the shortcuts might not be active. For example, a “copy” shortcut in an editor is only active if there’s a selection.

The keyboard shortcuts package allows using single character shortcuts or shortcuts with one or two modifiers. These are all examples of valid key combinations:

• { character: 'a' } is equivalent to pressing a.
• { character: 'del' } is equivalent to pressing the delete button.
• { character: 'a', modifier: 'primary' } is equivalent to pressing command + a on Mac.
• { character: 'a', modifier: 'primaryShift' } is equivalent to pressing command + shift + a on Mac.
• { character: 'a', modifier: 'alt' } is equivalent to pressing option + a on Mac.

As a WordPress API

In WordPress, the keyboard shortcuts package is used to register all the block editor shortcuts, but you can also use it to register your own custom shortcuts in your block or any WordPress plugin or page using the same API. It is available in the wp-keyboard-shorctuts wordpress script. If you plan on using it, in your plugin’s scripts, make sure to add the wp-keyboard-shorctuts as a dependency to your custom scripts:

function my_enqueue_scripts()
{
    wp_register_script( 'my_plugin_script', 'path-to-my-script.js', array( 'wp-keyboard-shortcuts' );
    wp_enqueue_script( 'my_plugin_script' );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

The wp.keyboardShortcuts global variable will be made available for you with all the APIs exposed by the package: useShortcut, ShortcutsProvider…

Super Powers

Editing keyboard shortcuts

An important aspect of implementing keyboard shortcuts in any application is to define the right key combinations for the right shortcut. That said, it is surprisingly hard to come up with combinations that work for everyone, in all browsers and all operating systems. For that reason, the keyboard shortcuts package allows the possibility to update the registered shortcuts and change their keyboard combination.

import { useSelect, useDispatch } from '@wordpress/data';
import { store } from '@wordpress/keyboard-shortcuts';

function ToggleIncrementShortcut() {
  const { getShortcutKeyCombination } = useSelect( store );
  const { registerShortcut } = useDispatch( store );

  const toggleShortcut = () => {
    const currentCharacter = getShortcutKeyCombination( 'mycounter/increment' )?.character;
    const nextCharacter = currentCharacter === 'a' ? 'i' : 'a';
    registerShortcut( {
      name: 'mycounter/increment',
      description: 'Increment the counter',
      keyCombination: {
        character: nextCharacter
      } 
    } );
  }

  return (
    <button onClick={ toggleShortcut }>
      Toggle between "i" and "a"
    </button>
  );
}

So as we can see in the example above, registering the shortcut again, overrides its current definition allowing us to update any of its properties including the key combination.

💡 In the future, the block editor might provide this automatically but until then, there’s an opportunity here for a WordPress plugin that provides a UI to edit the existing shortcuts.

The WordPress block editor is based around the idea that you can combine independent blocks together to write your post or build your page. Blocks can also use and interact with each other. This makes it very modular and flexible.

But the Block Editor does not embrace modularity for its behavior and output only, it is also built from the ground up as several reusable and independent modules or packages, that, combined together lead to the application and interface we all now. These modules are known as WordPress packages and are published and updated regularly on the npm package repository.

Right now these packages are built in the Block Editor Repository and used to power the block editor. Ultimately, these packages will be used to power any page in the WordPress Admin.

Modular architecture

Using a modular architecture has several benefits for all the actors involved:

• Each package is an independent unit and has a well defined public API that is used to interact with other packages and third-party code. This makes it easier for Core Contributors to reason about the codebase. They can focus on a single package at a time, understand it and make updates while knowing exactly how these changes could impact all the other parts relying on the given package.
• A module approach is also beneficial to the end-user. It allows to selectively load scripts on different WordPress Admin pages while keeping the bundle size contained. For instance, if we use the components package to power our plugin’s settings page, there’s no need to load the block-editor package on that page.
• This architecture also allows third-party developers to reuse these packages inside and outside the WordPress context by using these packages as npm or WordPress script dependencies.

Types of packages

Almost everything in the Gutenberg repository is built into a package. We can split the packages into two different types:

Production packages

These are the packages that ship in WordPress itself as JavaScript scripts. These constitute the actual production code that runs on your browsers. As an example, there’s a components package serving as a reusable set of React components used to prototype and build interfaces quickly. There’s also an api-fetch package that can be used to call WordPress Rest APIs.

Third-party developers can use these production packages in two different ways:

• If you’re building a JavaScript application, website, page that runs outside of the context of WordPress, you can consume these packages like any other JavaScript package in the npm registry.

npm install @wordpress/components

import { Button } from '@wordpress/components';

function MyApp() {
   return (
      <Button>Nice looking button</Button>
   );
}

• If you’re building a plugin that runs on WordPress, you’d probably prefer consuming the package that ships with WordPress itself. This allows multiple plugins to reuse the same packages and avoid code duplication. In WordPress, these packages are available as WordPress scripts with a handle following this format wp-package-name (e.g. wp-components). Once you add the script to your own WordPress plugin scripts dependencies, the package will be available on the wp global variable.

// myplugin.php
// Exemple of script registration dependending on the "components" and "element packages.
wp_register_script( 'myscript', 'pathtomyscript.js', array ('wp-components', "wp-element" ) );

// Using the package in your scripts
const { Button } = wp.components;

function MyApp() {
   return (
      <Button>Nice looking button</Button>
   );
}

Script dependencies definition can be a tedious task for developers. Mistakes and oversight can happen easily. If you want to learn how you can automate this task. Check the @wordpress/scripts and @wordpress/dependency-extraction-webpack-plugin documentation.

Packages with stylesheets

Some production packages provide stylesheets to function properly.

• If you’re using the package as an npm dependency, the stylesheets will be available on the build-style folder of the package. Make sure to load this style file on your application.
• If you’re working in the context of WordPress, you’ll have to enqueue these stylesheets or add them to your stylesheets dependencies. The stylesheet handles are the same as the script handles.

In the context of existing WordPress pages, if you omit to define the scripts or styles dependencies properly, your plugin might still work properly if these scripts and styles are already loaded there by WordPress or by other plugins, but it’s highly recommended to define all your dependencies exhaustively if you want to avoid potential breakage in future versions.

Packages with data stores

Some WordPress production packages define data stores to handle their state. These stores can also be used by third-party plugins and themes to retrieve data and to manipulate it (Refer to my previous post on the subject for more details here). The name of these data stores is also normalized following this format core/package-name (E.g. the @wordpress/block-editor package defines and uses the core/block-editor package).

If you’re using one of these stores to access and manipulate WordPress data in your plugins, don’t forget to add the corresponding WordPress script to your own script dependencies for your plugin to work properly. (For instance, if you’re retrieving data from the core/block-editor store, you should add the wp-block-editor package to your script dependencies like shown above).

Development packages

These are packages used in development mode to help developers with daily tasks to develop, build and ship JavaScript applications, WordPress plugins and themes. They include tools for linting your codebase, building it, testing it…

Going further

The WordPress packages are a gold mine and a huge time saver when it comes to building JavaScript application whether as a WordPress plugin or an independent application.

In the next weeks, I’ll try to write a series of posts to explain some of these packages in detail, how to reuse them in your own code. In the meantime, I encourage you to explore the documentation of the different packages on the block editor handbook.

With Gutenberg, we made the choice to use JavaScript heavily in order build the UI of the editor, not because we’re nerdy hipsters but essentially because it is the perfect fit to address the UI and UX challenges of a heavily interactive interface in the browser.

As a consequence, we’ll start to see a shift in the WordPress community. Plugin developers are required to use JavaScript more in order to extend the editor. Most blocks need to be developed using this technology. The modules Gutenberg provides (Components, data module, i18n, apiFetch…) will also encourage developers to extend other parts of WP-Admin in JavaScript. Instead of writing HTML/CSS screens from scratch and rendering them from the server, developers are able to bootstrap and prototype fully accessible new screens in WP-Admin by composing these components in a small number lines of code.

Learning process

But when we talk about JavaScript in general, we can think of two different approaches:

• Using untranspiled ES5 code.
• Leveraging build tools like babel, webpack… and write ESNext JavaScript code (ES2015 and more).

Most plugin authors are already writing ES5 code in their PHP rendered UIs or in their themes and the Gutenberg APIs can continue be used this way. But our role as Core Contributors should also be to educate people to get on the ESNext train as it can be a huge improvement in terms of productivity and development experience.

That said, learning ESNext and all the tools involved in the process can be a bit overwhelming if you’re coming from a PHP background without any prior heavy JavaScript experience. To help with the transition, the WordPress community started working and providing tools (Like Create Guten Block).

Using these tools can feel like “magic” though. It works but as a developer, you don’t really know what’s happening behind the scenes. Debugging code can be a challenge if you don’t understand how everything fits together.

For this particular reason, I created the WordPress JavaScript Plugin Starter. Unlike other starters thought, it’s written as a tutorial. Each commit of the repository is a step further in the setup and the README goes through each one of these steps and explains it.

Hopefully, At the end of the day, you’d be able to use the starter as a way to start a WordPress plugin but also master how this plugin works and how all the tools fit together to ship a production ready JavaScript plugins.