How to work with WordPress blocks outside Gutenberg with Node.js

The WordPress block editor is changing everything related to how we create content with this platform. There are many novelties that the new releases of WordPress bring regarding blocks, and there is still a long way to go in the future.

For this reason, developers who work with WordPress as a development platform should feel increasingly comfortable working with blocks. However, making the leap from PHP to JavaScript-based technologies can be tough.

Anyway, you have to update your skills and not be afraid of the new WordPress development stack. The sooner we are comfortable with it, the more opportunities we will have to innovate.

Today we are going to see how we can work with Gutenberg blocks without having to be inside the WordPress editor. Why? For several reasons…

The first and most obvious is because we can. For some time now, the definition of the core blocks in the Gutenberg editor has been available as a separate code package. This means that we can use them outside of WordPress thanks to the NPM package manager.

In addition, there is a whole series of functions to manage blocks and work with them. And they are also contained in their own package. Therefore, if we want to work with the standard WordPress blocks, we only have to import these two packages as dependencies in our project.

To achieve this, we must create a folder for our project, run npm init to create a package.json file with the project data, and then run the following command to install these two dependencies:

npm install @wordpress/block-library @wordpress/blocks

The next step is to create an index.js file with the code we want to execute. This code is written in Node.js, a variant of JavaScript that runs on servers. For today’s example, the content of index.js can be as follows:

const { 
  registerCoreBlocks
} = require( '@wordpress/block-library' );
const { 
  createBlock,
  serialize
} = require( '@wordpress/blocks' );
registerCoreBlocks();
const myBlock = createBlock( 
 'core/paragraph', 
 {
  content: 'This is a block created programmatically',
 }
);
const serializedBlock = serialize( myBlock );
console.log( serializedBlock );

The first two statements that appear in the preceding code are require statements to import the dependencies. As I said before, we want to import the standard WordPress block definition. We do this with require('@wordpress/block-library'). Since we only want to import the registerCoreBlocks function from this package, on the left side of the equality symbol we destructure that function.

In the same way we import the @wordpress/blocks package as a dependency. This package is the one that has the functions to work with blocks. There are a lot of functions defined in the package (you have them here), but for this example we only want createBlock to create new blocks and serialize to convert them into strings that we can save in the content of a WordPress post.

Now that we have the dependencies imported, we call the registerCoreBlocks function, which loads the definition of the standard WordPress block types so we can use them. From then on we can create blocks, as you can see when we call the createBlock function passing as a parameter the name of the type of block we want to create and an object with its attributes.

In the previous example we are going to create a paragraph block, so we pass the name 'core/paragraph' and inside the attributes object we pass the content of the paragraph to be created as a string inside the content key.

Finally, we call the serialize function, passing it the block we just created. As a result we will have a string that we can output with the console.log function.

Now we can run the above code typing node index.js in the terminal. If we do that, the following happens:

There is an error in the execution! The reason is that we need to have the window variable available, which is not defined. But what is this variable and why do we need it?

Window is a JavaScript object that the browser defines and represents the browser window itself. Since we are executing the code in our terminal (or if it were running in production, on a server), we do not have a browser with said variable. Does this mean we can’t use WordPress blocks outside a browser? Of course it doesn’t!

Node.js has several packages that allow us to simulate that we are running our code in a browser environment. In this case, we are going to use the browser-env package. We just have to install it as we did before with the WordPress packages:

npm install browser-env

In our index.js file we have to add a new require to import the browser-env dependency. But also, we have to “fix” the window object since it does not come with the required matchMedia method. If you copy the following code and add it to the beginning of the index.js file, the problem is solved:

// Setup environment to simulate a browser
// (mandatory to register Gutenberg blocks).
require( 'browser-env' )();
window.matchMedia =
 window.matchMedia ||
  function () {
   return {
    matches: false,
    addListener: function () {},
    removeListener: function () {},
   };
  };

Now you can run the code again and you will see that it does not fail and that it returns the textual representation of the paragraph block we just created using the createBlock function:

$ node index.js                                             
<!-- wp:paragraph -->
<p>This is a block created programmatically</p>
<!-- /wp:paragraph -->

You have all the code in this GitHub repository. The possibilities for working with blocks from outside the editor are enormous. You can create blocks, clone them, transform them to a different type of block, and much more.

Being able to work with blocks outside the WordPress editor allows us to manipulate the contents of our WordPress and work with them from anywhere. This opens up a world of enormous possibilities for developers that we are just beginning to explore.

We at Nelio are already making use of these possibilities. We’ll soon launch a new service that you’ll hopefully find very interesting. Stay tuned for the news that we are going to release in the upcoming weeks ?.

Featured image by Kelly Sikkema on Unsplash.