--- title: Connecting Gutenberg and Frontity published: true description: In this post, Mario shares the process and the steps we followed to rebuild our website (frontity.org) with Gutenberg and Frontity. tags: wordpress, react, javascript, webdev cover_image: https://frontity.org/wp-content/uploads/2020/11/gutenberg-frontity-asset.png canonical_url: https://frontity.org/blog/connecting-gutenberg-and-frontity/ --- This is a written version of the _"Connecting Gutenberg and Frontity: A Case Study"_ talk that I gave at the [2020 JavaScript for WordPress Conference](https://javascriptforwp.com/conference/). You can find the slides [here](https://drive.google.com/file/d/1o4hZ8hscnY8WmUERXDbXE45IVsk8tn7E/view) and watch the full talk on [Youtube](https://www.youtube.com/watch?v=5EIqBfD_LTY). [![](http://img.youtube.com/vi/5EIqBfD_LTY/0.jpg)](http://www.youtube.com/watch?v=5EIqBfD_LTY "") Gutenberg (also known as the block editor) is already being used by many WordPress users. Rolled into WordPress 5.0, it has reinvented the experience of creating and managing content in WordPress. In this talk, we walk you through the process we followed to rebuild our website ([frontity.org](https://frontity.org/)) with Gutenberg and Frontity. We share all the challenges and lessons learnt, and what we considered to be the best approach to solve them. ### Table of contents **Introduction**: * [Why use Gutenberg and Frontity together?](#why-use-gutenberg-and-frontity-together) * [Goals of the process](#goals-of-the-process) **Connecting Gutenberg and Frontity**: * [How did we implement it?](#how-did-we-implement-it) 1. Adapting Frontity to Gutenberg 2. Block patterns 3. Template parts 4. @frontity/html2react **Conclusions**: * [What went well](#what-went-well) * [Lessons learnt and next steps](#lessons-learnt-and-next-steps) * * * ### Introduction # Why use Gutenberg and Frontity together? As you already know, WordPress as a publishing tool is great. That is one of the main reasons why it's widely used for different websites. In addition, Gutenberg opened a new paradigm which is revolutionizing the way we build, edit, and publish online. Its goal is to make the publishing experience even easier. By using Gutenberg with a React framework like Frontity, you can benefit from the best of these two worlds. ![Why Gutenberg and Frontity asset](https://frontity.org/wp-content/uploads/2020/11/Why-Gutenberg-and-Frontity.png) First, you will get a great **editing experience** thanks to WordPress and Gutenberg. Frontity allows you to maintain the publishing workflow with all the awesome functionalities that are already made for the WordPress editor. On the other hand, because Frontity is based on React, you will be able to create more complex user interfaces while having a **great developer experience**. In the same way that WordPress usage is increasing each year and is the most popular CMS, React is becoming a popular library for taking over front-end development. Lastly, thanks to Frontity's unique approach, combining WordPress and React has never been easier. The framework deals with all the setup needed like Babel, WebPack, the WordPress REST API, the routing... so that you can focus on building your React theme. If you are interested in knowing more about why Frontity can be a great fit for your project as well as our vision, take a look at this [introductory talk about the framework](https://www.youtube.com/watch?v=9OkLcgxNSLo) that our co-founder Pablo gave at the JavaScript for WordPress Conference. # Goals of the process Before starting the migration, we defined the project's goals and requirements that we needed to keep in mind during the whole process. This helped us prioritize and make other decisions later. #### Explain Frontity better After discontinuing the development of Frontity PRO (our previous product) in order to focus on Frontity Framework, we hadn't updated our website to reflect the changes to the product. We felt that the new framework wasn't being properly explained. We had been working on new features which were not mentioned in the homepage, and some of the benefits of using Frontity weren't clearly expressed. For these reasons, our first and main goal was to redesign the whole website to explain everything better and start getting more traction. #### Make everything editable from Gutenberg Sometimes when developing a website, you are tempted to hardcode specific parts of the content or layout that you don't plan to update frequently. An example could be the header or the footer of a website. This can be even more tempting in a headless setup, where some aspects might be a bit more difficult to implement. In our case, we wanted the marketing team or any other member of the team to be able to easily change the website's copy, or to add or delete sections in the future without having to rely on the dev team. Such flexibility was an essential requirement for us. In the end, this is what a CMS like WordPress is for, right? #### Create new pages easily This is closely related to the previous point: we wanted the ability to create new pages in an easy way. Not just simple pages, but also more complex ones in which we could reuse different layout elements. We thought that, with a proper implementation, we should be able to build nice landing pages just by reusing some patterns of the homepage. We knew this was going to be another requirement at some point (for building the [10up partner page](https://frontity.org/partner/10up/) or similar ones, for example). And again, we didn't want anyone to have to depend on the dev team to do this. #### Find the best way to connect Gutenberg and Frontity Frontity aims to solve all the challenges that a headless setup may cause. For this reason, we want to ensure that Frontity's integration with the WordPress block editor is as smooth as possible. This was the perfect opportunity to understand it better, learn from our own experience, and work on solutions for any issue we might encounter. ### Connecting Gutenberg and Frontity # How did we implement it? We based the implementation on 4 important aspects and reasons. 1. **Adapting Frontity to Gutenberg**. This allowed us to use the block editor just as it is. 2. **Block patterns**. This enabled us to reuse layout elements in different parts of the website easily. 3. **Template parts**. This made it possible to edit common elements that are used in all pages (e.g. the header or footer). 4. **@frontity/html2react**. This allowed us to add React logic to any HTML element we wanted. ## 1\. Adapting Frontity to Gutenberg ### 1.1\. How Gutenberg works? In order to find the best way to connect Frontity and Gutenberg, we had to understand first how Gutenberg works: ![Gutenberg flow asset](https://frontity.org/wp-content/uploads/2020/11/Gutenberg-flow-vertical.png) **Add any block from the WordPress editor** Just as they do in any WordPress site, users can create their desired layout using the block editor. They first select the blocks they are going to use, and then define their specific properties. There are Gutenberg blocks for almost everything, and each block has different properties. For example, the paragraph block has a property to change the text colour, and in the image block you'll find properties to change the image's size or alignment. Similarly with the video block, which has different properties to change the controls or activate the autoplay functionality. In our case, we didn't find anything that we couldn't already do with the built-in Gutenberg blocks. This means that we didn't have to create any custom blocks for our website, which made the implementation much easier. **Gutenberg outputs the HTML adding some classes** Once the user saves a post, Gutenberg outputs the HTML and adds different classes to match each block's properties defined by the user. It doesn't output the block attributes but valid HTML. This is important because, in the end, both Gutenberg and React are basically just HTML. In other words, we don't have to link each block with React. The Gutenberg HTML, with the classes it adds, is available in the REST API and is fetched by Frontity automatically. This allows Frontity to work with it in the same way it works with any common post. It doesn't require any further integration. We just have to add React logic to the HTML elements we want. This is an example of the image block, aligned to the right:

**Gutenberg adds two css files to match that classes** In order to match the layout defined in the editor, Gutenberg creates two css files which add the logic to style the post. Since Frontity is already getting the HTML from the REST API, this is great because we just have to add these files in our Frontity theme to match the classes output in the HTML. From there, Gutenberg is already supported, and we simply have to add React logic to the HTML elements we want. This would be the css that matches the previous example: .wp-block-image .alignright { float: right; margin-left: 1em; } There are two exceptions that are not included in these files: colour palette and font sizes. In Gutenberg, you can define a [theme palette](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-color-palettes) (a set of colours) in order to select your own colours in the block editor. Gutenberg will create the new class `has-$slug-color` but this won't be included in the theme.css and style.css. So we have to make it match from within Frontity. We can add our own colours by adding this simple snippet to WordPress: add_action( 'after_setup_theme', 'prefix_register_colors' ); function prefix_register_colors() { add_theme_support( 'editor-color-palette', array( /* Frontity colors */ array( 'name' => esc_html__( 'Frontity', 'nude' ), 'slug' => 'frontity', 'color' => '#1f38c5', ), array( 'name' => esc_html__( 'Primary', 'nude' ), 'slug' => 'primary', 'color' => '#0f1c64', ), ) ); } The same happens with the different [font sizes](https://developer.wordpress.org/block-editor/developers/themes/theme-support/#block-font-sizes). You can define your own set of font sizes to replace the default ones, and Gutenberg will add the class `has-$slug-font-size` with this simple snippet: add_theme_support( 'editor-font-sizes', array( array( 'name' => __( 'Large', 'nude' ), 'shortName' => __( 'L', 'nude' ), 'size' => 20, 'slug' => 'large' ), array( 'name' => __( 'Medium', 'nude' ), 'shortName' => __( 'M', 'nude' ), 'size' => 16, 'slug' => 'medium' ), array( 'name' => __( 'Small', 'nude' ), 'shortName' => __( 'S', 'nude' ), 'size' => 14, 'slug' => 'small' ) ) ); Imagine we have a paragraph, then we change the font size to _medium_ and we select the _frontity_ color, previously included in our theme palette. Gutenberg will output something like this:

{ const data = state.source.get(state.router.link); return ( <> ... ); }; export default connect(Theme); After doing this, everything added from Gutenberg was supported except the colours and the font-sizes. As previously mentioned, we had defined our own colour palette and font-sizes. In order to match the different colours we had created, the first step we took was to add them to Frontity state as well. To do so, we added them to `state.theme.colors` in the [index.ts file](https://github.com/frontity/frontity.org/blob/dev/packages/frontity-org-theme/src/state/index.ts#L5-L17) of our theme. Now they were accessible from any part of our Frontity project. Apart from this, we created two processors ([explained later](#html2react-processors)): one for the [text-color](https://github.com/frontity/frontity.org/blob/dev/packages/frontity-org-theme/src/processors/text-color.tsx), and other for the [background-color](https://github.com/frontity/frontity.org/blob/dev/packages/frontity-org-theme/src/processors/background-color.tsx) that extracts the colour which is used and, looking into `state.theme.colors`, adds the css needed for this. Moreover, we created a new util named [addAlpha](https://github.com/frontity/frontity.org/blob/dev/packages/frontity-org-theme/src/utils/index.ts#L3-L16) (used in these processors) to add opacity to these colours if a specific class is matched. This isn't supported by Gutenberg yet, so we decided to implement it ourselves. On the other hand, to match the font-sizes, we added the css we wanted for the specific classes. We did it using a [processor](https://github.com/frontity/frontity.org/blob/dev/packages/frontity-org-theme/src/processors/paragraph.ts#L26-L36), but this can be done directly in the css files: .has-small-font-size { font-size: 14px; line-height: 20px; } .has-medium-font-size { font-size: 16px; line-height: 24px; } .has-small-font-size { font-size: 20px; line-height: 32px; } And that's it. Now that we had connected Gutenberg and Frontity, we just needed to add the React logic to the HTML elements we wanted. ## 2\. Block patterns From the Gutenberg side, we realised that we were using the same layouts in different parts of the website. We wanted to be able to reuse them in an easy way, not only for the existing pages but also for future ones. After some research, we decided to use [Block Patterns](https://developer.wordpress.org/block-editor/developers/block-api/block-patterns/) for this purpose. Block patterns are basically a group of Gutenberg blocks that have been combined together to create a page layout. Once you have created a block pattern, it can be reused throughout your website. That is, you can combine different blocks with different properties, create a pattern and placed it anywhere you like. Then you will only have to change the content within it. ![Block Patterns asset](https://frontity.org/wp-content/uploads/2020/11/Block-patterns.png) A good example of a block pattern can be found in the ["Why Frontity?"](https://frontity.org/#why-frontity) section. As you can see, all the feature items follow the same pattern: they have an icon with a squared background, a heading 4, and a paragraph with medium font size. Instead of building each item from scratch, we created a block pattern with the required properties and reused it to list each of the different features. ### 2.1\. How to create block patterns Here's the code that you can include in your `functions.php` or in a Code Snippet. However, for a more detailed explanation, please check the [Block Patterns documentation](https://developer.wordpress.org/block-editor/developers/block-api/block-patterns/). __( 'Pattern name' ), 'content' => '...Gutenberg HTML...', ) ); After adding this simple function, the patterns that you've created will appear in the Gutenberg editor. In order to create the HTML, what we did first was to create the patterns using the visual editor. Then we changed the properties that we needed. Once we had considered them finished, we switched from the visual to the code editor and copied and pasted the HTML. Doing things this way made everything much easier. For this you don't have to do anything in your Frontity project. This only affects the Gutenberg editing experience. ### 2.2\. How to use them Once we had created the patterns, it was really easy to use them in the Gutenberg editor. On the same button that you use to add blocks there's a new tab named Patterns where you can find the ones that were previously defined. ![How to add block patterns asset](https://frontity.org/wp-content/uploads/2020/11/Add-block-patterns-1024x810.png) ## 3\. Template parts The Gutenberg plugin in its experimental version creates a new Custom Post type named [Template Parts](https://developer.wordpress.org/block-editor/tutorials/block-based-themes/#what-is-needed-to-create-a-block-based-theme), which is an important part of [block-based themes](https://developer.wordpress.org/block-editor/tutorials/block-based-themes/). We decided to use it for the common elements on every page, such as the footer or the header. ![Template parts asset](https://frontity.org/wp-content/uploads/2020/11/Template-parts.png) As they are a CPT, we can edit them just as we do with any other post or page, and WordPress then outputs the content in the REST API. For example, if we create a Template Part for the footer using WordPress, we can fetch the content in this endpoint: [https://frontity.org/wp-json/wp/v2/template-parts?slug=footer](https://frontity.org/wp-json/wp/v2/template-parts?slug=footer). After creating all the template parts that we needed, the next step was to fetch them in our Frontity app and make sure they were available for every page. In order to achieve this, we had to: 1. [Include the Template Parts CPT](https://github.com/frontity/frontity.org/blob/dev/frontity.settings.js#L26-L35) in the `frontity.settings.js` file. As we're including `/blog/` for the post permalinks, we had to add that as well. 2. [Create an array](https://github.com/frontity/frontity.org/blob/dev/packages/frontity-org-theme/src/state/index.ts#L20-L26) in the `index.js` file of our theme to define all the template parts that we wanted to fetch. 3. [Create a Frontity action](https://github.com/frontity/frontity.org/blob/dev/packages/frontity-org-theme/src/actions.ts#L5-L9) to fetch all these template parts [Before Server Side Rendering](https://docs.frontity.org/learning-frontity/actions#beforessr-server-only-__). At this point, our Frontity state already had the content of all the template parts. Now we just had to create the React components that would consume this content. For example, we created [the `

santosguillamot

Connecting Gutenberg and Frontity

Join Our Newsletter. No Spam, Only the good stuff.