Ejecting (forking) an Arc Block

If there is an Arc block that does the majority of what you need but not all and to save time you wish to reuse the code and make some minor changes based on the desired functionality, the best option would be to eject (or sometimes commonly referred to as “forking”) an Arc block. When we use the phrase “eject a block”, that really means to make a custom block in your feature pack with the starting point of the Arc block that you can then adjust as needed.

Implications for ejecting a block

When you eject an Arc block you need to remember that you are no longer on the upgrade path and any new out-of-the-box features will not be reflected in the ejected version.

A slightly easier way to think of it is - you are taking an Arc block at that point in time.

When ejecting a block there are some items you need to be made aware of:

• Ensure you copy the entire block, children, and styles.
• If the block imports from @wpmedia/arc-themes-components , it will need to be included in the package.json for your bundle.
• You don’t need to eject @wpmedia/arc-themes-components - that is a separate package that is designed to be used as a reusable set of components.
• In the case where a block imports another block (which shouldn’t happen) you would need to copy both blocks.
• (v1 only) You don’t need to eject the SDK - that is a separate package that is designed to be used as a reusable set of components. This package is deprecated in v2.

Themes 2.0 components and block features and styling on ejected blocks

• Components - For ejected or custom blocks, you can utilize our components and those Arc XP components will remain on the upgrade path.
• Blocks - Ejected custom blocks will not receive feature upgrades. If your use case for ejecting is CSS or styling related, we recommend you use our blocks styling design system instead, to remain on the upgrade path.
• Blocks styling - Block styling applies to out-of-the-box components and blocks. This includes Arc XP components used on your custom blocks. Full custom blocks, not comprised of Arc XP components, will not be watched by our StyleBuilder script, but you can still apply your custom styling.

Deciding when to use an out-of-the-box block versus a custom block

The below guidance is intended to help your organization in deciding whether you can use an Arc XP Themes out-of-the-box (OOTB) or if creating a custom block will be necessary for your hard requirements. For a full list of components, blocks, and available design tokens, see Themes 2.0 - Blocks Styling Figma Library.

Ejecting breakdown

Shown below is an overview of a block showing the PageBuilder Engine entry and the block children. For this example we are using the Header Nav Chain Block - Arc-Themes-Blocks/Blocks/Header-Nav-Chain-Block At Stable · WPMedia/Arc-Themes-Blocks

Blocks structure

You should be able to tell that the blocks repo follows a similar folder structure as a feature pack. The block folder contains a folder of the Fusion block type. In this example, there is a chains folder and then inside there is a folder called header-nav-chain-block

To eject the header nav chain block you will need to make a copy of the header-nav-chain-block folder into your feature pack, copy the folder from here - Arc-Themes-Blocks/Blocks/Header-Nav-Chain-Block/Chains At Stable · WPMedia/Arc-Themes-Blocks

At this point you have half ejected the block, as this block relies on Themes components from @wpmedia/shared-styles you’ll also need to look into the block and see what shared styles components are being used and make a copy of those into your feature pack.

Here’s how the imports currently look for the ejected header nav chain block

import React, { useEffect, useState } from 'react';
import PropTypes from 'prop-types';
import styled from 'styled-components';
import { useContent } from 'fusion:content';
import { useFusionContext } from 'fusion:context';
import getProperties from 'fusion:properties';
import getThemeStyle from 'fusion:themes';
import getTranslatedPhrases from 'fusion:intl';
import { HamburgerMenuIcon, UserIcon } from '@wpmedia/engine-theme-sdk';
import SectionNav from './_children/section-nav';
import SearchBox from './_children/search-box';

// shares styles with header nav chain
// can modify styles in shared styles block
import '@wpmedia/shared-styles/scss/_header-nav.scss';

As you can see the block is importing import "@wpmedia/shared-styles/scss/_header-nav.scss";

You’ll now need to make a copy of that file into your feature pack. If we place it at the same level as the default.jsx file we can make the imports look as follows:

import React, { useEffect, useState } from 'react';
import PropTypes from 'prop-types';
import styled from 'styled-components';
import { useContent } from 'fusion:content';
import { useFusionContext } from 'fusion:context';
import getProperties from 'fusion:properties';
import getThemeStyle from 'fusion:themes';
import getTranslatedPhrases from 'fusion:intl';
import { HamburgerMenuIcon, UserIcon } from '@wpmedia/engine-theme-sdk';
import SectionNav from './_children/section-nav';
import SearchBox from './_children/search-box';

// Now the shared styles from Blocks is maintained within your custom code
import './_header-nav.scss';

The reason you need to eject dependencies from the @wpmedia/shared-styles block is that if Themes makes any changes to the shared styles components that your ejected block is using, we are unable to be 100% confident it will not cause your ejected version to stop working.

Creating a custom block

For full details on creating a custom block, see Creating a custom block. After you have created the custom block, you can follow the below steps to add and/or remove blocks to your feature pack.

Using an ejected / custom block instead of the Arc block

Removing Arc blocks from your bundle

If you want to remove an out-of-the-box block from your bundle to ensure it’s not used in PageBuilder Editor and to reduce your bundle size, you may remove that block from the Arc and Custom blocks configuration in Theme Settings, or directly from the blocks.json within your bundle. Below is an example of Arc blocks within the blocks.json of a bundle. The blocks.json is only used for out-of-the-box blocks.

"blocks": [
    "@wpmedia/global-phrases-block",
    "@wpmedia/alert-bar-block",
    "@wpmedia/article-body-block",
    "@wpmedia/alert-bar-content-source-block",
    "@wpmedia/article-tag-block",
    "@wpmedia/author-bio-block",
    "@wpmedia/byline-block",
    "@wpmedia/card-list-block",
    "@wpmedia/date-block",
    "@wpmedia/default-output-block",
    "@wpmedia/double-chain-block",
    "@wpmedia/extra-large-manual-promo-block",
    "@wpmedia/extra-large-promo-block",
    "@wpmedia/footer-block",
    "@wpmedia/full-author-bio-block",
    "@wpmedia/gallery-block",
    "@wpmedia/header-block",
    "@wpmedia/header-nav-block",
    "@wpmedia/header-nav-chain-block",
    "@wpmedia/headline-block",
    "@wpmedia/htmlbox-block",
    "@wpmedia/large-manual-promo-block",
    "@wpmedia/large-promo-block",
    "@wpmedia/lead-art-block",
    "@wpmedia/links-bar-block",
    "@wpmedia/masthead-block",
    "@wpmedia/medium-manual-promo-block",
    "@wpmedia/medium-promo-block",
    "@wpmedia/numbered-list-block",
    "@wpmedia/overline-block",
    "@wpmedia/quad-chain-block",
    "@wpmedia/results-list-block",
    "@wpmedia/right-rail-block",
    "@wpmedia/right-rail-advanced-block",
    "@wpmedia/search-results-list-block",
    "@wpmedia/section-title-block",
    "@wpmedia/share-bar-block",
    "@wpmedia/shared-styles",
    "@wpmedia/simple-list-block",
    "@wpmedia/single-chain-block",
    "@wpmedia/small-manual-promo-block",
    "@wpmedia/small-promo-block",
    "@wpmedia/subheadline-block",
    "@wpmedia/tag-title-block",
    "@wpmedia/text-output-block",
    "@wpmedia/textfile-block",
    "@wpmedia/top-table-list-block",
    "@wpmedia/triple-chain-block",
    "@wpmedia/video-player-block",
    "@wpmedia/content-api-source-block",
    "@wpmedia/collections-content-source-block",
    "@wpmedia/author-content-source-block",
    "@wpmedia/search-content-source-block",
    "@wpmedia/site-hierarchy-content-block",
    "@wpmedia/story-feed-author-content-source-block",
    "@wpmedia/story-feed-query-content-source-block",
    "@wpmedia/story-feed-sections-content-source-block",
    "@wpmedia/story-feed-tag-content-source-block",
    "@wpmedia/tags-content-source-block",
    "@wpmedia/unpublished-content-source-block",
    "@wpmedia/resizer-image-block",
    "@wpmedia/resizer-image-content-source-block",
    "@wpmedia/placeholder-image-block",
    "@wpmedia/event-tester-block"
  ],

Including custom blocks in your bundle

Your custom blocks, chains, layouts, and output-types will be within the components folder of your bundle. You may upload your custom blocks bundle within Theme Settings.

Feature pack structure

For full details on the feature pack file structure, including the blocks.json and components folder referenced above see:

• Feature pack directory structure
• Themes 2.0 - Feature pack structure (including site styles)

Naming conventions of custom blocks versus Arc blocks

Arc blocks

Out-of-the-box blocks will contain the @wpmedia prefix. This will display in both your bundle and the PageBuilder Editor interface. For example, the following will display in PageBuilder Editor for Arc blocks:

Custom blocks

You should rename your ejected blocks to a naming convention that best suits your organization’s best practices. If you do not rename the ejected block and still maintain the Arc block within your bundle, you will experience a build error.